Anamnesis documentation

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 locally for fast retrieval, and kept in sync across your fleet over your private network. There is no cloud account to create and no service to sign up for. Your memory stays on your machines: version-controlled, human-readable, and yours. The local-first core is open source under the Apache License 2.0 (repo: github.com/oscardvs/anamnesis).

The shape of it

The word anamnesis (ἀνάμνησις) is Greek for recollection: the act of calling knowledge back to mind. The system has five parts, each doing one job:

• Markdown is the source of truth. Notes live as plain .md files under ~/.anamnesis/memory/, so they are readable, git diff-able, and exactly the shape current models are good at using.
• A SQLite FTS5 index gives fast keyword recall. It is derived from the markdown and can always be rebuilt locally. It is never synced.
• Sync is git over a Tailscale mesh. Only markdown travels; the database file never leaves the machine, so it never corrupts.
• Claude Code talks to it through an MCP server (built on FastMCP) plus lifecycle hooks (SessionStart, SessionEnd, PreCompact).
• A Next.js dashboard is a git-like GUI to browse, search, edit, and inspect the history of your memory across every machine.

What is in the docs

If you just want to get running, jump to:

• Install - set up the server and run anamnesis init.
• How it works - the day-to-day loop of capture, recall, and sync.
• Across machines - put your fleet on one tailnet and share a repo.
• The dashboard - browse and edit your memory in a GUI.

For the precise surface area:

• CLI reference - init, inject, capture, sync, reindex, status, serve.
• MCP tools - memory_search, memory_list, memory_status, memory_write, memory_sync.
• Configuration - the ANAMNESIS_* environment variables.
• Security - the trust boundary and what is auto-approvable.

For the reasoning, see the internals:

• Architecture - the five layers and how Claude Code drives them.
• Data model - note types and the on-disk layout.
• Recall - FTS5, BM25, and ranking.
• Sync - the commit -> pull --rebase -> push cycle and conflict handling.
• Reflection - the deterministic default and the swappable summarization model.
• Design decisions - why files and not a knowledge graph.

Quickstart

Anamnesis runs as a local MCP server over a store at ~/.anamnesis (markdown notes plus a SQLite index that is rebuilt locally). Install it from PyPI:

uv tool install anamnesis-memory

Then wire this machine up in one command. anamnesis init registers the MCP server at user scope, installs the SessionStart / SessionEnd / PreCompact hooks, configures the store and your sync remote, and runs a first sync. It is idempotent (it backs up settings.json and never duplicates a hook):

anamnesis init            # interactive: confirm store dir, machine id, remote
anamnesis init --print    # dry-run: show exactly what it would do

Working on a single machine for now? Run anamnesis init --local-only and add a remote later by re-running init.

A full walkthrough lives in Install and Across machines.

How a memory travels

A note written on one machine becomes searchable on the others within a sync cycle. The hooks make this hands-off:

• SessionStart injects the most relevant notes for the current project (your global preferences, plus the project's durable notes and a couple of recent session summaries) and kicks off a background sync.
• SessionEnd captures a durable episodic note from the session transcript (the ask, the files touched, the outcome) and syncs it.
• PreCompact captures the same kind of note before the context is compacted, so nothing is lost.

The session-end summary is deterministic by default and needs no API key. The summarization model is a swappable config value (ANAMNESIS_REFLECTION_PROVIDER) for when a reflection model is plugged in later. See Capture and injection and Reflection.

On-disk layout

Memory lives in ~/.anamnesis/ (never inside the repo):

~/.anamnesis/
├── memory/            # markdown notes - the source of truth (a git repo, synced)
│   └── <type>/<id>.md
└── index.db           # SQLite FTS5 index - rebuilt locally, never synced

Notes carry one of three types: procedural, semantic, or episodic. See Data model.

Status

The local-first core is live end to end. Install is one line from PyPI (uv tool install anamnesis-memory && anamnesis init); the file-first store, the FastMCP server, the auto-capture and auto-inject hooks, git sync, and the reflection pass with its recall-gated merge are built, tested, and validated on real hardware across a real multi-machine fleet. A note written on the desktop is searchable on the laptop within a sync cycle, and the demo on the landing page is a real two-machine recording of exactly that.

The dashboard ships too: npx anamnesis-dashboard serves the git-like GUI over your store (browse, full-text search, history with diffs, a per-machine fleet view, inline edit), and npx anamnesis-dashboard --install-desktop puts a clickable launcher in your applications menu. The server is listed on the official MCP Registry as io.github.oscardvs/anamnesis, and the token numbers on the landing page are measured, not promised.

License and contributing

Anamnesis is open source under the Apache License 2.0. Issues and discussion are welcome on the GitHub repository.