Agent memory surface#

RelataDB is the agentic-first ontological database — one governed, bi-temporal knowledge base that speaks every database protocol. This page covers its agent-memory surface: the governed memory layer where what an agent knew, when, and why is defensible, not just convenient.

Most agent-memory products (Mem0, RushDB, Zep) optimize for convenience: push JSON, get semantic recall, schema-free, with embeddings computed for you. Relata optimizes for accountability: every belief is bi-temporal, provenance-stamped, and access-controlled. Since v1.1 embeddings are caller-supplied — either pre-compute _emb_text in the row payload or run the embedder sidecar for async drain — so the ingest hot path is pure throughput (no per-row model call). If you need memory that feels smart, those are great; if the memory must answer "what did the agent know, when, and why — and who was allowed to see it?", that's Relata.

Relata vs. the convenience-memory cohort#

Why Relata for agent memory#

Problems we solve#

Unlimited memory#

Relata gives an agent unbounded memory with bounded prompts by separating what the agent knows (unlimited) from what it sees per turn (bounded):

• Capacity is unbounded — durable storage is object-store (S3 / self-hosted S3-compatible), not RAM-bound like a vector DB. You run out of bucket, not memory.
• The agent never loads it all — each turn, recall returns only the small, relevant, ranked slice, capped by LIMIT N BUDGET T. A 10-year, billion-row memory and a 1 MB memory cost the same prompt budget; retrieval is selective, not exhaustive.
• Cold vs hot — cold history lives on object storage; active-case data is promoted into RAM/SSD via the tiered cache. Archive-scale capacity with interactive latency.

Fast and efficient on constrained hardware#

Relata is RAG-on-memory, engineered to run on a laptop or edge box with no GPU:

• No LLM on the hot path. Ingest canonicalizes + validates declared identities (deterministic, cheap). Auto-detection/extraction is lazy via materialized views (ADR-022) — you pay detection cost only on the slice you query, not on 100% of rows at write time.
• Early-pruned retrieval. IdentityIndex bloom filters + graph pushdown + a BM25 shortlist mean the vector path scans a tiny candidate set, not the whole corpus.
• Single binary, embedded free profile — one process, in-memory + optional object-store, running alongside the agent's own loop. No separate vector server, Redis, and graph DB to operate.
• Token-efficient — hybrid (keyword + vector + graph) returns higher-precision results, so fewer tokens are injected for the same answer quality, and the budget operator sets a hard ceiling.

Honest scope: single-node free/server with object-store + tiered cache is the shipped answer today. Multi-node cluster scale (deep partitioning) is the cluster profile and still maturing.

The five canonical memory types#

The 10 cognitive verbs#

Batch helpers: POST /memory/remember/batch and POST /memory/associate/batch are high-throughput variants that amortise the per-record index flush across a whole batch; per-item errors are returned per element and valid items still commit.

Surface note: The cognitive verbs are MCP tools and REST endpoints — they are not SQL keywords. The LIMIT N BUDGET T retrieval knobs (ADR-145) and recall … AS OF '<ts>' time-travel are expressed as verb/REST parameters (?top_k=, ?as_of= on GET /memory/recall). The underlying bi-temporal AS OF is available as real SQL over the base types (SELECT … FROM MemoryItem AS OF '<ts>').

Quick-start via MCP#

Relata exposes all the cognitive verbs as MCP tools. Point your agent's MCP client at the server and call tools directly:

// MCP initialize
POST /mcp/initialize
{"protocolVersion":"2024-11-05","clientInfo":{"name":"my-agent","version":"1.0"}}
 
// MCP list tools
GET /mcp/tools
// → returns the memory tools: remember, remember_batch, recall, recognize, episodes_in, justify, consolidate, forget, associate, resolve, summarise
 
