Anamnesis

Cross-machine memory for Claude Code

Your coding agent's memory, written on your desktop, already on your laptop 1,000 km away.

Website ·
Docs ·
Why it's honest ·
Dashboard

uv tool install anamnesis-memory && anamnesis init

</div>

---

> ἀνάμνησις (anamnesis) - Greek for recollection; the act of calling knowledge back to mind.

Anamnesis is a local-first, file-based memory layer for Claude Code that
syncs automatically across all of your own machines. Everything Claude learns about your projects -
conventions, architecture decisions, fixes that worked, what you did yesterday - is captured as plain
markdown, indexed for fast retrieval, and kept in sync across your fleet over your private network.

No cloud account required. Your memory stays on your machines, version-controlled, human-readable, and yours.

The problem

Claude Code's memory is trapped on one machine. Move to your laptop and it starts from zero. The existing
fixes - syncing a SQLite file through Dropbox or iCloud - are fragile and corrupt the database. Cloud memory
APIs solve cross-tool sharing on a single device, but nobody solves seamless background sync of a coding
agent's memory across the machines you already own. That gap is Anamnesis.

How it works

  ┌─────────────┐        git over your private mesh        ┌─────────────┐
  │  desktop    │  ◄────────────  (Tailscale)  ────────►   │  laptop     │
  │             │                                          │             │
  │  Claude Code│                                          │  Claude Code│
  │     ▼       │                                          │     ▼       │
  │  MCP server │   markdown (source of truth)             │  MCP server │
  │     ▼       │   + SQLite FTS index (rebuilt locally)   │     ▼       │
  │ ~/.anamnesis│                                          │ ~/.anamnesis│
  └─────────────┘                                          └─────────────┘

- File-first. Memory is markdown - human-readable, git diff-able, and exactly the shape the latest
models are best at using. (The research is unambiguous that simple files beat heavyweight graph stores
for this job.)
- Structured where it counts. A SQLite FTS5 index gives sub-millisecond BM25 recall; on a real corpus
it hits 94% recall@3, so vectors stay out until measurements say otherwise.
- Robust sync. Markdown is synced via git over your private Tailscale mesh and
the index is rebuilt locally - the database file is never synced and never corrupts. Conflicting edits
surface as git conflicts instead of being silently dropped.
- Claude-Code-native. An MCP server with read-only auto-query tools, plus session hooks: SessionStart
injects the relevant notes, SessionEnd captures a durable summary and syncs it. Zero manual steps.
- Memory that improves itself, audited. A reflection pass (any OpenAI-compatible model, config-driven)
distills session logs into durable notes, and a recall-gated merge consolidates duplicates. Every
generated note carries provenance and confidence in its front-matter, and nothing applies unless an eval
set proves recall is preserved.
- A git-like memory GUI. A dashboard to browse, search, edit, and see the history of your memory across
every machine.

Quickstart

Prereqs: Claude Code, uv, and git.

uv tool install anamnesis-memory && anamnesis init

That is the whole install. anamnesis init registers the MCP server with Claude Code at user scope,
installs the SessionStart / SessionEnd / PreCompact hooks, configures the store at ~/.anamnesis, and runs
a first sync. It is idempotent (backs up settings.json, never duplicates a hook), --print shows the full
plan without writing anything, and --local-only skips the remote until you want one.

Claude Code gets five tools: memory_search / memory_list / memory_status (read-only, safe to
auto-approve), memory_write, and memory_sync. Full reference:
CLI ·
MCP tools ·
configuration.

<details>
<summary>Developing from source instead</summary>

git clone https://github.com/oscardvs/anamnesis && cd anamnesis/server
uv venv --python 3.12
uv pip install -e ".[mcp,dev]"
uv run anamnesis init --print

The repo also ships a project-scoped .mcp.json. Claude Code launches MCP servers with a filtered
environment, so ANAMNESIS_HOME / ANAMNESIS_MACHINE_ID / ANAMNESIS_GIT_REMOTE belong in its "env"
block, not your shell. Server internals: server/README.md.

