Skip to content

Memory

The agent's persistent memory — the three markdown documents injected into every turn. A native client's "memory management" screen reads and writes them here. Verified against api/routes.py.

The three sections are a fixed enum: memory (the agent's working notes → memories/MEMORY.md), user (facts about the user → memories/USER.md), and soul (the agent's persona/identity → SOUL.md).

GET /api/memory

Response 

{
  "memory": "<MEMORY.md text>",
  "user": "<USER.md text>",
  "soul": "<SOUL.md text>",
  "project_context": "…",
  "memory_path": "…", "user_path": "…", "soul_path": "…",
  "memory_mtime": 1712000000.0, "user_mtime": null, "soul_mtime": null,
  "project_context_shadowed": false, "external_notes_enabled": false
}

Reads the active profile's memory files. Text is redacted server-side per the instance's redaction policy. *_mtime values are float epoch seconds or null (file absent). project_context is the workspace-scoped context note when present.

POST /api/memory/write

Body { "section": "memory"|"user"|"soul", "content": "<text>" } → { "ok": true, "section", "path": "<absolute file path>" }.

  • 400 on missing fields or an invalid section.
  • 400 if the target is a symlink (refused for safety).
  • 403 if the file isn't writable.

Writes the whole section (full replace). To edit, read the current text, modify, and write it back.

Editing pattern

There's no per-entry API — memory is document-level. A client edits by fetching the section, applying the user's change to the markdown, and POSTing the full new content. Keep edits small and preserve the rest of the document.