Memoria documentation

What is Memoria?

A deterministic long-term memory engine for AI agents — built to replace probabilistic vector guesswork and LLM write-wrappers.

Every memory is a typed, scored node connected to related memories by typed relationships (Supersedes, Causal, Semantic, DependsOn, Temporal). Unlike LLM memory wrappers that call a stochastic model on every write, Memoria's encode and recall paths are 100% deterministic: the same sequence of events produces the exact same state, the exact same Supersedes belief revisions, and the exact same recall trace in 12–17 ms with zero LLM tokens.

Memories live in retention tiers (Buffer → Episodic → Semantic → Core) and are automatically promoted, demoted, or forgotten based on importance and usage. Layered on top: 15-language multilingual reasoning, offline consolidation, reinforcement from feedback, safety filters (PII redaction + threat quarantine), and confidence scoring. Every operation is isolated by namespace.

Three ways to use it: connect an MCP client (Claude Code, OpenCode, Cursor), call the HTTP API directly, or use an SDK. Start with the Quickstart.

Quickstart

From zero to your first recall in three steps.

1. Get an API key

Create an account (or log in). You'll get an isolated namespace and your first key — it starts with mem_dev_ and is shown once. Generate more anytime from your account.

2. Connect your agent (MCP)

Add the Memoria MCP server to Claude Code with one command:

claude mcp add -s user --transport http memoria https://memoria.kolivri.com/v1/mcp \
  --header "Authorization: Bearer mem_dev_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

…or paste this into your MCP client config (Cursor, Claude Desktop, etc.):

{
  "mcpServers": {
    "memoria": {
      "type": "http",
      "url": "https://memoria.kolivri.com/v1/mcp",
      "headers": { "Authorization": "Bearer mem_dev_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }
    }
  }
}

3. Remember & recall

Your agent can now store and retrieve memories in your namespace. Or hit the HTTP API directly:

# store a memory
curl -X POST https://memoria.kolivri.com/v1/memories \
  -H "Authorization: Bearer $MEMORIA_KEY" -H "Content-Type: application/json" \
  -d '{"content":"We deploy on Fridays after 2pm","type":"Episodic","namespace":"my-project"}'

# recall what you know
curl -X POST https://memoria.kolivri.com/v1/memories/recall \
  -H "Authorization: Bearer $MEMORIA_KEY" -H "Content-Type: application/json" \
  -d '{"query":"when do we deploy?","namespace":"my-project"}'

Organization isolation is handled automatically behind the scenes from your API key — pass any project or workspace name (e.g. my-project or default) in the namespace field.

Core concepts

The concepts you work with when storing and recalling memories.

Memory tiers

Every memory has a retention tier. Migration between tiers is automatic, driven by salience and access patterns.

Memory types

The type you assign at encode time. Over the HTTP API and TypeScript SDK these are PascalCase (Episodic); over MCP, the Python SDK, and the CLI they're lowercase (episodic).

Relationship edge types

Memories are connected by typed relationships so recall can follow causal chains, dependency trees, and belief revisions.

Deterministic graph recall

Recall matches your query against your isolated namespace and traverses connected relationships (Causal, DependsOn, Semantic, Supersedes) to surface relevant context — even when an important decision does not share exact keywords with the prompt. Every traversal strictly enforces your organization namespace boundary.

Ranking & belief revision

Candidates are ranked deterministically using relevance, salience, recency, retention tier, and historical utility. When a newer memory Supersedes an older one, the outdated fact is automatically suppressed so your agent always receives current state.

Salience

Salience is a memory's importance (0–1). An explicit value you pass always wins; otherwise Memoria assigns it automatically based on novelty and high-consequence signals. Salience guides ranking and retention tier promotion.

Consolidation

Consolidation merges near-duplicate episodic captures into clean Semantic knowledge linked by Supersedes, reinforces co-accessed memories, groups related session events, and flags contradictions.

Feedback & reinforcement

Calling /v1/feedback or the feedback MCP tool marks a memory as useful or unhelpful, immediately adjusting its future ranking priority without deleting history.

Safety: PII & quarantine

Before storage, Memoria can redact sensitive identifiers (emails, phone numbers, API keys, payment cards) and quarantine suspected prompt-injection payloads so poisoned inputs do not corrupt agent context.

Confidence & diagnostics

Every recall evaluates result confidence and emits an auditable trace (GET /v1/trace/recent) so you can inspect why specific memories were returned.

Authentication

One key per request, scoped to your namespace.

API keys

Authenticate every request with your key as a Bearer token:

Authorization: Bearer mem_dev_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Keys look like mem_dev_ followed by 43 URL-safe characters. The raw key is shown once at creation and never stored — only a SHA-256 hash is kept, so if you lose a key you mint a new one. The token is opaque: it carries no embedded namespace; your scope is looked up server-side.

Namespaces & isolation

Every API key is automatically scoped to your organization behind the scenes — you never pass an org: identifier. The namespace field in API and MCP calls is purely for your own project, repository, or agent wing name (e.g. my-project, backend, or default). One organization's data can never surface in another's query.

Rotating & revoking keys

Mint additional keys and revoke any key instantly from your account. Revocation takes effect on the very next request (nothing is cached). You can only see and revoke keys under your own account.

Rate limits & quota

Requests are rate-limited per key (a token bucket). Exceed it and you get 429 Too Many Requests with a Retry-After header and a JSON body {code:"RATE_LIMIT_EXCEEDED", status:429, message}. Each organization also has a rolling usage quota; once it's exhausted, requests return 402 Payment Required until the window advances. The exact throughput and quota scale with your plan — check your account.

Connect via MCP

The Model Context Protocol is the fastest path — your agent gets memory tools automatically.

Add Memoria to Claude Code:

claude mcp add -s user --transport http memoria https://memoria.kolivri.com/v1/mcp \
  --header "Authorization: Bearer mem_dev_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Or configure any MCP client (Cursor, Claude Desktop, VS Code) with:

{
  "mcpServers": {
    "memoria": {
      "type": "http",
      "url": "https://memoria.kolivri.com/v1/mcp",
      "headers": { "Authorization": "Bearer mem_dev_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }
    }
  }
}

The connection speaks JSON-RPC 2.0 over streamable HTTP (protocol 2024-11-05). Namespace is chosen per call via the namespace argument (or the x-memoria-namespace header default).

Memory tools

Code-intelligence tools

Index a repository into a code/<project> namespace and these become available:

Calling a tool directly

The same tools are reachable over plain HTTP JSON-RPC at POST /v1/mcp:

curl -X POST https://memoria.kolivri.com/v1/mcp \
  -H "Authorization: Bearer $MEMORIA_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"recall_memories",
                 "arguments":{"query":"auth flow","namespace":"code/myapp"}}}'

