a-memory

Name: Ariel Memory
Author: cipher208

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

bash

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:

bash

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:

json

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

HTTP transport with dashboard:

bash

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

Or run from source:

bash

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

The five primitives

Agents see exactly six tools — one verb per intent (5 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)
`evolve`	grow	Records personality/rules evolution for the agent
project	continue	Per-project identity, decision log, artifact map, code index

Quick demo — Python MCP client:

python

# 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"])

65 fine-grained operations exist in total, grouped into coherent opt-in tiers: the 6 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, brief, and review (staged mutations) — e.g. ARIEL_EXPOSE=primitives,context,insight,write,wiki,brief,review (57 tools; the remaining 8 are admin-tier, exposed only via ARIEL_EXPOSE=all).

⚠️ 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; 65 tools (tiered exposure; 57 on the common combo, 6 primitives by default) including `/recall` protocol (multi-axis + disclosure triggers), session continuity recap (/new recovery pack), 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, 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), `DREAM:` markers, session-start inject, gap reports, compaction-aware rehydrate (drift log + salvage + one-shot rehydrate blocks), ru-NER privacy gate (cyrillic PERSON/ORG/LOC masking). Native integrations: Hermes runs ariel as an in-process `MemoryProvider` plugin, MiMoCode via a fork-hooks plugin, CowAgent via code-level hooks. Wiring guide →
🎯 Skills	Skill = Memory: agent-read Markdown pages (first-class `skill` wiki type), progressive disclosure (`wiki_list → wiki_search → wiki_read` with related-facts hydration), 4KB lint cap, promotion from `DREAM: skill:` episodes, shared SSOT sync across agents, usage-driven reinforcement — skills guide →
🔐 Security	NaCl `SecretBox` (XSalsa20-Poly1305) envelope encryption for auth/saga secrets, master key chain, rate limiting
🛠️ Ops	Auto-backup cron, saga rollback pattern, Prometheus metrics, read-only replica, hourly self-maintenance (decay + consolidation + auto-VACUUM)
🌐 Wiki	FTS5-indexed markdown files — edit in Obsidian/VS Code, search from MCP, 6 analytical perspectives (`wiki_summarize`), schema lint on save, external-dir sync

Architecture

mermaid

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	✅ 6 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, 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.