Memory: overview¶

Every project grows a memory: a structured, queryable record of the people, places, and things your conversations touch — who works where, what someone is like, when things happened, how everything connects. The agent reads it and writes back what it learns on every turn, so the memory gets sharper with each conversation.

Memory is a product surface of its own, not a chat side-effect. Explore it as an interactive graph, audit every change it has ever made, scrub through its history, correct it — in conversation or over the API — and script it end to end.

What memory holds¶

Entries come in three types — entities (people, organizations; conversation participants appear here), places, and things — and carry:

Name and a short hint (the summary shown in search results)
Characteristics — simple adjectives: curious, direct, old
Relationships to other entries — "mentor of", "employer of" — shown as labeled edges in the graph
Date of origin, a free-form status ("employed", "unemployed"), and the events the entry took part in

Relationships are directed and labeled, at most one from any entry to another, and entries are matched by name and type — the same person mentioned across a hundred conversations is a single entry that accumulates everything learned about them.

Events¶

When a conversation mentions something that happened — "Alice was laid off", "version 6.2 shipped", "the meeting on August 21" — it is recorded as an event:

Immutable. Events are append-only and hash-chained: each event's integrity hash covers the previous one, so tampering is detectable. Events are never modified or deleted.
Open vocabulary. An event has a topic (a meeting, an employment, a release — whatever fits), an optional status, a prose summary, a structured payload, and related entries.
Honest timestamps. Each event distinguishes when it happened (occurred at) from when Autopoetic learned it (recorded at).
Status propagation. Recording an event updates the status of the entries it involves — a layoff event sets the person's status to "unemployed".

How it's built¶

Most of the memory builds itself:

One memory pass per turn — each turn, the agent runs a single pass over the memory before its response is written: it searches for what's relevant, merges in new and changed facts, and commits them. The response is then composed against the already-updated memory, so it only ever describes knowledge that has actually been written back. The "Reading memory…" and "Actively learning…" statuses you see while it streams are this one pass at work.
Catch-up — conversations with Full memory access re-ingest past messages when needed, so nothing is lost to a failed update.
Ask mode — one-off questions answer against the memory read-only: nothing they touch is written back.

The rest is up to you. Each conversation controls its own access with the Project memory setting (Full / Read-only / None) — see chat features — and you can correct or extend the memory directly, in conversation or over the API.

The memory graph¶

Memory Graph (project page → Project Memory) renders the whole memory as an interactive force-directed graph you can pan and zoom:

Nodes are entries (colored by type); edges are labeled relationships.
Semantic neighbors — semantically similar entries appear as neighbors even without an explicit relationship between them.
Incremental loading — the graph starts with the most-connected entries and grows toward wherever you pan. Click a node to load more of its neighborhood.
Search — jump to any entry by name; the camera flies to it.
Strong ties cluster — entries that share many neighbors pull close together.
Deep links — event pages link their related entries straight into a focused graph view.
Ghost nodes — hollow circles mark entries that are referenced but no longer present (deleted or forgotten).

Time travel¶

Every generation of the memory is retained, so its full history is reconstructible. The graph's time slider scrubs through the memory's history generation by generation — see exactly what the memory looked like at any point in its life, then jump back to the present with the Live button. (Historical views show explicit relationships only.)

The changelog¶

Memory Changelog is a complete, paginated history of every change the memory has ever made — each batch of changes with its generation, timestamp, size, and integrity hashes. The detail view renders the before and after side by side, field by field, with word-level diffs: you can audit exactly what a conversation taught the agent.

The events timeline¶

The Events page is the full event log, newest first — topic, status, summary, and when it happened. The detail view shows the structured payload, the related entries (linked straight into the focused graph view), and the hash-chain integrity line.

Forgetting and correction¶

Forget — tell the agent to forget someone or something and the entry is deep-deleted, with every relationship pointing at it cleaned up. The agent also forgets entries it can no longer substantiate, rather than keeping unreliable information.
Edit — correct or extend any entry in conversation or over the API; every change lands in the changelog like any other.
Concurrent-edit safety — every entry carries a generation, and writes built on a stale read are rejected with a conflict instead of silently overwriting someone else's change.
Staged writes — programmatic writes stage first and persist durably on a flush, the same pattern the agent uses at the end of each learning pass.

API and MCP access¶

The memory is fully scriptable — the same operations the agent uses:

The platform API exposes search, read, create, update, and delete entries, relationships, events, graph neighborhoods, batch commits, and flush under /api/v2/customers/{customer_uuid}/projects/{project_uuid}/memory/….
The MCP server exposes the same surface as tools — search, read, upsert, delete, record events, create relationships, flush — for LLM clients and agents.

A project API key is required — see projects and teams for creating keys and the authentication flow.

Security¶

Memory is scoped to its project and encrypted at rest, with per-project keys. The graph, changelog, and events pages are part of project management (admin tier); over the API and MCP, reads are viewer-tier and writes editor-tier. See projects and teams for roles.