# aasthik17/anamnesis architecture

> Architecture diagram of the GitHub repository aasthik17/anamnesis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aasthik17/anamnesis
- Repository: https://github.com/aasthik17/anamnesis

## Overview

1. **Repository purpose**
   - Anamnesis is a Python CLI tool that adds persistent “memory” to a local codebase.
   - Its core boundary is between the **local Git repository** and the **memory layer** that stores, recalls, and consolidates code knowledge.

2. **Primary entry points**
   - `anamnesis/cli.py` is the main user-facing entry point: it exposes commands such as init, remember, ask, reflect, forget, status, visualize, and mcp-serve.
   - `anamnesis/mcp_server.py` exposes the same memory capabilities as MCP tools for AI coding clients.
   - `demo/run_demo.py` is a scripted end-to-end demonstration of the memory lifecycle.

3. **Configuration and environment setup**
   - `anamnesis/config.py` loads per-repo settings from `.anamnesis/config.json` and environment overrides.
   - This module also wires LLM-related environment variables so the rest of the system can switch between local Ollama and optional cloud-backed providers without changing command code.

4. **Memory subsystem**
   - `anamnesis/memory/client.py` is the central integration layer.
   - It manages the persistence model, the Cognee-backed memory operations, and the local fallback store in `.anamnesis/memories.json`.
   - That local JSON file is the repo’s durable ground truth, so recall can still work even if the graph/LLM path is unavailable.

5. **Memory consolidation**
   - `anamnesis/memory/consolidator.py` groups repeated bug reports or related memory entries into higher-level team rules.
   - This is the “memify/reflect” boundary: raw incidents are transformed into reusable conventions and coding guidance.
   - `anamnesis/memory/schemas.py` defines the structured memory objects passed between ingest, recall, and consolidation.

6. **Git integration**
   - `anamnesis/git/inspector.py` reads commit history, diffs, and repository state to extract relevant changes and bug-fix context.
   - `anamnesis/git/hooks.py` installs and manages the pre-commit hook that triggers recall before code is finalized.
   - This makes Git the main event source for memory ingestion and preventive warnings.

7. **UI and presentation layer**
   - `anamnesis/ui/formatter.py` formats terminal output and rich status/views for humans.
   - The CLI’s visualize command also produces a browser-based graph view, but that is still driven from the same memory data rather than a separate subsystem.

8. **LLM / embedding integration**
   - `anamnesis/utils/llm_helper.py` handles model/backend wiring and helper logic for local LLM usage.
   - The architecture is designed to use **Ollama locally by default**, with optional OpenAI/Cognee cloud support when configured.
   - This affects the system because extraction, summarization, clustering, and embeddings depend on these external model endpoints.

9. **Main data flow: ingest**
   - Git commits, staged diffs, bug reports, and architecture notes enter through the CLI or Git hook.
   - They are normalized by the git/memory layers, optionally enriched by an LLM, stored in Cognee-backed memory, and also persisted locally in `.anamnesis/memories.json`.

10. **Main data flow: recall**
   - When a developer asks a question or commits code, the system queries memory for similar past bugs, rules, or decisions.
   - Recall combines graph-oriented lookup with local scoring/fallback behavior, then returns concise warnings or contextual answers in the CLI or MCP client.

11. **Main data flow: consolidation and decay**
   - Repeated bug patterns are clustered into rules by the consolidator.
   - Stale or deleted-code memory can be pruned/decayed through forget operations.
   - This gives the system a lifecycle rather than a one-time index: memories evolve with the repo.

12. **Repository-specific storage boundaries**
   - `.anamnesis/config.json` stores per-project configuration.
   - `.anamnesis/memories.json` stores local memory records.
   - `.git/hooks/pre-commit` is the integration point where Anamnesis can block or warn on risky changes.

13. **Testing and validation**
   - `tests/test_cli.py` and `tests/test_memory.py` cover the command surface and memory behavior.
   - These tests indicate the two main architectural seams: user-facing CLI behavior and the underlying memory engine.

14. **How to diagram it**
   - A good architecture diagram should show four layers:
     - **Developer / Git workflow**
     - **Anamnesis CLI + MCP server**
     - **Memory/Git/LLM subsystems**
     - **External services and stores**: Cognee memory engine, Ollama/OpenAI, and the local `.anamnesis` files
   - The key interaction is that Git events and user commands both feed the same memory subsystem, which then returns recall, rules, or graph views.

