Codevira — persistent memory and decision enforcement for AI coding agents

Stop re-explaining your codebase to every AI tool — and stop the next agent from undoing the fix that took you three hours.

Quick Start  ·  See it in action  ·  Reference  ·  vs. other memory tools  ·  FAQ  ·  Website

Codevira 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

_{Claude Code · Claude Desktop · Cursor · Google Antigravity · OpenAI Codex · GitHub Copilot · any MCP-compatible AI tool}

30-second demo: MP4 · WebM · offline HTML player (no network, after cloning)

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

_{Latest: 4.0.1. 4.0 made enforcement universal — a locked decision now blocks a commit in every editor via a git pre-commit hook, not just an edit in Claude Code — and when it blocks, it shows the reasoning. 4.0.1 removes the deprecated codevira clean command plus two doctor/project-inventory fixes. Upgrading is automatic on the first server start. 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 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. Set CODEVIRA_AUTO_ADOPT=1 to 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.

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.

What's solid, what's not

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

MCP tool surface

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

Enforcement engine

CLI commands

Language support

Concurrency & safety

Upgrading & troubleshooting

Upgrading is automatic — codevira migrates your memory on the first server start after an upgrade, with no manual steps, and your existing decisions stay put. (After a pipx upgrade codevira, restart your IDE so its MCP server reloads the new binary.)

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 prune --ghosts), then run codevira doctor — it names the bound project and ships the exact fix for each ⚠/✗.

Full guides: IDE config hygiene · Antigravity · FAQ

Frequently asked

How do I give Claude Code persistent memory across sessions?

Install codevira and run codevira init in the project. Every new session starts with get_session_context() — a ~500-token brief of the project's decisions, current phase and next action — instead of you re-explaining the codebase.

Does this work with Cursor and Antigravity, or only Claude Code?

Memory works everywhere: every tool reads the same in-repo .codevira/decisions.jsonl and the generated AGENTS.md. codevira setup writes MCP server config automatically for the tools that support it (Claude Code, Claude Desktop, Cursor, Antigravity); Codex, Copilot and other agents are covered by the generated AGENTS.md. Hard edit-time blocking is Claude Code only — every other editor is covered at the commit boundary by codevira engine install-git-hook.

How is this different from a hand-written CLAUDE.md or AGENTS.md?

Those are static text you maintain by hand. Codevira generates AGENTS.md from a queryable decision log, keeps the reasoning attached to each decision, and blocks the edit that would break a locked one.

Does it use vectors or embeddings?

No. Decision search is SQLite FTS5/BM25 keyword search — no ChromaDB, no sentence-transformers, no torch. An AST scan in CI fails the build if any module but egress.py imports a network client.

Is my code or my memory sent anywhere?

No. Everything lives in <repo>/.codevira/ and ~/.codevira/ on your machine. MIT-licensed, no account, no API key, no cloud.

What does it cost in tokens?

Tools return summaries by default, get_session_context() is one ~500-token call, and the lean-12 tool profile cuts tools/list from 36 tools to 12 (~8.9K → ~3.5K tokens per session).

Longer answers: FAQ.md.

How Codevira compares

Most memory tools for AI agents retrieve. Codevira also enforces, and it is per-project across many tools rather than per-session inside one. If you need cross-machine cloud memory, a temporal knowledge graph at enterprise scale, or the top LongMemEval score, other tools are the better pick — that comparison is written out honestly, including where codevira loses: Codevira vs other AI memory tools (Mem0, claude-mem, Zep, MemPalace and others).

Deeper reading: Architecture · Wire protocol · How we dogfood it · Roadmap · Changelog · Migrating to 4.0 · How I built persistent memory for AI coding agents

Contributing

Contributions are genuinely welcome, and the backlog is open — see CONTRIBUTING.md for the dev setup and PR checklist.

Good places to start:

• Run it in an IDE you use and report what happened. That's how the support matrix grows.
• Windows. The sentinel-lock fallback is unit-tested but never load-tested on real hardware.
• Docs. Anything wrong or slow to find in this README or the FAQ is a bug — file it.

Channels:

• Bug? Open a bug report
• Feature or idea? Open a feature request
• Security issue? Read SECURITY.md — please don't use public issues for vulnerabilities.
• Conduct: CODE_OF_CONDUCT.md

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

License

MIT — free to use, modify, and distribute. See LICENSE.