Codevira MCP

It doesn't just remember — it enforces. Mark a decision do_not_revert and Codevira physically blocks the edit that would break it: before the file changes in Claude Code, and at the commit boundary in every other editor (codevira engine install-git-hook) — because they all commit with git. When it blocks, it shows you why the decision was made, not just that one exists. Local-first, MIT, no cloud, no vectors, no account.

Works with: Claude Code · Claude Desktop · Cursor · Google Antigravity · OpenAI Codex · GitHub Copilot · any MCP-compatible AI tool.

The problem — four pains, every AI project

If you've coded with AI agents on one project for longer than a week, you've felt all four:

1. Re-explaining your codebase every session. Every new chat starts from zero. You spend the first ten minutes (and thousands of tokens) catching the AI up on your architecture and conventions — then do it again tomorrow.

2. AI quietly undoing your careful decisions. You debugged a tricky retry policy for three hours last week. Today's session "simplifies" it, because nothing remembered why the complexity existed. Now it's broken again.

3. Cross-tool amnesia. Plan in Claude Code, autocomplete in Cursor, run tests in Antigravity — three agents, three blind copies of your project state, nothing carried over.

4. Token budget burned on re-discovery. The agent reads the same dozen files every session before doing any real work. You pay for the same lookups over and over.

Under all four is one root cause: your decisions live in your head, not anywhere the AI can be held to them. The reasoning that justifies a choice — why it won, what you rejected, when it stops being valid — is exactly what no tool captures. So every new agent is free to overwrite a decision it never knew you made.

Codevira fixes that by storing the decision together with its justification, and enforcing the ones you lock. It is not a knowledge base — it doesn't index your code as facts to search. A knowledge base answers "what is true?" and hopes the agent reads it; Codevira answers "what did we decide, and why?" — then physically blocks the edit that would break it. The knowledge is there, but it's always bound to a decision, never a corpus you query. Local, in-repo, shared across every AI tool.

Related MCP server: Tages

What using it looks like

The payoff is a loop: record once → shared everywhere → enforced later.

1. You (or the AI) record a decision — one MCP call, ~50 tokens.

record_decision(
  decision="Use bcrypt for password hashing",
  context="md5 considered and rejected — rainbow-table risk. Re-examine only if NIST guidance changes.",
  tags=["auth", "security"],
  do_not_revert=true,
)
→ D000412 recorded and locked.

It lands in <repo>/.codevira/decisions.jsonl — human-readable, git-committed, visible in git diff. Codevira regenerates a slim AGENTS.md contract from it.

2. Weeks later, a fresh Claude Code session tries to swap bcrypt for md5.

The Edit goes through Claude Code's PreToolUse hook first. Because the diff touches the locked decision's subject, the hook denies the tool call and hands the agent the original reasoning:

✗ Edit blocked — decision_lock (do_not_revert)
  D000412: "Use bcrypt for password hashing"
  context: md5 rejected — rainbow-table risk.
  The file was not modified. Surface this to the human and re-decide deliberately.

The regression never reaches disk. (An orthogonal edit to the same file — one whose diff doesn't touch the decision's subject — is allowed through and downgraded to a warn. Precision, not paranoia.)

3. You switch to Cursor the next morning — and it already knows.

You never re-explained anything. Cursor reads the same repo AGENTS.md (and, over MCP, can call search_decisions("auth")) and sees D000412 with its full context. A decision recorded in one tool is visible to every tool. The hard block is Claude Code only today; the shared memory is universal.

The honest caveat, updated in 4.0: only Claude Code's PreToolUse hook blocks at edit time, because only its edits route through codevira's engine. In Cursor / Codex / Copilot the decision is advisory context in AGENTS.md while you type.

4.0 closes that at the commit boundary instead. codevira engine install-git-hook runs locked decisions against staged changes through the same engine — so the veto is physical in any editor, because they all commit with git. Verified on a repo with no IDE hook installed: the commit was refused by git with the decision's reasoning attached. git commit --no-verify overrides once; CODEVIRA_GIT_HOOK_MODE=warn disables it. Merge commits are never blocked.

