Codevira

Cross-IDE decision memory for AI coding agents. One in-repo memory layer that every AI tool you use can read — plus PreToolUse hooks that physically block violating edits in Claude Code (other IDEs get the same decisions as AGENTS.md guidance, not a hard block). Local-first, MIT-licensed, ~83 MB pipx install.

Built for solo developers working on local projects with AI agents. Decisions live in <repo>/.codevira/decisions.jsonl — git-committed, team-shareable, visible in git diff. Every modern AI tool reads AGENTS.md, which codevira auto-generates as a slim 5 KB contract. Claude Code gets enforcement: PreToolUse hooks block Edit/Write calls that contradict decisions you marked do_not_revert.

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

What you get

• 🧠 One memory across every AI tool. A decision logged in Claude Code is visible to Cursor, Windsurf, Antigravity — all of them read the same .codevira/decisions.jsonl in your repo. No per-tool re-onboarding, no cloud sync.

• 🛡️ Hard enforcement, not soft hints. Decisions you mark do_not_revert get a PreToolUse hook (Claude Code) that physically refuses any Edit/Write call violating them. Other IDEs see the decision in AGENTS.md; Claude Code is the only one with hard hooks today.

• ⚡ One-command setup. pipx install codevira && codevira setup. Auto-detects installed AI tools (strong signals: binary on PATH + valid config file); only configures what's actually installed. Pass --force when the detector misses an install.

