Codevira MCP server
Commit Sep 11, 2026Provides a shared, in-repo memory layer for AI coding agents to store project decisions and enforce them by blocking regressive edits and commits.
Also known as sachinshelke/codevira
- Stars
- 12
- Tools
- 5
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Sep 11, 2026
- License
- MIT
What is Codevira MCP?
Codevira provides a shared, in-repo memory layer for AI coding agents to store project decisions and enforce them by blocking regressive edits and commits. It exposes 5 tools, such as get_session_context, list_decisions, list_tags.
Summary generated from the project's README
About Codevira MCP server
Developers working with multiple AI coding agents can use Codevira to establish a shared, in-repo memory layer. This local-first MCP server allows you to record project decisions and the reasoning behind them so that every tool on your machine stays informed. Instead of re-explaining your codebase to every new session, tools like Claude Code, Cursor, and GitHub Copilot can access a unified decision log stored within your repository.
Codevira distinguishes itself by moving beyond simple note-taking to active decision enforcement. By marking a decision with the do_not_revert flag, the server can physically block regressive edits within Claude Code and prevent invalid commits in any editor via a git hook. The system is designed to be lightweight and private, using keyword search instead of heavy vector databases, and requires no cloud accounts or external ML dependencies to function.
What you can do with it
- 1Preventing regressive code editsAn AI agent can be stopped from undoing a critical fix by blocking the specific tool call that violates a locked decision.
- 2Synchronizing context across different IDEsYou can plan a task in one AI tool and have the context immediately available when you switch to another editor.
- 3Reducing token usage and re-explanationAvoid wasting tokens by providing agents with summarized project decisions instead of making them re-read the entire codebase.
Written from the project's README. Every use case is checked against a quote from it.
Codevira MCP tools 5
Detected from the READMEget_session_contextlist_decisionslist_tagsrecord_decisionwrite_session_log
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablesachinshelke/codevira is public and reachablegithub.com/sachinshelke/codevira ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-15github.com/sachinshelke/codevira ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubCodevira is a local-first MCP server (Model Context Protocol) that gives every AI coding agent on your machine one shared, in-repo memory of the decisions you've made and why. What one tool learns, all of them know — and a decision you lock, none of them can silently undo: codevira refuses the edit in Claude Code and the commit in any editor.
pipx install codevira # ~66 MB pipx venv, no ML deps, no vectors
cd ~/Projects/my-project
codevira init # opt this project in
codevira setup # wire it into the AI tools on this machine
| What it is | A local MCP server that stores your project's decisions together with the reasoning behind them, in your repo. |
| What's different | It doesn't just remember — mark a decision do_not_revert and it physically blocks the edit (Claude Code) and, once you install the git hook, the commit (any editor) that would undo it. |
| Who it's for | Anyone running two or more AI coding tools on the same repo. |
| Default scope | Per-machine — memory is not git-tracked. codevira init --shared commits .codevira/ so teammates on the same repo share one decision log. |
| Cost | MIT · local-first · no cloud · no account · no vectors · nothing phones home. |
Why Codevira
AI agents write a large share of your code now. They're fast and capable, but each one is stateless across sessions and blind to the others — so you quietly became the memory.
| The pain | What Codevira does |
|---|---|
| Re-explaining your codebase every session — ten minutes and thousands of tokens, then again tomorrow | Every tool opens with the project's decisions already loaded |
| An agent "simplifies" a fix it never knew the reason for — three hours of debugging, undone | A locked decision is refused at the edit (Claude Code) and at the commit (any editor), with the original reasoning attached |
| Cross-tool amnesia — plan in Claude Code, code in Cursor, nothing carries over | One in-repo memory every MCP client reads |
| Token budget burned on re-discovery — the same dozen files re-read every session | Summary-first recall of only what's relevant |
The root cause under all four: your decisions live in your head, not anywhere the AI can be held to them.
Codevira is not a knowledge base. A knowledge base answers "what is true?" and hopes the agent reads it. Codevira answers "what did we decide, and why?" — then blocks the edit that would break it.
See it in action: record, block, recall
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 — plain text, human-readable, and diffable (and
git-tracked as soon as you run codevira init --shared). Codevira regenerates a slim AGENTS.md
contract from it — that file is always committed.
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") — D000412 comes back with its full context. A decision recorded in
one tool is visible to every tool.
Where the block is physical. Edit-time in Claude Code; commit-time in every editor via
codevira engine install-git-hook— because they all commit with git. Overrides, kill-switches and the precise boundary: Enforcement engine (expand).
What you get
| What it means | |
|---|---|
| One memory, 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. No per-tool re-onboarding, no cloud sync. |
| Enforcement, not notes | do_not_revert refuses the edit in Claude Code and refuses the commit in any editor. An Anti-Regression guard also blocks re-introducing a previously-fixed bug. Every guard ships a warn/off kill-switch. |
| One-command setup | codevira setup detects installed AI tools via strong signals (binary on PATH + valid config file) and configures only what's actually there. --force overrides a missed detect. |
| Local-first, no ML | Decision search is pure keyword/BM25 over SQLite FTS5 — no vectors, no ChromaDB, no sentence-transformers, no torch, nothing phones home. ~1–2 MB of memory per project. |
| Frugal by design | Tools return summaries by default; get_session_context() is one ~500-token call; the server cold-starts in well under a second with no ML model to load. |
| Concurrent-safe | Every write is a crash-safe atomic write behind a Posix fcntl.flock, so two IDEs on one project don't race. Details (expand) |
Latest: 4.2.0. Upgrade if you use codevira in more than one project: a stray registration at $HOME could make register-all discover exactly one project and discard every real one as “nested” (measured on a real machine: 1 found, 11 excluded). 4.2.0 also stops background work writing false entries to the crash log — 39 of 45 entries on that machine were one harmless line — and adds codevira reconcile to report duplicate and contradicting decisions. Upgrading is automatic, but a registration that was already wrong is not repaired for you: run codevira register-all once after upgrading to recover projects that went missing. Full release notes →
Quick Start
# 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
# 4. Install the universal commit-time backstop (enforces do_not_revert in ANY editor)
codevira engine install-git-hook
Step 4 is what makes enforcement universal. codevira init installs only a post-commit
reindex hook; the enforcing pre-commit hook is this separate, explicit opt-in.
Open any IDE — codevira's MCP server is ready. Then, 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.
Verify the install:
codevira doctor # health checks: ✓/⚠/✗ + a fix command for each
codevira replay # browse the decisions timeline
codevira sync # regenerate AGENTS.md from current decisions.jsonl
Team sharing. 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.
Opt-in tracking.
codevira initis the explicit opt-in. Codevira tracks only projects you'veinit-ed; a project you merely open stays inert (its tools return a "runcodevira init" hint and nothing is written), so~/.codevira/projects/never fills with projects you didn't choose. SetCODEVIRA_AUTO_ADOPT=1to track every project you open instead.
How it works
A local MCP server. Decisions live in <repo>/.codevira/*.jsonl — plain text, human-readable,
diffable, and git-tracked once you opt in with init --shared. A slim AGENTS.md is generated
from them for every IDE to read, and Claude Code lifecycle hooks — plus the opt-in git
pre-commit hook — enforce the ones you locked.
codevira init scaffolds everything above except roadmap.yaml and skills.jsonl, which are
written on first use. Deeper detail: docs/architecture.md.
Built to be trusted
Codevira holds a team's architectural decisions and can refuse your AI's edits. Every guarantee below is checked by the build, not asserted in this file.
| Test suite | 3,499 tests across 165 test files. More test code than product code (60,960 vs 46,782 lines). |
| CI | Every push to main and every pull request runs the suite on Python 3.10 / 3.11 / 3.12 / 3.13, plus a separate random-order run (collection-order blindness had hidden real state-leak bugs) and a mypy type-check job. |
| "Local-first" is enforced, not promised | tests/test_egress_boundary.py walks the import graph of the shipped package with an AST scan and fails the build if any module other than egress.py imports a network client. |
| Adversarial testing | scripts/chaos_smoke.py runs 8 hostile scenarios — SIGKILL during a held lock, symlink traversal, malformed MCP payloads, corrupt-JSONL degradation, read-only directories. |
| No destructive MCP tools | Every MCP tool carries destructiveHint=false. The only destructive operations (reset, uninstall) are CLI-only and require a typed confirmation — an autonomous agent cannot reach them. |
| Reversible memory | After a default init, .codevira/ is not git-tracked — so git revert can't undo a bad migration or an accidental wipe. codevira memory snapshot + codevira memory undo can, and the undo is itself undoable. |
What's solid, what's not
| Production-stable | Known-limited |
|---|---|
| Cross-IDE decision memory via in-repo JSONL | Hard PreToolUse enforcement at edit time is Claude Code only; other IDEs read AGENTS.md (advisory) and are backstopped at the commit boundary |
do_not_revert enforced at the Claude Code hook and, in any editor, at the commit boundary (codevira engine install-git-hook) |
Graph tools cover Python / TS / JS / Go / Rust; other languages → the AI Reads the file directly |
| FTS5/BM25 decision search | Real-time multi-machine sync — by design local-first; for team sharing, run codevira init --shared |
Per-project + cross-machine project inventory (global.db) |
No web UI — use the codevira://decisions MCP resource, or codevira replay --format html |
36 MCP tools advertised in tools/list (37 defined — refresh_graph is hidden) + 26 CLI commands + 7 engine policies |
The HTTP server (codevira serve) is single-project per launch — for daily use, stick with stdio |
Concurrent-safe storage (Posix fcntl.flock + Windows sentinel), thread + subprocess + chaos-tested |
Windows sentinel fallback is verified in unit tests but not yet load-tested on real Windows |
Anti-Regression on small Edit/MultiEdit hunks |
Anti-Regression does not yet detect full-file Write reverts; accuracy depends on fix: commit hygiene |
Reference
Everything below is depth for when you need it. Each section is collapsed — open the one you came for. Browser find-in-page does not search inside a closed section, so expand before Ctrl+F. What's in them:
CLI init setup doctor status projects untrack index sync repair-ids observe-git
replay search graph memory export import engine prune reset uninstall serve
working induce-skills eval register-all merge-driver
Env CODEVIRA_ENGINE CODEVIRA_TOOL_PROFILE CODEVIRA_DECISION_LOCK_MODE
CODEVIRA_ANTI_REGRESSION_MODE CODEVIRA_BLAST_RADIUS_MODE CODEVIRA_GIT_HOOK_MODE
CODEVIRA_DECISION_LOCK_CONTENT_AWARE CODEVIRA_SESSION_LOG_ENFORCER_MODE
CODEVIRA_AUTO_ADOPT CODEVIRA_IDE
Codevira MCP questions
What tools does Codevira MCP provide?
It exposes 5 tools, including get_session_context, list_decisions, list_tags, record_decision, write_session_log.
How does Codevira prevent AI agents from undoing important fixes?
It uses a 'do_not_revert' flag that physically blocks edits in Claude Code and prevents commits in any editor via a git hook if a decision is violated.
Does Codevira require a cloud account or internet connection?
No, it is a local-first tool that requires no signup, no cloud, and nothing phones home.
Can multiple AI tools share the same memory?
Yes, it provides one shared, in-repo memory that all MCP-compatible tools on your machine can read.
Does it use vector databases for searching decisions?
No, it uses pure keyword/BM25 search over SQLite FTS5 without any ML dependencies or vector databases.