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

# Memory endpoints

> Search, export, and import the Engine's long-term memory.

The Engine has three memory stores — episodes, knowledge, and the social
graph — plus a "soul" representing the user's core identity and learned
patterns. Memory updates as the agent runs; these endpoints let you read
and move it.

All memory endpoints require `X-Engine-Key`.

## POST /memory/knowledge/search

Search the knowledge store with hybrid (vector + keyword) scoring.

```http theme={null}
POST /memory/knowledge/search
Content-Type: application/json

{
  "query": "what does the user prefer for testing?",
  "limit": 20
}
```

| Field   | Type   | Required | Default | Purpose                     |
| ------- | ------ | -------- | ------- | --------------------------- |
| `query` | string | yes      | —       | The natural-language query. |
| `limit` | int    | no       | 20      | Max results (1–100).        |

Response is an array of knowledge facts:

```json theme={null}
[
  {
    "id": "...",
    "subject": "testing",
    "content": "User prefers integration tests against real DB, not mocks.",
    "type": "rule",
    "confidence": 0.92,
    "source": "trajectory:...",
    "valid_from": "2026-01-15T...",
    "valid_until": null
  }
]
```

## POST /memory/episodes/search

Same shape as knowledge search. Returns episodes — past events, conversations,
outcomes.

```http theme={null}
POST /memory/episodes/search
{ "query": "what did we ship last week?", "limit": 10 }
```

## POST /memory/social/search

Search the social graph (people, relationships).

```http theme={null}
POST /memory/social/search
{ "query": "who introduced the user to MCP?", "limit": 5 }
```

## GET /memory/soul

Get a summary of the soul.

```json theme={null}
{
  "identity": "...",
  "values": ["..."],
  "patterns": ["..."]
}
```

## GET /memory/soul/full

Same as `/memory/soul` but with all metadata and history. Larger payload.

## GET /memory/export

Export the entire memory as a portable JSON bundle. Useful for backup or
migration to a new Engine instance.

Response is an opaque JSON blob — pass it back to `/memory/import` to
restore.

## POST /memory/import

Import a memory bundle previously produced by `/memory/export`.

```http theme={null}
POST /memory/import
Content-Type: application/json

{
  "bundle": { /* the export payload */ }
}
```

Response indicates success and counts of imported records.

## See also

* [Memory in the architecture overview](../../../internal/architecture/overview#2-memory)
  for how the stores are organized.
* [Build a coding agent](../../guides/build-a-coding-agent) for an example
  of how memory threads back into the agent loop.