Agent Memory

Relata is the governed memory layer for AI agents. The agent-memory surface is ten cognitive verbs, exposed two ways: MCP tools (for tool-calling agents like Claude Desktop or OpenAI Agents SDK) and /memory/* HTTP endpoints (for direct clients). Five canonical memory types model the cognitive lifecycle.

Governance stays on by default: each verb requires a purpose token (recorded for audit), results carry provenance, and ACL + organisation isolation apply on every call.

The 10 cognitive verbs

Verb	Purpose
`remember`	Store a governed memory item (bi-temporal + provenance)
`recall`	Hybrid BM25 ⊕ vector retrieval fused via RRF, re-scored by confidence × recency × forgetting curve (optionally `AS OF`)
`recognize`	Is this identity already known? Returns a `MemoryItem` projection
`justify`	Provenance chain + audit trail for a memory item
`consolidate`	Supersede an old belief — closes the superseded row’s `valid_to`, inserts the new belief
`forget`	Schedule retention / legal-hold retract (not a hard delete)
`associate`	Associate two memory items
`resolve`	Resolve a memory item by policy (`latest_wins`, …)
`summarise`	Summarise a session / topic
`episodes_in`	Return full `Episode` detail for a session

Five canonical memory types

Type	Models
`MemoryItem`	A single belief / preference / fact
`AgentSession`	A conversation or task session
`ToolCall`	A tool invocation an agent made
`DecisionRecord`	A decision an agent took
`Episode`	A discrete cognitive episode within a session

Lifecycle (MCP)


// 1. remember — store a governed memory item
{ "method": "tools/call", "params": { "name": "remember",
  "arguments": { "content": "Customer Alice plans to renew in Q3.",
                 "session_id": "agent-session-42", "confidence": 0.9,
                 "purpose": "account_management" } } }
 
// 2. recall — hybrid BM25+vector retrieval
{ "method": "tools/call", "params": { "name": "recall",
  "arguments": { "query": "What do we know about Alice's renewal?",
                 "session_id": "agent-session-42", "top_k": 5,
                 "as_of": "2026-06-01T00:00:00Z",
                 "purpose": "account_management" } } }
 
// 3. forget — schedule retention
{ "method": "tools/call", "params": { "name": "forget",
  "arguments": { "id": "<MemoryItem-uuid>", "retain_days": 90,
                 "purpose": "data_retention" } } }

Lifecycle (HTTP)


curl -X POST http://localhost:9090/memory/remember \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RELATA_BEARER_TOKEN" \
  -d '{"content":"Alice plans to renew in Q3.","purpose":"account_management"}'
 
curl -X POST http://localhost:9090/memory/recall \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RELATA_BEARER_TOKEN" \
  -d '{"query":"Alice renewal","top_k":5,"purpose":"account_management"}'

Mem0-style high-level surface

The Python Memory client and the Rust Memory client wrap the verbs in a Mem0-style surface — add / search / forget:


from relata import Memory
 
with Memory("http://localhost:9090", purpose="agent-notes") as m:
    mem_id = m.add("Alice prefers dark mode")     # store
    hits = m.search("ui preferences", top_k=5)    # recall
    m.forget(mem_id)                              # governed retract

Agent-framework adapters

Drop-in governed memory backends for the major agent frameworks. Each wraps Memory, so purpose + ACL stay on. None imports its framework, so they load with or without it installed.

Framework	Import	Shape
LangChain	`relata_adapters.langchain.RelataMemory`	`BaseMemory`
LlamaIndex	`relata_adapters.llamaindex.RelataMemory`	`BaseMemory`
CrewAI	`relata_adapters.crewai.RelataStorage`	`Storage`
AutoGen v0.2	`relata_adapters.autogen.RelataMemory`	`Memory` (async)
AG2 (v0.4+)	`relata_adapters.ag2.RelataAG2Memory`	`MemoryProtocol`
Pydantic-AI	`relata_adapters.pydantic_ai.RelataMemoryBackend`	memory backend
smolagents	`relata_adapters.smolagents.RelataTool`	tool callable
LangGraph	`relata_langgraph.RelataCheckpointer`	checkpointer
Auto-detect	`relata_adapters.registry.get_memory_adapter()`	picks the right class


from relata_adapters.langchain import RelataMemory
 
mem = RelataMemory(base_url="http://localhost:9090", purpose="agent")
# chain = ConversationChain(llm=..., memory=mem)

A2A — agent-to-agent

The A2AClient wraps the A2A (Agent-to-Agent) protocol surface: task dispatch, LangGraph checkpoint sharing, and the agent card.


from relata import RelataClient, A2AClient
 
with RelataClient(url, bearer_token=token, purpose="agent-coordination") as client:
    a2a = A2AClient.from_client(client)
    task = a2a.create_task(skill="translate", input={"text": "hello"})
    print(a2a.agent_card())

Ranking model

recall ranks results by:

Hybrid retrieval — BM25 ⊕ vector fused via reciprocal-rank fusion (RRF).
Re-scoring — confidence × recency × forgetting curve (memory_verbs::rank_recall).

The forgetting curve is configurable per tenant; default is Ebbinghaus-style exponential decay.

Implementation references

Layer	Code
Cognitive verb builders	`relata-query::memory_verbs`
MCP tools (10)	`serve/mcp.rs`
HTTP endpoints (10)	`serve.rs`
E2E coverage	`tests/http_e2e.rs`
ADRs	ADR-142 (cognitive verbs), ADR-143 (canonical types), ADR-144 (MCP surface), ADR-145 (retrieval operators), ADR-146 (benchmark suite)