Verified on Claude Code (2026-08-01, 4.0.0b1): a locked decision returns permissionDecision: deny with exit 2, the refusal carries the decision's reasoning, rejected alternatives and re-examination trigger, and the verdict is recorded with its evidence. Other IDEs are supported but not yet verified to this standard — each is being taken one at a time rather than inferred (D00012Q).

Quick Start — three commands

# 1. Install (production install: ~66 MB pipx venv, no ML deps)
pipx install codevira

# 2. Opt this project in (writes .codevira/, AGENTS.md, .gitignore)
cd ~/Projects/my-project
codevira init

# 3. Wire codevira into every AI tool detected on this machine
codevira setup

By default codevira keeps decision memory per-machine (not committed), so unrelated projects never bleed into each other; AGENTS.md and .gitignore are still committed. To share memory with teammates on the same GitHub repo, run codevira init --shared — it keeps .codevira/ git-tracked, and a built-in git merge driver reconciles concurrent edits. Open any IDE — codevira's MCP server is ready.

Opt-in tracking (v3.7.0). codevira init is the explicit opt-in. Codevira tracks only projects you've init-ed; a project you merely open stays inert (its tools return a "run codevira init" hint and nothing is written), so ~/.codevira/projects/ never fills with projects you didn't choose. Existing tracked projects are grandfathered — zero migration. Set CODEVIRA_AUTO_ADOPT=1 to track every project you open instead.

Verify:

codevira doctor          # 18 health checks, ✓/⚠/✗ + a fix command for each
codevira replay          # browse the decisions timeline
codevira sync            # regenerate AGENTS.md from current decisions.jsonl

Try it. In your AI tool, ask: "Use get_session_context to brief me on this project." You get a ~500-token structured project state in one tool call instead of the AI re-reading docs.

What you get

• One memory across every AI tool. A decision logged in Claude Code is visible to Cursor, Antigravity, Codex, Copilot — all read the same .codevira/decisions.jsonl and generated AGENTS.md in your repo. No per-tool re-onboarding, no cloud sync.

• Enforcement, not just notes (Claude Code). Decisions you mark do_not_revert get a PreToolUse hook that refuses violating edits, plus an Anti-Regression guard that blocks re-introducing a previously-fixed bug. Every guard ships a per-policy warn/off env kill-switch and a global CODEVIRA_ENGINE=0. Other IDEs get the same decisions as advisory AGENTS.md.

• One-command setup. pipx install codevira && codevira setup detects installed AI tools via strong signals (binary on PATH + valid config file) and configures only what's actually installed. --force overrides a missed detect.

