How to Enable and Use Editable Memory Slots in AgentMemory

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.

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 where the isSlotsEnabled() function checks process.env["AGENTMEMORY_SLOTS"] (lines 98-100).

Verify the flag is active via the configuration endpoint:

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: KV.globalSlots for global defaults and KV.slots for project-scoped overrides. When the service starts, the seedDefaults() function in 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 (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):

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

Retrieve a specific slot by label:

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.

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:

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:

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:

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 (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:

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.
• 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}