Main entry points: [`anamnesis/memory/client.py`](https://github.com/aasthik17/anamnesis/blob/main/anamnesis/memory/client.py) (Memory client), [`anamnesis/cli.py`](https://github.com/aasthik17/anamnesis/blob/main/anamnesis/cli.py) (CLI), [`anamnesis/config.py`](https://github.com/aasthik17/anamnesis/blob/main/anamnesis/config.py) (Config), [`anamnesis/utils/llm_helper.py`](https://github.com/aasthik17/anamnesis/blob/main/anamnesis/utils/llm_helper.py) (LLM helper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Developer workflow"]
  node_developer(("Developer<br/>actor"))
  node_gitrepo[("Local repo")]
end

subgraph group_entry["Entry points"]
  node_cli["CLI<br/>command interface<br/>[cli.py]"]
  node_mcp["MCP server<br/>tool server<br/>[mcp_server.py]"]
  node_demo["Demo script<br/>demo runner<br/>[run_demo.py]"]
end

subgraph group_core["Core engine"]
  node_config["Config<br/>settings loader<br/>[config.py]"]
  node_hooks["Git hooks<br/>git integration<br/>[hooks.py]"]
  node_inspector["Git inspector<br/>change reader<br/>[inspector.py]"]
  node_memory_client["Memory client<br/>memory orchestrator<br/>[client.py]"]
  node_consolidator["Consolidator<br/>rule builder<br/>[consolidator.py]"]
  node_schemas["Schemas<br/>data model<br/>[schemas.py]"]
  node_llm_helper["LLM helper<br/>backend wiring<br/>[llm_helper.py]"]
end

subgraph group_presentation["Presentation"]
  node_formatter["Formatter<br/>[formatter.py]"]
  node_graph_view(("Browser graph<br/>visualization"))
end

subgraph group_external["External stores"]
  node_memories_json[("memories.json<br/>local memory store<br/>[memories.json]")]
  node_config_json["config.json<br/>project config<br/>[config.json]"]
  node_cognee[("Cognee<br/>memory engine")]
  node_ollama{{"Ollama / OpenAI<br/>model endpoints"}}
end

node_developer -->|"commands"| node_cli
node_developer -->|"edits"| node_gitrepo
node_gitrepo -->|"pre-commit"| node_hooks
node_cli -->|"load"| node_config
node_cli -->|"inspect"| node_inspector
node_cli -->|"orchestrate"| node_memory_client
node_cli -->|"render"| node_formatter
node_cli -->|"visualize"| node_graph_view
node_mcp -->|"tools"| node_memory_client
node_demo -->|"drives"| node_cli
node_hooks -->|"recall"| node_memory_client
node_inspector -->|"ingest"| node_memory_client
node_config -->|"wire"| node_llm_helper
node_config -->|"settings"| node_memory_client
node_memory_client -->|"cluster"| node_consolidator
node_memory_client -->|"shape"| node_schemas
node_memory_client -->|"store"| node_cognee
node_memory_client -->|"fallback"| node_memories_json
node_memory_client -->|"summarize"| node_llm_helper
node_llm_helper -->|"default / optional"| node_ollama
node_consolidator -.->|"reuse"| node_schemas
node_config_json -->|"source"| node_config

click node_cli "https://github.com/aasthik17/anamnesis/blob/main/anamnesis/cli.py"
click node_mcp "https://github.com/aasthik17/anamnesis/blob/main/anamnesis/mcp_server.py"
click node_demo "https://github.com/aasthik17/anamnesis/blob/main/demo/run_demo.py"
click node_config "https://github.com/aasthik17/anamnesis/blob/main/anamnesis/config.py"
click node_hooks "https://github.com/aasthik17/anamnesis/blob/main/anamnesis/git/hooks.py"
click node_inspector "https://github.com/aasthik17/anamnesis/blob/main/anamnesis/git/inspector.py"
click node_memory_client "https://github.com/aasthik17/anamnesis/blob/main/anamnesis/memory/client.py"
click node_consolidator "https://github.com/aasthik17/anamnesis/blob/main/anamnesis/memory/consolidator.py"
click node_schemas "https://github.com/aasthik17/anamnesis/blob/main/anamnesis/memory/schemas.py"
click node_formatter "https://github.com/aasthik17/anamnesis/blob/main/anamnesis/ui/formatter.py"
click node_llm_helper "https://github.com/aasthik17/anamnesis/blob/main/anamnesis/utils/llm_helper.py"
click node_memories_json "https://github.com/aasthik17/anamnesis/blob/main/demo/sample_project/.anamnesis/memories.json"
click node_config_json "https://github.com/aasthik17/anamnesis/blob/main/.anamnesis/config.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_developer,node_gitrepo toneBlue
class node_cli,node_mcp,node_demo toneAmber
class node_config,node_hooks,node_inspector,node_memory_client,node_consolidator,node_schemas,node_llm_helper toneMint
class node_formatter,node_graph_view toneRose
class node_memories_json,node_config_json,node_cognee,node_ollama toneIndigo
```

## Components

### Developer workflow

User actions and Git events that drive the system.

- **Developer**: actor · Uses the CLI and edits the local repo.
- **Local repo**: repo · The codebase Anamnesis observes and protects.

### Entry points

CLI, MCP, and demo surfaces.

- [CLI](https://github.com/aasthik17/anamnesis/blob/main/anamnesis/cli.py): command interface · Main command surface for init, remember, ask, reflect, forget, status, visualize, and mcp-serve. · `anamnesis/cli.py`
- [MCP server](https://github.com/aasthik17/anamnesis/blob/main/anamnesis/mcp_server.py): tool server · Exposes memory capabilities to AI coding clients. · `anamnesis/mcp_server.py`
- [Demo script](https://github.com/aasthik17/anamnesis/blob/main/demo/run_demo.py): demo runner · Runs an end-to-end memory lifecycle demonstration. · `demo/run_demo.py`

### Core engine

Configuration, Git integration, memory orchestration, and consolidation.

- [Config](https://github.com/aasthik17/anamnesis/blob/main/anamnesis/config.py): settings loader · Loads repo config and environment overrides. · `anamnesis/config.py`
- [Git hooks](https://github.com/aasthik17/anamnesis/blob/main/anamnesis/git/hooks.py): git integration · Installs and manages pre-commit recall behavior. · `anamnesis/git/hooks.py`
- [Git inspector](https://github.com/aasthik17/anamnesis/blob/main/anamnesis/git/inspector.py): change reader · Reads commits, diffs, and repo state for memory ingestion. · `anamnesis/git/inspector.py`
- [Memory client](https://github.com/aasthik17/anamnesis/blob/main/anamnesis/memory/client.py): memory orchestrator · Central integration layer for persistence, recall, and fallback storage. · `anamnesis/memory/client.py`
- [Consolidator](https://github.com/aasthik17/anamnesis/blob/main/anamnesis/memory/consolidator.py): rule builder · Clusters repeated incidents into reusable team rules. · `anamnesis/memory/consolidator.py`
- [Schemas](https://github.com/aasthik17/anamnesis/blob/main/anamnesis/memory/schemas.py): data model · Structured memory objects shared across ingest, recall, and consolidation. · `anamnesis/memory/schemas.py`
- [LLM helper](https://github.com/aasthik17/anamnesis/blob/main/anamnesis/utils/llm_helper.py): backend wiring · Selects and adapts local or cloud model backends. · `anamnesis/utils/llm_helper.py`

### Presentation

Human-facing formatting and output.

- [Formatter](https://github.com/aasthik17/anamnesis/blob/main/anamnesis/ui/formatter.py): ui formatter · Formats terminal status, warnings, and rich output. · `anamnesis/ui/formatter.py`
- **Browser graph**: visualization · Rendered visualization driven from memory data.

### External stores

Local durable files and optional model backends.

- [memories.json](https://github.com/aasthik17/anamnesis/blob/main/demo/sample_project/.anamnesis/memories.json): local memory store · Durable ground truth for local recall and fallback behavior. · `demo/sample_project/.anamnesis/memories.json`
- [config.json](https://github.com/aasthik17/anamnesis/blob/main/.anamnesis/config.json): project config · Per-repo Anamnesis configuration file. · `.anamnesis/config.json`
- **Cognee**: memory engine · Primary graph-backed memory backend.
- **Ollama / OpenAI**: model endpoints · Optional local or cloud LLM and embedding providers.

## Connections

- Developer → CLI: commands · Uses the CLI to manage memory and query code context.
- Developer → Local repo: edits · Works in the local codebase that Anamnesis watches.
- Local repo → Git hooks: pre-commit · Git workflow triggers recall before changes are finalized.
- CLI → Config: load · Reads repo configuration and environment overrides.
- CLI → Git inspector: inspect · Collects commit and diff context for memory operations.
- CLI → Memory client: orchestrate · Routes remember, ask, reflect, forget, and status flows.
- CLI → Formatter: render · Formats terminal output for humans.
- CLI → Browser graph: visualize · Produces the browser-based graph view.
- MCP server → Memory client: tools · Exposes the same memory capabilities to MCP clients.
- Demo script → CLI: drives · Exercises the end-to-end lifecycle through the command surface.
- Git hooks → Memory client: recall · Invokes memory checks during Git events.
- Git inspector → Memory client: ingest · Feeds extracted repo changes into memory operations.
- Config → LLM helper: wire · Selects backend behavior and model settings.
- Config → Memory client: settings · Supplies repository-specific runtime settings.
- Memory client → Consolidator: cluster · Turns repeated incidents into higher-level rules.
- Memory client → Schemas: shape · Uses structured memory objects as the internal contract.
- Memory client → Cognee: store · Persists and queries the primary memory backend.
- Memory client → memories.json: fallback · Keeps the local durable memory record in sync.
- Memory client → LLM helper: summarize · Uses model helpers for extraction, summarization, and embedding.
- LLM helper → Ollama / OpenAI: default / optional · Prefers local Ollama, with optional cloud-backed providers.
- Consolidator → Schemas: reuse · Builds rules from the shared memory schema.
- config.json → Config: source · Project config file loaded by the settings layer.
