memory

v0.2.18

Durable cross-session agent memory — named banks of always-injected markdown rules and auto-extracted memories, hybrid BM25 + entity recall, pinning, and supersede-never-delete history. Plain files on disk; every operation is a traced function.

license: Apache-2.0Published 6h agoagent bm25 context memory rag recall

Install

bash

iii trigger compose::add worker=memory

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Functions23

memory::bank::create

Function

Create a named memory bank: an isolated scope of rules and memories, e.g. one per project or persona. Idempotent; sessions select it via metadata `memory_bank`.

Request

descriptionstring
Human description shown in listings and the console.
namestringrequired
Bank name, `[a-z0-9][a-z0-9_-]{0,63}` (it becomes a folder name).

Response

bankobjectrequired
Summary row for `memory::bank::list` and the console page.
- descriptionstring
- memoriesinteger· uintrequiredmin 0
  Live memory (memory) count.
- namestringrequired
- pinnedinteger· uintrequiredmin 0
- rulesinteger· uintrequiredmin 0
  Rule (always-injected markdown) count.
createdbooleanrequired
False when the bank already existed (create is idempotent).

memory::bank::delete

Function

Delete a memory bank: the folder moves to the store's .trash, recoverable by hand.

Request

namestringrequired

Response

okbooleanrequired
trashed_tostringrequired
Where the bank folder was moved (under the store's `.trash/`).

memory::bank::list

Function

List every memory bank with memory/rule/pin counts.

Request

Empty object

Response

banksobject[]required
- descriptionstring
- memoriesinteger· uintrequiredmin 0
  Live memory (memory) count.
- namestringrequired
- pinnedinteger· uintrequiredmin 0
- rulesinteger· uintrequiredmin 0
  Rule (always-injected markdown) count.

memory::delete

Function

Delete a memory (tombstone: sets invalid_at). It leaves recall immediately but stays on disk, readable with include_superseded.

Request

bankstring
Bank; omitted: the calling session's bank, else the configured default.
idstringrequired

Response

memoryobjectrequired
One memory item. Serialized whole as a `memories.jsonl` line; replay is last-wins by `id`, so an update appends a full record with a bumped `revision` and a delete appends a tombstoned record (`invalid_at` set) — history is never destroyed, only superseded.
- confidenceone ofrequired
  How a memory entered the store.
  one of (3)
  Variant 1
  valuestringenum extracted
  Variant 2
  valuestringenum inferred
  Variant 3
  valuestringenum stated
- corroborationinteger· uint32min 0
  Times this memory was independently re-observed. Boosts recall rank.
- created_atinteger· uint64requiredmin 0
  Milliseconds since epoch.
- entitiesstring[]
  Entity handles used as an exact-match retrieval signal.
- idstringrequired
  Content fingerprint (`fp` + FNV-1a of the normalized text), so re-ingesting the same source reinforces instead of duplicating.
- invalid_atinteger· uint64min 0
  Set when the memory stopped being true (superseded or deleted). The record stays on disk and remains queryable with `include_superseded: true`.
- pinnedboolean
  Pinned memories are never touched by any automatic path (consolidation, decay); only an explicit `memory::pin`/`memory::update` changes them.
- revisioninteger· uint64min 0
  Bumped on every appended revision of this id; replay keeps the highest.
- sourceany of
  any of (2)
  Variant 1
  agentstring
  entry_idstring
  session_idstring
  Variant 2
  valuenull
- stated_atinteger· uint64min 0
  When the fact was last STATED (created, re-observed, text edited). Unlike `updated_at`, pin/tag/entity edits never bump it, so consolidation can order "which statement is current" by it. Legacy records load as None.
- superseded_bystring
  Memory id that replaced this one, when superseded by content.
- tagsstring[]
  Topical labels for filtering WITHIN a bank ("iii", "workers", "billing") — organization, not ranking. Normalized lowercase, capped like entities. Old records without the field load as untagged.
- textstringrequired
- updated_atinteger· uint64requiredmin 0

memory::doctor

Function

Self-test memory end to end: data-dir writability, a scratch-bank write/read/trash roundtrip, and sibling reachability (router, session-manager). Reports degraded states explicitly, not a bare process-up health.

Request

Empty object

Response

checksobject[]required
- detailstringrequired
- namestringrequired
- okbooleanrequired
okbooleanrequired
True only when every REQUIRED check passed (sibling reachability is reported but advisory).

memory::extract-job

Function

Internal: queue-delivered extraction job — errors propagate so the queue retries and dead-letters instead of losing the pass.

Request

bankstring
The bank the turn was injected with. Absent: resolved when the job runs (the worker never saw the turn, or the job predates this).
session_idstringrequired
skipboolean
The turn ran without memory (an invalid or deleted bank): the job only steps the cursor past it.
untilstring
The turn's last user/assistant entry: the pass reads no further.

Response

okbooleanrequired

memory::get

Function

Fetch one memory by id, including superseded/tombstoned records.

Request

bankstring
Bank; omitted: the calling session's bank, else the configured default.
idstringrequired

Response

memoryobjectrequired
One memory item. Serialized whole as a `memories.jsonl` line; replay is last-wins by `id`, so an update appends a full record with a bumped `revision` and a delete appends a tombstoned record (`invalid_at` set) — history is never destroyed, only superseded.
- confidenceone ofrequired
  How a memory entered the store.
  one of (3)
  Variant 1
  valuestringenum extracted
  Variant 2
  valuestringenum inferred
  Variant 3
  valuestringenum stated
- corroborationinteger· uint32min 0
  Times this memory was independently re-observed. Boosts recall rank.
- created_atinteger· uint64requiredmin 0
  Milliseconds since epoch.
- entitiesstring[]
  Entity handles used as an exact-match retrieval signal.
- idstringrequired
  Content fingerprint (`fp` + FNV-1a of the normalized text), so re-ingesting the same source reinforces instead of duplicating.
- invalid_atinteger· uint64min 0
  Set when the memory stopped being true (superseded or deleted). The record stays on disk and remains queryable with `include_superseded: true`.
- pinnedboolean
  Pinned memories are never touched by any automatic path (consolidation, decay); only an explicit `memory::pin`/`memory::update` changes them.
- revisioninteger· uint64min 0
  Bumped on every appended revision of this id; replay keeps the highest.
- sourceany of
  any of (2)
  Variant 1
  agentstring
  entry_idstring
  session_idstring
  Variant 2
  valuenull
- stated_atinteger· uint64min 0
  When the fact was last STATED (created, re-observed, text edited). Unlike `updated_at`, pin/tag/entity edits never bump it, so consolidation can order "which statement is current" by it. Legacy records load as None.
- superseded_bystring
  Memory id that replaced this one, when superseded by content.
- tagsstring[]
  Topical labels for filtering WITHIN a bank ("iii", "workers", "billing") — organization, not ranking. Normalized lowercase, capped like entities. Old records without the field load as untagged.
- textstringrequired
- updated_atinteger· uint64requiredmin 0

memory::hook::pre-generate

Function

Internal: harness pre-generate hook — injects the session bank's rules into the system prompt and recalled memories as one appended message. Never denies.

Request

generateany of
any of (2)
Variant 1
messagesunknown
Transcript messages as assembled so far — the window this step sends, persisted notices (earlier rules updates included) replayed in place (schema-free: shapes belong to the router).
system_promptstring
Variant 2
valuenull
metadataunknown
Turn metadata (`harness::send` options.metadata); `memory_bank` here overrides the session-level selection for this turn.
session_idstring
stepinteger· uint64min 0
Step within the turn; 0 is the step that opens it.
turn_idstring
The turn this step belongs to; its bank is recorded under it.

Response

annotationsobject
decisionstringrequired
mutationsany of
any of (2)
Variant 1
append_messagesunknown[]required
system_promptstring
Variant 2
valuenull

memory::list

Function

List a bank's memories page by page, newest first. `include_superseded` shows history too.

Request

bankstring
Bank; omitted: the calling session's bank, else the configured default.
include_supersededboolean
Include superseded/tombstoned records (the history view).
limitinteger· uintmin 0
Page size, default 50, max 500.
offsetinteger· uintmin 0
tagstring
Only memories carrying this tag.

Response

memoriesobject[]required
- confidenceone ofrequired
  How a memory entered the store.
  one of (3)
  Variant 1
  valuestringenum extracted
  Variant 2
  valuestringenum inferred
  Variant 3
  valuestringenum stated
- corroborationinteger· uint32min 0
  Times this memory was independently re-observed. Boosts recall rank.
- created_atinteger· uint64requiredmin 0
  Milliseconds since epoch.
- entitiesstring[]
  Entity handles used as an exact-match retrieval signal.
- idstringrequired
  Content fingerprint (`fp` + FNV-1a of the normalized text), so re-ingesting the same source reinforces instead of duplicating.
- invalid_atinteger· uint64min 0
  Set when the memory stopped being true (superseded or deleted). The record stays on disk and remains queryable with `include_superseded: true`.
- pinnedboolean
  Pinned memories are never touched by any automatic path (consolidation, decay); only an explicit `memory::pin`/`memory::update` changes them.
- revisioninteger· uint64min 0
  Bumped on every appended revision of this id; replay keeps the highest.
- sourceany of
  any of (2)
  Variant 1
  agentstring
  entry_idstring
  session_idstring
  Variant 2
  valuenull
- stated_atinteger· uint64min 0
  When the fact was last STATED (created, re-observed, text edited). Unlike `updated_at`, pin/tag/entity edits never bump it, so consolidation can order "which statement is current" by it. Legacy records load as None.
- superseded_bystring
  Memory id that replaced this one, when superseded by content.
- tagsstring[]
  Topical labels for filtering WITHIN a bank ("iii", "workers", "billing") — organization, not ranking. Normalized lowercase, capped like entities. Old records without the field load as untagged.
- textstringrequired
- updated_atinteger· uint64requiredmin 0
totalinteger· uintrequiredmin 0

memory::on-config-change

Function

Internal: hot-reload memory from the authoritative configuration when it changes — reopens the store on a data_dir change and swaps the per-call tuning snapshot otherwise.

Request

idstring
Configuration id that changed (advisory; the handler re-fetches).

Response

okbooleanrequired

memory::on-session-deleted

Function

Internal: session::deleted handler — drops the session's extraction cursor.

Request

session_idstring

Response

okbooleanrequired

memory::on-turn-completed

Function

Internal: harness turn-completed handler — enqueues one durable extraction job (a single router::complete call) for the finished turn; inline fallback without a queue.

Request

parentunknown
Set on a sub-agent's turn (its live parent link).
parent_session_idstring
Set on a parentless spawn's turn (its display parent).
session_idstring
turn_idstring

Response

okbooleanrequired

memory::pin

Function

Pin or unpin a memory. Pinned memories rank higher in recall and are untouchable by every automatic path.

Request

bankstring
Bank; omitted: the calling session's bank, else the configured default.
idstringrequired
pinnedbooleanrequired

Response

memoryobjectrequired
One memory item. Serialized whole as a `memories.jsonl` line; replay is last-wins by `id`, so an update appends a full record with a bumped `revision` and a delete appends a tombstoned record (`invalid_at` set) — history is never destroyed, only superseded.
- confidenceone ofrequired
  How a memory entered the store.
  one of (3)
  Variant 1
  valuestringenum extracted
  Variant 2
  valuestringenum inferred
  Variant 3
  valuestringenum stated
- corroborationinteger· uint32min 0
  Times this memory was independently re-observed. Boosts recall rank.
- created_atinteger· uint64requiredmin 0
  Milliseconds since epoch.
- entitiesstring[]
  Entity handles used as an exact-match retrieval signal.
- idstringrequired
  Content fingerprint (`fp` + FNV-1a of the normalized text), so re-ingesting the same source reinforces instead of duplicating.
- invalid_atinteger· uint64min 0
  Set when the memory stopped being true (superseded or deleted). The record stays on disk and remains queryable with `include_superseded: true`.
- pinnedboolean
  Pinned memories are never touched by any automatic path (consolidation, decay); only an explicit `memory::pin`/`memory::update` changes them.
- revisioninteger· uint64min 0
  Bumped on every appended revision of this id; replay keeps the highest.
- sourceany of
  any of (2)
  Variant 1
  agentstring
  entry_idstring
  session_idstring
  Variant 2
  valuenull
- stated_atinteger· uint64min 0
  When the fact was last STATED (created, re-observed, text edited). Unlike `updated_at`, pin/tag/entity edits never bump it, so consolidation can order "which statement is current" by it. Legacy records load as None.
- superseded_bystring
  Memory id that replaced this one, when superseded by content.
- tagsstring[]
  Topical labels for filtering WITHIN a bank ("iii", "workers", "billing") — organization, not ranking. Normalized lowercase, capped like entities. Old records without the field load as untagged.
- textstringrequired
- updated_atinteger· uint64requiredmin 0

memory::preview

Function

Preview the memory injection for a hypothetical chat message: the exact system-prompt memory section a new session gets (rules, budgets, truncation markers; running sessions receive changes as an appended update), the memories the turn would be handed (post ambient floor and token budget), and the appended message verbatim. Runs the pre-generate hook's own code.

Request

bankstring
Bank to preview; omitted: the calling session's bank, else the configured default.
querystringrequired
The hypothetical user message (what someone would type in chat).

Response

bankstringrequired
memoriesobject[]required
Memories the turn would be handed, post ambient floor and token budget, in injection order.
- memoryobjectrequired
  One memory item. Serialized whole as a `memories.jsonl` line; replay is last-wins by `id`, so an update appends a full record with a bumped `revision` and a delete appends a tombstoned record (`invalid_at` set) — history is never destroyed, only superseded.
  confidenceone ofrequired
  How a memory entered the store.
  Show 3 nestedHide nested
  one of (3)
  Variant 1
  valuestringenum extracted
  Variant 2
  valuestringenum inferred
  Variant 3
  valuestringenum stated
  corroborationinteger· uint32min 0
  Times this memory was independently re-observed. Boosts recall rank.
  created_atinteger· uint64requiredmin 0
  Milliseconds since epoch.
  entitiesstring[]
  Entity handles used as an exact-match retrieval signal.
  idstringrequired
  Content fingerprint (`fp` + FNV-1a of the normalized text), so re-ingesting the same source reinforces instead of duplicating.
  invalid_atinteger· uint64min 0
  Set when the memory stopped being true (superseded or deleted). The record stays on disk and remains queryable with `include_superseded: true`.
  pinnedboolean
  Pinned memories are never touched by any automatic path (consolidation, decay); only an explicit `memory::pin`/`memory::update` changes them.
  revisioninteger· uint64min 0
  Bumped on every appended revision of this id; replay keeps the highest.
  sourceany of
  Show 2 nestedHide nested
  any of (2)
  Variant 1
  agentstring
  entry_idstring
  session_idstring
  Variant 2
  valuenull
  stated_atinteger· uint64min 0
  When the fact was last STATED (created, re-observed, text edited). Unlike `updated_at`, pin/tag/entity edits never bump it, so consolidation can order "which statement is current" by it. Legacy records load as None.
  superseded_bystring
  Memory id that replaced this one, when superseded by content.
  tagsstring[]
  Topical labels for filtering WITHIN a bank ("iii", "workers", "billing") — organization, not ranking. Normalized lowercase, capped like entities. Old records without the field load as untagged.
  textstringrequired
  updated_atinteger· uint64requiredmin 0
- scorenumber· floatrequired
  Recall score; 0.0 for memories added by the ambient floor.
messagestring
The appended `<memory>` message body, verbatim; absent when no memory fits the budget.
retrievalstringrequired
Retrieval mode that ran (`bm25-entity` or `bm25-entity-semantic`; `none` when memories are not injected).
rulesinteger· uintrequiredmin 0
Rules included, and whether any were cut by `max_rule_chars`.
rules_truncatedbooleanrequired
system_prompt_sectionstringrequired
The memory section appended to the system prompt (ambient header + rules), exactly as injected — truncation markers included.

memory::recall

Function

Search a bank's memories relevant to a query (BM25 + entities + corroboration + recency; no LLM). The same scorer the pre-generate hook uses — call it to preview an injection. mode lexical/semantic returns one raw arm (plain BM25, or cosine).

Request

bankstring
Bank to search; omitted: the calling session's bank, else the configured default.
include_supersededboolean
Also rank superseded/tombstoned records (the history view).
limitinteger· uintmin 0
Max memories returned (default: the configured recall_limit).
modeall of
`hybrid` (default) is the fused scorer the hook uses. `lexical` and `semantic` return ONE raw arm (plain BM25, or cosine as the score) for callers that fuse arms themselves — consolidation interleaves both so a near-duplicate is never buried by the fused rank.
all of (1)
Variant 1
valuestringenum hybrid, lexical, semantic
querystringrequired
tagstring
Only rank memories carrying this tag.

Response

bankstringrequired
memoriesobject[]required
- memoryobjectrequired
  One memory item. Serialized whole as a `memories.jsonl` line; replay is last-wins by `id`, so an update appends a full record with a bumped `revision` and a delete appends a tombstoned record (`invalid_at` set) — history is never destroyed, only superseded.
  confidenceone ofrequired
  How a memory entered the store.
  Show 3 nestedHide nested
  one of (3)
  Variant 1
  valuestringenum extracted
  Variant 2
  valuestringenum inferred
  Variant 3
  valuestringenum stated
  corroborationinteger· uint32min 0
  Times this memory was independently re-observed. Boosts recall rank.
  created_atinteger· uint64requiredmin 0
  Milliseconds since epoch.
  entitiesstring[]
  Entity handles used as an exact-match retrieval signal.
  idstringrequired
  Content fingerprint (`fp` + FNV-1a of the normalized text), so re-ingesting the same source reinforces instead of duplicating.
  invalid_atinteger· uint64min 0
  Set when the memory stopped being true (superseded or deleted). The record stays on disk and remains queryable with `include_superseded: true`.
  pinnedboolean
  Pinned memories are never touched by any automatic path (consolidation, decay); only an explicit `memory::pin`/`memory::update` changes them.
  revisioninteger· uint64min 0
  Bumped on every appended revision of this id; replay keeps the highest.
  sourceany of
  Show 2 nestedHide nested
  any of (2)
  Variant 1
  agentstring
  entry_idstring
  session_idstring
  Variant 2
  valuenull
  stated_atinteger· uint64min 0
  When the fact was last STATED (created, re-observed, text edited). Unlike `updated_at`, pin/tag/entity edits never bump it, so consolidation can order "which statement is current" by it. Legacy records load as None.
  superseded_bystring
  Memory id that replaced this one, when superseded by content.
  tagsstring[]
  Topical labels for filtering WITHIN a bank ("iii", "workers", "billing") — organization, not ranking. Normalized lowercase, capped like entities. Old records without the field load as untagged.
  textstringrequired
  updated_atinteger· uint64requiredmin 0
- scorenumber· floatrequired
retrievalstringrequired
Retrieval mode actually used — degradation is explicit, never silent. `hybrid`: `bm25-entity`, or `bm25-entity-semantic` when the query was embedded through `router::embed`. `lexical`: `lexical`. `semantic`: `semantic`, or `semantic-unavailable` (empty result — NOT "no matches") when the query could not be embedded.

memory::reload

Function

Drop all in-RAM state and reload every bank from disk — the recovery hatch after editing bank files by hand.

Request

Empty object

Response

banksinteger· uintrequiredmin 0
okbooleanrequired

memory::rule::list

Function

List a bank's rules (markdown, injected whole into the system prompt on every turn). Stored as plain files under the bank's rules/ folder; editing them by hand is equivalent.

Request

bankstring
Bank whose rules to list; omitted: the calling session's bank, else the configured default.

Response

bankstringrequired
rulesobject[]required
- contentstringrequired
- namestringrequired
- updated_atinteger· uint64requiredmin 0
  Milliseconds since epoch (file mtime).

memory::rule::set

Function

Create or replace one rule (atomic write; empty content removes it). Rules are plain markdown files under the bank's rules/ folder.

Request

bankstring
Bank to write into; omitted: the calling session's bank, else the configured default. Created on first use.
contentstringrequired
Markdown content. Empty removes the rule.
namestringrequired
Rule name, `[a-z0-9][a-z0-9_-]{0,63}` (it becomes `<name>.md`).

Response

existsbooleanrequired
False when the empty content removed the rule.
okbooleanrequired

memory::save

Function

Save one memory explicitly. Content-fingerprinted: re-saving the same text reinforces the existing memory instead of duplicating it. Use when the user says `remember this`.

Request

bankstring
Target bank; omitted: the calling session's bank, else the configured default.
entitiesstring[]
Entity handles (people/projects/tools) used as a retrieval signal.
pinnedboolean
session_idstring
Provenance session, when saved on behalf of a conversation.
tagsstring[]
Topical labels for filtering within the bank (organization, not ranking).
textstringrequired
The memory, one self-contained sentence.

Response

createdbooleanrequired
False when the text fingerprint matched an existing memory (it was reinforced instead).
memoryobjectrequired
One memory item. Serialized whole as a `memories.jsonl` line; replay is last-wins by `id`, so an update appends a full record with a bumped `revision` and a delete appends a tombstoned record (`invalid_at` set) — history is never destroyed, only superseded.
- confidenceone ofrequired
  How a memory entered the store.
  one of (3)
  Variant 1
  valuestringenum extracted
  Variant 2
  valuestringenum inferred
  Variant 3
  valuestringenum stated
- corroborationinteger· uint32min 0
  Times this memory was independently re-observed. Boosts recall rank.
- created_atinteger· uint64requiredmin 0
  Milliseconds since epoch.
- entitiesstring[]
  Entity handles used as an exact-match retrieval signal.
- idstringrequired
  Content fingerprint (`fp` + FNV-1a of the normalized text), so re-ingesting the same source reinforces instead of duplicating.
- invalid_atinteger· uint64min 0
  Set when the memory stopped being true (superseded or deleted). The record stays on disk and remains queryable with `include_superseded: true`.
- pinnedboolean
  Pinned memories are never touched by any automatic path (consolidation, decay); only an explicit `memory::pin`/`memory::update` changes them.
- revisioninteger· uint64min 0
  Bumped on every appended revision of this id; replay keeps the highest.
- sourceany of
  any of (2)
  Variant 1
  agentstring
  entry_idstring
  session_idstring
  Variant 2
  valuenull
- stated_atinteger· uint64min 0
  When the fact was last STATED (created, re-observed, text edited). Unlike `updated_at`, pin/tag/entity edits never bump it, so consolidation can order "which statement is current" by it. Legacy records load as None.
- superseded_bystring
  Memory id that replaced this one, when superseded by content.
- tagsstring[]
  Topical labels for filtering WITHIN a bank ("iii", "workers", "billing") — organization, not ranking. Normalized lowercase, capped like entities. Old records without the field load as untagged.
- textstringrequired
- updated_atinteger· uint64requiredmin 0

memory::supersede

Function

Retire one memory in favor of another: tombstone with a superseded_by pointer, never a plain delete. The consolidation seam; pinned memories cannot be superseded. reinforce makes it a merge (the non-pinned survivor absorbs the retired record's observations); reason is carried on the item-changed events.

Request

bankstring
Bank; omitted: the calling session's bank, else the configured default.
idstringrequired
Memory to retire.
reasonstring
Why — carried on the `memory::item-changed` events this call emits (not persisted on the record). Trimmed, capped at 500 chars.
reinforceboolean
Merge semantics: the survivor absorbs the retired record's observations (corroboration += retired + 1) in the same call. A pinned survivor is never written. Default false (a state change: the new record replaces the old, nothing to absorb).
superseded_bystringrequired
Live memory that replaces it.

Response

memoryall ofrequired
The retired record.
all of (1)
Variant 1
confidenceone ofrequired
How a memory entered the store.
Show 3 nestedHide nested
one of (3)
Variant 1
valuestringenum extracted
Variant 2
valuestringenum inferred
Variant 3
valuestringenum stated
corroborationinteger· uint32min 0
Times this memory was independently re-observed. Boosts recall rank.
created_atinteger· uint64requiredmin 0
Milliseconds since epoch.
entitiesstring[]
Entity handles used as an exact-match retrieval signal.
idstringrequired
Content fingerprint (`fp` + FNV-1a of the normalized text), so re-ingesting the same source reinforces instead of duplicating.
invalid_atinteger· uint64min 0
Set when the memory stopped being true (superseded or deleted). The record stays on disk and remains queryable with `include_superseded: true`.
pinnedboolean
Pinned memories are never touched by any automatic path (consolidation, decay); only an explicit `memory::pin`/`memory::update` changes them.
revisioninteger· uint64min 0
Bumped on every appended revision of this id; replay keeps the highest.
sourceany of
Show 2 nestedHide nested
any of (2)
Variant 1
agentstring
entry_idstring
session_idstring
Variant 2
valuenull
stated_atinteger· uint64min 0
When the fact was last STATED (created, re-observed, text edited). Unlike `updated_at`, pin/tag/entity edits never bump it, so consolidation can order "which statement is current" by it. Legacy records load as None.
superseded_bystring
Memory id that replaced this one, when superseded by content.
tagsstring[]
Topical labels for filtering WITHIN a bank ("iii", "workers", "billing") — organization, not ranking. Normalized lowercase, capped like entities. Old records without the field load as untagged.
textstringrequired
updated_atinteger· uint64requiredmin 0
reinforcedbooleanrequired
True when the survivor was reinforced (`reinforce` asked and the survivor is not pinned).

memory::tags

Function

List the tags across a bank's live memories with usage counts, most used first — the filter source for tag-scoped list/recall.

Request

bankstring
Bank; omitted: the calling session's bank, else the configured default.

Response

bankstringrequired
tagsobject[]required
- countinteger· uintrequiredmin 0
- tagstringrequired

memory::ui-content

Function

Serve the memory worker's injected console UI assets (content function for its console:script / console:style / console:module triggers).

Request

pathstringrequired
The asset path from the trigger config (e.g. `state/page.js`).

Response

contentstringrequired
The asset source, verbatim.
content_typestringrequired
MIME type the console should serve the asset with.

memory::update

Function

Revise a memory's text, entities, or pin flag in place (same id, bumped revision; the prior revision stays in the on-disk log).

Request

bankstring
Bank; omitted: the calling session's bank, else the configured default.
entitiesstring[]
idstringrequired
pinnedboolean
tagsstring[]
Replace the tag set (empty list clears).
textstring

Response

memoryobjectrequired
One memory item. Serialized whole as a `memories.jsonl` line; replay is last-wins by `id`, so an update appends a full record with a bumped `revision` and a delete appends a tombstoned record (`invalid_at` set) — history is never destroyed, only superseded.
- confidenceone ofrequired
  How a memory entered the store.
  one of (3)
  Variant 1
  valuestringenum extracted
  Variant 2
  valuestringenum inferred
  Variant 3
  valuestringenum stated
- corroborationinteger· uint32min 0
  Times this memory was independently re-observed. Boosts recall rank.
- created_atinteger· uint64requiredmin 0
  Milliseconds since epoch.
- entitiesstring[]
  Entity handles used as an exact-match retrieval signal.
- idstringrequired
  Content fingerprint (`fp` + FNV-1a of the normalized text), so re-ingesting the same source reinforces instead of duplicating.
- invalid_atinteger· uint64min 0
  Set when the memory stopped being true (superseded or deleted). The record stays on disk and remains queryable with `include_superseded: true`.
- pinnedboolean
  Pinned memories are never touched by any automatic path (consolidation, decay); only an explicit `memory::pin`/`memory::update` changes them.
- revisioninteger· uint64min 0
  Bumped on every appended revision of this id; replay keeps the highest.
- sourceany of
  any of (2)
  Variant 1
  agentstring
  entry_idstring
  session_idstring
  Variant 2
  valuenull
- stated_atinteger· uint64min 0
  When the fact was last STATED (created, re-observed, text edited). Unlike `updated_at`, pin/tag/entity edits never bump it, so consolidation can order "which statement is current" by it. Legacy records load as None.
- superseded_bystring
  Memory id that replaced this one, when superseded by content.
- tagsstring[]
  Topical labels for filtering WITHIN a bank ("iii", "workers", "billing") — organization, not ranking. Normalized lowercase, capped like entities. Old records without the field load as untagged.
- textstringrequired
- updated_atinteger· uint64requiredmin 0

Triggers2

memory::bank-changed

Trigger

A memory bank was created or trashed. Payload: { event_type, bank }.

Invocation

bankstring
Only deliver events for this bank.

Return

valueunknown

memory::item-changed

Trigger

A memory was created, updated, superseded, or deleted in a memory bank. Payload: { event_type, bank, memory, reason? } (reason on consolidation changes, and `redacted: <labels>` when secrets were redacted on save/update). Bind console/live views here.

Invocation

bankstring
Only deliver events for this bank.

Return

valueunknown

Install

Functions23

Triggers2

Search the registry