• 🔒 Local-first, MIT-licensed. Decisions in <repo>/.codevira/*.jsonl, code graph in .codevira-cache/ (rebuildable, gitignored), nothing leaves your machine. No SaaS, no account, no telemetry.

• 📦 Slim install (~83 MB pipx venv). No ChromaDB, no sentence-transformers, no torch. FTS5 SQLite for decision search, individual tree-sitter grammars (TS/JS/Go/Rust) for the code graph. MCP server starts in <100 ms.

• 🔐 Concurrent-safe under multi-IDE load. Every on-disk write goes through mcp_server/storage/atomic.py — crash-safe atomic writes + Posix fcntl.flock (Windows sentinel fallback). Two IDEs hitting the same project don't race on manifest.yaml / roadmap.yaml / AGENTS.md. Pinned by an in-process 50-thread stress test, a 20-subprocess cross-process stress test, and an adversarial chaos harness (scripts/chaos_smoke.py — 29 attacks including SIGKILL during lock, symlink traversal, malformed MCP payloads). See docs/architecture.md § "Concurrent-write safety".

Related MCP server: Tages

The Problem (Four Pains Codevira Solves)

If you code with AI agents on a project longer than a week, you've felt all of these:

1. Re-explaining your codebase every session

Every new chat starts from zero. The AI doesn't know your architecture, your conventions, your "we don't do it that way" decisions. You waste the first 10 minutes (and thousands of tokens) catching it up — only to do it again tomorrow.

2. AI undoing your careful decisions

Last week you debugged a tricky retry policy for 3 hours. Today's AI session refactors it to a simpler version because it has no idea why the complexity exists. Now it's broken again.

3. Cross-tool amnesia

You started planning in Claude Code. Switched to Cursor for autocomplete. Opened Antigravity to run tests. Three different agents, three different blind copies of your project state. Nothing carries over.

4. Token budget burned on re-discovery

Your AI agent reads the same 12 files every session before doing any actual work. You're paying API costs for the same lookups, over and over.

Codevira is a persistent memory layer that fixes all four — for every AI tool, on every project, on your local machine.

What's new in v3.4.0 — reliable project binding + honest docs

The headline fix: one user-scope codevira server now binds the right project instead of silently contaminating memory across projects. Upgrade and restart your MCP server to pick this up.

Since the v3.0.0 lean reset: 3.1 added five memory subsystems (working memory, skills, spatial, consensus, reflections), 3.3 added LLM-distilled preferences. Full history is in the CHANGELOG; what's coming next is in the Roadmap.

Full v3.4.0 release notes: CHANGELOG.md.

What's new in v3.0.0 — audited, lean, opinionated

Major version. v3.0.0 is the biggest API contraction since v2.0 shipped: 21 MCP tools deleted, 8 CLI subcommands deleted, per-IDE nudge file matrix collapsed to AGENTS.md only, IDE detection hardened from "directory exists" to "binary on PATH + valid config file." Full plan + rationale in docs/audit-2026-05-22.md; per-item kill list in docs/surface-cuts-2026-05-22.md.

Full v3.0.0 release notes: CHANGELOG.md.

Upgrading from v2.x? See the Migration notes section.

Quick Start — three commands

# 1. Install
pipx install codevira

# 2. Bootstrap the project (writes .codevira/, AGENTS.md, .gitignore)
cd ~/Projects/my-project
codevira init

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

Then commit .codevira/ + AGENTS.md + .gitignore to git so your teammates inherit the project memory. Open any IDE; codevira's MCP server is ready.

Verify:

codevira doctor          # 11-ish health checks, ✓/⚠/✗
codevira list-decisions  # any decisions recorded yet?
codevira sync            # regen AGENTS.md from current decisions.jsonl

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

What codevira setup actually does

The one command above replaces what used to take 5+ steps in v1.x:

• Detects installed AI tools via STRONG signals:

  • Claude Code: claude on PATH

  • Claude Desktop: ~/Library/Application Support/Claude/config.json exists + parses

  • Cursor: ~/.cursor/ + (cursor on PATH OR mcp.json exists)

  • Windsurf: mcp_config.json in ~/.windsurf/ or ~/.codeium/windsurf/

  • Antigravity: ~/.gemini/antigravity/mcp_config.json

• Injects MCP server config into each detected tool's config file (per-IDE schema handled automatically; no JSON to hand-edit).

• Installs Claude Code lifecycle hooks (SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, Stop) — these are what turn codevira from passive memory into the active guardian that blocks edits violating do_not_revert decisions.

• Writes AGENTS.md with the slim codevira-managed block (5 KB cap; preserves user content outside the marker boundaries).

Flags:

• --dry-run — preview without writing

• --ide <name> — narrow to one IDE (claude, claude_desktop, cursor, windsurf, antigravity, agents_md)

• --force — configure an --ide value even if codevira didn't auto-detect it (escape hatch for portable binaries / unusual config locations)

• -y / --yes — skip the confirmation prompt

• --no-hooks / --no-mcp / --no-nudge-files — scope-narrow the steps

What codevira doctor reports

11 health checks in one run, each with a concrete fix_command for any WARN or FAIL. Read-only — never modifies anything.

$ codevira doctor
Codevira health check
────────────────────────────────────────────────────────────
✓  python_version         Python 3.13 (≥ 3.10 required)
✓  codevira_data_dir      /Users/you/.codevira exists and is writable
✓  project_root           /Users/you/Projects/my-project is a valid project root
✓  codevira_dir           .codevira/ present (4 decision(s))
✓  agents_md_size         AGENTS.md is 1,234 bytes (≤10 KB safety threshold)
✓  graph_db               graph.db has all 4 expected tables
✓  global_db              ~/.codevira/global.db opens cleanly
✓  detected_ides          2 AI tool(s) detected: claude, cursor
✓  nudge_files            AGENTS.md present with codevira block
✓  watcher_circuit        watcher circuit clean (no recent failures)
✓  engine_kill_switch     engine ON (default; CODEVIRA_ENGINE not set)
✓  claude_mcp_visibility  codevira visible to Claude Code
✓  crash_log_size         no crash log (clean state)
────────────────────────────────────────────────────────────
summary: 13 pass · 0 warn · 0 fail

Daily-use commands

The CLI surface is 21 commands (the daily-use ones below):

Run codevira <cmd> --help for the full flag list on any subcommand.

Uninstall

# Reverse every system write made by init/setup. Preserves user content
# outside codevira marker blocks byte-for-byte.
codevira uninstall

# Common flags:
codevira uninstall --dry-run     # preview the plan; touch nothing
codevira uninstall --yes          # skip confirmation
codevira uninstall --keep-data    # uninstall the binary's footprint but
                                  # leave ~/.codevira/ and per-project
                                  # .codevira/ dirs alone
# Then remove the binary:
pipx uninstall codevira

Uninstall also strips legacy v2.1.x per-IDE nudge files (CLAUDE.md / GEMINI.md / .windsurfrules / .cursor/rules/codevira.mdc / .github/copilot-instructions.md) for users upgrading from older versions. User content outside the codevira markers stays.

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)                         │
│                                                                 │
│   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                     │
│                                                                 │
│   .codevira-cache/           gitignored, rebuildable             │
│     graph.sqlite             code graph (tree-sitter)           │
│     fts5.sqlite              FTS5 index over decisions.jsonl    │
│     hash-cache.db            file change detection              │
└─────────────────────────────────────────────────────────────────┘
                              ↑ MCP / hooks
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  PIPX INSTALL (~83 MB venv, ~/.local/pipx/venvs/codevira)       │
│                                                                 │
│   codevira (CLI + MCP server)                                   │
│      - pure Python, <100 ms startup                             │
│      - no chromadb / sentence-transformers / torch              │
└─────────────────────────────────────────────────────────────────┘
                              ↑ stdio MCP
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  IDE (Claude Code / Cursor / Windsurf / Antigravity / Codex /…) │
│                                                                 │
│   UserPromptSubmit → codevira hook → relevance-gated inject     │
│   Edit / Write → PreToolUse → block if do_not_revert violated   │
│   Stop → PostToolUse → optional outcome tracking                 │
└─────────────────────────────────────────────────────────────────┘

Token-efficient by design

Codevira is built around the principle that AI agent context windows are precious. Tools return summaries by default with opt-in full data:

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

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

• search_decisions(query) / list_decisions() — truncated matches by default. Pass full=true for verbatim text; pass summary_only=true for just IDs and one-line summaries.

The agent always asks for what it needs, in the size it needs.

Shrink the tool surface itself. The advertised MCP tools/list is a fixed per-session cost (~4K tokens for the full 24-tool surface). Set CODEVIRA_TOOL_PROFILE=lean in the MCP server's env block to advertise only the 11 daily-driver tools (~46% smaller); hidden tools still work when called explicitly. Bigger wins usually come from disabling MCP servers you aren't actively using.

MCP Tools

49 tools surfaced to AI clients via tools/list (token-optimized, summary-first): the core decision/roadmap/graph surface plus the v3.1.0 memory subsystems (working memory, skills, spatial, consensus, reflections) and the v3.3.0 preference tools. One additional admin tool (refresh_graph) is registered but hidden from tools/list because it runs automatically in the background — humans invoke it via codevira sync. Set CODEVIRA_TOOL_PROFILE=lean to advertise only the daily-driver subset. v3.0.0 cut 21 v2.x tools that produced noise or had no real users — see CHANGELOG.md for the full kill list.

Reads — the memory surface

Writes — capturing decisions

Roadmap

Code graph (Python + TS/JS + Go + Rust via tree-sitter)

Memory subsystems (v3.1.0)

Preferences (v3.3.0)

MCP Workflow Prompts

v3.0.0 removed 4 v2.x prompts (review_changes, debug_issue, pre_commit_check, architecture_overview) because they referenced deleted MCP tools. The slim surface means the AI can synthesize these workflows from the kept tools directly.

Language support

Decisions / AGENTS.md / roadmap are language-agnostic. Code-graph features require a tree-sitter grammar; v3.0.0 ships TS, JS, Go, Rust. The opt-in extra pip install 'codevira[all-languages]' re-adds the 17-grammar pack for Java, Ruby, PHP, C, C++, Kotlin, Swift, etc.

Production-stable vs known-limited

Background

Want to understand the full story behind why this was built, the design decisions, what didn't work, and how it compares to other tools in the ecosystem?

Read the full write-up: How I Built Persistent Memory for AI Coding Agents

Contributing

Contributions are welcome. Read CONTRIBUTING.md for the full guide.

• Reporting a bug? Open a bug report

• Requesting a feature? Open a feature request

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

FAQ

Common questions about setup, usage, architecture, and troubleshooting — see FAQ.md.

Roadmap

Current release: v3.4.0 — one user-scope server now binds the right project per call (no more cross-project memory contamination), Windows/UNC workspace roots, and a codevira doctor binding check.

Next up (directional, not dated):

• Summary-first payloads + session-transcript ingest — leaner responses, and memory that learns from how sessions actually went

• Eval harness — measurable recall + enforcement quality in CI

• Managed memory files beyond AGENTS.md — CLAUDE.md, .cursor/rules, GEMINI.md

• Optional [semantic] recall — off by default; the base install stays pure-keyword, no vectors, no model download

• TypeScript get_signature, finer-grained decision locking, learned hot-path tuning

What's built, the full upcoming list, and the long-term vision — ROADMAP.md.

Star History

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

License

MIT — free to use, modify, and distribute.