{
"markdown": "\n\n# Anamnesis\n\n**Cross-machine memory for Claude Code**\n\n[](https://pypi.org/project/anamnesis-memory/)\n[](https://github.com/oscardvs/anamnesis/actions/workflows/ci.yml)\n[](https://pypi.org/project/anamnesis-memory/)\n[](./LICENSE)\n\n[**Website**](https://oscardvs.github.io/anamnesis/) ·\n[**Docs**](https://oscardvs.github.io/anamnesis/docs) ·\n[**Benchmark**](#benchmark) ·\n[**Dashboard**](#dashboard)\n\n```bash\nuv tool install anamnesis-memory && anamnesis init\n```\n\n
\n\n---\n\n> **ἀνάμνησις** *(anamnesis)*: Greek for *recollection*, the act of calling knowledge back to mind.\n\nAnamnesis is a local-first, file-based memory layer for [Claude Code](https://claude.com/claude-code) that\nsyncs across your own machines. What Claude learns about your projects (conventions, architecture decisions,\nfixes that worked, what you did yesterday) is stored as plain markdown, indexed locally for search, and kept\nin sync over your private network.\n\nClaude Code's own memory stays on the machine where it was written. Copying a SQLite index through a cloud\nfolder such as Dropbox or iCloud corrupts it. Anamnesis syncs the markdown with git instead and rebuilds the\nindex on each machine, so a note written on your desktop is searchable from your laptop.\n\nNo cloud account is required. The memory stays on your machines, version-controlled and human-readable.\n\n## How it works\n\n```\n ┌─────────────┐ git over your private mesh ┌─────────────┐\n │ desktop │ ◄──────────── (Tailscale) ────────► │ laptop │\n │ │ │ │\n │ Claude Code│ │ Claude Code│\n │ ▼ │ │ ▼ │\n │ MCP server │ markdown (source of truth) │ MCP server │\n │ ▼ │ + SQLite FTS index (rebuilt locally) │ ▼ │\n │ ~/.anamnesis│ │ ~/.anamnesis│\n └─────────────┘ └─────────────┘\n```\n\n- **Files first.** Each note is a markdown file under `~/.anamnesis/memory/`, readable and `git diff`-able.\n The markdown is the source of truth; everything else is derived from it.\n- **A local index.** A SQLite FTS5 index gives keyword (BM25) recall. It is rebuilt locally and is not\n synced. On the project's eval set, keyword search reaches about 94% recall, so there is no vector store\n until measurements call for one.\n- **Sync over git.** The markdown is a git repo synced over your private [Tailscale](https://tailscale.com)\n mesh, or any git remote you control. Only the markdown travels; each machine rebuilds its own index, so\n the database file is not copied between machines. If two machines edit the same note, sync reports a git\n conflict instead of dropping either side.\n- **Claude Code integration.** An MCP server exposes read-only query tools, and session hooks do the rest:\n SessionStart injects the relevant notes, and SessionEnd captures a summary of the session and syncs it.\n- **Reflection and merge.** An optional reflection pass (any OpenAI-compatible model, set in config)\n distills session notes into durable notes, and `anamnesis merge` consolidates near-duplicates. Generated\n notes carry provenance and confidence in their front-matter. `merge --apply` is gated on your eval set so\n it does not lower recall, and `anamnesis eval` measures reflection before and after on a sandbox copy.\n- **A dashboard.** A web GUI to browse, search, edit, and read the history of your memory across every\n machine.\n\n## Quickstart\n\nPrereqs: [Claude Code](https://claude.com/claude-code), [`uv`](https://docs.astral.sh/uv/), and git.\n\n```bash\nuv tool install anamnesis-memory && anamnesis init\n```\n\n`anamnesis init` registers the MCP server with Claude Code at user scope, installs the SessionStart,\nSessionEnd, and PreCompact hooks, configures the store at `~/.anamnesis`, and runs a first sync. It is\nidempotent: it backs up `settings.json` and does not duplicate hooks. `--print` shows the full plan without\nwriting anything, and `--local-only` skips the remote until you want one.\n\nClaude Code gets five tools: `memory_search`, `memory_list`, and `memory_status` (read-only, safe to\nauto-approve), plus `memory_write` and `memory_sync`. Full reference:\n[CLI](https://oscardvs.github.io/anamnesis/docs/reference/cli) ·\n[MCP tools](https://oscardvs.github.io/anamnesis/docs/reference/mcp-tools) ·\n[configuration](https://oscardvs.github.io/anamnesis/docs/reference/configuration).\n\n\nDeveloping from source instead
\n\n```bash\ngit clone https://github.com/oscardvs/anamnesis && cd anamnesis/server\nuv venv --python 3.12\nuv pip install -e \".[mcp,dev]\"\nuv run anamnesis init --print\n```\n\nThe repo also ships a project-scoped `.mcp.json`. Claude Code launches MCP servers with a filtered\nenvironment, so `ANAMNESIS_HOME` / `ANAMNESIS_MACHINE_ID` / `ANAMNESIS_GIT_REMOTE` belong in its `\"env\"`\nblock, not your shell. Server internals: [`server/README.md`](./server/README.md).\n\n \n\n## Cross-machine sync\n\nMemory is a git repo (`~/.anamnesis/memory/`) synced over your private\n[Tailscale](https://tailscale.com) mesh, or any git remote you control. Set it up once:\n\n1. **Put every machine on the same tailnet** ([install Tailscale](https://tailscale.com/download),\n `tailscale up`). Pick one always-on machine to host the shared repo; `tailscale status` prints its\n MagicDNS name (for example `host.your-tailnet.ts.net`).\n\n2. **Create one shared bare repo on the host:**\n ```bash\n git init --bare -b main ~/anamnesis-memory.git\n ```\n\n3. **Point each machine at it:**\n ```bash\n anamnesis init --remote 'you@host.your-tailnet.ts.net:anamnesis-memory.git'\n ```\n The host itself uses the local path: `--remote \"$HOME/anamnesis-memory.git\"`.\n\nSync runs `commit -> pull --rebase -> push` and rebuilds the local index after pulling, so a note written on\none machine is searchable on the others within a sync cycle. If you started with `--local-only`, re-run\n`init --remote ...` later; the store attaches to the remote and pushes its history.\n\n## Hooks\n\n`anamnesis init` installs three Claude Code hooks:\n\n- **SessionStart** injects the most relevant notes for the current project (your global preferences, the\n project's durable notes, and a couple of recent session summaries) and starts a background sync.\n- **SessionEnd** captures an episodic note from the session transcript and syncs it, so it is on your other\n machines by the next session. **PreCompact** captures the same kind of note before context compaction.\n\nTwo more commands build on them:\n\n- **Reflection (optional).** Point `anamnesis config set reflection.provider ...` at an OpenAI-compatible\n model and `anamnesis reflect` distills accumulated session notes into durable conventions. With\n `reflection.auto` set, it runs at session end once a project has enough unreflected notes.\n `anamnesis merge` consolidates near-duplicates and only applies if recall on your eval set holds.\n- **Import.** `anamnesis import` copies Claude Code's own per-project memory into the store, so notes you\n already wrote for it are included.\n\nTo set the hooks up by hand instead of with `init`, copy\n[`examples/hooks.settings.json`](./examples/hooks.settings.json) into `~/.claude/settings.json` and point it\nat your install.\n\n## Benchmark\n\n[`bench/cross-machine-tokens/`](./bench/cross-machine-tokens) runs one scripted task on a fresh machine\ntwice: once without Anamnesis, where the agent explores the project to learn its conventions, and once with\nthe real SessionStart memory block injected. It drives the Claude Code CLI headlessly on a synthetic project,\nso a Pro/Max subscription is enough and no API key is needed.\n\nThe committed `result.json` (3 runs per arm on claude-opus-4-8) shows about 8% fewer total input tokens\nwith memory, 366k versus 336k on average, with output tokens and turn count about the same. The conventions\nwere known from the first turn instead of being rediscovered. An earlier version of the scenario used a\n5-file project and showed no difference; that null result is documented in the same README.\n\n## Dashboard\n\nA web GUI for the memory store: browse and full-text search every note, edit markdown with per-note history,\nsee every machine (which one wrote what and when it last synced), and run reflection from the browser.\nProvenance badges show where each note came from: you, a session capture, reflection, or import.\n\n\n\n```bash\nnpx anamnesis-dashboard # http://localhost:3000\n```\n\nor, from the CLI you already have:\n\n```bash\nanamnesis dashboard\n```\n\nNeeds Node 20 or newer. From a repo clone, `cd dashboard && npm run dev` works for development.\n\nIt is a thin read/write client over the same local store the MCP server uses: it reads the SQLite index\ndirectly and shells out to the `anamnesis` CLI for writes and sync. Use `--port`, `--store`, and\n`--no-open` to adjust how it serves. See [`dashboard/README.md`](dashboard/README.md) for configuration\nand design notes.\n\n## Status\n\nSeptember 2026: v0.1.3 is on PyPI. The local-first core is done and has been used across a real\nmulti-machine setup: the store, the MCP server, the hooks, git sync, the one-command install, the reflection\nand merge passes with their eval harness, and the dashboard. APIs may still change between releases.\n\nNext: a hosted relay for people without their own mesh (the server already ships `anamnesis relay` commands\nbehind a `[relay]` extra, but they are not documented yet) and team memory.\n\n## Repository layout\n\n| Path | What |\n| ------------- | --------------------------------------------------------------------- |\n| `server/` | The MCP memory server and CLI (Python, [FastMCP](https://gofastmcp.com)). |\n| `dashboard/` | The memory GUI (Next.js). |\n| `site/` | The public website and docs ([live](https://oscardvs.github.io/anamnesis/)). |\n| `bench/` | The cross-machine token benchmark and the demo recording pipeline. |\n| `examples/` | A hand-written `hooks.settings.json` for manual hook setup. |\n\n## Contributing\n\nIssues and discussion are welcome. If the install is rough on your machine, open an issue with the exact\ncommand you ran and its output.\n\n## License\n\n[Apache License 2.0](./LICENSE). See [`NOTICE`](./NOTICE).\n",
"bytes": 10911,
"sha": "0956ca8004cff8f94a50102ba2acd3e7c855032d0a0209a07e5126824625be61",
"repo_slug": "oscardvs/anamnesis",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_oscardvs_anamnesis_f1261a73/readme"
}