Memory Stores

Once a Session ends, the Agent’s context is gone by default. Memory Stores let an Agent’s learnings and outputs persist across Sessions — the next time the Agent runs, it can “remember” earlier work.

Core Concepts

Concept	Description
Memory Store	A memory repository scoped by project or domain
Memory	A single memory, identified by path; each memory has a unique mem_... ID
Version	An immutable snapshot generated on every create, update, or delete

Hierarchy: Store → Memory → Version.

API Endpoints

Method	Path	Description
POST	/memory_stores	Create a Memory Store
GET	/memory_stores	List Memory Stores
GET	/memory_stores/{id}	Get a Memory Store
POST	/memory_stores/{id}	Update a Memory Store
POST	/memory_stores/{id}/archive	Archive a Memory Store
DELETE	/memory_stores/{id}	Delete a Memory Store
POST	/memory_stores/{id}/memories	Create a Memory
GET	/memory_stores/{id}/memories	List Memories
GET	/memory_stores/{id}/memories/{memory_id}	Get a Memory (with content)
POST	/memory_stores/{id}/memories/{memory_id}	Update a Memory
DELETE	/memory_stores/{id}/memories/{memory_id}	Delete a Memory
GET	/memory_stores/{id}/memory_versions	List Memory Versions
GET	/memory_stores/{id}/memory_versions/{memory_version_id}	Get a Memory Version (with content)
POST	/memory_stores/{id}/memory_versions/{memory_version_id}/redact	Redact a Memory Version

Path Rules

A Memory’s path must be a relative path:

• Valid: notes/meeting-2026-05-18.md, config.yaml.
• Invalid: /notes/meeting.md (cannot start with /), ../secrets (cannot contain ..).

Paths organize memories like a filesystem.

End-to-End Flow

1. Create a Memory Store

curl -X POST https://api.qoder.com/api/v1/cloud/memory_stores \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "project-alpha-memory",
    "description": "Agent knowledge base for project Alpha"
  }'

Example response:

{
  "id": "memstore_019e5cdb9c3f71c3b6505eba937a40b4",
  "created_at": "2026-05-18T08:00:00.000Z",
  "name": "project-alpha-memory",
  "type": "memory_store",
  "updated_at": "2026-05-18T08:00:00.000Z",
  "archived_at": null,
  "description": "Agent knowledge base for project Alpha",
  "metadata": {},
  "status": "active",
  "entry_count": 0,
  "total_size": 0
}

2. Create a Memory

curl -X POST https://api.qoder.com/api/v1/cloud/memory_stores/memstore_019e5cdb9c3f71c3b6505eba937a40b4/memories \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "decisions/arch-choice.md",
    "content": "# Architecture Decision\n\nChose microservices because the team is scaling and needs independent deployments."
  }'

The list endpoint does not return content; call the single-memory endpoint to read contents.

3. Get a Memory

Fetch the full content (including content) by memory_id:

curl https://api.qoder.com/api/v1/cloud/memory_stores/memstore_019e5cdb9c3f71c3b6505eba937a40b4/memories/mem_019e5cdba1b674e4a6a7d4f8c9b3e2a1 \
  -H "Authorization: Bearer $QODER_PAT"

Response:

{
  "id": "mem_019e5cdba1b674e4a6a7d4f8c9b3e2a1",
  "type": "memory",
  "memory_store_id": "memstore_019e5cdb9c3f71c3b6505eba937a40b4",
  "path": "decisions/arch-choice.md",
  "content": "# Architecture Decision\n\nChose microservices because the team is scaling and needs independent deployments.",
  "content_size_bytes": 99,
  "content_sha256": "1712de0d497a5aeef2beeccf4fbb7d5a16944975438d0c25447b9c1fba13099a",
  "version": 1,
  "metadata": {},
  "created_at": "2026-05-18T08:00:00.000Z",
  "updated_at": "2026-05-18T08:00:00.000Z"
}

4. Update a Memory

Updates use POST against the memory_id. A new version snapshot is generated automatically. To guard against concurrent writes, pass the content_sha256 you last read — the API returns 409 Conflict if it no longer matches the server’s current content:

curl -X POST https://api.qoder.com/api/v1/cloud/memory_stores/memstore_019e5cdb9c3f71c3b6505eba937a40b4/memories/mem_019e5cdba1b674e4a6a7d4f8c9b3e2a1 \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Architecture Decision v2\n\nMoved to a Modular Monolith because microservice operational costs exceeded the budget.",
    "content_sha256": "1712de0d497a5aeef2beeccf4fbb7d5a16944975438d0c25447b9c1fba13099a"
  }'

Request fields:

Field	Type	Required	Description
content	string	Yes	New content, up to 100 KB
content_sha256	string	No	Expected SHA-256 of the current content (optimistic concurrency). Omit to skip the check
metadata	object	No	Metadata to attach

If content_sha256 is supplied and does not match the server (a concurrent write was detected), the API returns 409 Conflict. Re-GET the memory, then retry.

5. Use in a Session

Reference Memory Stores through resources[] when creating the Session:

curl -X POST https://api.qoder.com/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_xxx",
    "environment_id": "env_xxx",
    "resources": [
      {
        "type": "memory_store",
        "memory_store_id": "memstore_019e5cdb9c3f71c3b6505eba937a40b4",
        "access": "read_write",
        "instructions": "Use this memory for project context."
      }
    ]
  }'

The Agent can read from and write to linked Memory Stores within the Session.

Memory paths in the sandbox

Memories are mounted at /data/.qoder/awareness/<memory.path> inside the sandbox. There are no memory_store or memory ID naming levels in the sandbox — all memories are flattened under awareness/. The Agent cannot see the memory_store concept; it only reads files by path.

Version Tracking

Every create, update, or delete on a Memory produces a snapshot. Versions are immutable and provide a complete change history. List them with GET /memory_stores/{id}/memory_versions (optionally filtered by memory_id), and read a single version’s content with GET /memory_stores/{id}/memory_versions/{memory_version_id}.

If a version captured sensitive content, redact it to permanently remove the stored content while keeping the version metadata for audit.

Stat Fields

Field	Description
entry_count	Total number of Memories in the Store
total_size	Combined byte size of all Memory content

FAQ

Q: How many Memory Stores can a Session reference? A: Multiple Stores are supported; link as needed.

Q: Can a Memory’s path contain subdirectories? A: Yes — paths like notes/2026/05/daily.md are supported.

Q: Are there capacity limits on a Memory Store? A: Refer to your account quota. Limits are typically generous for normal projects.

Create a separate Memory Store per project to keep memories from getting mixed up.