> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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:

```json theme={null}
{
  "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

```bash theme={null}
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."
  }'
```

<Note>
  The list endpoint does not return `content`; call the single-memory endpoint to read contents.
</Note>

### 3. Get a Memory

Fetch the full content (including `content`) by `memory_id`:

```bash theme={null}
curl https://api.qoder.com/api/v1/cloud/memory_stores/memstore_019e5cdb9c3f71c3b6505eba937a40b4/memories/mem_019e5cdba1b674e4a6a7d4f8c9b3e2a1 \
  -H "Authorization: Bearer $QODER_PAT"
```

Response:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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](/cloud-agents/api/memory-stores/redact-version) 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.

<Note>
  Create a separate Memory Store per project to keep memories from getting mixed up.
</Note>