Memoria documentation

What is Memoria?

A long-term memory engine for AI agents — modeled on how human memory works, not on vector search alone.

Every memory is a typed, scored node in a concurrent graph, connected to other memories by weighted, typed edges. Retrieval runs on spreading activation: a query lights up the most relevant memories, then activation flows outward across the graph so that causally, semantically, and temporally related memories surface too — even when their wording doesn't match the query.

Memories live in retention tiers (Buffer → Episodic → Semantic → Core) and are automatically promoted, demoted, or forgotten based on how important they are and how often they're used. Layered on top: consolidation (offline pattern extraction), reinforcement from feedback, safety filters (PII redaction + threat quarantine), and a metacognition layer that judges its own confidence. Every operation is isolated by namespace.

Three ways to use it: connect an MCP client (Claude Code, 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://brain.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://brain.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://brain.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":"org:acme-3f9c2a"}'

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

Use your own namespace (shown in your account) in the namespace field — your key is scoped to it.

Core concepts

The ideas that make recall work. You don’t need all of this to start — but it explains why Memoria surfaces what it does.

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).

Edge types & activation decay

Edges are typed and weighted. When activation spreads across an edge it is multiplied by the edge weight and the edge type's decay factor — so a strong Causal link (0.80) carries recall much further than a weak Contradicts link (0.30).

Spreading activation

Recall runs in two stages. Seeding: the query is matched to memories in your namespace by cosine similarity, plus BM25 keyword seeds (discounted to 80%). Spreading: activation flows outward from those seeds across edges — at each hop, activation = source activation × edge weight × edge-type decay × any intent boost. The spread is bounded (≈3 hops, with per-wave and total node caps and an activation floor). Every edge crossing re-verifies namespace membership, so activation can never leak into another tenant's data. The payoff: a memory whose text doesn't match your query can still be recalled because it's causally or semantically connected to something that does.

Scoring

Each activated candidate's final score multiplies several factors (in log space): activation level × salience × freshness^intent × tier boost × utility. Freshness decays with time since last access. The tier boost depends on query intent — factual queries favour Semantic (1.5×) and Core (2.0×). A popularity anti-bias multiplier gently penalises memories retrieved often but rarely confirmed useful. Superseded memories are down-ranked to 5% of their score.

Salience

Salience is a memory's importance (0–1). An explicit value you pass always wins. Otherwise it's computed from novelty (how different this is from what's stored), consequence (high-stakes keywords like production, incident, outage, security, breach, critical), and any hint — the loudest signal dominates, others nudge. Default with no signal: 0.3. Salience feeds scoring, decay resistance, and tier-promotion thresholds.

Consolidation

An offline replay pass (analogous to sleep). Over a recent window it runs four detectors: repetition (near-duplicate clusters distilled into one Semantic summary, linked by Supersedes), co-access (frequently co-retrieved pairs reinforced), temporal burst (memories created close in time grouped as an episode), and contradiction (conflicting near-identical memories flagged). It turns a pile of raw episodic captures into deduplicated semantic knowledge over time.

Feedback & reinforcement

Memoria learns from use. Every recall strengthens CoRetrieval edges among top results and bumps access counts. Explicit feedback marks a memory useful or not: a prediction-error update nudges its expected-utility (and, on a big surprise, its salience), and reward is propagated back along the activation path that produced the hit. Conversely, dampening quietly suppresses query–memory pairs that repeatedly prove unhelpful — without ever deleting anything.

Safety: PII & quarantine

Two layers run before storage. PII redaction replaces emails, phone numbers, API keys, credit-card and Social-Security numbers, IPs, URLs, and names with reversible placeholders ([EMAIL_1]). Quarantine classifies content for credential patterns, instruction-injection attempts (EN + HE), and suspicious URLs; confidence rises with signal count (1→0.4, 2→0.7, 3+→0.95) and flagged content is marked quarantined.

Metacognition

Retrieval judges itself. It auto-detects a context mode from your namespace shape (organizational, support, research, personal…), assesses its own confidence (High / Moderate / Low) from the score distribution, detects re-querying (a sign the last answer missed), and can intervene mid-pipeline — broadening when seeds are too few, narrowing when too many, or returning empty when nothing clears the bar.

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

Each account gets one organization with a unique namespace, auto-generated as org:<you>-<hex> (e.g. org:alice-3f9c2a) — shown in your account. Your key resolves to that namespace, and all reads/writes are scoped to it. Spreading activation re-checks namespace membership on every edge, so one tenant's data can never surface in another's query. Pass your namespace in the namespace field of API calls.

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://brain.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://brain.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://brain.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://brain.kolivri.com, all routes under /v1, Bearer auth.

Memory

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

curl -X POST https://brain.kolivri.com/v1/memories/recall \
  -H "Authorization: Bearer $MEMORIA_KEY" -H "Content-Type: application/json" \
  -d '{"query":"authentication tokens","namespace":"org:acme-3f9c2a","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://brain.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://brain.kolivri.com",
  apiKey: process.env.MEMORIA_KEY,   // -> Authorization: Bearer <key>
  namespace: "org:acme-3f9c2a",      // required; default for every call
});

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 shows your namespace and keys, and the Quickstart gets you connected in a minute.