wadachi 0.16.0

Your AI forgets everything between sessions. Wadachi fixes that.
Wadachi (轍): the tracks wheels leave in a road — formerly known as Engram.

The MCP-native memory server for the LLM Wiki pattern.
Persistent memory + semantic search for Claude Code, Claude Desktop, Cursor, and any MCP client.

Live demo →  ·  docs + an interactive constellation over a fictional sample brain

The Problem

Every time you open Claude Code on a project, it starts from zero. It re-reads files, re-analyzes architecture, re-discovers patterns — burning tokens and time on things it already figured out yesterday.

You end up repeating yourself:

"Remember, we're using the observer pattern here..."
"The deploy script needs the --feynotes flag..."
"We already tried that approach, it doesn't work because..."

The Solution

Wadachi gives your AI a persistent brain — a local knowledge base where it stores insights, decisions, and patterns, then retrieves them instantly at the start of every session.

One tool call at session start. All relevant context loaded. Zero wasted tokens re-discovering.

How it works

1. Connect — wadachi init wires the server into Claude Code (and Antigravity) automatically; any MCP client works.
2. Register your projects — filesystem paths mapped to project names, so memories land in the right scope.
3. Start with context — every session opens with get_context: relevant memories, recent decisions, what needs review.
4. Store as you go — bugs, configs, patterns, decisions get saved the moment they're figured out. The brain compounds.

Where Wadachi sits: the harness

A stack has been forming under AI agents — prompt → context → harness → loop. Prompt engineering was wording one request well; context engineering was curating what the model sees before each call. Both hit the same wall: the window fills, quality falls off a cliff (context rot), and the usual remedy — summarising to make room (compaction) — buys that room by throwing away precision.

A harness is the scaffolding outside the model that re-initialises the agent step by step: fresh context each step, durable state read back from disk, work resumed exactly where it stopped. Nothing gets summarised, because nothing had to fit. Agent = Model + Harness.

Wadachi is not a harness. It is the memory of one — and memory here has two layers, with two different lifetimes:

• The hippocampus — what you learned. Survives the end of a session. It is everything described below: memories, decisions, beliefs, the graph, sleep. Built.
• The desk — what you are doing. Survives the end of a context window: the plan for the task in flight, the steps already done, where the thread was dropped. Built. desk opens one, desk_log records each attempt — especially the failures — and desk_read (or get_context, which surfaces it automatically) picks the work back up in a session that knows nothing.

And the boundary that keeps the two projects honest: Wadachi never executes anything, and never decides when something starts. No runner, no sandbox, no scheduler — those belong to whatever harness drives your agent. reflect, sleep and consolidate look loop-shaped, but they are background maintenance that proposes; they never decide that work should begin.

→ Full explanation: The harness — where Wadachi sits

Features

Persistent Memory — Knowledge stored as markdown files with SQLite metadata. Survives across sessions, searchable, human-readable.

Semantic Search — Finds memories by meaning, not just keywords. Ask for "linearizzazione sistemi" and it finds your notes on equilibrium points, even if the word "linearizzazione" never appears in them. Powered by local embeddings via fastembed — no API calls, no costs, runs on your machine.

Project Profiles — Register your projects with their filesystem paths. Wadachi auto-detects which project you're in and scopes memories accordingly. Your FeyNotes memories stay separate from your LaPlacebo memories.

Auto-Context — get_context is the killer tool: one call at session start that detects the project, gathers relevant memories, loads recent decisions, and returns everything your AI needs to hit the ground running.

Decision Log — Not just what you know, but what you decided and why. When a future session faces the same choice, it sees the rationale and the rejected alternatives — no more re-debating solved problems.

Constellation — Graph-Aware Recall — Plain recall is pure cosine top-k, so a memory that's strongly connected to your query but not textually similar never surfaces. Wadachi builds a weighted graph over your brain from citation edges ("memoria #82", "aggiorna #77" parsed from the prose), semantic k-NN edges, and shared-entity edges, then runs HippoRAG-style spreading activation (Personalized PageRank). recall_associative pulls up neighbours of your best hits even when their raw similarity is low — and returns the plain-cosine baseline alongside, so you can compare.

Entity Knowledge Graph (Graphify) — Extracts the entities inside your notes (convert.py, Di Gennaro, Opus 4.8) and the relations between them, linking memories that mention the same thing even when neither cites the other. Extraction runs through the local claude CLI — it uses your Claude plan, not metered API, so it costs $0 — and degrades gracefully when not installed.

Belief Revision — A plain store treats every memory as true forever; a brain shouldn't. review_beliefs does a read-only pass that flags memories likely gone stale — superseded by a newer note, past a temporal deadline ("resets 1 Jul"), or provisional/fallback wording — and annotates them in recall instead of silently trusting them. It never deletes: it suggests, you confirm with flag_stale / set_belief. Every update is non-destructive, so prior versions stay recoverable via memory_history.

Reflection & Insights — The brain thinks between sessions. reflect combines memories to surface cross-project analogies and non-obvious connections that no single memory holds — reusing the entity graph it already built, so no extra LLM cost. Candidates are proposed, never auto-trusted: you accept_insight (promoted to a real linked memory) or reject_insight.

Procedural Memory — Recency-ranked recall can hide the right rule and let you repeat a mistake twice. review_procedures clusters recurring incident memories by root theme and proposes a single always-on rule for review — human-in-the-loop, it never rewrites your operating instructions itself.

Quick Start

Three commands and your AI has a memory:

# 1 · install (pipx or uv — semantic search included, runs locally)
pipx install "wadachi[semantic]"        # or: uv tool install "wadachi[semantic]"

