Ariel Memory

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.

[CI] [codecov] [License: MIT] [Python 3.11+] [Ruff] [MCP Compatible] [Docs] [Release]

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-memorya-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.gitcd a-memoryuv syncuv 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:

Quick demo — Python MCP client:

# think — routed to the right store automaticallyawait session.call_tool("think", {"text": "User prefers dark mode", "layer": "user"})
# dream — finds it across every store, a week laterres = 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

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

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

• 4-layer memory hierarchy with layer isolation
• Hybrid search (FTS5 + MIB binary embeddings)
• Knowledge graphs (epistemic + temporal)
• Hourly consolidation sweep + DB self-maintenance
• mcp 2.x native SDK
• Repo renamed to Cipher208/a-memory; PyPI package live (pip install a-memory)
• Temporal timeline wired end to end (think/evolve/project events + dream recent digest)
• Dream-cycle inject + auto-generated CONTEXT.md snapshot (curated context + 6 wiki perspectives + recent episodes, per-layer, per-agent)
• Phase C — auto-hooks keystone (push-model memory: per-agent conversation daemons, external event dispatcher, importance-gated auto-save, staged mutations with review/revert, dream markers, session-start inject, gap reports; guide)
• Phase D — compaction-aware rehydrate (drift log + salvage into the summarizer + one-shot rehydrate blocks; MiMoCode plugin / Hermes native MemoryProvider / CowAgent hooks — integration guide)
• Phase D — /recall protocol (multi-axis proportional recall: markers → session → semantic → expand → day; drives Hermes per-turn prefetch)
• Phase D — Skill = Memory (Markdown skills as a first-class wiki type, progressive disclosure wiki_list → wiki_search → wiki_read, 4KB lint cap, promotion pipeline, shared SSOT sync, usage-driven evolution — skills guide)
• Phase D — working memory + meta-memories (agent scratchpad re-injected at session start, deterministic reflections, smart context budget with weighted floors, counterfactual notes, was_useful quality feedback loop)
• Phase D — memory tools D1.2-D1.9 (session continuity recap + steering hints, tool-output compression + recall verification, provenance fact-blame, Memory Query DSL, typed memory schemas, declarative rules engine; coherent ARIEL_EXPOSE tiers: context / insight / write)
• Phase E — hardening & closure (18 items across 3 waves): durability — atomic L1 persistence (temp→fsync→os.replace) + per-instance ring files, a circuit breaker guarding the embedding model path (3 failures → open 30s → hash-fallback keeps recall serving), least-privilege wiki roots + traversal-safe backup restore; operations — memory_diagnose/memory_heal (DB/migrations/L1-files/breaker checks + remigrate/reset-breakers/purge), integrity score in the report card, <cache:break> markers + stable-first inject ordering for provider prompt caches; retrieval — faceted tag queries (dimension:value, same-dim OR / cross-dim AND), memory-kind weights in ACT-R scoring, disclosure triggers («when X, surface Y» recall-side rules); wiring — real context_threshold/memory_pressure emitters (Hermes plugin + autohooks daemon), on_turn_end event, wiki_write staged mutations with revert, transition-level consolidation revert, causal-link producer on memory_graph_add; validation — DREAM markers anchored to message start (document-fragment false positives eliminated), post-compaction semantic audit (episode coverage by the L4 set)
• Phase F — L0→L4 pipeline (bi-temporal fact intervals, hot/warm/cold L0 tiers with CLACK export, SHA-256 capture dedup, hash-chained journal, provenance drill-down)
• Phase G — self-wiring graph (12 deterministic miners: sessions, markers, provenance, co-retrieval, entities, zero-result questions, wiki↔fact bridges)
• Phase H closeout — EDM/ITS dual-route rerank + eval harness (NDCG@5, drift score, negative-control protocol, LongMemEval-S adapter)
• S17 Stage-1 tail — deterministic retrieval mode, ENGRAM procedural kind, AdaptiveRAG pre-gate (27 LLM-free query features), EMA importance gate, counter-signal aliases, SHA-256 L0 dedup, zero-result miner, ru-NER privacy gate
• S18-19 wave (15 items) — global is_current view + changed_since delta mode, per-query ACT-R min-max, per-block max_chars, semantic dedup gate, channel-granular sources, 3-option conflict contract (supersede/retain/annotate), orphan-anchor GC, nightly gap-registry, per-agent harness breaker, provenance edge filter, wiki↔fact metadata backlinks, wiki_read related-facts hydration, RU lemma keys (pymorphy3), 2-class textcat pilot (flag-gated), S17 supplements 8-11 (cold-archive drill-down, confirming layer, junk-vector detector, HDBSCAN clusters), B6 anti-hub degree cap
• S20 eval — №11 ablation on MINI + LongMemEval-S (50-question stride): full dual-route arm wins on both datasets, published-baseline comparison (GPT-4o long-context league, above ChatGPT-memory); dense e5-small run 3: no parity gain over hash on this split — hash stays prod
• Hardening wave (1.12.0) — the speaker-layer defect fixed at the writer (distill_and_route read a kind where it needed the speaker) plus a provenance-based purge of the 65 rows it had already mislabelled; a kind classifier that no longer hands a permanent label to harness boilerplate or to compound words (pre-commit, mergeCommit); the gap registry getting the reader S18 planned but never built; the L4 expectation measured against the L4 bar instead of the L3 one (71% of the diff_gap backlog was that one wrong number); and a quality gate that could not fail now failing correctly — an unpinned scanner had silently moved its JSON schema out from under it
• Screenshot / asciinema demo in README
• LLM-assisted consolidation on top of the deterministic sweep
• Stage 2 — tool-surface redesign (slot system, URI keys, inject/key consolidation — planned with the A-remainder)
• LongMemEval full 500-question split + dense-aware threshold retraining (e5-small parity shown, not a win on the 50-question stride)

Contributing

PRs welcome! See CONTRIBUTING.md.

License

MIT © Cipher208

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

[Star History]