By default, an Agent's context disappears when a Session ends. Memory Stores persist learnings and outputs across Sessions so the Agent can recall earlier work.
Core Concepts
| Concept | Description |
|---|
| Memory Store | A memory repository scoped by project or domain |
| Entry | A single memory, identified by path; each entry has a unique entry_id |
| Version | An immutable snapshot generated on every write, update, or delete |
| Redact | Irreversibly mask the contents of a version (for compliance) |
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 |
| DELETE | /memory_stores/{id} | Delete a Memory Store |
| POST | /memory_stores/{id}/memories | Create an Entry |
| GET | /memory_stores/{id}/memories | List Entries |
| GET | /memory_stores/{id}/memories/{entry_id} | Get an Entry (with content) |
| PUT | /memory_stores/{id}/memories/{entry_id} | Update an Entry (OCC) |
| DELETE | /memory_stores/{id}/memories/{entry_id} | Delete an Entry |
| POST | /memory_stores/{id}/versions/{version_id}/redact | Redact a version |
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"
}'
{
"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."
}'
The list endpoint does not return content; call the single-entry endpoint to read contents.
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"
{
"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
}'
| Field | Type | Required | Description |
|---|
content | string | Yes | New content |
version | integer | Yes | Current Entry version (for conflict detection) |
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"
Deletion uses the entry_id (e.g. mem_019e5cdba1b674e4a6a7d4f8c9b3e2a1); deleting by the path query parameter is not supported.
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"]
}'
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"
Stat Fields
| Field | Description |
|---|
entry_count | Total number of Entries in the Store |
total_size | Combined byte size of all Entry contents |
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.
Create a separate Memory Store per project to keep memories from getting mixed up.
