Related Pages

Related topics: Backend Server, MCP Tools & AI Integration, Data Layer & Dashboard Frontend, Cross-Machine Sync, Hooks, Reflection Workflows & Customization

Overview & System Architecture

Anamnesis is a local-first memory and recall store for development environments. The name ("ἀνάμνησις", recollection) reflects its purpose: persistent, machine-scoped memory that is queried, synced, and surfaced back to agents and humans on demand. The system is split into three runtime surfaces — a CLI, a long-running server, and a documentation site — that share a single on-disk store rooted at a configurable home directory. Source: README.md:1-40

High-Level Components

The repository is organized so that the CLI, the server, and the docs are siblings under one workspace, each owning one responsibility:

• CLI (anamnesis command) — User-facing entry point. It exposes lifecycle commands such as anamnesis init, which provisions the store, writes config.json, and performs an initial sync. As of v0.1.3, the CLI honors the same environment variables as every other component (ANAMNESIS_HOME, ANAMNESIS_MACHINE_ID), fixing a long-standing inconsistency where init silently fell back to ~/.anamnesis. Source: README.md:40-120
• Server (server/) — A persistent daemon that holds the authoritative store, accepts remote reads/writes, and exposes a network protocol for agents running on other machines or containers. It reads the same config.json produced by the CLI, so a CLI-initiated store is immediately consumable by the server. Source: server/README.md:1-60
• Documentation site (site/) — A static MDX-based site that ships user guides and internals documentation, including the canonical architecture page that this wiki mirrors. Source: site/content/docs/internals/architecture.mdx:1-40

The contributor guide (CLAUDE.md) defines the build, test, and release conventions used across all three surfaces, ensuring the CLI, server, and docs evolve in lockstep. Source: CLAUDE.md:1-40

Configuration & On-Disk Layout

Anamnesis uses a single source of truth for configuration: a config.json file at the store root, paired with two environment variables that override defaults without rewriting the file.

Before v0.1.3, anamnesis init ignored both variables and always wrote its bootstrap files and ran the first sync against ~/.anamnesis. The fix makes the init path consult the same resolution chain as every other command. Re-running init on an existing store now preserves the store's prior state instead of clobbering it, which matters for fleet-style scripted deployments and for users with non-default store homes. Source: README.md:60-140, site/content/docs/internals/architecture.mdx:40-120

The store itself holds at minimum a config.json, an identity marker derived from ANAMNESIS_MACHINE_ID, and the memory payloads produced by sync runs. The CLI is the only component that is allowed to create this layout; the server and external clients are expected to attach to an already-initialized store. Source: server/README.md:40-100

Runtime Data Flow

The following diagram captures the principal relationships between the CLI, the store on disk, the server, and the agents that consume memory. It mirrors the layering described in the project's internals documentation.

flowchart LR
    User["User / Agent"] --> CLI["anamnesis CLI"]
    CLI --> Init["anamnesis init"]
    Init --> Env["ANAMNESIS_HOME / ANAMNESIS_MACHINE_ID"]
    Init --> Store[("Store: config.json + memory blobs")]
    CLI --> Sync["Sync / Read / Write"]
    Sync --> Store
    Store --> Server["anamnesis server"]
    Server --> Remote["Remote agents & fleet nodes"]
    Site["Docs site (MDX)"] -. describes .-> CLI
    Site -. describes .-> Server

The CLI is the write path for the local store; the server is the fan-out path for everyone else. Both rely on the same configuration resolution so that an init performed in one shell context remains valid in another. Source: site/content/docs/internals/architecture.mdx:60-160

Boundaries, Conventions, and Operational Notes

Several invariants are enforced consistently across components and are worth internalizing before extending the system:

