Your AI coding agent
has amnesia.

Every AI tool you use shares one local record of the decisions you've made and why — and codevira enforces the ones you lock: blocking the edit before it touches disk in Claude Code, and the commit in every other editor, because they all commit with git. When it blocks, it shows you the reasoning.

Get started free See how it works ↓

📁~1 MB per project 🔀lives in your repo 💻machine-to-machine transfer 🔒no cloud ⚖️MIT licensed

terminal

# install once
$ pipx install codevira

# wire up every AI tool on this machine
$ codevira setup

# opt a project in — codevira tracks only what you init
$ cd my-project && codevira init

36MCP toolsthe sharpened agent surface

8hook policiesenforcing memory live

~2 mswarm tool callnever blocks your IDE

0cloud dependenciesyour code stays home

At a glance

The whole system, one picture

Every AI tool on your machine reads and writes one memory that lives in your repo — and the decisions you lock escalate from remembered, to surfaced, to refused.

Diagram: codevira sits at the centre of your toolchain. Claude Code, Claude Desktop, Cursor and Antigravity connect over the MCP server, while OpenAI Codex and GitHub Copilot read the generated AGENTS.md — all of them recording decisions into and recalling context from one in-repo memory at .codevira/*.jsonl. Six capabilities orbit that memory: Decision Memory (why it won, what you rejected), Enforcement Engine (7 policies, 5 lifecycle events), Code Graph (blast radius: who calls this), Cross-Tool Sync (one log, every MCP client), Session Context (~500-token brief, one call) and Anti-Regression (blocks re-breaking a fixed bug). A strip along the bottom shows how far a decision goes: remember, surface, warn, block.

The story

Why codevira exists

01 · THE PROBLEM

Brilliant in the moment.
Amnesiac across sessions.

Today's coding agents write code at a senior level — then forget everything when the session ends. You re-explain the architecture. You re-justify old choices. And one day an agent confidently reverts the bcrypt decision you made three months ago, because nothing remembered why.

02 · THE INSIGHT

Remembering isn't enough.
Memory must push back.

Notes that nobody reads don't prevent regressions. Codevira sits in the agent's tool-call path: when an edit would revert a protected decision or re-introduce a fixed bug, the edit is blocked — with the original reasoning surfaced, so human and AI can re-decide deliberately.

03 · THE PHILOSOPHY

Your memory belongs to you.
Not to one IDE. Not to a cloud.

Project memory lives in .codevira/ — human-readable JSONL, git-tracked, diffable, ~1 MB. Switch IDEs, switch machines, switch AI vendors: the memory comes with you. Codevira is built to be a primitive the whole AI ecosystem can build on, not a feature of one tool.

“ Every AI tool you open reads and writes the same project memory. What one learns, all of them know — and what you lock, an agent in Claude Code can't quietly revert.
The Codevira design contract

How it works

Four moments in the life of a memory

Watch the loop: a decision is recorded once, shared everywhere, enforced forever — and your agents keep learning on top.

1 Record The AI captures a decision — one MCP call, ~50 tokens.

2 Share Every other AI tool sees it instantly via the same repo files.

3 Enforce Months later, a careless edit is vetoed before the file changes.

4 Learn Skills and fix history accumulate on top.

claude code

The graph

Memory you can see

Run codevira graph and your project's decision memory renders as an interactive, fully offline HTML viewer — decisions, files, tags, and the lineage between them. This is a live miniature. Drag the nodes. Click one.

live · drag & click a node

protected decision file

D000412

decision

Use bcrypt for password hashing

context

md5 considered and rejected — rainbow-table risk. Re-examine only if a NIST recommendation changes.

do_not_revertsecurityauth

← click any node to inspect it

Generated per-project by codevira graph — searchable, queryable, zero network.

The wedge

Memory that pushes back

🔒

Decision lock 3.5

Mark a decision do_not_revert and the lifecycle hook vetoes any AI edit that would undo it. Now content-aware: an edit blocks only when it actually touches the decision's subject — orthogonal changes pass. Precision, not paranoia.

🛡️

Anti-regression

Commits tagged fix: build a fix-history database. An AI silently re-introducing a fixed bug gets stopped at the door.

📡

Blast-radius veto

Editing a public signature that 12 files depend on? Codevira shows the callers and refuses until the change covers them.

🧠

Working memory

Decay-scored intra-session scratchpad. The agent's train of thought survives context compaction.

⚙️

Skill library

Reusable procedures ("how we rebase here") with git-driven reinforcement — skills that keep failing get archived automatically.

🔎

Refusals that explain themselves 4.0

When a locked decision blocks an edit, codevira shows why it was made — the reasoning, the rejected alternatives, the condition to revisit — not just that a rule exists.

🔗

Survives a team merge 4.0

Records are content-addressed, so a decision's supersession chain stays intact when two machines merge the same repo — no lost locks, no dangling history.

↩️

One egress door, one undo 4.0

A single audited module is the only thing that can touch the network — a CI test fails the build if any other file imports an HTTP client. codevira memory undo rolls back any change.

📦

Machine transfer 3.3

codevira export setup → one archive → codevira import on the new machine. Memory and learning come with you.

👥

Team-shared memory 3.7.1

codevira init --shared commits the project's decision memory so teammates on the same repo share it; a built-in git merge driver reconciles concurrent edits. Default stays per-machine, so unrelated projects never bleed together. Opt-in.

The hard block now runs two ways. In Claude Code (and Antigravity), a PreToolUse hook refuses the edit before it touches disk. In every other editor — Cursor, Codex, Copilot — an opt-in git pre-commit hook (codevira engine install-git-hook) runs the same engine at the commit boundary, so the veto is physical there too — because every editor commits with git. Without the git hook, those tools still get the decisions as strong AGENTS.md guidance. Shared memory was always universal; as of 4.0, hard enforcement is too — at whatever point each tool reaches.

Cross-IDE

One memory. Every tool.

A decision logged in Claude Code shows up in Cursor. A fix recorded today blocks the same regression in Cursor tomorrow — through MCP plus an auto-generated AGENTS.md every modern tool reads natively.

Claude CodeMCP + hooks

CursorMCP + AGENTS.md

CopilotAGENTS.md

Gemini CLIGEMINI.md (opt-in)

CodexAGENTS.md

AntigravityMCP + AGENTS.md

Any MCP clientstandard protocol

codevira setup writes MCP server entries for Claude Code, Claude Desktop, Cursor and Antigravity. Codex and Copilot get the memory the way they already read it — the generated AGENTS.md, no MCP config needed. Gemini CLI isn't a setup target; point it at the memory by opting a project's GEMINI.md in via .codevira/config.yaml.

Why not just…

Your tools alone vs. with codevira

Every IDE has some context feature. None of them persist across tools, none of them enforce, and the moment you switch IDEs you start from zero.

Capability	IDE alone (chat history, .cursorrules)	Rules files (hand-written CLAUDE.md)	Cloud memory (SaaS recall tools)	Codevira
Memory survives the session	✗	✓	✓	✓
Shared across every IDE	✗	partial	✓	✓
Writes itself (AI-captured)	✗	✗ manual	✓	✓
Enforces — blocks reverting edits	✗	✗ advisory	✗ advisory	✓
Blocks re-introducing fixed bugs	✗	✗	✗	✓
Knows your code graph (blast radius)	✗	✗	✗	✓
Local-first — code never leaves	✓	✓	✗ their cloud	✓
Git-tracked, diffable, reviewable	✗	✓	✗	✓
Learns your preferences from real prompts	✗	✗	partial	✓
Price	—	free	subscription	free · MIT

Codevira doesn't replace your IDE's features — it's the layer underneath all of them.

Token economics

Memory is cheaper than amnesia

Re-explaining your project every session costs real tokens — and real money. Codevira's read surface is summary-first by design: one ~500-token call replaces the catch-up conversation entirely.

“Catch me up on this project”

New session, returning agent.

without

~20,000 tk

re-paste architecture · re-read files · re-justify choices

with

~500 tk

one get_session_context() call

~97% less

“What did we decide about auth?”

Mid-session architecture question.

without

~8,000 tk

grep, open 5 files, reconstruct intent — often wrong

with

~250 tk

one search_decisions("auth") call — with the original why

~97% less

A regression ships

The expensive one nobody budgets for.

without

~60,000 tk

bug report · debugging session · re-fix · re-review

with

~0 tk

edit vetoed at the hook — before the file changed

prevented

Illustrative sessions from codevira's own development. The injection side is just as frugal: ≤3 relevant decisions per prompt, 0 tokens when off-topic, ~30 tokens for your style profile.

Machine to machine

Your memory moves with you

New laptop? Two commands. Project memory already travels with git clone — the transfer archive brings your cross-project learning (preferences, learned rules) on top.

old machine → new machine

# old machine — one archive with everything
$ codevira export setup
✓ codevira-setup.tar.gz
  project memory (.codevira/) + global learning

# new machine
$ pipx install codevira
$ codevira import codevira-setup.tar.gz
✓ project memory restored
✓ global learning merged — never overwrites what's already there
$ codevira init   # re-register IDEs, rebuild caches

Moves with git Decisions, sessions, skills — already in your repo. Clone and they're there.

Moves in the archive Cross-project learning: your preferences and learned rules, merged — not overwritten — into the new machine.

Rebuilt fresh Code-graph caches and indexes are machine-local and regenerate on first run. Nothing to migrate, nothing to break.

Integration

MCP is the SDK

Codevira speaks the Model Context Protocol — the open standard every major AI tool already implements. codevira setup auto-configures everything it detects; here's what it writes, per tool, if you'd rather do it by hand.

# one command — detects installed AI tools, writes MCP configs,
# installs Claude Code lifecycle hooks, generates AGENTS.md
$ codevira setup

✓ Claude Code    MCP config + 5 lifecycle hooks
✓ Cursor         MCP config + AGENTS.md
✓ Gemini CLI     MCP config + AGENTS.md

Fully reversible: codevira uninstall removes every system write.

// ~/.claude.json  — one user-scope entry (v3.7.0 default)
{
  "mcpServers": {
    "codevira": {
      "command": "/path/to/codevira-python",
      "args": ["-m", "mcp_server"]
    }
  }
}

One registration for every project — the server resolves the active project from your editor's workspace roots at runtime. Claude Code also gets lifecycle hooks (PreToolUse / PostToolUse / UserPromptSubmit / Stop / SessionStart) — that's where enforcement lives.

// ~/.cursor/mcp.json  — one user-scope entry (v3.7.0 default)
{
  "mcpServers": {
    "codevira": {
      "command": "/path/to/codevira-python",
      "args": ["-m", "mcp_server"]
    }
  }
}

One entry, project resolved from workspace roots at runtime. Cursor also reads the repo's AGENTS.md natively — the decision digest rides along with zero config.

# Codevira is a standard MCP stdio server — any client in any
# language connects with the usual MCP SDK. Python example:

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

params = StdioServerParameters(command="codevira-python", args=["-m", "mcp_server"])
async with stdio_client(params) as (r, w):
    async with ClientSession(r, w) as s:
        await s.initialize()
        ctx = await s.call_tool("get_session_context", {})

36 tools: decisions, roadmap, code graph, working memory, skills, provenance. TypeScript, Go, Rust, Java MCP SDKs all work the same way.

# No SDK at all? The memory is just files in your repo.
$ cat .codevira/decisions.jsonl | jq '.decision'
"Use bcrypt for password hashing"
"JSONL is the canonical store; SQLite is a rebuildable index"

# Every language that can read a file can read codevira memory.
# That's the point.

Git-tracked, human-readable, vendor-neutral. Your memory survives every tool you'll ever switch to.

Capability	Python	TS / JS	Go	Rust	Every other language
Decision capture, search & enforcement	✓	✓	✓	✓	✓
Cross-IDE memory via AGENTS.md	✓	✓	✓	✓	✓
Roadmap, sessions, skills, preferences	✓	✓	✓	✓	✓
Code graph + blast-radius analysis	✓	✓	✓	✓	reads file
Symbol-level `query_graph`	✓	✓	✓	✓	reads file

Python, TypeScript, JS/JSX, Go, and Rust get full symbol tools; for other languages the agent reads the file directly.

Questions

Frequently asked

What is Codevira?

A governed decision log for AI coding agents. It stores the decisions you make together with the reasoning that justifies them — why a choice won, what you rejected, when to revisit — and enforces the ones you lock across Claude Code, Cursor, Antigravity and every other editor, blocking edits that would revert them or re-introduce a fixed bug. It's not a knowledge base you query; the knowledge is always bound to a decision. Everything is local and lives in your repo.

Does Codevira send my code anywhere?

No. Everything runs locally. Decisions live in <repo>/.codevira/decisions.jsonl and the code graph is a SQLite cache under ~/.codevira/. Search is pure keyword/BM25 (SQLite FTS5) — no embeddings, no model download, nothing phones home. Your code never leaves your machine.

Do I need to run codevira init for every project?

Yes — as of v3.7.0, codevira init is the explicit opt-in. Codevira tracks only the projects you initialize; 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 never chose. You register the MCP server once, not per project. Set CODEVIRA_AUTO_ADOPT=1 to track every project you open instead.

Does Codevira use embeddings or semantic search?

No, not in the default install. Decision search is pure keyword/BM25 ranking via SQLite FTS5 — no vectors, no sentence-transformers, no ChromaDB, nothing to download on first use. That's why a project's memory is ~1 MB, the production install is ~66 MB, and — with no model to load — warm tool calls return in ~2 ms.

Which AI coding tools does it work with?

Claude Code, Claude Desktop, Cursor, and Google Antigravity via MCP; OpenAI Codex and GitHub Copilot read the generated AGENTS.md natively. One codevira setup configures every tool it detects. As of 4.0, hard enforcement is no longer Claude-Code-only: it blocks the edit before it touches disk in Claude Code and Antigravity (a PreToolUse hook), and the commit in every other editor (an opt-in git pre-commit hook).

How does it block edits in editors other than Claude Code?

Every editor commits with git. codevira engine install-git-hook adds a pre-commit hook that runs the same decision engine as the IDE hook, so a locked decision physically blocks the commit in Cursor, Codex, Copilot — any tool. In Claude Code the block happens even earlier, before the file changes. Without the git hook, other tools still get the decisions as strong AGENTS.md guidance. Override a single commit with git commit --no-verify.

Does it work for a team, or across my machines?

Yes. .codevira/ lives in your repo, so decisions travel with git clone. Records are content-addressed (uid = sha256 of the record), so a decision's supersession chain survives a two-host git merge — no lost locks, no dangling history. codevira export setup carries your cross-project learning (preferences, learned rules) to a new machine, merged rather than overwritten.

How much does it cost?

Free and open source under the MIT license. No account, no API key, no cloud, no subscription — pipx install codevira and you're done.

Give your agents a memory.

Open source, MIT, local-first. Two commands and every AI tool on your machine shares it.

Get started on GitHub View on PyPI

Your AI coding agenthas amnesia.

The whole system, one picture

Why codevira exists

Brilliant in the moment.Amnesiac across sessions.

Remembering isn't enough.Memory must push back.

Your memory belongs to you.Not to one IDE. Not to a cloud.

Four moments in the life of a memory

Memory you can see

Use bcrypt for password hashing

Memory that pushes back

Decision lock 3.5

Anti-regression

Blast-radius veto

Working memory

Skill library

Refusals that explain themselves 4.0

Survives a team merge 4.0

One egress door, one undo 4.0

Machine transfer 3.3

Team-shared memory 3.7.1

One memory. Every tool.

Your tools alone vs. with codevira

Memory is cheaper than amnesia

“Catch me up on this project”

“What did we decide about auth?”

A regression ships

Your memory moves with you

MCP is the SDK

Frequently asked

Give your agents a memory.

Your AI coding agent
has amnesia.

Brilliant in the moment.
Amnesiac across sessions.

Remembering isn't enough.
Memory must push back.

Your memory belongs to you.
Not to one IDE. Not to a cloud.