How do I install Ariel Memory?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Ariel Memory need an API key?

No required environment variable is listed on this record.

What transport does Ariel Memory use?

Ariel Memory runs locally over stdio.

When was Ariel Memory last checked?

Last checked 2026-11-09. Two-layer memory MCP server for AI agents with 37 tools, RAG, graphs, wiki, auth

Ariel Memory MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y [email protected]

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1claude mcp add io.github.cipher208-ariel-memory -- npx -y mcp-ariel-memory@1.0.0

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.cipher208-ariel-memory": {4      "command": "npx",5      "args": [6        "-y",7        "[email protected]"8      ]9    }10  }11}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 1.0.0
Last checked

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

a-memory

Your AI agents forget. a-memory makes them remember. 4-tier agent memory with hybrid search and a real knowledge graph — all in plain SQLite files. Zero cloud. Zero external APIs.

Also available on PyPI: pip install a-memory — optional extras: a-memory[embeddings] for real multilingual embeddings.

Why SQLite?

Every other memory server sends your agent's data through a cloud API or requires a separate vector database.

a-memory stores everything in SQLite files on your machine.

Zero infrastructure. No Docker, no database server, no embedding API keys.
Zero data leaving your network. Works air-gapped.
Layer-isolated by design. User facts and agent identity never share a namespace.
One directory = entire memory. Back up with cp, sync with rsync.

Why this exists

Three problems a-memory solves:

① Agent self-evolution — your AI stops repeating mistakes between sessions. It remembers decisions, errors, and corrections in a dedicated agent layer, and an hourly consolidation sweep promotes what matters into long-term facts.

② User persona persistence — your agent knows who it's talking to even after weeks of silence. Preferences, history, emotional context live in the user layer, isolated from agent identity.

③ Project continuity — project tracks per-project context: decisions with rationale and outcomes, artifact maps, a graphify-powered code index — so a fresh session picks up where the last one left off.

Get started

pip install a-memory
a-memory          # MCP server on stdio — connect from any MCP client

The server runs without these, but the privacy gate (hooks ingest) and the graph miners need two spaCy NER models. Neither is on PyPI — en-core-web-sm 404s there and ru-core-news-sm is an unrelated placeholder — so they can only be installed by wheel URL, and a wheel URL cannot be a dependency: PyPI rejects any distribution whose metadata carries a direct URL. One command installs them from the URLs the package already knows:

a-memory-ner                 # install (console script, ships in the wheel)
a-memory-ner --check         # report what is missing, install nothing

From a source checkout, python scripts/install_ner_models.py is the same command.

Skipping them is safe: the gate falls back and reports degraded instead of failing.

Point your MCP client at it:

{
  "mcpServers": {
    "a-memory": {
      "command": "a-memory"
    }
  }
}

HTTP transport with dashboard:

a-memory --transport http --port 8000 --dashboard

Or run from source:

git clone https://github.com/Cipher208/a-memory.git
cd a-memory
uv sync
uv run ariel-memory

The seven primitives

Agents see exactly seven tools — one verb per intent, plus the event bridge (6 verbs + memory_hook), no tool-choice paralysis:

Primitive	Intent	What it does
`think`	remember	Routes content to the right layer (L4 facts / L3 episodes / wiki / graph) based on importance, emotion, and relations
`dream`	recall	Hybrid search across ALL layers (FTS5 + binary embeddings + wiki + graph), returns a token-budgeted digest
`forget`	let go	Context-aware deletion with Shadow Bin archival (exact / fuzzy / recent) — plus a dry run that writes nothing and an undo that puts back what the bin kept
`evolve`	grow	Records personality/rules evolution for the agent
`project`	continue	Per-project identity, decision log, artifact map, code index
`wake_up`	resume	One-call memory lift for a fresh session — the critical set in one call, instead of walking a recall protocol step by step
`memory_hook`	signal	The event bridge: fires one lifecycle event (`session_started`, `new_message`, …) so an external harness can push memory into ariel on its own schedule

Quick demo — Python MCP client:

# think — routed to the right store automatically
await session.call_tool("think", {"text": "User prefers dark mode", "layer": "user"})

# dream — finds it across every store, a week later
res = await session.call_tool("dream", {"query": "dark mode preference"})
print(res["summary"])

66 fine-grained operations exist in total, grouped into coherent opt-in tiers: the 7 primitives are exposed by default; add context (recall protocol, /new session recap, smart context budget, steering hints, tool-output compression), insight (Memory Query DSL, provenance fact-blame, quality loop, reflections, stats), write (typed memory schemas, declarative rules engine, scratchpad, counterfactuals, episodes), plus wiki and review (staged mutations, memory_report_card, daily_brief). The usual live-agent surface is one preset — ARIEL_EXPOSE=agent (59 tools), equivalent to primitives,context,insight,write,wiki,review. The remaining 7 are admin-tier: ARIEL_EXPOSE=operator (66) or all.

Tier history, because older guides still name a brief tier: it was dissolved on 2026-09-07 — daily_brief now rides review. If a doc tells you to pass brief, it is pre-1.10 and the token is simply ignored.

⚠️ Env sanitization gotcha (stdio): MCP clients pass a sanitized environment to stdio servers — setting ARIEL_EXPOSE in your shell profile does nothing. Define the tier set in your MCP client config (the env block of the server entry — see configuration guide). The server logs its resolved surface at startup (tool exposure: N/M tools) — if your agent reports seeing only the primitives, check that line first, then restart the client session (tool lists are cached per session).

Features