• Single store, single config. There is exactly one config.json per ANAMNESIS_HOME. The CLI owns writes to it, the server reads from it, and the docs describe it. Source: site/content/docs/internals/architecture.mdx:80-140
• Machine identity is environment-driven. ANAMNESIS_MACHINE_ID is the canonical identity for sync conflicts and audit trails; do not derive machine identity from filenames or process state. Source: README.md:80-140
• Idempotent init. anamnesis init must be safe to re-run. v0.1.3 made this guarantee explicit so that fleet scripts and recovery workflows do not need special-casing. Source: README.md:100-160
• Server is stateless about layout. The server never assumes ~/.anamnesis; it resolves the store through the same environment contract as the CLI. Source: server/README.md:60-120
• Docs are first-class. Architecture-level changes are expected to land as edits to site/content/docs/internals/architecture.mdx alongside the code, so the wiki and the runtime cannot drift. Source: site/content/docs/internals/architecture.mdx:1-40, CLAUDE.md:20-60

When to Read Which File

For new contributors, the recommended reading order is: README.md for the user-facing contract, site/content/docs/internals/architecture.mdx for the internal model, server/README.md for the server's wire-level responsibilities, and CLAUDE.md for build, test, and contribution conventions. Together they cover the full surface from a one-line CLI invocation up to the multi-host sync topology. Source: README.md:1-40, site/content/docs/internals/architecture.mdx:1-40, server/README.md:1-60, CLAUDE.md:1-40

Related Pages

Related topics: Overview & System Architecture, Data Layer & Dashboard Frontend, Cross-Machine Sync, Hooks, Reflection Workflows & Customization

Backend Server, MCP Tools & AI Integration

Purpose and Scope

The Anamnesis backend server exposes the project's memory store to external AI assistants through the Model Context Protocol (MCP). It packages four responsibilities into a single Python package located under server/src/anamnesis/:

• A long-running MCP server that advertises tools over stdio/JSON-RPC.
• A capture pipeline that records conversational turns into the local memory store.
• An injection pipeline that rehydrates relevant prior memories into new prompts.
• An LLM-backed summarization and reflection layer that distills raw captures into durable notes.

The CLI in cli.py acts as the unified entry point for both humans (anamnesis init, anamnesis sync) and machine clients (anamnesis serve), keeping argument parsing, environment handling, and configuration loading consistent across all subcommands. As of v0.1.3, anamnesis init honors ANAMNESIS_HOME and ANAMNESIS_MACHINE_ID env vars, fixing earlier drift where the first sync wrote to the default ~/.anamnesis even when overrides were set.

CLI Entry Point and Configuration

cli.py wires subcommands to the rest of the package. The serve subcommand resolves the configured store path, opens the memory client, and hands it to the MCP server factory in server.py. Environment variables (ANAMNESIS_HOME, ANAMNESIS_MACHINE_ID, plus provider keys for the summarizer) are read centrally so that init, serve, capture, and reflect all agree on the same store identity. Source: server/src/anamnesis/cli.py.

MCP Server and Tool Surface

server.py implements the MCP server loop. It registers a small set of JSON-RPC tools that wrap the capture, inject, search, and reflect primitives. Tool handlers are thin adapters: they validate arguments, call into the domain modules, and serialize results back into MCP-compliant responses. This keeps the transport layer separate from the memory logic. Source: server/src/anamnesis/server.py.

Typical tools exposed include equivalents of memory_capture (append a turn), memory_inject (fetch context for a prompt), memory_search (semantic lookup), and memory_reflect (trigger a consolidation pass). AI clients — Claude Desktop, Cursor, or any MCP-aware agent — discover these tools at startup and call them through the protocol.

Capture Pipeline

capture.py is the write-side module. When the MCP memory_capture tool is invoked, the handler normalizes the incoming message (role, content, timestamp, machine id), computes or fetches its embedding, and writes a record into the store. The function is also called directly by the CLI when syncing offline transcripts, which is why the same code path must respect ANAMNESIS_HOME and ANAMNESIS_MACHINE_ID — a bug here previously caused the first sync to land in ~/.anamnesis regardless of overrides, as noted in the v0.1.3 release. Source: server/src/anamnesis/capture.py.

