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.

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:

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

---

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

| Lifecycle hooks | ✅ 19 names (12 user + 13 age