Build

Agent memory

Agent memory is a private store of durable facts an agent keeps across runs and sessions. Each agent owns one store. It is a first-class store with a fixed, typed shape — not a generic table the agent happens to write to — so memory can carry its own mechanics (typed kinds, importance, pinning) without bending the tables engine.

An agent reaches its own memory through three intrinsic tools that Mobius injects automatically; you do not grant them. The store is also observable and editable out of band, through the API and the agent's Memory tab, so an operator can read, correct, or seed what an agent knows.

Entries

A memory entry is addressed by a key — a path-safe string such as user.timezone or repo.deploy-branch. Writing to a key that already exists replaces the entry in place and bumps its version; a new key is a new memory.

Field	Meaning
`key`	Stable identifier the agent reuses to update a memory.
`content`	The remembered text.
`kind`	One of `fact`, `preference`, `episode`, `summary`.
`importance`	`0`–`100`; higher entries are preferred when memory is compacted.
`pinned`	Exempts the entry from compaction regardless of importance.
`metadata`	A small structured sidecar (provenance, tags).

Kinds

fact — durable factual knowledge ("prod runs in us-east-1").
preference — a stable preference ("the user prefers terse replies").
episode — a record of something that happened; episodes are the first candidates for summarization.
summary — a compacted summary distilled from other entries.

How an agent uses memory

The mobius.memory.* tools are injected into every agent turn. The agent is guided to:

Recall at the start of a task, before assuming it knows nothing: mobius.memory.recall (optionally with a query).
Remember whenever it learns something durable: mobius.memory.remember with a key and content.
Forget something no longer true: mobius.memory.forget with its key.

mobius.memory.remember {"key": "user.timezone", "content": "America/New_York", "kind": "preference"}

Recall returns the most recently updated entries first and accepts an optional keyword query over keys and content and an optional kind filter.

Observe and edit from the API

The store is provisioned on first write. Editing an entry here is equivalent to the agent calling mobius.memory.remember.

GET    /v1/projects/{project}/agents/{agent}/memory
GET    /v1/projects/{project}/agents/{agent}/memory/entries?query={q}&kind={kind}
PUT    /v1/projects/{project}/agents/{agent}/memory/entries/{memory_key}
DELETE /v1/projects/{project}/agents/{agent}/memory/entries/{memory_key}

GET .../memory returns a summary (total entry count and counts by kind); GET .../memory/entries lists and searches entries with cursor pagination. The agent's Memory tab in the app is the same surface: search, edit, pin, and delete entries, and watch them change as the agent works.

Memory or tables?

Both store structured data an agent can rely on, but they answer different questions:

Use agent memory	Use a table
What this one agent privately remembers.	Data shared across agents, steps, or people.
Free-form keyed notes the agent manages itself.	Rows with a schema you define and query.
Recall woven into every turn by default.	Explicit grants and table tools.

Reach for memory first when the data belongs to a single agent. Reach for a table when the data is intentionally shared or needs a queryable schema.

Agents define the agent identity and tools.
Tables hold shared, schema-backed structured data.
Agent sessions are the durable conversations where recall and remember happen.