Anamnesis MCP

"Learning is not acquiring new knowledge. It is recollecting what was already known."
— Plato

Anamnesis is a Model Context Protocol (MCP) server that gives AI coding agents persistent, traceable memory across all your projects and sessions.

Not summaries. Not lossy compression. Cue-pointer records that link back to the full original context — the conversations, decisions, and breakthroughs you already had — so your agent can recollect them when they matter.

---

The Problem

Every AI agent session starts cold. Your agent has no memory of:

• The Lambda cold-start issue you debugged together last week
• The architectural decision you made in a different project that applies here
• The pattern that worked in CutIndex that would save two hours right now
• The conversation yesterday where you figured out exactly this problem

Claude Code can search your local session files — but it searches blind, without knowing what's inside. What's missing is an index of meaning: lightweight cue records that fire when context is similar and point the agent back to the full original artifact.

That is Anamnesis.

---

How It Works

Anamnesis does not store summaries of your conversations. It stores cue vectors that point at full traceable artifacts.

Memory record = {
  cue_vector:    embedding of "what this context felt like"
  context_tags:  ["aws-lambda", "cold-start", "python", "2026-03"]
  project:       "CutIndex"
  artifact_type: "conversation" | "diff" | "trace" | "decision"
  artifact_ptr:  path to full original → ~/.claude/sessions/uuid.jsonl
  outcome:       "solved" | "eureka" | "abandoned" | "partial"
  summary:       "Solved Lambda cold-start by increasing reserved concurrency"
}

The vector is not the memory. The vector is the trigger that tells the agent where to look. The full conversation is preserved, untouched, on your machine.

When similar context fires in a new session, Anamnesis surfaces the cue and fetches the original artifact. The agent recollects — it does not guess.

---

The Memory SDLC

Memories in Anamnesis go through a lightweight review process before they become trusted context — exactly like code changes go through a PR review before they merge.

Agent detects significant event (Eureka, decision, pattern)
  → writes proposed memory to pending/ queue

Reviewer agent scans pending/ (scheduled or on-demand)
  → checks for secrets, evaluates quality, flags duplicates
  → proposes accept / modify / reject

Human reviews (one-click in most cases)
  → accepts → memory promoted to confirmed/ store
  → rejects → discarded

Periodic maintenance agent
  → scans confirmed/ for staleness and redaction needs

This means Anamnesis memories are earned, not automatic. The confirmed store is a curated record of what you and your agent have genuinely learned together — not a dump of everything that was ever said.

---

Security: The Moral Compass

Agents encounter secrets in conversation. Anamnesis strips them before they reach the memory store.

Fast redaction runs at write time using pattern matching:

REDACT_PATTERNS = [
    r"(api_key|secret|password|token|credential)\s*[=:]\s*\S+",
    r"[A-Za-z0-9+/]{40,}={0,2}",   # base64 blobs
    r"[0-9a-f]{32,}",               # hex keys
    r"aws_\w+\s*=\s*\S+",           # AWS credentials
    r"(sk|pk|rk)[-_][a-zA-Z0-9]{20,}",  # API key prefixes
]

Deeper LLM-assisted redaction runs periodically against the confirmed store. The agent's standing instruction in any JARVIS.md or AGENTS.md configuration is explicit: store the shape of what happened, never the values.

---

MCP Tools

Tool	Description
anamnesis_recall	Primary read tool. Called at session start or when context feels familiar. Searches confirmed memories by cue similarity. Returns matched summaries and optionally fetches full artifacts.
anamnesis_remember	Primary write tool. Called when the agent solves something significant, recognises a pattern, or makes a non-obvious decision. Writes to pending queue for review.
anamnesis_search	Lightweight keyword + tag search. Faster than recall for when you know what you're looking for.
anamnesis_review	Returns pending memory queue for human review.
anamnesis_confirm	Human accepts, rejects, or edits a pending memory.
anamnesis_stats	Usage overview: memories by project, by outcome, recent activity, top tags.

Tool Descriptions (Engineered for Agent Triggering)

The descriptions below are crafted so that a properly configured agent reaches for the right tool at the right moment — not only when explicitly instructed.

anamnesis_recall

Use this tool at the start of any non-trivial problem, and whenever the current context feels familiar — a similar error, a similar architecture pattern, a similar library issue. This is your long-term memory across all projects. Do not rely only on training data when you may have directly relevant experience stored here.

anamnesis_remember

Use this tool when you solve something that took real effort, discover a pattern that wasn't obvious, make an architectural decision with non-obvious reasoning, or find a fix that contradicted what documentation said. Do not use for routine work. Set eureka_flag=true if this is something the broader developer community would benefit from knowing.

---

Installation

Requirements

• Python 3.11+
• uv (recommended) or pip
• OpenAI API key (for remote embeddings) OR Ollama running locally (for private local embeddings)

Install

# Via uv (recommended)
uv tool install anamnesis-mcp

# Via pip
pip install anamnesis-mcp

Configure in Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "anamnesis": {
      "command": "uvx",
      "args": ["anamnesis-mcp"],
      "env": {
        "EMBEDDING_MODEL": "text-embedding-3-small",
        "OPENAI_API_KEY": "sk-...",
        "ANAMNESIS_STORE": "~/.anamnesis"
      }
    }
  }
}

Configure in GitHub Copilot (.agent.md)

Create ~/.config/github-copilot/agents/jarvis.agent.md:

---
name: jarvis
description: Personal developer context engine with persistent memory
tools:
  - anamnesis_recall
  - anamnesis_remember
  - anamnesis_search
