🧠 Agent Memory

Memory is the mem0-style high-level surface over the governed /memory/* verbs (ADR-144). Every belief is bi-temporal, provenance-tracked, and governable.

mem = Memory("http://localhost:9090",
             purpose="agent-notes",
             bearer_token="perftoken",
             session_id="shadow-ledger")

add — store a belief

mid1 = mem.add("Alice Chen authorized $2.3M wire to Pacific Trust account 7742 on Jan 15.",
               confidence=0.95, memory_class="episodic")
mid2 = mem.add("Bob Smith directs ShellCo Ltd, received $850K from the offshore account.")
mid3 = mem.add("Carla Nunez blew the whistle — four fraudulent transfers, $2.8M total.")
mid4 = mem.add("Classic laundering: placement → layering → integration.",
               memory_class="procedural")
# mid1 = "019fe254-3647-77fc-..."

One call stored a bi-temporal row (valid_from/valid_to + system_from/system_to), linked it to the session, scored it with confidence, and hash-chained it to the provenance graph. No extra tables, no vector store setup.

add_batch — high-throughput write

ids = mem.add_batch([
    "The wire transfer matches a known fraud pattern: rapid offshore movement.",
    {"content": "Customer #1234 has no prior history with this beneficiary.",
     "confidence": 0.8, "memory_class": "semantic"},
    "Beneficiary account opened 2 days before the transfer request.",
])
# ids = ["019fe255-...", "019fe256-...", "019fe257-..."]

search — recall ranked by relevance × recency × confidence

hits = mem.search("How much money was transferred?", top_k=2)

Score	Memory
1.0000	Classic laundering: placement → layering → integration.
0.6444	Carla Nunez blew the whistle — four fraudulent transfers, $2.8M total.

mem.search("Who is the whistleblower?")
# [{"content": "Carla Nunez blew the whistle...", "score": 1.0, ...}]
 
mem.search("What is ShellCo?")
# [{"content": "Bob Smith directs ShellCo Ltd...", "score": 1.0, ...}]

search_detailed — observe the ADR-145 retrieval-quality knobs

envelope = mem.search_detailed(
    "money transfer",
    top_k=5,
    min_confidence=0.5,            # CONFIDENCE
    recency_half_life_secs=86400,  # RECENCY
    budget_tokens=2048,            # BUDGET
    stability_days=30.0,           # FORGETTING_CURVE
    cancel_threshold=0.2,          # CANCEL_WHEN
)
# envelope = {"rows": [...],
#             "recall_cost_tokens": 412,   # BUDGET running total
#             "cancelled": False}          # CANCEL_WHEN short-circuit

associate — link two memories

mem.associate(mid1, mid2, relation="same_investigation")
# {"from_id": mid1, "to_id": mid2, "relation": "same_investigation"}

episodes — list sessions

mem.episodes(session_id="shadow-ledger")
# [{"id": "ep_1", "session_id": "shadow-ledger",
#   "summary": "Operation Shadow Ledger investigation", ...}]

justify — provenance chain

mem.justify(mid1)
# {"found": True,
#  "provenance": {"prov_hex": "a3f8b2c1...",
#                  "source": "memory:remember",
#                  "timestamp": "2026-08-08T16:20:14Z"}}

When the regulator asks "why did the agent flag this transaction?", you have the answer — every belief is traceable.

update / resolve / summarise / forget

new_id = mem.update(mid1, "UPDATED: Alice authorized $2.3M — confirmed by 2 sources.")
# Old belief is superseded, not deleted. Bi-temporal history preserves it.
 
mem.resolve(new_id)   # follow the supersession chain to canonical head
# {"id": new_id, "content": "UPDATED: ...", "supersedes": [mid1]}
 
mem.summarise([mid1, mid2, mid3], summary_content="Three findings on Shadow Ledger.")
# {"id": "summ_...", "content": "Three findings on Shadow Ledger."}
 
mem.forget(mid4)      # governed retention-policy retract (not a hard delete)
# {"memory_item_id": mid4, "policy": "soft_delete",
#  "forget_at_ns": 1789234560000000000}

The full Memory surface (15 methods)

Method	Verb	Purpose
`add(content, ...)`	remember	store a belief, return its id
`add_batch(items)`	remember_batch	bulk write, return ids in order
`search(query, top_k=)`	recall	ranked retrieval
`search_detailed(query, ...)`	recall	full envelope with cost/cancelled
`batch_search(queries)`	recall×N	multiple queries merged
`get(memory_id)`	recognize	single fetch, or `None`
`update(id, content)`	consolidate	supersede an old belief
`forget(memory_id)`	forget	governed retention retract
`associate(src, dst, rel)`	associate	typed link between memories
`episodes(session_id=)`	episodes_in	list sessions
`justify(memory_id)`	justify	PROV-O provenance chain
`resolve(memory_id)`	resolve	follow supersession to canonical head
`summarise(ids)`	summarise	summary belief from sources
`get(memory_id)`	recognize	single fetch
`close()`	—	close the HTTP pool

Next: MCP Tools — the same 69 governed agent tools that Claude, Cursor, and Cline get when you point them at RelataDB.

🧠 Agent Memory#

add — store a belief#

add_batch — high-throughput write#

search — recall ranked by relevance × recency × confidence#

search_detailed — observe the ADR-145 retrieval-quality knobs#

associate — link two memories#

episodes — list sessions#

justify — provenance chain#

update / resolve / summarise / forget#