Memory Stores

Core Concepts

Hierarchy: Store → Entry → Version.

API Endpoints

Path Rules

An Entry's path must be a relative path:

• Valid: notes/meeting-2026-05-18.md, config.yaml.

• Invalid: /notes/meeting.md (cannot start with /).

Paths organize memories like a filesystem.

End-to-End Flow

1. Create a Memory Store

curl -X POST https://api.qoder.com.cn/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",
  "type": "memory_store",
  "name": "project-alpha-memory",
  "description": "Agent knowledge base for project Alpha",
  "status": "active",
  "entry_count": 0,
  "total_size": 0,
  "metadata": {},
  "created_at": "2026-05-18T08:00:00Z",
  "updated_at": "2026-05-18T08:00:00Z"
}

2. Create an Entry

curl -X POST https://api.qoder.com.cn/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."
  }'

3. Get an Entry

Fetch the full content (including content) by entry_id:

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

Example response:

{
  "content": "# Architecture Decision\n\nChose microservices because the team is scaling and we need independent deployments.",
  "content_sha256": "1712de0d497a5aeef2beeccf4fbb7d5a16944975438d0c25447b9c1fba13099a",
  "created_at": "2026-05-18T08:00:00Z",
  "id": "mem_019e5cdb9c3f71c3b6505eba937a40b5",
  "metadata": {},
  "path": "decisions/arch-choice.md",
  "size": 99,
  "store_id": "memstore_019e5cdb9c3f71c3b6505eba937a40b4",
  "type": "memory",
  "updated_at": "2026-05-18T09:30:00Z",
  "version": 2
}

4. Update an Entry

Send a PUT request with the entry_id and the current version for optimistic concurrency control. A new version snapshot is created automatically:

curl -X PUT https://api.qoder.com.cn/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.",
    "version": 1
  }'

Request fields:

If the supplied version doesn't match the server (concurrent write detected), the API returns 409 Conflict. Re-GET the latest version, then retry.

5. Delete an Entry

Delete by entry_id:

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

6. Use in a Session

Reference Memory Stores via memory_store_ids when creating the Session:

curl -X POST https://api.qoder.com.cn/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_xxx",
    "memory_store_ids": ["memstore_019e5cdb9c3f71c3b6505eba937a40b4"]
  }'

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

Memory Entry paths in sandbox

Memory entries are mounted at /data/.qoder/awareness/<entry.path> inside the sandbox. All entries are flattened under awareness/ with no memory_store or entry_id naming levels. The Agent reads files solely by entry.path.

Version Tracking

Every create, update, or delete produces an immutable version snapshot, providing a complete change history for each Entry.

Redact

When a version contains sensitive content that must be wiped permanently:

curl -X POST https://api.qoder.com.cn/api/v1/cloud/memory_stores/memstore_019e5cdb9c3f71c3b6505eba937a40b4/versions/ver_xyz789/redact \
  -H "Authorization: Bearer $QODER_PAT"

Caution: Redaction is irreversible — once redacted, the content cannot be recovered.

Stat Fields

FAQ

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

Q: Can an Entry's path contain subdirectories? A: Yes — paths like notes/2026/05/daily.md are supported.

Q: Are versions kept after I delete an Entry? A: Deletion creates a "delete" version record; earlier versions remain traceable.

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