For AI agent builders

Most agent stacks are glued together from five pieces: a vector DB for retrieval, a memory tool (Mem0/Zep) for recall, a graph DB for relationships, a governance layer you build yourself, and an audit log you hope is defensible. Each piece has its own consistency model, its own identity, and its own idea of "current truth." RelataDB replaces all five with one governed store — and your agent gets memory that's bi-temporal, recall that's tunable, and every belief traceable to the tool call that produced it.

This is the agent-memory layer for regulated, audited, defensible AI — where a hallucinated or unexplainable memory is a liability, not a quirk.

What you replace

Today (polyglot)	With Relata
Vector DB (Pinecone / Qdrant / pgvector)	Hybrid search (BM25 + HNSW + identity fusion, RRF) in one store
Memory tool (Mem0 / Zep / Cognee)	10 governed cognitive verbs with recall-quality knobs
Graph DB for relationships	The graph forms itself from standardized identities
Framework-specific memory glue	7 Python adapters + 3 TS adapters + a LangGraph checkpointer
Hallucinated entity extraction	Deterministic canonical-type detection (76 kinds, zero hallucination)
Bolt-on audit/provenance	PROV-O per memory + tamper-evident hash chain + `justify`

The agent stack

        ┌─────────────── your agent (LangGraph / CrewAI / custom) ──────────────┐
        │                                                                       │
        │  MemoryClient  ◄──►  10 cognitive verbs (remember … summarise)         │
        │      │                  + recall-quality knobs                         │
        │      │                                                                 │
        │  McpClient     ◄──►  40+ tools: investigate, find_threats,             │
        │                       rag_store_answer, nl_query, hybrid_search …       │
        │                                                                       │
        │  VectorClient  ◄──►  embed (text + image/face/audio/video) + KNN/hybrid│
        │                                                                       │
        │  RelataClient  ◄──►  governed SQL / Cypher / GraphQL over the same store│
        └───────────────────────────────┬───────────────────────────────────────┘
                                         │  one governed bi-temporal store
                                         ▼
                          identity fusion + provenance + cell-level ACL + audit chain

The 10 cognitive verbs + recall-quality knobs

Every memory is a governed, bi-temporal MemoryItem (content + confidence + memory_class + valid_from/to + system_from/to) linked back to the ToolCall and AgentSession that produced it.

Verb	What it does
`remember` / `add`	Store a memory (episodic / semantic / procedural).
`recall` / `search`	Hybrid BM25 + vector retrieval, re-scored by confidence × recency × forgetting curve.
`recognize` / `get`	Fetch one memory with full provenance attached.
`justify`	The PROV-O chain (ToolCall → MemoryItem → DecisionRecord) — why the agent believes this.
`consolidate` / `update`	Supersede a memory; old retained in history, new gets higher confidence.
`forget`	Governed retention-policy retract (NOT hard delete).
`associate`	Typed, provenance-stamped link between two memories/entities.
`episodes`	List `Episode` records for a session, ordered by valid_from.
`resolve`	Follow the supersession chain to the canonical live memory.
`summarise`	Produce a governed, provenance-stamped summary belief from source memories.

The recall-quality knobs — tune what comes back, not just how many:

mem.search("how do we reset the IR sensor?",
    top_k=10,
    min_confidence=0.6,            # CONFIDENCE floor
    recency_half_life_secs=259200,  # 3-day decay  (RECENCY)
    budget_tokens=1500,            # hard prompt budget — can't overflow (BUDGET)
    stability_days=30,             # Ebbinghaus forgetting (FORGETTING_CURVE)
    cancel_threshold=0.92,         # stop early on a great match (CANCEL_WHEN)
)

search_detailed exposes recall_cost_tokens + cancelled so you can observe the knobs' effect. See Agent memory reference (recall knobs + the 5 operators).

RAG — governed, with provenance per answer

A RAG answer in most stacks is a black-box string. In Relata it's a governed RagAnswer row linked to its RagSource rows, with PROV-O and the ToolCall that produced it — defensible and replayable.

# MCP path — the simplest surface
mcp.call_tool("rag_store_answer", {
    "question": "What's our refund policy for EU customers?",
    "answer": "14-day no-questions refund under EU consumer law…",
    "confidence": 0.92,
    "sources": ["doc-refund-policy", "regulation-eu-2011-83"],
    "purpose": "support",
})
 
# Retrieve for the next turn — governed hybrid search over your knowledge corpus
mcp.call_tool("search_knowledge", {
    "query": "EU refund window",
    "min_confidence": 0.5,
    "purpose": "support",
})

The RAG ingest path is POST /ingest/document (NDJSON chunks + a manifest) or the MCP ingest_document tool — async, returns a task_id you poll. See Ingestion.

MCP tools — natural-language investigation + retrieval

40+ MCP tools, callable from any MCP-compatible agent runtime (Claude Desktop, Cursor, your own):

mcp.call_tool("nl_query", {"query": "show me high-risk customers added this week",
                           "interpret": True, "purpose": "analytics"})
# → rows + generated_sql + model_id + llm_used (audit fields)
 
mcp.call_tool("investigate_entity", {"entity_type": "Person",
                                     "entity_id": "alice-001",
                                     "purpose": "security_incident"})
