How aasthik17/anamnesis works
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: client.py Memory client · cli.py CLI · config.py Config · llm_helper.py LLM helper
Components 18
Developer workflow
User actions and Git events that drive the system.
- Developer · Uses the CLI and edits the local repo.
- Local repo · The codebase Anamnesis observes and protects.
Entry points
CLI, MCP, and demo surfaces.
- CLI · Main command surface for init, remember, ask, reflect, forget, status, visualize, and mcp-serve.
anamnesis/cli.py - MCP server · Exposes memory capabilities to AI coding clients.
anamnesis/mcp_server.py - Demo script · Runs an end-to-end memory lifecycle demonstration.
demo/run_demo.py
Core engine
Configuration, Git integration, memory orchestration, and consolidation.
- Config · Loads repo config and environment overrides.
anamnesis/config.py - Git hooks · Installs and manages pre-commit recall behavior.
anamnesis/git/hooks.py - Git inspector · Reads commits, diffs, and repo state for memory ingestion.
anamnesis/git/inspector.py - Memory client · Central integration layer for persistence, recall, and fallback storage.
anamnesis/memory/client.py - Consolidator · Clusters repeated incidents into reusable team rules.
anamnesis/memory/consolidator.py - Schemas · Structured memory objects shared across ingest, recall, and consolidation.
anamnesis/memory/schemas.py - LLM helper · Selects and adapts local or cloud model backends.
anamnesis/utils/llm_helper.py
Presentation
Human-facing formatting and output.
- Formatter · Formats terminal status, warnings, and rich output.
anamnesis/ui/formatter.py - Browser graph · Rendered visualization driven from memory data.
External stores
Local durable files and optional model backends.
- memories.json · Durable ground truth for local recall and fallback behavior.
demo/sample_project/.anamnesis/memories.json - config.json · Per-repo Anamnesis configuration file.
.anamnesis/config.json - Cognee · Primary graph-backed memory backend.
- Ollama / OpenAI · Optional local or cloud LLM and embedding providers.
Connections 22
- 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.