• Local-first, no ML. Everything lives in <repo>/.codevira/*.jsonl (git), with rebuildable caches under ~/.codevira/. Decision search is pure keyword/BM25 (SQLite FTS5) — no vectors, no ChromaDB, no sentence-transformers, no torch, nothing phones home. ~1–2 MB of committed memory per project.

• Frugal by design. Tools return summaries by default; warm tool calls return in a few milliseconds; the server cold-starts in well under a second with no ML model to load.

• Concurrent-safe under multi-IDE load. Every write is a crash-safe atomic write behind a Posix fcntl.flock (Windows sentinel fallback), so two IDEs on one project don't race — verified by thread, subprocess, and adversarial chaos tests. Details in Concurrency & safety.

Latest: 4.0 (beta) — the release that makes enforcement universal and memory self-explaining. A locked decision now blocks a commit in every editor (git pre-commit), not just an edit in Claude Code — and when it blocks, it shows the reasoning: why the decision was made, what you rejected, when to revisit. Content-addressed records survive a two-host git merge; one audited module is the only thing that can touch the network (CI-enforced); 15 unused MCP tools were cut with migration messages. One breaking change (per-tenant global.db), with codevira memory undo as the rollback path. Upgrading is automatic on the first server start, no manual steps. All model-free, all local. See the CHANGELOG.

How It Works

Codevira is a Model Context Protocol server that runs locally and gives any AI tool a structured, queryable memory of your codebase.

┌─────────────────────────────────────────────────────────────────┐
│  IN THE PROJECT REPO (committed to git)          (selected)     │
│                                                                 │
│   AGENTS.md                  ≤5 KB slim contract, auto-generated │
│      ↑                                                          │
│   .codevira/                                                    │
│     decisions.jsonl          full text + metadata (append-only) │
│     digest.jsonl             slim summary for prompt injection  │
│     outcomes.jsonl           kept/reverted from git observation │
│     manifest.yaml            tag→ids, file→ids index (regen)    │
│     enforcement.yaml         which decisions hard-block         │
│     config.yaml              project settings                   │
│     sessions.jsonl           session events                     │
│     roadmap.yaml             phase tracking                     │
│     (also: skills / reflections / preferences / learned rules)  │
│                                                                 │
│   .codevira-cache/           gitignored, rebuildable            │
│     fts5.sqlite              FTS5 index over decisions.jsonl    │
│     hash-cache.db            file change detection              │
│     working.jsonl            intra-session scratchpad           │
│   (the code graph is a per-project SQLite db under ~/.codevira/)│
└─────────────────────────────────────────────────────────────────┘
                              ↑ MCP / hooks ↓
┌─────────────────────────────────────────────────────────────────┐
│  PIPX INSTALL (~66 MB venv, ~/.local/pipx/venvs/codevira)      │
│   codevira (CLI + MCP server)                                   │
│      - pure Python; no chromadb / sentence-transformers / torch │
│      - server cold-start well under 1 s; warm tool calls ~2 ms  │
└─────────────────────────────────────────────────────────────────┘
                              ↑ stdio MCP ↓
┌─────────────────────────────────────────────────────────────────┐
│  IDE (Claude Code / Cursor / Antigravity / Codex /…)         │
│                                                                 │
│   UserPromptSubmit → codevira hook → relevance-gated inject     │
│   Edit / Write → PreToolUse → block if do_not_revert violated   │
│   PostToolUse → Post-Edit Graph Refresh (+ working-mem fanout)  │
│   Stop → Token Budget / Session-Log Enforcer                    │
└─────────────────────────────────────────────────────────────────┘

Token-efficient by design

AI context windows are precious. Tools return summaries by default with opt-in full data:

• get_node(path) — ~100 tokens by default (counts + flags); full=true for the full rules array.

• get_impact(path) — up to 10 affected files; summary_only=true for just counts (~80 tokens) before you dig deeper.

• search_decisions(query) / list_decisions() — top 5 truncated matches by default; full=true for verbatim text, summary_only=true for one-line summaries, then expand(ids=[…]) to pull only the few full records you want.

Shrink the tool surface itself. The advertised tools/list is a fixed per-session cost (~8K tokens for the full 51-tool surface). Set CODEVIRA_TOOL_PROFILE=lean in the MCP server's env block to advertise only the 12 daily-driver tools — a ~71% token trim of tools/list. Hidden tools still work when called explicitly.

MCP tool surface (deep dive)

51 tools are surfaced to AI clients via tools/list (a 52nd, refresh_graph, is registered but hidden — humans invoke it via codevira sync). All 51 carry MCP ToolAnnotations (readOnlyHint / destructiveHint=false / idempotentHint): 29 are read-only and can run without a confirmation prompt, and no MCP tool is destructive — the only destructive ops (reset / uninstall) are CLI-only, never exposed over MCP. Good to know for anyone wiring codevira into an autonomous agent.

The lean 12 (CODEVIRA_TOOL_PROFILE=lean) are deterministic and worth knowing verbatim, since they're what you keep:

get_session_context · get_impact · get_node · get_roadmap · search_decisions
list_decisions · expand · record_decision · update_phase_status
complete_phase · update_next_action · write_session_log

Reads — the memory surface

Writes — capturing decisions

Roadmap

get_roadmap · get_phase · add_phase · update_phase_status · update_next_action · complete_phase · defer_phase · bulk_import_phases.

Code graph

get_node (file metadata) · get_impact (blast radius) · query_graph (function-level callers/callees/tests/dependents/symbols) · get_playbook (curated rules for add_tool / add_service / add_schema / debug_pipeline / commit / write_test). Plus the hidden refresh_graph.

Memory subsystems

Removed in 4.0 (52 tools → 37 defined; 36 advertised)

Cut on measured usage across 4,203 transcripts, not on taste. The data they wrote is untouched — these were surfaces, and codevira export still includes everything.

See MIGRATING.md for the upgrade path.

MCP Workflow Prompt

onboard_session — full project catch-up for new sessions; wraps get_session_context().

Language support

Decisions / AGENTS.md / roadmap are language-agnostic — they work for any language. Code-graph and symbol tools cover exactly Python (stdlib ast) plus TS / TSX / JS / JSX / Go / Rust (bundled tree-sitter grammars — 4 pip packages, since TSX ships inside the TypeScript grammar). For any other language the AI Reads the file directly. The legacy 17-grammar [all-languages] pack was removed in v2.2.0 to keep the install lean.

Enforcement engine (deep dive)

Codevira ships 8 default engine policies ("heroes"), each hooked to Claude Code lifecycle events: SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, Stop.

How verdicts combine. The three edit guards compose into a single verdict — first block wins by priority (Decision Lock 100 > Anti-Regression 80 > Blast-Radius 50). The highest-priority block's message is what you see; the rest are recorded as telemetry.

Fail-open and opt-in. The dispatcher never raises: each policy is wrapped in try/except and returns allow on failure. CODEVIRA_ENGINE=0 disables all policies; each edit guard also has a per-policy off|warn|block env override (CODEVIRA_DECISION_LOCK_MODE, CODEVIRA_ANTI_REGRESSION_MODE, CODEVIRA_BLAST_RADIUS_MODE). And enforcement is not global across all Claude Code projects — in any project you never ran codevira init on, the hooks stay fully inert.

Why "Claude Code only." The hard-block path is Claude Code's real PreToolUse hook. Edits from Cursor / Codex / Copilot go straight to the filesystem — they never reach codevira's PreToolUse engine at all — so those IDEs get the decisions as advisory AGENTS.md context instead.

Concurrency & safety

Every on-disk write goes through mcp_server/storage/atomic.py: a crash-safe atomic write (mkstemp + fsync + os.replace) behind a Posix fcntl.flock (with an in-process threading.Lock first, and a Windows O_EXCL sentinel fallback). Appends to the JSONL logs are line-atomic — concurrent appenders never interleave bytes. Result: two IDEs hitting the same project don't race on manifest.yaml / roadmap.yaml / AGENTS.md.

This is exercised by a 50-operation stress over a 10-thread pool, a 20-subprocess cross-process stress (spawn), and an adversarial chaos harness (scripts/chaos_smoke.py — 8 scenarios / 29 checks including SIGKILL during a held lock, symlink traversal, malformed MCP payloads, corrupt-JSONL graceful degradation, and read-only-directory hostility). See docs/architecture.md § "Concurrent-write safety".

CLI

~26 user-facing commands; the daily-use ones:

Run codevira <cmd> --help for full flags. Uninstall with codevira uninstall then pipx uninstall codevira.

Production-stable vs known-limited

Background

Want the full story — why this was built, what didn't work, how it compares to other memory tools? Read How I Built Persistent Memory for AI Coding Agents.

Contributing

Contributions welcome — see CONTRIBUTING.md.

• Bug? Open a bug report

• Feature? Open a feature request

• Security issue? Read SECURITY.md — please don't use public issues for vulnerabilities.

FAQ & Roadmap

Common questions on setup, usage, and troubleshooting: FAQ.md. What's built, what's next, and the long-term vision: ROADMAP.md. Full release history: CHANGELOG.md.

Upgrading. It's automatic — codevira migrates your memory on the first server start after an upgrade, with no manual steps, and your existing decisions stay put. If an IDE then shows the wrong project, doesn't show codevira at all, or memory looks missing, it's almost always a stale IDE-config entry rather than lost data. Two fixes cover most cases: remove a stray or temporary entry with codevira untrack <path> (or sweep dead ones with codevira clean --ghosts), then run codevira doctor — it names the bound project and ships the exact fix for each ⚠/✗. Full guides: IDE config hygiene and Antigravity.

Star History

If Codevira saves you tokens or sanity, a star helps other developers find it.

License

MIT — free to use, modify, and distribute.