memory::bank::create
functionCreate 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`.
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
functionDelete a memory bank: the folder moves to the store's .trash, recoverable by hand.
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.
Delete a memory (tombstone: sets invalid_at). It leaves recall immediately but stays on disk, 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
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.
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
List a bank's memories page by page, 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
Preview the memory injection 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 pre-generate hook's own code.
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.
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.
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
List the 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
memory::ui-content
functionServe the memory worker's injected console UI assets (content function for its console:script / console:style triggers).
pathstring*required
The asset path from the trigger config (e.g. `state/page.js`).
contentstring*required
The asset source, verbatim.
content_typestring*required
MIME type the console should serve the asset with.
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
