# Codevira > Stop re-explaining your project to AI agents every session. One memory layer for Claude Code, Cursor, Windsurf, Antigravity — local, MIT, no signup. - **Type:** MCP server - **Install:** `agentstack add mcp-sachinshelke-codevira` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [sachinshelke](https://agentstack.voostack.com/s/sachinshelke) - **Installs:** 0 - **Category:** [Search](https://agentstack.voostack.com/c/search) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [sachinshelke](https://github.com/sachinshelke) - **Source:** https://github.com/sachinshelke/codevira - **Website:** https://sachinshelke.github.io/codevira/ ## Install ```sh agentstack add mcp-sachinshelke-codevira ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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`, `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. ```text $ 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 ```bash # 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](https://modelcontextprotocol.io) 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. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** yes - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-sachinshelke-codevira - Seller: https://agentstack.voostack.com/s/sachinshelke - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.