# 🗄️ Mnemo — the agent that never forgets

> A standalone AI assistant with a **persistent, temporal memory brain**. Tell it something in one session; ask about it in a completely new session and it recalls it — with who, what, *and when* — citing its sources.

Mnemo pairs a **temporal knowledge graph** ([Graphiti](https://github.com/getzep/graphiti) on [FalkorDB](https://www.falkordb.com/)) with a **Claude-session harness** (MCP tools + hooks + skills), so any Claude Code session can `remember` and `recall` across time. Its persona is *the archivist*: precise, unhurried, and it never states a fact without saying where and when it was true.

```
you (session 1):  "Remember: Marco leads Solaris; it launches Q4 2027; it depends on Helios."
you (session 2):  "Who leads Solaris, when does it launch, what does it depend on?"
Mnemo:            Lead: Marco · Launch: Q4 2027 · Depends on: Helios API   (as of 2026-07-17)
```

---

## How it works

Mnemo has two layers, exactly like a well-run agent: a **git-versioned identity** (markdown) and a **memory brain** (a graph database). A thin connection layer (MCP + hooks) plugs that brain into any Claude session.

```mermaid
flowchart TB
    subgraph SESSION["🧠 Claude session (this repo, any repo, or Claude Desktop)"]
        Q["You ask a question<br/>or state a fact"]
    end

    subgraph CONNECT["🔌 Connection layer"]
        direction LR
        MCPR["recall tool"]
        MCPM["remember tool"]
        SS["SessionStart hook<br/>· ensure DB up<br/>· surface tools"]
        STP["Stop hook<br/>· auto-learn:<br/>summarize + ingest"]
    end

    subgraph BRAIN["💾 Memory brain"]
        direction LR
        GR["Graphiti<br/>extract entities + typed edges<br/>bi-temporal validity"]
        FDB[("FalkorDB<br/>property graph")]
        EMB["fastembed<br/>local embeddings"]
    end

    Q -->|"tell"| MCPM --> GR
    Q -->|"ask"| MCPR --> GR
    GR <--> FDB
    GR <--- EMB
    SS -.injects context.-> SESSION
    STP --> GR
```

**Ingest and recall** — remembering turns text into a graph; recalling runs a hybrid search over it and answers in persona:

```mermaid
flowchart LR
    T["raw text<br/>(who / what / when)"] --> RM["remember()"]
    RM --> EX["Graphiti extraction<br/>· entities as typed nodes<br/>· relationships as typed edges<br/>· dates/status as node attributes"]
    EX --> KG[("FalkorDB<br/>temporal property graph")]

    QQ["a question"] --> RC["recall()"]
    KG --> HS["hybrid search_()<br/>vector + BM25 + graph traversal"]
    RC --> HS
    HS --> CTX["facts + entity attributes + source excerpts"]
    CTX --> ANS["Claude answers in the<br/>archivist persona, with citations"]
```

**Why memory survives across sessions** — nothing is shared between sessions except the graph on disk:

```mermaid
sequenceDiagram
    participant S1 as Session 1 (Mon)
    participant M as Mnemo
    participant DB as FalkorDB (volume)
    participant S2 as Session 2 (Fri · fresh process)
    S1->>M: remember("Marco leads Solaris, launches Q4 2027")
    M->>DB: extract → nodes + typed edges + valid-time
    Note over S1,DB: session ends → Stop hook summarizes & ingests it too
    S2->>M: recall("who leads Solaris? when?")
    M->>DB: hybrid search (edges + nodes + episodes)
    DB-->>S2: Marco · Q4 2027 (cited, as-of dated)
```

### The pieces

| Piece | File | Role |
|---|---|---|
| Identity | `personality.md`, `CLAUDE.md` | The archivist persona + operating rules (git-versioned) |
| Graph types | `mnemo/types.py` | Custom entities (`Project, Feature, Person, Meeting, Company`) + typed edges (`BelongsTo, WorksOn, Said, DependsOn, Attended`); dates/status/roles captured as **node attributes** |
| Memory wrapper | `mnemo/memory.py` | `ingest()` and `recall()` — recall uses Graphiti's `search_()` (edges **+** nodes **+** episodes), not the edge-only default |
| MCP server | `mnemo/mcp_server.py`, `.mcp.json` | Exposes `recall` / `remember` as MCP tools to any Claude session |
| Hooks | `.claude/hooks/` | SessionStart (ensure DB up, surface tools) · Stop (detached auto-learn worker) |
| Auto-learn worker | `mnemo/ingest_session.py` | Summarizes a finished session and ingests it (kill-switch: create `.mnemo-nolearn`) |
| Skills | `.claude/skills/{recall,remember}` | Ergonomic in-session use |
| Agent | `mnemo/agent.py` | Recalls, then answers in persona with citations |

Embeddings run **locally** (`fastembed`, 384-dim) so no embeddings key is needed; the LLM (extraction + answers) is **Claude**, and the client accepts both a standard `sk-ant-api03` key **and** a Claude Code `sk-ant-oat` OAuth token.

---

## How Mnemo compares

Most "AI memory" is either a flat vector store (good at *similar text*, blind to *relationships* and *time*) or an opaque per-user blob you can't inspect. Mnemo is a **temporal knowledge graph** with a Claude-native connection layer.

| Capability | **Mnemo** | Vanilla RAG (vector DB) | Mem0 | Raw Graphiti / Zep | Letta (MemGPT) | ChatGPT-style memory |
|---|:--:|:--:|:--:|:--:|:--:|:--:|
| Storage model | temporal property graph | flat chunks + vectors | vectors (+opt. graph) | temporal graph | tiered memory blocks | opaque per-user store |
| Typed relationships (who→what) | ✅ | ❌ | partial | ✅ | ❌ | ❌ |
| Temporal "as-of" / fact invalidation | ✅ bi-temporal | ❌ | limited | ✅ | ❌ | ❌ |
| Hybrid retrieval (vector + BM25 + graph) | ✅ | vector only | vector | ✅ | n/a | n/a |
| Cross-session persistence | ✅ | ✅ (if wired) | ✅ | ✅ | ✅ | ✅ (per user) |
| Auto-learns from each session | ✅ (Stop hook) | ❌ | manual | ❌ (library) | ✅ | ✅ |
| Claude Code / MCP native (drop-in tools + hooks) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Runs fully local (offline embeddings) | ✅ fastembed | depends | depends | depends | depends | ❌ cloud |
| Works with a Claude Code OAuth token | ✅ | n/a | n/a | n/a | n/a | n/a |
| Inspectable + cites source & time | ✅ | ❌ | ❌ | partial | partial | ❌ |

**Where Mnemo sits:** it is *not* a competitor to Graphiti — it is **built on Graphiti**. Think of it as **Graphiti (the brain) + a Claude-session body**: the MCP tools, the SessionStart/Stop hooks, the archivist persona, and the operational glue (OAuth-token auth, local embeddings, portable `${CLAUDE_PROJECT_DIR}` config, comprehensive `search_()` recall) that turn a memory *library* into a memory *agent* you can talk to.

**vs. a Notion/RAG-backed assistant** (e.g. an agent whose "memory" is a Notion database): those retrieve documents by similarity. Mnemo retrieves *facts and their relationships over time* — it can answer "who **used to** own this, and who owns it **now**", which flat retrieval cannot.

### What Mnemo is **not** (yet)

Honest scope — it's an experiment, not a product:

- No multi-user / auth on the graph — single local user.
- No managed hosting or horizontal scale (FalkorDB is a local Docker container).
- Extraction is LLM-driven and ~good, not perfect — occasionally a detail is missed (it will say "not found" rather than hallucinate).
- Auto-learned summaries vary in quality; recall-heavy sessions produce thin summaries.
- No daemon; the brain is up while `docker compose` is running.

---

## Quickstart

```bash
git clone <this repo> && cd mnemo-agent
cp .env.example .env          # set ANTHROPIC_API_KEY (sk-ant-api03 key OR sk-ant-oat token)
docker compose up -d          # start FalkorDB (defaults to port 6380)
python -m venv .venv && . .venv/bin/activate && pip install -r requirements.txt
python scripts/seed.py        # load the fictional sample data (Atlas project)
pytest -v                     # prove it: ingest + recall + temporal, all live
```

Then talk to it from any Claude Code session in this repo — the SessionStart hook wires the `recall`/`remember` tools automatically. To use Mnemo from *any* repo or Claude Desktop, add the `.mcp.json` server to your global config.

## Verified behaviour

Proven live (see the test suite + `docs/`):

- **Cross-session:** store in one `claude` process, recall in a separate one — including dates and dependencies.
- **Temporal:** after a reassignment, "who **currently** owns X" returns the new owner, not the stale one (edge invalidation).
- **Durable:** survives a `docker compose restart` (data in the FalkorDB volume).
- **MCP transport:** tools list and call over the real MCP stdio protocol.
- **Auto-learn:** finished sessions are summarized and ingested by the Stop hook.

## Design & internals

- `docs/2026-07-16-mnemo-agent-design.md` — the design spec.
- `docs/agent-memory-plan.md` — the graph-first memory model this is built on (why a graph, not a flat table; the 3-tier idea; engine selection).

## Tech stack

Python 3.12 · [Graphiti](https://github.com/getzep/graphiti) `graphiti-core` · [FalkorDB](https://www.falkordb.com/) (Docker) · [Anthropic Claude](https://www.anthropic.com/) (extraction + answers) · [fastembed](https://github.com/qdrant/fastembed) (local embeddings) · [MCP](https://modelcontextprotocol.io/) (FastMCP) · pytest.