# How to Enable and Use Editable Memory Slots in AgentMemory

> Enable and use editable memory slots in AgentMemory by setting AGENTMEMORY_SLOTS true and using /agentmemory/slot endpoints to manage persona and preferences.

- Repository: [Rohit Ghumare/agentmemory](https://github.com/rohitg00/agentmemory)
- Tags: how-to-guide
- Published: 2026-05-10

---

**Set the `AGENTMEMORY_SLOTS=true` environment variable to enable editable memory slots, then use the `/agentmemory/slot*` HTTP endpoints to read, modify, and pin slots like *persona* and *user_preferences*.**

AgentMemory is an open-source memory service for AI agents that supports dynamic **editable memory slots**—named text containers that persist across sessions. This guide explains how to enable the slot feature flag and manipulate built-in slots such as *persona* and *preferences* using the REST API and core functions defined in the `rohitg00/agentmemory` repository.

## Enabling the Slot Feature Flag

Editable memory slots are gated behind the **`AGENTMEMORY_SLOTS`** feature flag. To activate the slot management API and related functions, set the environment variable and restart the service.

```bash
export AGENTMEMORY_SLOTS=true

```

Add this to your `.env` file or Docker Compose configuration, then restart the AgentMemory service. The flag is read during initialization in [`src/functions/slots.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/functions/slots.ts) where the `isSlotsEnabled()` function checks `process.env["AGENTMEMORY_SLOTS"]` (lines 98-100).

Verify the flag is active via the configuration endpoint:

```bash
curl -s http://localhost:8080/agentmemory/config/flags | jq '.flags[] | select(.key=="AGENTMEMORY_SLOTS")'

```

When enabled, the service registers the `mem::slot-*` function family and corresponding HTTP routes; otherwise, these endpoints return HTTP 503 errors.

## Slot Architecture and Storage Model

AgentMemory stores slots in two distinct **KV namespaces** defined in [`src/state/schema.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/state/schema.ts): `KV.globalSlots` for global defaults and `KV.slots` for project-scoped overrides. When the service starts, the `seedDefaults()` function in [`src/functions/slots.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/functions/slots.ts) (lines 54-66) populates the store with built-in slots including **persona**, **user_preferences**, and **tool_guidelines** if they do not already exist.

Built-in slots are created with **`readOnly: false`** by default, meaning they can be edited or deleted like custom slots. Each slot carries metadata including `sizeLimit`, `description`, and a **`pinned`** flag that determines automatic inclusion in LLM prompts.

The HTTP API routes are registered in [`src/triggers/api.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/triggers/api.ts) (lines 80-90), which maps endpoints such as `GET /agentmemory/slot` to the internal `mem::slot-get` function.

## Managing Slots via the HTTP API

All slot endpoints support an optional **`Authorization: Bearer <secret>`** header if the `AGENTMEMORY_SECRET` environment variable is configured. Responses follow the standard AgentMemory JSON format: `{ success: true, ... }`.

### List and Retrieve Slots

Query all available slots (global and project-scoped):

```bash
curl http://localhost:8080/agentmemory/slots

```

Retrieve a specific slot by label:

```bash
curl "http://localhost:8080/agentmemory/slot?label=persona"

```

### Create or Update a Slot

Use `POST /agentmemory/slot` to create new slots or update existing ones. Specify the `scope` as `"global"` or `"project"` and set `pinned: true` to include the slot in LLM context automatically.

```bash
curl -X POST http://localhost:8080/agentmemory/slot \
  -H "Content-Type: application/json" \
  -d '{
        "label": "my_notes",
        "content": "Initial project context",
        "description": "Personal scratchpad",
        "pinned": false,
        "scope": "project",
        "sizeLimit": 3000
      }'

```

### Append and Replace Operations

The **`mem::slot-append`** function (exposed via `POST /agentmemory/slot/append`) adds text to the end of an existing slot, automatically inserting a newline if the current content lacks one:

```bash
curl -X POST http://localhost:8080/agentmemory/slot/append \
  -H "Content-Type: application/json" \
  -d '{
        "label": "persona",
        "text": "\nI also enjoy gardening on weekends."
      }'

```

To overwrite content completely, use the **`mem::slot-replace`** function via `POST /agentmemory/slot/replace`:

```bash
curl -X POST http://localhost:8080/agentmemory/slot/replace \
  -H "Content-Type: application/json" \
  -d '{
        "label": "user_preferences",
        "content": "Prefer TypeScript, use eslint‑airbnb, avoid global variables."
      }'

```

Both operations enforce the slot's `sizeLimit` and acquire a per-slot lock before writing to prevent race conditions.

### Delete Slots

Remove non-read-only slots using `DELETE /agentmemory/slot`:

```bash
curl -X DELETE http://localhost:8080/agentmemory/slot \
  -H "Content-Type: application/json" \
  -d '{ "label": "my_notes" }'

```

## Using Slots in LLM Sessions

AgentMemory automatically injects **pinned** slots into the system prompt sent to the LLM via the `renderPinnedContext` helper in [`src/functions/slots.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/functions/slots.ts) (lines 82-90). Because built-in slots like *persona* and *user_preferences* are created with `pinned: true`, their content appears in the context without additional API calls.

To include a custom slot in the LLM prompt, create it with the pinned flag:

```bash
curl -X POST http://localhost:8080/agentmemory/slot \
  -H "Content-Type: application/json" \
  -d '{
        "label": "my_style_guide",
        "content": "Prefer snake_case for variables, use single‑quote strings.",
        "pinned": true,
        "scope": "project"
      }'

```

Subsequent calls to `mem::context` or any LLM-driven function will prepend this content to the system prompt.

## Summary

- Enable editable memory slots by setting `AGENTMEMORY_SLOTS=true` and restarting the service.
- Verify activation via `/agentmemory/config/flags` before attempting slot operations.
- Manipulate slots through the `/agentmemory/slot*` REST endpoints or internal `mem::slot-*` functions defined in [`src/functions/slots.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/functions/slots.ts).
- Use `pinned: true` when creating slots to automatically include them in LLM context via `renderPinnedContext()`.
- Built-in slots (*persona*, *user_preferences*) are editable by default and stored in `KV.globalSlots`.

## Frequently Asked Questions

### Why do I receive a 503 error when calling slot endpoints?

The `AGENTMEMORY_SLOTS` feature flag is disabled. Set the environment variable to `true` and restart the service. The `isSlotsEnabled()` check in [`src/functions/slots.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/functions/slots.ts) guards all slot-related logic and returns HTTP 503 when the flag is missing or false.

### Can I delete the default *persona* or *user_preferences* slots?

Yes. The built-in slots are created with `readOnly: false`, so you can delete them via `DELETE /agentmemory/slot` or modify them using the append/replace endpoints. If deleted, they will not be re-seeded unless you manually trigger `seedDefaults()` or clear the KV store.

### What is the difference between global and project-scoped slots?

Global slots are stored in the `KV.globalSlots` namespace and persist across all projects using the same AgentMemory instance. Project-scoped slots reside in `KV.slots` and are isolated to the current project context. Set the `scope` property accordingly when creating a slot via the API.

### How do I prevent a slot from being included in every LLM prompt?

Set `pinned: false` when creating or updating the slot (or omit the property, as it defaults to false). Only slots with `pinned: true` are automatically concatenated into the system context by the `renderPinnedContext` function.