mcp.call_tool("find_threats", {"entity_type": "Alert", "purpose": "security_incident"})
mcp.call_tool("hybrid_search", {"entity_type": "Document",
                                "query": "refund policy EU", "top_k": 10,
                                "purpose": "support"})

The nl_query response carries generated_sql + model_id + llm_used so you know whether the SQL came from the deterministic local translator or an LLM — essential for audit. Deterministic local translator runs when RELATA_LLM_URL is unset (air-gap friendly); the LLM is used when set. See MCP Tools.

Framework adapters — drop Relata in as governed memory

Python — 7 adapters (relata_adapters, ships with the package; install only your framework):

# LangChain
from relata_adapters.langchain import RelataMemory
memory = RelataMemory(base_url="http://localhost:9090", purpose="agent",
                      bearer_token="<token>")
 
# CrewAI / AutoGen / AG2 / Pydantic-AI / smolagents / LlamaIndex — same shape
from relata_adapters.crewai import RelataStorage
 
# Auto-detect which is installed and return the right class
from relata_adapters.registry import get_memory_adapter
Adapter = get_memory_adapter()

LangGraph checkpointer (pip install relata-sdk[langgraph]):

from relata_langgraph import RelataCheckpointer, AsyncRelataCheckpointer
checkpointer = RelataCheckpointer(endpoint="http://localhost:9090",
                                 token="<token>")
graph = builder.compile(checkpointer=checkpointer)

A real BaseCheckpointSaver subclass — persists graph state via the governed A2A checkpoint door, so an agent's full trajectory is as auditable as its memories.

TypeScript — 3 adapters (LangChain / LlamaIndex / LangGraph) + a CLI binary (npx @zysec-ai/relata-sdk health).

A2A — agent-to-agent tasks

Agents delegate and share state through governed A2ATask rows + checkpoints:

a2a = A2AClient.from_client(client)
task_id = a2a.submit_task({"kind": "summarize_case", "case_id": "case-7",
                           "purpose": "investigation"})
a2a.save_checkpoint("thread-1", "step-3", {"draft": "..."})

6 embedding modalities

Embed through VectorClient or /embed — text, image (CLIP), face crop (ArcFace), audio (CLAP), video keyframe (CLIP), plus batch text:

vc.embed("Alice Smith")                # text (CPU lexical default; GPU sidecar via RELATA_ACCEL_ENDPOINT)
vc.embed_image(b64)                    # CLIP — multimodal RAG
vc.embed_face(b64)                     # ArcFace — see [Multimedia search](/docs/guides/multimedia-search)
vc.embed_audio(b64)                    # CLAP
vc.embed_video(b64)                    # CLIP keyframe

Worked design — a governed support agent

from relata import RelataClient, Memory
from relata_adapters.langchain import RelataMemory
 
client = RelataClient("http://localhost:9090", bearer_token="<token>",
                      purpose="support")
 
# 1. RAG: ingest your policy docs once
client.ingest_document(chunks_jsonl=open("policies.jsonl").read(),
                       manifest_json=open("manifest.json").read())
 
# 2. Per-conversation governed memory
mem = Memory("http://localhost:9090", bearer_token="<token>", purpose="support")
mem.add("Customer AC-042 prefers email replies; past refund disputes.",
        memory_class="semantic", confidence=0.9)
 
# 3. Answer with retrieval + memory, store the answer with provenance
answer = mcp.call_tool("hybrid_search",
                       {"entity_type": "Document", "query": "<user q>", "top_k": 5})
mcp.call_tool("rag_store_answer", {
    "question": "<user q>", "answer": "<drafted answer>",
    "sources": [s["id"] for s in answer],
    "confidence": 0.88, "purpose": "support",
})
 
# 4. Every belief is justifiable later
mem.justify(answer_id)   # → the ToolCall + sources that produced it

Every step is governed, bi-temporal, and audit-logged — a compliance review can reconstruct exactly what the agent believed, retrieved, and answered at any past moment.

Tips & takeaways

Start with budget_tokens. It's the single biggest agent-loop win — the prompt literally cannot overflow the model's context window.
Use deterministic extraction where you can. SmartIngest's canonical-type detectors are zero-hallucination; reserve the LLM for genuine NL tasks, not for "is this the same person."
justify is your compliance superpower. It turns "why did the agent say that?" from a forensic nightmare into a one-call answer.
Pair RagAnswer rows with PURPOSE. A RAG answer that drives an automated action should carry a purpose so the action is as auditable as the retrieval.
Don't replicate your warehouse into memory. recall is selective (ranked, bounded, early-cancelable) — let the agent query a billion-row memory at the same prompt cost as a megabyte one.
LangGraph state belongs in the checkpointer, not in ad-hoc JSON — that's what makes an agent's trajectory replayable and audit-ready.

For AI agent builders#

What you replace#

The agent stack#

The 10 cognitive verbs + recall-quality knobs#

RAG — governed, with provenance per answer#

MCP tools — natural-language investigation + retrieval#

Framework adapters — drop Relata in as governed memory#

A2A — agent-to-agent tasks#

6 embedding modalities#

Worked design — a governed support agent#

Tips & takeaways#

See also#