Inject Pipeline

inject.py performs the inverse operation. Given a user prompt, it embeds the query, queries the store for top-k semantically similar memories, and assembles them into a context block that the calling assistant can prepend to its prompt. The module is intentionally narrow — formatting, token budgeting, and ranking policy live here, while the actual MCP response is assembled by server.py. Source: server/src/anamnesis/inject.py.

AI Integration: Summarization and Reflection

llm_summarizer.py wraps the external LLM provider used to compress raw captures. It accepts a batch of recent turns, calls the configured model with a structured prompt, and returns a short note plus optional tags. Failures are surfaced as typed exceptions so that the reflect loop can decide whether to retry or skip.

reflect.py is the curation scheduler. It scans the store for clusters of related entries that have not yet been consolidated, asks llm_summarizer.py to produce a higher-level note, and writes the result back as a new memory. Over time, this produces a hierarchy: raw captures at the leaves, distilled summaries above them, which inject.py can surface when a prompt touches a mature topic. Source: server/src/anamnesis/llm_summarizer.py, server/src/anamnesis/reflect.py.

End-to-End Flow

flowchart LR
  A[AI Client] -->|MCP tool call| B[server.py]
  B --> C[capture.py]
  B --> D[inject.py]
  B --> E[reflect.py]
  E --> F[llm_summarizer.py]
  C --> G[(Memory Store)]
  D --> G
  E --> G
  F -->|external LLM| F

A typical interaction: the assistant calls memory_inject before answering — inject.py retrieves prior context from the store. After replying, it calls memory_capture to record the turn. Periodically, memory_reflect runs to consolidate older entries into summaries, keeping the store compact and retrieval-relevant.

Operational Notes

• Store identity is process-global: ANAMNESIS_HOME selects the directory and ANAMNESIS_MACHINE_ID tags every record, so multi-machine installs stay partitioned.
• The MCP server is stateless between requests; all persistence is delegated to the store.
• Summarization is optional — if no provider key is configured, reflect.py degrades to a pass-through that still deduplicates but skips LLM-driven synthesis.

Related Pages

Related topics: Backend Server, MCP Tools & AI Integration, Cross-Machine Sync, Hooks, Reflection Workflows & Customization

Data Layer & Dashboard Frontend

The anamnesis project is split into two cooperating halves: a Python server / data layer that owns persistent state, and a Next.js dashboard frontend that surfaces that state to users. The data layer is the source of truth; the dashboard is a thin, read-mostly client that wraps the same abstractions in TypeScript and renders them as a web UI.

Server-Side Data Store

The Python package anamnesis centers on a single store object. store.py defines the persistence abstraction that every CLI subcommand and background worker relies on. It resolves the store's home directory from the ANAMNESIS_HOME environment variable and falls back to ~/.anamnesis when the variable is unset, and it reads the machine identifier from ANAMNESIS_MACHINE_ID when one is provided. Source: server/src/anamnesis/store.py:1-80.

Configuration is loaded from a config.json written into the store root during anamnesis init. As of v0.1.3, init honors ANAMNESIS_HOME and ANAMNESIS_MACHINE_ID consistently with the rest of the codebase — earlier releases wrote config.json and ran the first sync against the default path even when environment variables were set, which broke fleet deployments and custom store homes. Source: server/src/anamnesis/store.py:80-160.

The store exposes a small, stable surface — open/close, read, write, sync, and migration hooks — rather than a full ORM. This keeps the dashboard's TypeScript client simple and lets migrate.py run schema updates against the same on-disk format.

Migrations

migrate.py applies schema changes to an existing store. It detects the current schema version from config.json, compares it to the version bundled with the running CLI, and runs any pending migrations in order. The migrate routine is idempotent: re-running it on an up-to-date store is a no-op, and the v0.1.3 fix ensures that re-running init on an existing store preserves the store's previously written state instead of overwriting it. Source: server/src/anamnesis/migrate.py:1-120.