// MCP call — remember
POST /mcp/tools/call
{
  "name": "remember",
  "arguments": {
    "content": "User prefers concise summaries",
    "session_id": "sess_abc123",
    "confidence": 0.9,
    "purpose": "personalisation"
  }
}
// → {"isError": false, "content": [{"type":"text","text":"{\"id\":\"<uuid>\",\"confidence\":0.9,...}"}]}
 
// MCP call — remember_batch (high-throughput write path)
POST /mcp/tools/call
{
  "name": "remember_batch",
  "arguments": {
    "items": [
      {"content": "User prefers dark mode", "session_id": "sess_abc123", "confidence": 0.9},
      {"content": "User timezone is UTC+5:30", "session_id": "sess_abc123", "confidence": 0.85},
      {"content": "User speaks English and Hindi", "session_id": "sess_abc123", "confidence": 0.95}
    ],
    "purpose": "personalisation"
  }
}

Quick-start via HTTP REST#

Step 1 — Remember a fact#

POST /memory/remember
Content-Type: application/json
 
{
  "content": "User prefers dark mode",
  "session_id": "sess_abc123",
  "confidence": 0.9,
  "purpose": "personalisation"
}

Response:

{
  "isError": false,
  "content": [{
    "type": "text",
    "text": "{\"id\":\"550e8400-e29b-41d4-a716-446655440000\",\"confidence\":0.9,\"valid_from\":1750000000000000000}"
  }]
}

Step 2 — Recall related memories#

GET /memory/recall?q=user+preferences&top_k=5&purpose=personalisation

Response:

{
  "isError": false,
  "content": [{
    "type": "text",
    "text": "{\"memories\":[{\"id\":\"550e8400...\",\"content\":\"User prefers dark mode\",\"score\":0.97}],\"total\":1}"
  }]
}

Step 3 — Justify a memory (provenance)#

GET /memory/justify/550e8400-e29b-41d4-a716-446655440000?purpose=audit

Returns the full ToolCall → MemoryItem → DecisionRecord provenance chain.

Step 4 — Consolidate (update with higher confidence)#

POST /memory/consolidate
Content-Type: application/json
 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "content": "User prefers dark mode (confirmed across three sessions)",
  "confidence": 0.98,
  "purpose": "personalisation"
}

Returns {"superseded": "<old-id>", "new_id": "<new-id>"}.

Step 5 — Schedule forgetting#

DELETE /memory/forget/550e8400-e29b-41d4-a716-446655440000?retain_days=30&purpose=gdpr

Returns {"scheduled": true, "policy": "delete_after_30d"}.

Governance model#

Every memory operation passes through three governance layers:

1. PURPOSE — The purpose field (e.g. "personalisation", "audit", "gdpr") is recorded in the audit log and may be required by ACL policy. When PURPOSE is omitted, the operation is recorded as unpurposed but still allowed in open mode (ADR-125).

2. ACL — Cedar-inspired ABAC rules control which agent identities can write, read, or delete memories in a given organisation. Cell-level masking applies to sensitive fields.

3. Provenance chain — Every MemoryItem references the AgentSession and ToolCall that produced it. The hash-chained manifest makes the chain tamper-evident. justify replays the chain on demand.

Multi-agent isolation#

When multiple agents share one Relata instance, pass a tenant_id header:

POST /memory/remember
X-Relata-Agency: agent-team-alpha

The planner enforces tenant_id keying so agents never see each other's memories without an explicit cross-organisation grant (ADR-132).

session_id is not a tenant boundary. The session_id (typically an agent's Ed25519 pubkey) groups a conversation — it is not an isolation key. Two organisations reusing the same session_id are kept apart only by their tenant (org). On a multi-tenant profile (server/cluster with more than one tenant, or RELATA_TENANCY_MODE=multi) memory writes with no tenant are rejected 403. Present a per-tenant credential — X-Organization-Id or a tenant-scoped bearer token — for every memory write.

See also#

• MCP tools reference
• Bi-temporal queries
• Error codes