# 2 · guided setup: brain dir, database, Claude Code registration
wadachi init

# 3 · restart Claude Code — every session now starts with get_context

wadachi init creates the brain directory (default ~/.wadachi), brings the database to the latest schema, and registers the MCP server in Claude Code and Antigravity automatically. It is idempotent — safe to re-run anytime.

git clone https://github.com/EliaCinti/wadachi.git
cd wadachi
pip install -e ".[semantic]"
wadachi init

{
  "mcpServers": {
    "wadachi": {
      "command": "wadachi",
      "args": [],
      "env": {
        "BRAIN_DIR": "/Users/you/.wadachi"
      }
    }
  }
}

{
  "mcpServers": {
    "wadachi": {
      "command": "wadachi",
      "args": []
    }
  }
}

{
  "mcpServers": {
    "wadachi": {
      "command": "wadachi",
      "args": []
    }
  }
}

Register a project

In your first Claude session with Wadachi connected:

Register my project "feynotes" with description "Lecture audio to interactive web pages"
and path "/Volumes/ExtremeSSD/University/Lecture_From_Audio/"

Use it

From now on, every session can start with get_context and your AI already knows what's going on. As you work, important discoveries get stored automatically. Over time, the brain compounds — each session is smarter than the last.

Tools

Wadachi exposes 37 MCP tools — 26 in the menu by default, the ones a session reaches for while working, grouped by area below. The other 11 are brain maintenance, marked (maintenance): they stay out of the menu because measuring 741 real sessions showed they get chosen roughly once in total during work — but they are never gone, only a step further away, from the CLI (wadachi sleep, wadachi doctor) or by setting WADACHI_TOOLSETS=work,maintenance for a session that wants them back. manual prints the full description of every tool, in the menu or out.

Memory

Search & Context

Decisions

Projects

Desk

Constellation — Graph

Belief Revision

Reflection & Insights (all maintenance)

Procedural Memory (maintenance)

Consolidation

Provenance & Time

Memory Categories

Storage

All data lives locally in ~/.wadachi (configurable via BRAIN_DIR env var; a legacy ~/.engram dir keeps working):

~/.wadachi/
├── brain.db                    # SQLite: metadata + cached embeddings
├── global/                     # Cross-project knowledge
│   ├── python-venv-tips.md
│   └── git-workflow.md
└── projects/
    ├── feynotes/
    │   ├── pipeline-architecture.md
    │   ├── katex-gotchas.md
    │   └── deploy-workflow.md
    └── laplacebo/
        └── solver-design.md

Memories are plain markdown files with YAML frontmatter — readable and editable by hand.

LLM Wiki native · Obsidian vault · OKF bundle

The brain follows Karpathy's LLM Wiki pattern: an agent-maintained markdown wiki with [[wikilinks]], a generated index.md catalog, an append-only log.md, and a SCHEMA.md documenting the conventions (edit it — the schema file is yours). Every link becomes a graph edge that associative recall and consolidation travel on.

• Obsidian: the brain dir is a vault — open it and get the graph view for free. Zero lock-in.
• OKF: every file carries the Open Knowledge Format type field — the brain is a conformant OKF bundle, portable to any OKF consumer.
• wadachi doctor --fix upgrades pre-OKF brains in place (content never touched).

Upgrading

Your memories always survive an upgrade. The database schema is versioned: on first start after an update, wadachi applies any pending migrations — and backs up your brain.db automatically (to <brain>/backups/) before touching anything. Existing brains from older versions (including the Engram era, ~/.engram) are adopted in place: nothing to export, nothing to lose.

wadachi export              # optional but wise: read-only portable snapshot first
pipx upgrade wadachi        # or: uv tool upgrade wadachi
# restart Claude Code — migrations (if any) run on first start, after a backup

wadachi export never touches the brain (no migrations run) — safe even on a pre-wadachi Engram brain. wadachi restore <archive> --to <dir> brings it back somewhere new; --replace swaps the active brain (safety-exporting the current state first).

Search Modes

Wadachi ships with two search backends:

Semantic search runs entirely on your machine — no API calls, no cloud, no costs. The embedding model (BAAI/bge-small-en-v1.5, ~33M params) downloads once and runs locally.

Recently shipped

• Constellation — graph-aware associative recall (citation + semantic + entity edges, HippoRAG-style spreading activation)
• Graphify entity graph — entity/relation extraction over the brain via the local claude CLI ($0)
• Belief revision — stale / superseded / temporal flagging, annotated in recall, non-destructive
• Reflection & insights — cross-memory analogies proposed for accept/reject
• Procedural memory — recurring-incident clustering into candidate rules
• Non-destructive memory history — every update preserves prior versions
• Web graph visualizer — interactive constellation view, live at wadachi.eliacinti.dev

Roadmap

• Auto-summarize old memories to reduce token usage
• Memory importance decay (surface recent and frequently-accessed memories first)
• Claude Code hooks for automatic context injection + brain backup on session stop
• Export/sync with Notion
• Conversation history indexing
• Multi-language embedding model for better Italian support

Contributing

PRs welcome — read CONTRIBUTING.md first (philosophy: local-first, memories are sacred, propose don't auto-edit). Not a coder? The most valuable contribution is telling us how you use wadachi — there's no telemetry, feedback is all we have.

Acknowledgments

Inspired by mstrehse/mcp-brain — a Go-based MCP memory server that sparked the idea. Wadachi is a ground-up rewrite in Python with semantic search, project awareness, and auto-context injection.

License

MIT