Migrations are intentionally narrow — they touch files on disk, not a database engine — which is why the same store can be opened by both the Python server and the dashboard's typed accessors without coordination. Source: server/src/anamnesis/migrate.py:120-220.

Dashboard Data Access

The dashboard mirrors the server's split into a thin wrapper layer (store.ts), a typed data accessor (db.ts), and a VCS-aware helper (git.ts). store.ts resolves ANAMNESIS_HOME in the browser/server runtime and exposes an openStore() helper that returns a read-only handle; it does not write, because the dashboard is treated as an untrusted viewer. Source: dashboard/src/lib/store.ts:1-90.

db.ts defines the TypeScript types and query functions that map directly onto the on-disk format written by store.py. Functions here are pure: they take a store handle and return typed records, with no hidden caching. This makes the dashboard safe to re-render frequently without coordinating with the server. Source: dashboard/src/lib/db.ts:1-150.

git.ts reads .git-style metadata from the store so the dashboard can show provenance, last-sync timestamps, and per-machine history without shelling out to a full git client. Source: dashboard/src/lib/git.ts:1-110.

Dashboard UI Entry

dashboard/src/app/page.tsx is the top-level route. It calls openStore() on the server, runs the typed queries from db.ts, and passes the results into client components as props. The page is intentionally stateless: every navigation re-fetches from the store rather than relying on client-side caches, which keeps the dashboard consistent with the on-disk state after a sync. Source: dashboard/src/app/page.tsx:1-80.

The data flow between the two halves is therefore unidirectional and explicit:

flowchart LR
  CLI[anamnesis CLI] -->|writes| Disk[(Store on disk\n~/.anamnesis or $ANAMNESIS_HOME)]
  Migrate[migrate.py] -->|upgrades schema| Disk
  Disk -->|openStore| StoreTS[store.ts]
  StoreTS --> DbTS[db.ts]
  GitTS[git.ts] -.reads metadata.-> Disk
  DbTS --> Page[app/page.tsx]
  GitTS --> Page

The __init__.py re-exports the most common entry points so both the CLI and the dashboard's server-side code can import from a single path. Source: server/src/anamnesis/__init__.py:1-40.

Operational Notes

• Vanilla installs are unaffected by the v0.1.3 fix; the regression only impacted users with a custom ANAMNESIS_HOME, a fleet script setting ANAMNESIS_MACHINE_ID, or anyone re-running init on an already-initialized store.
• Read-only dashboard: the dashboard's store.ts deliberately does not expose writes, so a misconfigured frontend cannot corrupt the store.
• Schema drift: if a dashboard build expects a newer schema than the on-disk store has, migrate.py must be run before the dashboard is opened against it; db.ts will surface this as a typed error rather than silently returning partial data.

Related Pages

Related topics: Overview & System Architecture, Backend Server, MCP Tools & AI Integration, Data Layer & Dashboard Frontend

Cross-Machine Sync, Hooks, Reflection Workflows & Customization

Anamnesis is built around a portable memory store that can be synchronized across machines, customized through hooks, and queried by external agents via the Model Context Protocol (MCP). This page documents how those subsystems fit together: the sync engine, the onboarding flow that configures it, the hook system that intercepts lifecycle events, and the reflection workflows that turn raw interactions into reusable memory.

1. Cross-Machine Sync

The sync subsystem is anchored by ANAMNESIS_HOME (the store root) and ANAMNESIS_MACHINE_ID (the per-host identifier). Together they let a single logical store live on multiple machines without collisions. sync.py is the module that drives reconciliation between the local store and remote peers, reading machine identity from the environment so that fleet deployments and developer laptops share one source of truth. Source: server/src/anamnesis/sync.py:1-120

Configuration of sync is centralized in config.py, which loads config.json from ANAMNESIS_HOME and merges it with environment defaults. As of v0.1.3, the init flow was fixed so that anamnesis init honors ANAMNESIS_HOME and ANAMNESIS_MACHINE_ID like every other component; previously it silently wrote to ~/.anamnesis and performed the first sync against the default location, which broke custom store homes and fleet scripts. Source: server/src/anamnesis/config.py:1-80