---

You are a persistent developer assistant with access to long-term memory
across all projects via Anamnesis.

Before starting any non-trivial problem, call anamnesis_recall with the
current context. When you solve something significant or discover a
non-obvious pattern, call anamnesis_remember. Never store secrets,
credentials, or proprietary business logic in memories.

---

File Structure

~/.anamnesis/
├── config.json          # Embedding model, API keys, optional AIOverflow connection
├── memories.db          # SQLite — all memory records and cue vectors
├── artifacts/           # Full original artifacts (Markdown, preserved verbatim)
│   ├── [uuid].md
│   └── ...
├── pending/             # Memory PRs awaiting human review
│   ├── [uuid].json
│   └── ...
└── exports/             # Human-readable exports

All data is local. Nothing leaves your machine unless you configure a hosted sync (see Roadmap).

---

Roadmap

Phase 1 — Core MCP (current)

• [x] Repo setup and BUSL 1.1 licence
• [ ] SQLite memory store with cue-pointer schema
• [ ] Embedding pipeline (remote: OpenAI, local: Ollama/nomic-embed-text)
• [ ] anamnesis_recall tool with cue similarity search
• [ ] anamnesis_remember tool with redaction at write time
• [ ] anamnesis_search keyword + tag search
• [ ] Memory SDLC: pending → review → confirmed lifecycle
• [ ] anamnesis_review and anamnesis_confirm tools
• [ ] Claude Code session ingestion (~/.claude/ JSONL parser)
• [ ] CLI review interface (Rich terminal UI)
• [ ] PyPI publish as anamnesis-mcp
• [ ] Submit to MCP registries (mcp.so, pulsemcp.com, awesome-mcp-servers)

Phase 2 — Enriched Sources

• [ ] claude.ai conversation export ingestion (JSON dump parser)
• [ ] Git diff and commit message ingestion
• [ ] Local Ollama embedding support (fully private, no API cost)
• [ ] anamnesis_stats tool
• [ ] Web review UI (lightweight local server)
• [ ] Periodic maintenance agent (staleness detection, deep redaction)

Phase 3 — Hosted Sync

• [ ] Encrypted cloud sync across devices (hosted service, commercial licence)
• [ ] Team/shared memory namespace
• [ ] AIOverflow MCP integration (Eureka flag → community post draft)
• [ ] Cross-device review interface

---

Architecture

The Cue-Pointer Record (Schema)

@dataclass
class MemoryRecord:
    id: str                    # UUID
    cue_vector: list[float]    # 1536-dim embedding (text-embedding-3-small)
                               # or 768-dim (nomic-embed-text local)
    context_tags: list[str]    # Technology and domain tags
    project: str               # Project name (auto-detected from cwd)
    project_path: str          # Absolute path to project root
    artifact_type: str         # conversation | diff | trace | decision | note
    artifact_ptr: str          # Pointer to full original artifact
    summary: str               # 1-3 sentences, human-readable, no secrets
    outcome: str               # solved | eureka | abandoned | partial
    eureka_flag: bool          # True = community-worthy, triggers AIOverflow draft
    status: str                # pending | confirmed | archived
    redacted: bool             # True if redaction was applied
    created_at: datetime
    confirmed_at: datetime | None

Artifact Pointer Format

file:///home/user/.anamnesis/artifacts/uuid.md   # stored locally
claude-code:///session/uuid                       # Claude Code JSONL session
git:///path/to/repo@commitHash                    # git commit reference
aioverflow:///post/id                             # published community post

Tech Stack

Component	Choice	Rationale
MCP server	Python + FastMCP	Fastest to build, native to Claude Code ecosystem
Memory store	SQLite + sqlite-vss	Zero dependencies, local-first, portable
Remote embeddings	OpenAI text-embedding-3-small	$0.02/million tokens — effectively free
Local embeddings	nomic-embed-text via Ollama	Fully private, no API cost
Vector search	sqlite-vss or numpy cosine	Lightweight, no external DB required
Redaction	Python regex + scheduled LLM pass	Fast at write time, deep on schedule
CLI	Rich (Python)	Clean terminal UI for memory review

---

Licence

Anamnesis MCP is licensed under the Business Source License 1.1 (BUSL-1.1).

You may:

• Use Anamnesis freely for personal use and development
• Self-host Anamnesis for non-commercial purposes
• Read, modify, and contribute to the source code
• Use Anamnesis internally within your organisation

You may not (without a commercial licence):

• Offer Anamnesis as a hosted or managed service to third parties
• Embed Anamnesis in a commercial product you sell or license to others
• Use Anamnesis to build a competing offering

Change Date: 2030-03-15
Change License: Apache License 2.0

After the Change Date, this software will be available under Apache 2.0.

For commercial licensing enquiries: [contact details]

See LICENSE for full terms.

---

Why "Anamnesis"?

In Platonic philosophy, anamnesis is the doctrine that learning is not the acquisition of new knowledge but the recollection of what the soul already knew. The knowledge was always there — it needed only the right context to surface it.

Your agent already spoke to you about this. The conversation happened. The solution was found. Anamnesis gives it back.

---

Contributing

Contributions are welcome under the BUSL terms above. Please open an issue before submitting a PR for significant changes.

A Contributor Licence Agreement (CLA) will be required for contributions — this is standard practice for BUSL projects and protects both contributors and the project. Details in CONTRIBUTING.md (coming soon).

---

Built by Arek Kulpa · Part of the SDLC.AI developer tooling ecosystem