</details>

Cross-machine sync

Memory is a git repo (~/.anamnesis/memory/) synced over your private
Tailscale mesh - or any git remote you control. Set it up once:

1. Put every machine on the same tailnet (install Tailscale,
tailscale up). Pick one always-on machine to host the shared repo; tailscale status prints its
MagicDNS name (for example host.your-tailnet.ts.net).

2. Create one shared bare repo on the host:

   git init --bare -b main ~/anamnesis-memory.git

   

3. Point each machine at it:

   anamnesis init --remote 'you@host.your-tailnet.ts.net:anamnesis-memory.git'

   

Sync runs commit -> pull --rebase -> push and rebuilds the local index after pulling, so a note written on
one machine is searchable on the others within a sync cycle. Started local-only? Re-run init --remote ...
whenever; the store attaches to the remote and pushes its whole history.

Hands-off capture, sync, and reflection

The hooks anamnesis init installs make memory automatic:

- SessionStart injects the most relevant notes for the current project (your global preferences, the
project's durable notes, a couple of recent session summaries) and kicks off a background sync.
- SessionEnd captures a durable episodic note from the session transcript and syncs it, so it is on
your other machines by the next session. PreCompact does the same before context compaction.
- Reflection (optional). Point anamnesis config set reflection.provider ... at any OpenAI-compatible
model and anamnesis reflect distills accumulated session notes into durable conventions; with
reflection.auto it runs itself at session end once a project crosses the threshold. anamnesis merge
consolidates near-duplicates, and both are gated: they only apply if recall on your eval set holds.
- Import. anamnesis import mirrors Claude Code's own per-project memory into the store, so nothing
you already taught it is left behind.

Manual setup instead of init: copy examples/hooks.settings.json into
~/.claude/settings.json and point it at your install.

Measured, not promised

Memory tools love token claims, so we measured ours and published the harness:
bench/cross-machine-tokens/ runs the same scripted task on a fresh machine
with and without Anamnesis (real injected memory block, real agent runs, reproducible on a Pro/Max
subscription - no API key needed). Result: about 8% fewer input tokens, same task, conventions known from
the first turn. The point is not the token bill; it is never re-teaching your setup. The earlier null
result is published right next to it.

Dashboard

A git-like GUI for your memory: browse and full-text search every note, edit markdown with per-note history,
see your whole fleet (which machine wrote what, when it last synced), and drive reflection from the browser.
Provenance badges show where every note came from: you, a session capture, reflection, or import.

npx anamnesis-dashboard      # http://localhost:3000

or, from the CLI you already have:

anamnesis dashboard

Needs Node 20 or newer. From a repo clone, cd dashboard && npm run dev still works for development.

It is a thin read/write client over the same local store the MCP server uses (it reads the SQLite index
directly and shells out to the anamnesis CLI for writes and sync). Use --port, --store, and
--no-open to adjust how it serves. See dashboard/README.md for configuration
and design notes.

Status

v0.1.0 is on PyPI. The local-first core is complete and validated on real hardware: store, MCP server,
hooks, git sync, one-command install, the reflection/consolidation loop (measured on a real corpus: working
set shrank ~14% with recall unchanged), and the dashboard. Early and moving fast - APIs may still change;
watch/star to follow along. Roadmap next: hosted relay for users without their own mesh, team memory.

Repository layout

| Path | What |
| ------------- | --------------------------------------------------------------------- |
| server/ | The MCP memory server + CLI (Python, FastMCP). |
| dashboard/ | The git-like memory GUI (Next.js). |
| site/ | The public website and docs (live). |
| bench/ | The honest token benchmark + demo recording pipeline. |
| scripts/ | Dev & ops helper scripts. |

Contributing

Issues and discussion are welcome. If you try the install and anything is rough, an issue with the exact
command and output is a gift.

License

Apache License 2.0 - see NOTICE.