Successful results come back as {content:[{type:"text", text:<json>}]}. Call tools/list to see everything the server advertises.

HTTP API

Everything the agents do, over plain REST. Base URL https://memoria.kolivri.com, all routes under /v1, Bearer auth.

Memory

curl -X POST https://memoria.kolivri.com/v1/memories \
  -H "Authorization: Bearer $MEMORIA_KEY" -H "Content-Type: application/json" \
  -d '{"content":"user prefers dark mode","type":"Episodic","namespace":"my-project","salience":0.8,"context":{"user_id":"john-123"}}'

curl -X POST https://memoria.kolivri.com/v1/memories/recall \
  -H "Authorization: Bearer $MEMORIA_KEY" -H "Content-Type: application/json" \
  -d '{"query":"authentication tokens","namespace":"my-project","token_budget":4096}'

Batch & bulk

Learning

Prospective memory (intentions)

Introspection

An interactive OpenAPI spec is served at /v1/openapi.json (Swagger UI at /v1/docs). Auth/rate-limit errors return {code, status, message}; most other errors are a bare status code.

Code intelligence

Index a repository into a code/<project> namespace and Memoria becomes a queryable map of it — definitions, references, call graphs, blast radius.

Example: find everything a change would affect

curl -X POST https://memoria.kolivri.com/v1/code/impact \
  -H "Authorization: Bearer $MEMORIA_KEY" -H "Content-Type: application/json" \
  -d '{"namespace":"code/myapp","symbol":"calc_total","max_depth":5,"limit":200}'
# -> { symbol, affected:[{ qualified_name, file, line, depth, min_confidence }], total, truncated }

All code tools are also exposed as MCP tools (see Connect via MCP) and in the TypeScript SDK under memoria.code.*. Findings are graded (exact / heuristic / ambiguous) with confidence scores — treat rename and dead-code output as a reviewed worklist, not an automatic edit.

SDKs

TypeScript / JavaScript

A thin, zero-dependency fetch client for the HTTP API (Node 18+ or the browser). Enum values are PascalCase (Episodic).

import { Memoria } from "@memoria/sdk";

const memoria = new Memoria({
  baseUrl: "https://memoria.kolivri.com",
  apiKey: process.env.MEMORIA_KEY,   // -> Authorization: Bearer <key>
  namespace: "my-project",           // project / workspace name (org scoping is automatic)
});

const { id, tier } = await memoria.encode({ content: "Deployed v2 to prod", type: "Episodic" });
const hits = await memoria.recall({ query: "deployment", token_budget: 2048 });
const { context } = await memoria.buildContext("deployment", 4096);

// code intelligence over an indexed namespace:
const refs = await memoria.code.findReferences("calc_total");

Non-2xx responses throw MemoriaError { message, status, body }.

Python

A native (PyO3) module that links the engine in-process — embedded, no server or HTTP. Build with maturin develop. Enum-like strings are lowercase (episodic). Surface: encode · recall · build_context · forget · health.

from memoria import Memoria

m = Memoria()  # in-process; wraps the engine directly

mid = m.encode("Deployed v2 to prod", "episodic", "myapp")
out = m.recall("deployment", "myapp", token_budget=2048)
for r in out["results"]:
    print(r["score"], r["content"])

print(m.build_context("deployment", "myapp", 4096)["context"])

The Python SDK is for embedding the engine locally. For the hosted cloud service, use MCP, the HTTP API, or the TypeScript SDK.

CLI

The memoria binary runs against a local SQLite database (default ~/.memoria/memoria.db). Global flags: --db PATH, --format text|json, --verbose.

--db must come before the subcommand: memoria --db /path.db health. Memory types accept lowercase values.

FAQ & limits

Still stuck? Your account has your API keys and Memory Explorer, and the Quickstart gets you connected in a minute.