The high-level flow is:

flowchart LR
  A[anamnesis init] --> B[Write config.json to ANAMNESIS_HOME]
  B --> C[Stamp ANAMNESIS_MACHINE_ID]
  C --> D[Run first sync via sync.py]
  D --> E[(Local store)]
  D --> F[(Remote peer stores)]

2. Onboarding & Initial Configuration

onboard.py implements the one-time bootstrap performed by anamnesis init. It is responsible for creating the store directory layout, writing a fresh config.json, and triggering the inaugural sync. Because it now reads the same environment variables as the rest of the system, re-running init on an existing store is idempotent and preserves the store's identity rather than overwriting it. Source: server/src/anamnesis/onboard.py:1-150

Environment-driven configuration is the recommended setup for non-vanilla installs. The .env.example file documents the surface area users typically customize:

Source: .env.example:1-40

This indirection lets operators ship a single image or script to many machines and have each one land in a different store with a different identity, without code changes.

3. Hooks & Customization

Anamnesis exposes lifecycle hooks so that teams can plug in side effects (logging, redaction, external notifications) without forking the core. The canonical shape lives in examples/hooks.settings.json, which is the template the onboard flow copies into the store on first run. Hooks fire at well-known points such as pre_sync, post_sync, on_reflect, and on_query, letting customizers observe and transform data as it moves through the system. Source: examples/hooks.settings.json:1-60

Because hooks are loaded from a JSON file inside the store, they are themselves subject to sync. A hook added on one machine will, after the next sync round, appear on every peer — which is what makes "customization" a first-class part of the cross-machine story rather than a per-host patch.

4. Reflection Workflows

Reflection is the process that promotes transient interactions into durable memory. The workflow is driven by the same sync and hook infrastructure: a pre_reflect hook can normalize or redact, the reflection engine writes entries into the local store, and a post_reflect hook can fan out notifications or trigger downstream pipelines. The next sync.py cycle propagates the new entries to peers under the current ANAMNESIS_MACHINE_ID. Source: server/src/anamnesis/sync.py:120-220

External agents (LLMs, IDEs, automation scripts) integrate through MCP, declared in .mcp.json at the repository root. The MCP server entry exposes the store and reflection APIs as tools, so a model can read existing memory, request a reflection, or query across machines without bespoke glue code. Source: .mcp.json:1-30

A typical end-to-end reflection workflow therefore looks like:

1. An agent writes an interaction through the MCP tool surface.
2. The pre_reflect hook normalizes and tags the entry.
3. The reflection engine commits the entry to the local store.
4. sync.py reconciles the entry across peers keyed by ANAMNESIS_MACHINE_ID.
5. post_sync hooks fire on each machine that receives the new entry, enabling local side effects such as cache warming or downstream indexing.

Source: server/src/anamnesis/onboard.py:150-220

Putting It Together

The three subsystems form a single loop: init establishes identity and layout, hooks customize behavior at every boundary, and sync keeps the resulting state consistent across machines. The v0.1.3 fix to anamnesis init is a good illustration of the design intent — every entry point must consult the same environment-driven identity, so that customization made through .env, config.json, or hooks.settings.json is respected uniformly, whether you are running on a single laptop or across a fleet. Source: server/src/anamnesis/config.py:80-160

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/oscardvs/anamnesis

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/oscardvs/anamnesis

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/oscardvs/anamnesis

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/oscardvs/anamnesis

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/oscardvs/anamnesis

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/oscardvs/anamnesis

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/oscardvs/anamnesis

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using anamnesis with real data or production workflows.

• v0.1.3 - github / github_release
• v0.1.2 - github / github_release
• v0.1.1 - github / github_release
• v0.1.0 - github / github_release
• v0.0.2 - github / github_release
• Configuration risk requires verification - GitHub / issue