memory::bank::create
functionCreate (or idempotently ensure) a named memory bank — an isolated scope of rules and memories, e.g. one per project or persona. Sessions select it via metadata `memory_bank`.
descriptionstring
Human description shown in listings and the console.
namestring*required
Bank name, `[a-z0-9][a-z0-9_-]{0,63}` (it becomes a folder name).
bankobject*required
Summary row for `memory::bank::list` and the console page.
memoriesinteger· uint*requiredmin 0
Live memory (memory) count.
pinnedinteger· uint*requiredmin 0
rulesinteger· uint*requiredmin 0
Rule (always-injected markdown) count.
createdboolean*required
False when the bank already existed (create is idempotent).
memory::bank::delete
functionMove a bank's folder into the store's .trash (recoverable by hand); never destroys data.
trashed_tostring*required
Where the bank folder was moved (under the store's `.trash/`).
memory::bank::list
functionList every memory bank with memory/rule/pin counts.
banksobject[]*required
memoriesinteger· uint*requiredmin 0
Live memory (memory) count.
pinnedinteger· uint*requiredmin 0
rulesinteger· uint*requiredmin 0
Rule (always-injected markdown) count.
Tombstone a memory (sets invalid_at). It leaves recall immediately but stays on disk and readable with include_superseded.
memoryobject*required
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 of*required
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· uint64*requiredmin 0
Milliseconds since epoch.
entitiesstring[]
Entity handles used as an exact-match retrieval signal.
idstring*required
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.
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.
updated_atinteger· uint64*requiredmin 0
End-to-end self-test: data-dir writability, a save→recall→trash roundtrip in a scratch bank, and sibling reachability (router, session-manager). Reports degraded states explicitly instead of a bare process-up health.
okboolean*required
True only when every REQUIRED check passed (sibling reachability is reported but advisory).
Fetch one memory by id, including superseded/tombstoned records.
memoryobject*required
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 of*required
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· uint64*requiredmin 0
Milliseconds since epoch.
entitiesstring[]
Entity handles used as an exact-match retrieval signal.
idstring*required
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.
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.
updated_atinteger· uint64*requiredmin 0
Internal: harness pre-generate hook — injects the session bank's rules into the system prompt and recalled memories as one appended message. Never denies.
generateany of
any of (2)
variant 1
messagesunknown
Transcript messages as assembled so far (schema-free: shapes belong to the router).
metadataunknown
Turn metadata (`harness::send` options.metadata); `memory_bank` here overrides the session-level selection for this turn.
mutationsany of
any of (2)
variant 1
append_messagesunknown[]*required
Page through a bank's memories, newest first. `include_superseded` shows history too.
include_supersededboolean
Include superseded/tombstoned records (the history view).
limitinteger· uintmin 0
Page size, default 50, max 500.
tagstring
Only memories carrying this tag.
memoriesobject[]*required
confidenceone of*required
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· uint64*requiredmin 0
Milliseconds since epoch.
entitiesstring[]
Entity handles used as an exact-match retrieval signal.
idstring*required
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.
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.
updated_atinteger· uint64*requiredmin 0
totalinteger· uint*requiredmin 0
memory::on-config-change
functionInternal: 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.
idstring
Configuration id that changed (advisory; the handler re-fetches).
Internal: session::deleted handler — drops the session's extraction cursor.
Internal: harness turn-completed handler — enqueues one durable extraction job (a single router::complete call) for the finished turn; inline fallback without a queue.
Pin or unpin a memory. Pinned memories rank higher in recall and are untouchable by every automatic path.
memoryobject*required
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 of*required
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· uint64*requiredmin 0
Milliseconds since epoch.
entitiesstring[]
Entity handles used as an exact-match retrieval signal.
idstring*required
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.
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.
updated_atinteger· uint64*requiredmin 0
Full injection dry-run for a hypothetical chat message: the exact system-prompt memory section (rules, budgets, truncation markers), the memories the turn would be handed (post ambient floor and token budget), and the appended message verbatim. Runs the same code as the pre-generate hook.
bankstring
Bank to preview; the configured default when omitted.
querystring*required
The hypothetical user message (what someone would type in chat).
memoriesobject[]*required
Memories the turn would be handed, post ambient floor and token budget, in injection order.
memoryobject*required
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 of*required
How a memory entered the store.
… expand 3 nestedcollapse
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· uint64*requiredmin 0
Milliseconds since epoch.
entitiesstring[]
Entity handles used as an exact-match retrieval signal.
idstring*required
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
… expand 2 nestedcollapse
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.
updated_atinteger· uint64*requiredmin 0
scorenumber· float*required
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.
retrievalstring*required
Retrieval mode that ran (`bm25-entity` or `bm25-entity-semantic`).
rulesinteger· uint*requiredmin 0
Rules included, and whether any were cut by `max_rule_chars`.
rules_truncatedboolean*required
system_prompt_sectionstring*required
The memory section appended to the system prompt (ambient header + rules), exactly as injected — truncation markers included.
Rank a bank's memories against a query (BM25 + entity match + corroboration + recency; no LLM). The same scorer the pre-generate hook uses — call it to preview an injection.
bankstring
Bank to search; the configured default when omitted.
include_supersededboolean
Also rank superseded/tombstoned records (the history view).
limitinteger· uintmin 0
Max memories returned (default: the configured recall_limit).
tagstring
Only rank memories carrying this tag.
memoriesobject[]*required
memoryobject*required
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 of*required
How a memory entered the store.
… expand 3 nestedcollapse
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· uint64*requiredmin 0
Milliseconds since epoch.
entitiesstring[]
Entity handles used as an exact-match retrieval signal.
idstring*required
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
… expand 2 nestedcollapse
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.
updated_atinteger· uint64*requiredmin 0
scorenumber· float*required
retrievalstring*required
Retrieval mode actually used — degradation is explicit, never silent. Currently always `bm25-entity`; a semantic signal joins when the router grows an embeddings surface.
Drop all in-RAM state and reload every bank from disk — the recovery hatch after editing bank files by hand.
banksinteger· uint*requiredmin 0
memory::rule::list
functionList 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.
bankstring
Bank whose rules to list; the configured default when omitted.
rulesobject[]*required
updated_atinteger· uint64*requiredmin 0
Milliseconds since epoch (file mtime).
memory::rule::set
functionCreate or replace one rule (atomic write; empty content removes it). Rules are plain markdown files under the bank's rules/ folder.
bankstring
Bank to write into; the configured default when omitted. Created on first use.
contentstring*required
Markdown content. Empty removes the rule.
namestring*required
Rule name, `[a-z0-9][a-z0-9_-]{0,63}` (it becomes `<name>.md`).
existsboolean*required
False when the empty content removed the rule.
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`.
bankstring
Target bank; the configured default when omitted.
entitiesstring[]
Entity handles (people/projects/tools) used as a retrieval signal.
session_idstring
Provenance session, when saved on behalf of a conversation.
tagsstring[]
Topical labels for filtering within the bank (organization, not ranking).
textstring*required
The memory, one self-contained sentence.
createdboolean*required
False when the text fingerprint matched an existing memory (it was reinforced instead).
memoryobject*required
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 of*required
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· uint64*requiredmin 0
Milliseconds since epoch.
entitiesstring[]
Entity handles used as an exact-match retrieval signal.
idstring*required
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.
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.
updated_atinteger· uint64*requiredmin 0
memory::supersede
functionRetire one memory in favor of another: tombstone with a superseded_by pointer, never a plain delete. The consolidation seam; pinned memories cannot be superseded.
idstring*required
Memory to retire.
superseded_bystring*required
Live memory that replaces it.
memoryobject*required
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 of*required
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· uint64*requiredmin 0
Milliseconds since epoch.
entitiesstring[]
Entity handles used as an exact-match retrieval signal.
idstring*required
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.
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.
updated_atinteger· uint64*requiredmin 0
Distinct tags across a bank's live memories with usage counts, most used first — the filter source for tag-scoped list/recall.
tagsobject[]*required
countinteger· uint*requiredmin 0
Revise a memory's text, entities, or pin flag in place (same id, bumped revision; the prior revision stays in the on-disk log).
tagsstring[]
Replace the tag set (empty list clears).
memoryobject*required
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 of*required
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· uint64*requiredmin 0
Milliseconds since epoch.
entitiesstring[]
Entity handles used as an exact-match retrieval signal.
idstring*required
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.
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.
updated_atinteger· uint64*requiredmin 0
