Codevira

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.

[](https://pypi.org/project/codevira/) [](https://pypi.org/project/codevira/) [](https://pepy.tech/project/codevira) [](LICENSE) [](https://modelcontextprotocol.io) [](CONTRIBUTING.md)

Built for solo developers working on local projects with AI agents. Decisions live in /.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

/.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 — narrow to one IDE (claude, claudedesktop, cursor, windsurf, antigravity, agentsmd`)

• --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 23 commands (the daily-use ones below):

| Command | What it does | |---|---| | codevira init | Bootstrap .codevira/ + AGENTS.md + .gitignore in this project | | codevira setup | Detect installed AI tools + write MCP configs + Claude Code hooks | | codevira doctor | Health check (read-only; ✓/⚠/✗ + fix commands) | | codevira status | Show index health + project state | | codevira projects | List tracked projects with staleness (today / 5d ago / stale 45d); projects archive drops one from the registry | | codevira index | Build / refresh the code graph cache | | codevira sync | Regenerate AGENTS.md + manifest + digest from decisions.jsonl | | codevira observe-git | Classify past decisions as kept/modified/reverted from git history | | codevira replay | Browse the decisions timeline (terminal / markdown / HTML) | | codevira search | Search decisions from the terminal (FTS5/BM25); --all-projects searches every registered repo, --json for scripts | | codevira clean | Remove orphaned project data | | codevira reset | Destructive cleanup (auto-exports decisions first) | | codevira export | Standalone decision backup (JSON / SQL); export setup bundles project memory + global learning for machine transfer | | codevira import | Restore a codevira export setup archive on a new machine (merges global learning) | | codevira graph | Render an interactive, self-contained HTML viewer of decision memory (offline, queryable) | | codevira uninstall | Reverse every system write codevira made (see ["Uninstall"](#uninstall)) | | codevira serve | Start MCP HTTP server (single-project; stdio is the daily mode) | | codevira engine | Internal — invoked by Claude Code lifecycle hook scripts |

Run codevira --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.

---

What's new in v3.5.0 — the read side gets intelligent

> Codevira's leverage is the read side: does it surface the right > memory at the right moment, with low noise? v3.5.0 makes that side > measurable, leaner, and self-tuning — and grew the smarts without > bundling a model or adding a single runtime dependency.

| Area | What you get | |---|---| | Summary-first decisions + expand | search_decisions / list_decisions now default to compact one-line rows; a new expand(ids=[…]) tool fetches full records only for the few you care about. full=true still works; CODEVIRA_DECISION_DETAIL=full restores the old verbose default. | | Content-aware decision lock | A do_not_revert file no longer hard-blocks every edit. An edit blocks only when its diff actually touches the locked decision's subject; a provably-orthogonal edit downgrades to a warn (the decision is still surfaced). Restore strict file-level locking with CODEVIRA_DECISION_LOCK_CONTENT_AWARE=0. | | It learns from real sessions | codevira reflect --from-sessions reads your local Claude Code / Codex / Gemini transcripts (read-only), flags failures + user corrections with no LLM, and folds a sanitized digest into reflection candidates — never auto-creating decisions. | | Measured + self-tuning recall | codevira eval scores read-side relevance (recall@k / MRR) on cases self-derived from your own memory — no fixtures to rot. codevira tune-weights learns the ranking weights against that eval and persists only a proven win (opt in at the hot path via CODEVIRA_LEARNED_WEIGHTS). | | More managed memory files | Beyond AGENTS.md, codevira can maintain CLAUDE.md, GEMINI.md, and .cursor/rules/codevira.mdc from one canonical block — opt in via .codevira/config.yaml: managed_files. Content outside the markers is preserved byte-for-byte. | | Opt-in synonym recall | A no-dependency synonym map widens a query so database can recall a decision recorded about postgres. Off by default (CODEVIRA_SYNONYM_WIDENING=1) — it trades a little ranking precision for recall. | | Polish | get_signature JS/JSX accuracy fixed; the two git outcome stores (confidence + replay) reconciled into one classifier; the doctor ghost_projects false positive fixed (empty leftover dirs are stale, not ghosts). |

Full v3.5.0 release notes: [CHANGELOG.md](CHANGELOG.md#350--2026-06-19).

Earlier releases — full history in the [CHANGELOG](CHANGELOG.md): v3.4 reliable per-call project binding (one user-scope server, no cross-project contamination) · v3.1 five memory subsystems (working memory, skills, spatial, consensus, reflections) · v3.0 the lean audit (46 → 24 tools, AGENTS.md-only nudge, ~83 MB install down from ~450 MB) · v2.2 dropped ChromaDB/vectors for SQLite FTS5.

---

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,  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

| Feature                       | Python | TS/JS | Go | Rust | Others |
|-------------------------------|:------:|:-----:|:--:|:----:|:------:|
| Decision capture + search     | ✓      | ✓     | ✓  | ✓    | ✓      |
| Cross-IDE memory via AGENTS.md| ✓      | ✓     | ✓  | ✓    | ✓      |
| Roadmap / sessions            | ✓      | ✓     | ✓  | ✓    | ✓      |
| Code graph + blast radius     | ✓      | ✓     | ✓  | ✓    | —      |
| `get_signature` / `get_code`  | ✓      | ✓     | ✓  | ✓    | —      |

Decisions / AGENTS.md / roadmap are language-agnostic. Code-graph
features require a tree-sitter grammar; codevira ships Python, TS, JS,
Go, Rust. For other languages the AI `Read`s the file directly — the
legacy 17-grammar `[all-languages]` pack was removed in v2.2.0 to keep
the install lean (v2.3.0 may re-add specific grammars on demand).

---

## Production-stable vs known-limited

| Production-stable | Known-limited |
|---|---|
| Cross-IDE decision memory via in-repo JSONL | The PreToolUse hook enforcement is Claude Code only today. Other IDEs read AGENTS.md (soft signal), but don't have hard blocks |
| `do_not_revert` enforcement at Claude Code PreToolUse | Symbol tools (`get_signature` / `get_code`) cover Python / TS / JS / Go / Rust; for other languages the AI `Read`s the file directly (the legacy `[all-languages]` grammar pack was removed in v2.2.0) |
| FTS5 decision search with BM25 ranking | Real-time multi-machine sync — by design, codevira is local-first; for team sharing, commit `.codevira/` to git |
| Per-project + cross-machine project inventory (`global.db`) | Web UI for browsing decisions — use the `codevira://decisions` MCP resource in Claude Desktop, or `codevira replay --format html` for a static file |
| All 50 surfaced MCP tools + 23 CLI commands + 8 engine policies | The HTTP server (`codevira serve`) is single-project per launch — for daily use, stick with stdio via `codevira setup` |
| Concurrent-safe storage layer (Posix `fcntl.flock` + Windows sentinel fallback). Proven against 50-thread + 20-subprocess stress + 29-attack chaos harness | The cross-process file-lock contract has been exercised on macOS + Linux CI; the Windows sentinel-file fallback is verified via unit-test simulation but hasn't been load-tested on real Windows yet |
| Code graph data store is functional but the v3.0.0 spec target (`/.codevira-cache/graph.sqlite`) and the actual location (`/graph/graph.db`) drifted during the surface-cut audit. Tracked for v3.1 reconciliation | n/a (functional today; spec-truthfulness gap only) |

---

## 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](docs/how-i-built-persistent-memory-for-ai-agents.md)

---

## Contributing

Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for
the full guide.

- **Reporting a bug?** [Open a bug report](https://github.com/sachinshelke/codevira/issues/new?template=bug_report.md)
- **Requesting a feature?** [Open a feature request](https://github.com/sachinshelke/codevira/issues/new?template=feature_request.md)
- **Found a security issue?** Read [SECURITY.md](SECURITY.md) — please
  don't use public issues for vulnerabilities.

---

## FAQ

Common questions about setup, usage, architecture, and troubleshooting
— see [FAQ.md](FAQ.md).

## Roadmap

**Current release:** **v3.5.0** — the read side gets intelligent:
summary-first decisions + `expand`, a content-aware decision lock,
read-only session-transcript ingest, a self-derived relevance eval +
learned weight tuning, multi-file managed memory, and opt-in synonym
recall — all with no new runtime dependencies.

**Next up** (directional, not dated):

- **Opt-in `[semantic]` recall** — off by default; the base install
  stays pure-keyword, no vectors, no model download
- **Symbol / region-level decision locking** — lock a function or
  block, not just the whole file
- **Cross-project decision search** — `search_decisions` across all
  your local projects, not just the current one

What's built, the full upcoming list, and the long-term vision —
**[ROADMAP.md](ROADMAP.md)**.

## Star History

If Codevira saves you tokens or sanity, a star helps other

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sachinshelke](https://github.com/sachinshelke)
- **Source:** [sachinshelke/codevira](https://github.com/sachinshelke/codevira)
- **License:** MIT
- **Homepage:** https://sachinshelke.github.io/codevira/

Install and usage instructions live in the source repository linked above.