remember
Persist agent memories with tags, importance, source, and type. Supports supersession keys to retire obsolete values and lineage tracking for erasure compliance.
Instructions
Store a memory (append-only; raw text is never edited afterward). tags group memories into
cohorts; value (>=1) is its importance — higher-value memories outrank merely-similar ones at
recall. Recall does NOT change it: a read leaves value, last_access and the state digest as they were,
so an anchor or witness pinned to the store stays valid across reads. credit is what moves a
memory's standing after an outcome. mtype ∈ {episodic, semantic, procedural} sets the
decay prior — episodic (events) fades fast, semantic (durable facts) slow, procedural (rules /
preferences) barely; pass it when you know the kind, else it's inferred.
Optional key is a deterministic (subject, relation) supersession key (e.g. "billing-api::auth-method"):
storing a new value with the same key retires the old one so recall never returns the stale value — no
similarity threshold, no extra LLM call. Use it for facts that get updated (config, prices, versions,
status). Pass object = the asserted VALUE (e.g. "frankfurt") alongside key: with the echo guard on
(default here), a later RE-STATEMENT of an already-retired value cannot resurrect it (a corrected fact
stays corrected even if the old value is said again). Without object the guard still catches a verbatim
restatement (text hash), but a reworded one needs the value in object to be caught. Set reaffirm=True
to intentionally revert to a previously-retired value (an explicit change-of-mind, not an echo).
source — WHO OR WHAT this came from ("crm/alice", "user-42", "docs.example.com/pricing"). Pass it
whenever the memory is about, or came from, an identifiable person or system. It is what makes the
memory reachable later by SUBJECT rather than only by id: forget_subject("crm/alice") erases a
person's data and everything derived from it, erasure_audit can then say whether anything survived,
and slash can forfeit a source's standing after a bad outcome. Without it a record is attributable
to nothing, and none of those can reach it -- measured: a store written through this server answered
would_erase=0 to every right-to-erasure request, while the same write with a source answered 1.
derived_from — the ids this memory was BUILT FROM (a summary, a merge, a conclusion drawn from
earlier notes). Provenance rides along the edge: erasing the source erases what was derived from it,
so a summary of a person's file goes when their file goes. erasure_audit walks these edges and
reports unaudited -- never a pass -- when nothing declares them, because a store with no edges to
walk has not been checked, it has been left uninspected.
If this server was started with a PROJECT scope (--project <name> / INSPEXIMUS_PROJECT), the memory is
stamped with it and later recalls in OTHER projects will not return it. The active scope is echoed back
as project in the result (null = unscoped, shared by every project).
Returns the new id, and the VERDICT on the write: blocked is true when a keyed write was retired
on arrival (policy names the guard, current_id the value that stands, note what to do);
lineage_dropped is the anchor count of the value this write followed when this write carries
no derived_from; persisted is false when the save after the write failed (persist_error
says why; the server retries on its next write). A result with blocked: true or
persisted: false is not a landed write.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | ||
| tags | No | ||
| text | Yes | ||
| mtype | No | ||
| value | No | ||
| object | No | ||
| source | No | ||
| user_id | No | ||
| agent_id | No | ||
| reaffirm | No | ||
| session_id | No | ||
| derived_from | No |