API reference¶
veramem.Memory
¶
Verifiable, outcome-aware, share-safe memory for AI agents.
mem = Memory() # auto-detects Ollama / OpenAI / Anthropic mem.add("I moved to Berlin in March", user_id="alice") mem.search("where does alice live?", user_id="alice").hits[0].memory.text
reindex()
¶
Re-embed every memory and episode with the current embedder.
add(messages, *, user_id=None, agent_id=None, session_id=None, team_id=None, infer=True, timestamp=None, metadata=None, resources=None)
¶
Remember a message, a list of chat messages, a tool result or a document.
messages: str | {"role","content"[,"name","timestamp"]} | list of those. Roles: user, assistant, tool, document, system. The role decides authority.
search(query, *, user_id=None, agent_id=None, limit=10, granularity='auto', kinds=None, include_shared=True, as_of=None, record=True, include_raw=True)
¶
Hybrid, access-controlled retrieval. Returns hits with evidence and a trace_id.
answer(question, *, user_id=None, agent_id=None, limit=20, style='concise', max_rounds=2, today=None)
¶
Answer from memory only, with citations; abstains when evidence is missing.
evidence(memory_id, *, user_id=None, agent_id=None)
¶
Resolve a memory's evidence pointers back to the raw episodes.
history(memory_id, *, user_id=None, agent_id=None)
¶
Version chain (oldest first) plus the ledger entries for each version.
update(memory_id, text, *, user_id=None, agent_id=None)
¶
Manual correction by the owner. Creates a new version and keeps history.
The correction itself is stored as a user episode, so the new version is grounded in evidence like any other memory.
delete(memory_id, *, user_id=None, agent_id=None)
¶
Retract a memory (kept for audit, hidden from retrieval). See forget().
forget(memory_id=None, *, user_id=None, agent_id=None, everything=False)
¶
Hard-erase one memory, or everything about a user (right to be forgotten).
feedback(trace_id, reward, *, cited=None, user_id=None, agent_id=None)
¶
Report how well a search/answer worked: reward in [-1, 1].
cited: the memory ids your agent actually used (must come from that trace).
Defaults to the answer's citations, or the top retrieved memories for a search.
user_id/agent_id: when given, the trace must belong to that caller.
train_ranker(*, user_ids=None, min_examples=30)
¶
Fit the outcome ranker on rated traces; use it with Memory(ranking="ranker").
learn(task, trajectory, reward, *, user_id=None, agent_id=None, scope=None, shareable=False)
¶
Distil a finished task into a reusable experience (if the outcome is decisive).
check_action(memory_ids, *, user_id=None, agent_id=None)
¶
May these memories bind a protected tool call? (authority gate)
Memories the caller may not read are reported as missing, so the gate can't be used to probe other users' memories.
share(*, user_id, team_id=None, memory_ids=None, min_utility=0.6)
¶
Share the user's consented experiences (de-identified) with a team or everyone.
moderate(memory_id, action, *, reason='')
¶
Operator action on a shared (team/public) memory: "retract" or "forget".
End users cannot change pooled memories; this is the audited operator path.
shared_with(*, user_id=None, limit=200)
¶
Team and public memories this user may read (never other users' private ones).
agents_of(user_id)
¶
Agents currently granted access to this user's memory.
export(*, user_id)
¶
Portable JSON of everything stored about a user (data-subject access).
import_(data)
¶
Load a veramem.export.v1 document (ids are preserved, existing ids skipped).
verify()
¶
Check the ledger chain, episode hashes and memory text against the ledger.
veramem.AsyncMemory
¶
Same API as Memory, with awaitable methods.
Data types¶
veramem.types.MemoryItem
¶
Bases: BaseModel
utility
property
¶
Posterior mean of a Beta(1,1) prior over 'this memory helps'.
veramem.types.Evidence
¶
Bases: BaseModel
A pointer into an Episode: the exact span that supports a memory.
veramem.types.Authority
¶
Bases: str, Enum
How much a memory may be trusted to act on.
Follows the source-authority taxonomy of AuthMem-Bench ("When Memory Becomes Authority", 2026): direct user evidence is Authorized, the agent's own claims are Attested, everything else (tools, documents, other users) is Unendorsed. Consolidation may never raise a memory's authority above its weakest evidence.
veramem.types.SearchResult
¶
Bases: BaseModel
context(max_items=None, with_evidence=True)
¶
Render hits as a compact, citable context block for a prompt.
veramem.types.Answer
¶
Bases: BaseModel