Memoreal documentation

Long-term memory for AI agents — connect a client, call the API, and your agent remembers across sessions. Grounded, graph-based recall with automatic tiering and consolidation.

What is Memoreal?

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, Memoreal'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.

Deterministic, not stochastic

Zero LLM calls on encode or recall. Supersedes belief revision, multi-session counting, and temporal queries execute deterministically in <15 ms.

Connected memory graph

Recall traverses causal, semantic, and temporal relationships to surface facts that flat vector similarity misses.

Auditable & tenant-isolated

Every recall emits a reproducible trace (/v1/trace/recent), and every query enforces strict organization and namespace isolation.

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 Memoreal MCP server to Claude Code with one command:

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

Or run via the zero-install npm / npx stdio bridge (@kolivri/memoreal-mcp):

claude mcp add memoreal -e MEMOREAL_API_KEY="mem_dev_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" -- npx -y @kolivri/memoreal-mcp
MEMOREAL_API_KEY="mem_dev_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" npx -y @kolivri/memoreal-mcp

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

{
  "mcpServers": {
    "memoreal": {
      "type": "http",
      "url": "https://memoreal.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://memoreal.kolivri.com/v1/memories \
  -H "Authorization: Bearer $MEMOREAL_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://memoreal.kolivri.com/v1/memories/recall \
  -H "Authorization: Bearer $MEMOREAL_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.

TierRetentionLifecycleNotes
BufferShort-termPromotes on repeated access or high salienceAutomatically expired when unused.
EpisodicMedium-termPromotes with sustained usage across sessionsCaptures session events and task history.
SemanticLong-termPromotes when confirmed as durable knowledgeDistilled project facts and conventions.
CorePermanentPinned or created as core rulesNever decays or expires.

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

TypeMeaning
BufferShort-lived scratch memory awaiting promotion.
EpisodicAn event or experience carrying temporal context.
SemanticDistilled factual knowledge.
CoreImmutable foundational knowledge.
ProceduralA learned action sequence or workflow.
ProspectiveA future-oriented intention or reminder.

Relationship edge types

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

Edge typeMeaning
CausalOne memory caused or led to another.
DerivedFromSource was derived from the target — a provenance trail.
DependsOnSource requires the target to hold.
AssumesSource depends on the truth of a target assumption.
SupersedesSource replaces the target; outdated memories are automatically suppressed.
EvidenceSource provides evidence supporting the target.
SemanticShared meaning or topic, linked automatically at encode time.
CoRetrievalFrequently retrieved together and reinforced on co-access.
SchemaLinked through a shared category schema.
ContainsStructural containment (project → dir → file → definition).
PredictsSource predicts the target will be needed.
TemporalSequential proximity in time, linked automatically.
ContradictsMarks conflicting statements so stale or contradictory state is surfaced.

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 Memoreal 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, Memoreal 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 Memoreal to Claude Code:

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

Or configure any MCP client (Cursor, Claude Desktop, VS Code) over Streamable HTTP:

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

Or connect via npm / npx stdio (@kolivri/memoreal-mcp):

claude mcp add memoreal -e MEMOREAL_API_KEY="mem_dev_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" -- npx -y @kolivri/memoreal-mcp
MEMOREAL_API_KEY="mem_dev_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" npx -y @kolivri/memoreal-mcp
{
  "mcpServers": {
    "memoreal": {
      "command": "npx",
      "args": ["-y", "@kolivri/memoreal-mcp"],
      "env": {
        "MEMOREAL_API_KEY": "mem_dev_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "MEMOREAL_NAMESPACE": "my-project"
      }
    }
  }
}

The connection speaks JSON-RPC 2.0 over streamable HTTP (protocol 2024-11-05) at https://memoreal.kolivri.com/v1/mcp (with backward-compatible support for legacy https://memoria.kolivri.com/v1/mcp). Namespace is chosen per call via the namespace argument (or the x-memoreal-namespace / x-memoria-namespace header default).

Memoreal provides 14 MCP tools natively on Hosted Cloud + Local (encode_memory, batch_encode, recall_memories, build_context, forget_memory, delete_by_context, feedback, consolidate, health, stats, search_code, explain_code, list_agent_wings, handoff_to_agent). Deep static code-intelligence tools require the Local CLI Engine.

Memory & agent tools

ToolAvailabilityParamsDoes
encode_memoryHosted Cloud + Localnamespace, content, type?, salience?, context?Store a memory with tier classification (buffer, episodic, semantic, core).
batch_encodeHosted Cloud + Localmemories:[{ content, type?, namespace, ... }]Atomically store multiple memories in a single batch call.
recall_memoriesHosted Cloud + Localquery, namespace?, token_budget?, min_salience?Retrieve relevant memories ranked deterministically within a token budget.
build_contextHosted Cloud + Localquery, namespace?, token_budget?Assemble a token-budgeted <memory_context> block for a query.
forget_memoryHosted Cloud + LocalidDelete a memory and its incident graph edges by UUID.
delete_by_contextHosted Cloud + Localkey, value, namespace?Bulk delete memories matching a context metadata [key, value] pair.
feedbackHosted Cloud + Localid, usefulMark a recalled memory useful or noisy to adjust its ranking priority.
consolidateHosted Cloud + LocalnamespaceRun offline consolidation: merge duplicates and detect patterns & edges.
healthHosted Cloud + Local—Engine health across namespaces, active counts, and quota status.
statsHosted Cloud + LocalnamespacePer-namespace memory count, tier breakdown, and 30-day API usage.
list_agent_wingsHosted Cloud + Localnamespace?List specialist agent wings (architect, reviewer, qa, security, ops).
handoff_to_agentHosted Cloud + Localwing, summary, task?, files?, memory_ids?Record a structured handoff into a specialist agent wing.

Code-intelligence tools

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

ToolAvailabilityDoes
search_codeHosted Cloud + LocalSearch indexed code definitions and architectural notes in Memoreal.
explain_codeHosted Cloud + LocalWhat a symbol is, who calls it, its tests and context.
find_referencesLocal CLI EngineEvery reference to a symbol (graded exact, heuristic, ambiguous).
find_fileLocal CLI EngineLocate a file/dir by path substring, shallowest first.
impactLocal CLI EngineTransitive blast radius of changing a symbol (reverse-call walk).
call_treeLocal CLI EngineNested caller (in) or callee (out) tree for a symbol.
dead_code · test_gapsLocal CLI EngineUncalled definitions · definitions with no test.
rename · diff_riskLocal CLI EngineReviewed rename worklist · callers at risk for changed symbols.
implementorsLocal CLI EngineTypes implementing a trait/interface (Rust / TS).
explain_diff · explain_errorLocal CLI EngineAnalyse a unified diff · an error/stack trace.
navigate · get_hierarchyLocal CLI EngineWalk the containment map · a node’s full vertical context.

Calling a tool directly

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

curl -X POST https://memoreal.kolivri.com/v1/mcp \
  -H "Authorization: Bearer $MEMOREAL_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://memoreal.kolivri.com, all routes under /v1, Bearer auth.

Hosted Cloud routes run on Hosted Cloud and sync to your persistent tenant partition. Experimental and codebase-indexing AST routes run on the Local Engine Only.

Memory

POST/v1/memoriesHosted Cloud
Encode one memory. Runs quarantine + dedup; returns its tier and salience.
Body{ content, type, namespace, salience?, context?, links? }
Returns201 { id, created_at, salience, tier, quarantined, is_duplicate, duplicate_of? }
curl -X POST https://memoreal.kolivri.com/v1/memories \
  -H "Authorization: Bearer $MEMOREAL_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"}}'
POST/v1/memories/recallHosted Cloud
Recall memories for a query through the full pipeline; returns scored results + metacognition.
Body{ query, namespace, token_budget?=4096, min_salience?=0, context?, mode? }
Returns200 { results:[{ memory, score }], total_candidates, latency_ms, metacognition? }
curl -X POST https://memoreal.kolivri.com/v1/memories/recall \
  -H "Authorization: Bearer $MEMOREAL_KEY" -H "Content-Type: application/json" \
  -d '{"query":"authentication tokens","namespace":"my-project","token_budget":4096}'
POST/v1/memories/contextHosted Cloud
Build a single token-budgeted context string from recalled memories.
Body{ query, namespace, token_budget?=4096, format?=Structured (Structured|Narrative|Raw), context?, mode? }
Returns200 { context, memories_used }
POST/v1/memories/recall/enhancedHosted Cloud
Recall with diversity filtering, recall tracing, and confidence metadata.
Body{ query, namespace, token_budget?, diversity?=0.7, min_salience?, mode? }
Returns200 { results, total_candidates, latency_ms, cache_hit, trace_id?, metacognition? }
DELETE/v1/memories/:idHosted Cloud
Forget a memory by UUID.
Body(none)
Returns200 { deleted }
GET/v1/memories/:id/neighborsHosted Cloud
List a memory’s outgoing edges.
Body(none)
Returns200 { edges:[{ target_id, edge_type, weight }] }

Batch & bulk

POST/v1/memories/batchHosted Cloud
Encode up to 1000 memories at once (plain or gzip+base64 body; ≤64 MiB decompressed).
Body{ memories:[{ content, type?, salience?, context?, namespace }] }
Returns201 { ids, encoded, failed, compressed_size, raw_size }
POST/v1/memories/recall/batchHosted Cloud
Run several recall queries in one request.
Body{ queries:[{ query, namespace, token_budget? }] }
Returns200 { results: MemoryResult[][] }
DELETE/v1/memories/by-contextHosted Cloud
GDPR-style bulk delete: forget every memory whose context key equals a value. (POST /v1/memories/by-context/delete is an alias.)
Body{ namespace, context_key, context_value }
Returns200 { deleted }

Learning

POST/v1/consolidateHosted Cloud
Run offline consolidation over a namespace.
Body{ namespace }
Returns200 { patterns_found, edges_created, memories_created, contradictions }
POST/v1/feedbackHosted Cloud
Submit retrieval feedback for a memory; drives reward + dampening.
Body{ memory_id? | recall_id?, useful?, score? }
Returns200 { updated }

Prospective memory (intentions)

POST/v1/intentionsLocal Engine Only
Create an intention with a context / time / event trigger.
Body{ trigger_type, trigger_data, action, salience, expires_at?, namespace }
Returns201 { id }
GET/v1/intentions?namespace=NSLocal Engine Only
List active (unfired, unexpired) intentions.
Body(query)
Returns200 { intentions:[{ id, trigger_type, action, salience, expires_at?, created_at, namespace }] }
DELETE/v1/intentions/:idLocal Engine Only
Delete an intention.
Body(none)
Returns200 { deleted }

Introspection

GET/v1/healthHosted Cloud
Engine health / liveness: counts and tier distribution.
Body(none)
Returns200 { memory_count, edge_count, tier_distribution, namespace_count }
GET/v1/stats?namespace=NSHosted Cloud
Per-namespace aggregate statistics.
Body(query)
Returns200 (MemoryStats)
GET/v1/meta/knowledge-map?topic=T&namespace=NSLocal Engine Only
Metamemory confidence/gap entry for a topic.
Body(query)
Returns200 (KnowledgeMapEntry)
GET/v1/meta/contradictions?namespace=NSLocal Engine Only
List detected contradictions in a namespace.
Body(query)
Returns200 { contradictions:[…] }
GET/v1/graph/dot?namespace=NS&max_nodes=50Local Engine Only
Export the namespace graph as Graphviz DOT text.
Body(query)
Returns200 text/plain (DOT)
GET/v1/trace/:recall_idHosted Cloud
Fetch a stored recall trace (from enhanced recall).
Body(none)
Returns200 (RecallTrace)
GET/v1/events/streamHosted Cloud
Server-Sent Events stream of lifecycle events (30s keep-alive).
Body(none)
Returnstext/event-stream
GET/v1/events?since=RFC3339Hosted Cloud
Poll recent lifecycle events after a timestamp.
Body(query)
Returns200 [{ event_type, data, timestamp, id }]

An interactive OpenAPI 3.1 specification is served at /v1/openapi.json (with documentation at /docs#rest). Auth and rate-limit errors return {code, status, message}; most other errors return standard HTTP status codes.

Code intelligence

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

Method · PathAvailabilityPurpose
POST /v1/code/searchHosted Cloud + LocalSemantic search over indexed definitions (optional type filter).
POST /v1/code/explainHosted Cloud + LocalWhat a symbol is, who uses it (live scan), and its tests.
POST /v1/code/referencesLocal Engine OnlyEvery reference to a symbol — call / definition / mention, graded.
POST /v1/code/findLocal Engine OnlyFind files/dirs whose path matches a name, shallowest first.
POST /v1/code/impactLocal Engine OnlyBlast radius: transitive reverse-call walk of what could break.
POST /v1/code/call-treeLocal Engine OnlyNested caller (in) or callee (out) tree.
POST /v1/code/dead-codeLocal Engine OnlyDefinitions with no in-namespace caller (removal candidates).
POST /v1/code/test-gapsLocal Engine OnlyNon-test definitions with no direct test caller.
POST /v1/code/renameLocal Engine OnlyReviewed line-level edit worklist for a rename (not an auto-patcher).
POST /v1/code/diff-riskLocal Engine OnlyFor a set of changed symbols, their direct callers at risk.
POST /v1/code/implementorsLocal Engine OnlyTypes whose impl Trait for Type names a symbol (Rust today).
POST /v1/code/diff · /errorLocal Engine OnlyNatural-language analysis of a unified diff · an error/stack trace.
POST /v1/code/build-edgesLocal Engine OnlyMaterialise Contains + DependsOn edges after indexing (idempotent).

Example: find everything a change would affect

curl -X POST https://memoreal.kolivri.com/v1/code/impact \
  -H "Authorization: Bearer $MEMOREAL_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). Search and explain run natively on Hosted Cloud + Local, while structural AST analysis runs on the Local CLI Engine. Findings are graded (exact / heuristic / ambiguous) with confidence scores — treat rename and dead-code output as a reviewed worklist, not an automatic edit.

SDKs & API Clients

TypeScript / JavaScript (Node 20+ & Browser)

No external package installation required — call the API directly with standard fetch or paste this clean zero-dependency client into your codebase:

// Zero-dependency TypeScript / Node 20+ fetch client
export class MemorealClient {
  private readonly baseUrl: string;
  private readonly apiKey: string;

  constructor(
    baseUrl = "https://memoreal.kolivri.com",
    apiKey = process.env.MEMOREAL_KEY || process.env.MEMORIA_KEY || "mem_dev_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  ) {
    this.baseUrl = baseUrl.replace(/\/+$/, '');
    this.apiKey = apiKey;
  }

  private async request<T>(path: string, options: RequestInit = {}): Promise<T> {
    const res = await fetch(`${this.baseUrl}${path}`, {
      ...options,
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${this.apiKey}`,
        ...options.headers,
      },
    });
    if (!res.ok) {
      const err = await res.json().catch(() => ({ message: res.statusText }));
      throw new Error(`Memoreal HTTP ${res.status}: ${JSON.stringify(err)}`);
    }
    return res.json() as Promise<T>;
  }

  /** Store a memory (Episodic, Semantic, Buffer, Core) */
  async encode(content: string, namespace = 'my-project', type = 'Episodic', salience = 0.8) {
    return this.request<{ id: string; tier: string }>('/v1/memories', {
      method: 'POST',
      body: JSON.stringify({ content, namespace, type, salience }),
    });
  }

  /** Assemble a token-budgeted memory context block */
  async buildContext(query: string, namespace = 'my-project', token_budget = 4096) {
    return this.request<{ context: string; memories_used: number }>('/v1/memories/context', {
      method: 'POST',
      body: JSON.stringify({ query, namespace, token_budget }),
    });
  }

  /** Recall memories scored by BM25, tier weight, and salience */
  async recall(query: string, namespace = 'my-project', token_budget = 4096) {
    return this.request<{ results: Array<{ score: number; memory: any }> }>('/v1/memories/recall', {
      method: 'POST',
      body: JSON.stringify({ query, namespace, token_budget }),
    });
  }
}

// Backward-compatible alias for existing integrations
export { MemorealClient as MemoriaClient };

// Example usage:
const memoreal = new MemorealClient("https://memoreal.kolivri.com", process.env.MEMOREAL_KEY || process.env.MEMORIA_KEY);
await memoreal.encode("Deployments require passing end-to-end integration tests", "my-project");
const { context } = await memoreal.buildContext("deployment requirements", "my-project");
console.log(context);
MethodEndpointAvailability
encode(content, ns?, type?, salience?)POST /v1/memoriesHosted Cloud
buildContext(query, ns?, budget?)POST /v1/memories/contextHosted Cloud
recall(query, ns?, budget?)POST /v1/memories/recallHosted Cloud
forget(id)DELETE /v1/memories/:idHosted Cloud
encodeBatch(memories)POST /v1/memories/batchHosted Cloud
consolidate(ns) · feedback(id, useful)POST /v1/consolidate · /v1/feedbackHosted Cloud
deleteByContext(key, val, ns?)DELETE /v1/memories/by-contextHosted Cloud
health() · stats(ns)GET /v1/health · /v1/statsHosted Cloud

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 memoreal import Memoreal

m = Memoreal()  # 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, connect via MCP (https://memoreal.kolivri.com/v1/mcp) or use the HTTP API with standard fetch or requests. Local Rust workspace crates (memoria-core, memoria-server) are also available in the repository for embedded engine development.

CLI

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

CommandDoes
memoreal healthGraph stats: memory/edge counts, tier distribution.
memoreal encode --namespace NS --content T --type episodicEncode a memory; prints its id.
memoreal recall --namespace NS --query T [--budget 4096]Recall ranked results for a query.
memoreal search --namespace NS --query TBM25 lexical search (top 20).
memoreal forget --id UUIDDelete a memory by UUID.
memoreal stats --namespace NSPer-namespace stats + health assessment.
memoreal consolidate --namespace NSRun offline consolidation.
memoreal migrate --namespace NSRun tier promotion/demotion/GC.
memoreal contradictions --namespace NSDetect contradictory memory pairs.
memoreal meta --namespace NS --topic TMetamemory knowledge-map for a topic.
memoreal export --namespace NSDump all memories in a namespace as JSON.
memoreal import json|csv --file F --namespace NSImport memories from a file.
memoreal graph dot|ascii …Export the graph (Graphviz DOT / ASCII neighborhood).
memoreal backup|restore --file FChecksummed JSON backup / restore.
memoreal trace --lastShow the most recent recall trace.
memoreal pii-check --content TScan text for PII.

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

FAQ & limits

Is my data isolated from other customers?

Yes. Your key resolves to your own organization and namespace, and every read, write, and graph traversal enforces strict tenant boundaries — one organization’s data can never surface in another’s query.

What happens when I lose a key?

You can’t recover it — only a hash is stored. Mint a new key from your account and revoke the old one. Revocation is effective on the next request.

Do I have to manage tiers or forgetting myself?

No. Promotion, demotion, and garbage-collection between Buffer → Episodic → Semantic → Core happen automatically from salience and access patterns. Pin a memory or set it to Core to keep it forever.

How big can a batch be?

Up to 1000 memories per /v1/memories/batch call; the decompressed payload must be ≤64 MiB. For larger loads, send multiple batches.

What are the rate limits?

Requests are rate-limited per key (429 with a Retry-After header when you exceed it), and each org has a rolling usage quota (402 when it’s exhausted, until the window advances). The exact numbers scale with your plan — see your account.

Which memory-type casing do I use?

PascalCase (Episodic) over the HTTP API and TypeScript SDK; lowercase (episodic) over MCP, the Python SDK, and the CLI.

How do I use code intelligence?

Index a repo into a code/<project> namespace, then call the /v1/code/* endpoints or the corresponding MCP tools. Findings are graded by confidence — treat rename/dead-code as a reviewed worklist.

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