Category	What's inside
🧠 Memory	L1 Reflex (atomic persistence) → L2 Sessions → L3 Episodic → L4 Core, importance scoring, typed memory kinds with TTL policies, layer isolation; bi-temporal fact history (is_current view hides superseded rows globally, `changed_since` delta-polling, drill-down to raw source surviving cold archival), hash-chained L0 journal with hot/warm/cold tiers; 66 tools (tiered exposure; 59 on the agent preset, 7 primitives by default) including `/recall` protocol (multi-axis + disclosure triggers), session continuity recap (/new recovery pack), one-call `wake_up`, open-question registry surfaced in the session brief, steering hints, tool-output compression + recall verification, provenance fact-blame, Memory Query DSL (faceted tags), typed memory schemas, a declarative rules engine, smart context budget (weighted token floors), reflections, counterfactuals, was_useful quality loop, operator diagnose/heal + integrity score
🔍 Search	FTS5 + MIB binary embeddings + hybrid RRF ranking, multi-source merge (RAG + Wiki + Episodic + Core + Graph), EDM/ITS dual-route rerank (information-gain scoring, №11-eval winner), semantic dedup gate (cosine, opt-in), RU-lemma key normalization (pymorphy3), counter-signal pessimisation, ACT-R activation with per-query min-max multipliers and memory-kind weights, embedding-path circuit breaker (graceful hash-fallback), deterministic retrieval mode, dream digest
🕸️ Graph	Epistemic knowledge graph + temporal timeline, typed nodes and edges, BFS traversal, 1-hop GraphRAG expansion (provenance-aware edge filter), 12 self-maintaining miners (degree-capped anti-hub, wiki↔fact provenance bridges with metadata backlinks, co-retrieval, zero-result gaps), orphan-anchor GC, nightly gap-registry — and a reader for it: the registry now records how often each hole is re-observed (`seen_count`) and surfaces the most persistent ones in the session brief, so an agent sees her own unanswered questions instead of a table nobody reads. Opt-in HDBSCAN embedding clusters with louvain agreement
📁 Projects	Decision log (what/why/outcome), artifact map, graphify code index — survives between sessions
⚡ Auto-Hooks	Push-model memory: a per-agent daemon tails the conversation and ariel saves what matters on its own — importance thresholds (EMA-adaptive), staged mutations (proposal → review → apply → revert), markers, session-start inject, gap reports, (drift log + salvage + one-shot rehydrate blocks), ru-NER privacy gate (cyrillic PERSON/ORG/LOC masking). : Hermes runs ariel as an in-process plugin, MiMoCode via a fork-hooks plugin, CowAgent via code-level hooks.

Architecture

graph TD
    A[LLM Agent] -->|MCP Protocol| B[mcp_server]
    B --> C{Importance Scoring}
    C --> D[L1: ReflexBuffer]
    D --> E[L2: SessionStore]
    E --> F{EmotionTrigger?}
    F -->|high emotion| G[L3: EpisodicMemory]
    F -->|normal| H[L4: CoreMemory]

    B --> I[RAG Engine]
    I --> J[FTS5 Search]
    I --> K[MIB Binary Search]
    I --> L[Hybrid RRF Ranking]

    B --> M[Wiki System]
    M --> N[.md Files]
    M --> O[SQLite Index]

    B --> P[Knowledge Graphs]
    P --> Q[Epistemic Graph]
    P --> R[Temporal Graph]

    B --> S[Project Store]
    S --> T[Decisions / Artifacts / Code Index]

    U[Hourly Sweep] -->|consolidate| G
    U -->|promote| H
    U -->|auto-VACUUM| V[(SQLite)]

Comparison

	a-memory	mem0	letta (memgpt)	chroma
MCP native	✅ 7 primitives	❌ no MCP server	❌	❌
Layer isolation	✅ User vs Agent namespaces	❌	❌	❌
Local-only (no cloud)	✅ SQLite — 0 infra	⚠️ API or self-host Docker	❌ needs LLM API	✅ local OSS + Cloud option
Own semantic search (no API)	✅ FTS5 + MIB binary hybrid	⚠️ BM25+entity (LLM-dependent)	❌ LLM-only	⚠️ hybrid on Cloud only
Knowledge graph	✅ Typed nodes + edges + temporal timeline	⚠️ entities only	❌	❌
Envelope encryption (secrets)	✅ NaCl SecretBox (auth/saga secrets; memory data is plaintext SQLite)	❌	❌	❌
Lifecycle hooks	✅ 19 names (12 user + 13 agent slots), per-layer, config-gated	limited	limited	none
Self-maintenance	✅ Hourly consolidation + auto-VACUUM	❌	❌	❌
Backup / restore	✅ Auto-cron + saga rollback	❌	❌	❌

Notes (Sep 2026): mem0 now ships a self-hosted Docker image and a managed cloud with hybrid BM25+entity search; chroma is 29k★ and added hybrid+FTS5 to its Cloud tier (OSS server remains vector-only). What still differentiates a-memory: zero-infra SQLite (no Docker), NaCl-encrypted auth/saga secrets, layer isolation, hourly self-maintenance, and the temporal graph timeline.

Roadmap

Contributing

PRs welcome! See CONTRIBUTING.md.

License

⭐ If this project helps you, star it on GitHub.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Ariel Memory?

Does Ariel Memory need an API key?

What transport does Ariel Memory use?

When was Ariel Memory last checked?

Documentation

a-memory

Why SQLite?

Why this exists

Get started

The seven primitives

Features

Architecture

Comparison

Roadmap

Contributing

License