Skip to main content
Glama

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

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.


Related MCP server: Tages

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 &ldquo;nested&rdquo; (measured on a real machine: 1 found, 11 excluded). 4.2.0 also stops background work writing false entries to the crash log &mdash; 39 of 45 entries on that machine were one harmless line &mdash; 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 &rarr;


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.

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

MCP tool surface

36 tools are advertised to AI clients via tools/list (37 are defined — a 37th, refresh_graph, is registered but hidden; humans invoke it via codevira sync). Every tool carries MCP ToolAnnotations (readOnlyHint / destructiveHint=false / idempotentHint): most are read-only and can run without a confirmation prompt, and no MCP tool is destructive — the only destructive ops (reset / uninstall) are CLI-only, never exposed over MCP. Good to know for anyone wiring codevira into an autonomous agent.

The lean 12 (CODEVIRA_TOOL_PROFILE=lean) are the ones you keep — set that in the MCP server's env block to cut tools/list from 36 tools to 12, roughly a two-thirds smaller payload (~8.9K → ~3.5K tokens of fixed per-session cost). Hidden tools still work when called explicitly.

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

Reads — the memory surface

Tool

Description

get_session_context

THE "catch me up" call. ~500 tokens: current phase, next action, recent decisions, top tags, last session brief.

search_decisions(query)

FTS5/BM25 over decisions.jsonl. Top 5 truncated by default; full=true / summary_only=true. all_projects=true searches every registered repo, tagging each result with its project.

expand(ids=[…])

Fetch full records for just the ids you care about — the summary-first complement to search_decisions / list_decisions. Read-only; in the lean 12.

list_decisions

Paginate / filter: since_date, file_pattern, protected_only, tags, include_superseded.

list_tags

All tags with decision counts.

get_history(file_path)

Recent decisions touching a file.

check_conflict(decision_text)

Surface duplicate / contradictory decisions BEFORE you write.

Writes — capturing decisions

Tool

Description

record_decision

Capture a decision. do_not_revert=true triggers Claude Code PreToolUse enforcement; symbol="login" scopes the lock to one function/class. It supersedes a strong unprotected near-duplicate instead of appending a twin.

supersede_decision(old_id, new_decision, reason)

Retire an old decision, link to its replacement, keep the audit trail.

mark_decision_outdated(decision_id, reason)

Retire a decision that's simply no longer true (no successor) so it stops surfacing. Reversible via set_decision_flag. do_not_revert needs force=True.

reaffirm_decision(decision_id)

Re-confirm a soft-expired do_not_revert lock.

set_decision_flag(decision_id, …)

Toggle do_not_revert / tags / is_outdated.

write_session_log

Structured session record.

Roadmap — get_roadmap · get_phase · add_phase · update_phase_status · update_next_action · complete_phase · defer_phase · bulk_import_phases.

Code graph — get_node (file metadata) · get_impact (blast radius) · query_graph (function-level callers/callees/tests/dependents/symbols) · get_playbook (curated rules for add_tool / add_service / add_schema / debug_pipeline / commit / write_test). Plus the hidden refresh_graph.

Memory subsystems

Subsystem

Tools

What it covers

Working memory (4)

working_add, working_get, working_promote, get_working_context

Intra-session scratchpad, decay-scored (importance × e^(−Δt/τ=6h) + 0.5·access_count), capacity-bounded. Auto-populated by the PostToolUse fan-out.

Skill library (6)

record_skill, get_skill, apply_skill_outcome, list_skills, supersede_skill, promote_skill_to_playbook

Reusable procedures; FTS5 composite ranking (BM25 + tag-Jaccard + recency); auto-archive at 5 consecutive failures or 90 unused days (do_not_revert exempt).

Provenance (1)

origin_of

Which IDE, which machine, when — what attributes an amendment across a two-host merge. (CODEVIRA_IDE is a cooperative signal, spoofable, not a security boundary.)

Workflow prompt — onboard_session: full project catch-up for new sessions; wraps get_session_context().

Removed in 4.0 (52 tools → 37 defined; 36 advertised). Cut on measured usage across 4,203 transcripts, not taste — the data they wrote is untouched, and codevira export still includes everything. See MIGRATING.md.

Removed

Instead

consensus_check, consensus_status, consensus_propose_supersession, consensus_resolve

origin_of

reflect, get_reflections, list_reflections

—

spatial_nearby, spatial_heat, spatial_neighborhood, spatial_affordances

get_impact

distill_preferences, search_preferences

the style panel in get_session_context

get_code, get_signature

read the file — both measured zero calls in 2.5 months

Enforcement engine

Codevira ships 7 default engine policies ("heroes"), each hooked to Claude Code lifecycle events: SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, Stop.

Policy

Event

What it does

Decision Lock

PreToolUse

Blocks an edit that touches a do_not_revert decision's subject. Content-aware: a provably-orthogonal edit downgrades to a warn; a token-touching edit blocks. Strict file-level locking via CODEVIRA_DECISION_LOCK_CONTENT_AWARE=0.

Anti-Regression

PreToolUse

Blocks edits that look like reverts of previously-fixed bugs. Fix-history is scanned from fix: / bug: / hotfix: / fixes #N commit messages and self-freshens on read when git HEAD advances. Caveat: calibrated for small Edit/MultiEdit hunks; full-file Write reverts are deliberately exempt (future work).

Blast-Radius Veto

PreToolUse

Blocks a signature-removing/modifying edit to a high-fan-in file (purely-additive signatures pass). Shows the callers.

Relevance Inject

UserPromptSubmit

Injects ≤3 relevant decisions per prompt; 0 tokens when off-topic.

Session-Log Enforcer

SessionStart + Stop

Blocks (or, in warn mode, nudges) a session that shipped commits without a write_session_log. A second consecutive block degrades to a warn so a session that genuinely cannot log still finishes.

Post-Edit Graph Refresh

PostToolUse

Reindexes edited files in the background.

Token Budget / telemetry

Stop

Records outcome telemetry.

How verdicts combine. The three edit guards compose into a single verdict — first block wins by priority (Decision Lock 100 > Anti-Regression 80 > Blast-Radius 50). The highest-priority block's message is what you see; the rest are recorded as telemetry.

Fail-open and opt-in. The dispatcher never raises: each policy is wrapped in try/except and returns allow on failure. CODEVIRA_ENGINE=0 disables all policies; each edit guard also has a per-policy off|warn|block env override (CODEVIRA_DECISION_LOCK_MODE, CODEVIRA_ANTI_REGRESSION_MODE, CODEVIRA_BLAST_RADIUS_MODE). Enforcement is not global across all Claude Code projects — in any project you never ran codevira init on, the hooks stay fully inert.

The universal backstop (4.0). codevira engine install-git-hook installs a pre-commit hook that runs locked decisions against staged changes through the same engine — so a do_not_revert decision is enforced in any editor, because they all commit with git. git commit --no-verify overrides a single commit; CODEVIRA_GIT_HOOK_MODE=warn (or off) changes it globally; merge commits are never blocked.

Why edit-time blocking is Claude Code only. The hard-block path is Claude Code's real PreToolUse hook. Edits from Cursor / Codex / Copilot go straight to the filesystem — they never reach codevira's PreToolUse engine — so those IDEs get decisions as advisory AGENTS.md context, with the git pre-commit hook as the universal backstop. Verified: Claude Code returns permissionDecision: deny (exit 2) with the decision's reasoning, rejected alternatives and re-examination trigger attached; the git hook refuses the commit with the same reasoning. Other IDEs are supported but verified one at a time rather than inferred.

CLI commands

26 subcommands. Two are internal (merge-driver, invoked by git's merge driver, and register-all, a setup helper); three more are advanced (working, induce-skills, eval). The daily-use ones are below — run codevira <cmd> --help for full flags:

Command

What it does

codevira init

Opt this project in: .codevira/ + AGENTS.md + .gitignore + git merge driver. Add --shared to commit memory for team sharing (default keeps it per-machine)

codevira setup

Detect installed AI tools + write MCP configs + Claude Code hooks

codevira doctor

Health checks (read-only; ✓/⚠/✗ + a fix command each)

codevira status

Index health + project state

codevira projects

List tracked projects with staleness; projects archive <name> drops one

codevira untrack <path>

Remove one stray or temporary project entry

codevira index

Build / refresh the code-graph cache

codevira sync

Regenerate AGENTS.md + manifest + digest from decisions.jsonl

codevira repair-ids

Detect/repair cross-engineer decision-id collisions (--apply; --semantic reports near-duplicates)

codevira observe-git

Classify past decisions as kept/modified/reverted from git history

codevira replay

Browse the decisions timeline (terminal / markdown / HTML)

codevira search <query>

Search decisions from the terminal (FTS5/BM25); --all-projects, --json

codevira graph

Render an interactive, offline HTML viewer of decision memory

codevira memory

snapshot / undo the memory store — the rollback path git revert can't give you

codevira export / import

Back up / restore project memory + global learning across machines

codevira engine

install-git-hook installs the universal pre-commit backstop; status / disable / enable

codevira prune

Remove orphaned project dirs, dead global.db rows, ghost dirs and legacy backups. Never touches decisions, IDE configs or hooks. --dry-run first

codevira reset

Destructive cleanup of this project's memory (auto-exports first; requires a typed confirmation)

codevira uninstall

Reverse every system write codevira made — ~/.codevira/ including snapshots, every IDE config entry, the launchd service. Preserves user content outside markers. Requires typing uninstall

codevira clean

Removed in 4.0.1 — it was a full uninstall mis-named as tidy-up, and its old description destroyed a real install. It now errors invalid choice. Use prune to tidy, uninstall to remove

codevira serve

Start the single-project MCP HTTP server (stdio is the daily mode)

To fully remove codevira: run the uninstall command above, then pipx uninstall codevira.

Language support

Feature

Python

TS/JS

Go

Rust

Others

Decision capture + search

✓

✓

✓

✓

✓

Cross-IDE memory via AGENTS.md

✓

✓

✓

✓

✓

Roadmap / sessions

✓

✓

✓

✓

✓

Code graph + blast radius

✓

✓

✓

✓

—

Symbol-level query_graph

✓

✓

✓

✓

—

Decisions / AGENTS.md / roadmap are language-agnostic — they work for any language. Code-graph and symbol tools cover exactly Python (stdlib ast) plus TS / TSX / JS / JSX / Go / Rust (bundled tree-sitter grammars). For any other language the AI Reads the file directly. The legacy 17-grammar [all-languages] pack was removed in v2.2.0 to keep the install lean.

Concurrency & safety

Every on-disk write goes through mcp_server/storage/atomic.py: a crash-safe atomic write (mkstemp + fsync + os.replace) behind a Posix fcntl.flock (with an in-process threading.Lock first, and a Windows O_EXCL sentinel fallback). Appends to the JSONL logs are line-atomic — concurrent appenders never interleave bytes. Result: two IDEs hitting the same project don't race on manifest.yaml / roadmap.yaml / AGENTS.md.

This is exercised by a 50-operation stress over a 10-thread pool, a 20-subprocess cross-process stress (spawn), and an adversarial chaos harness (scripts/chaos_smoke.py — 8 scenarios including SIGKILL during a held lock, symlink traversal, malformed MCP payloads, corrupt-JSONL graceful degradation, and read-only-directory hostility). See docs/architecture.md § "Concurrent-write safety".


Upgrading & troubleshooting

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

One exception, if you are coming from 4.1.0 or earlier. A bug could register $HOME itself as a project, and every genuine project below it was then discarded as a "nested sub-store". 4.2.0 stops that happening, but it does not repair a registration that is already wrong — nothing prunes the bad row on upgrade. If projects went missing from an IDE, run this once:

codevira register-all --dry-run   # read-only; shows what IS registered

If that prints one project at your home directory with your real ones listed as excluded nested, that is this bug. Before clearing it, look at what would be removed:

codevira untrack --dry-run "$HOME"   # read-only; lists IDE entries AND the data dir

Read that output. untrack deletes the project's data directory, not just the registry entry. If you were bound to $HOME by mistake, any decisions recorded during that time live in that directory and will go with it. If the dry-run lists a data dir you might want, copy it aside first (cp -R the path it names). Your other projects each have their own directory and are not affected.

Then clear and re-register:

codevira untrack -y "$HOME"
codevira register-all

Restart the IDE afterwards.

(codevira doctor will not catch this one: its checks cover the current binding and whether global.db opens, not what is registered inside it.)

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.

Start here before your first PR. One caveat it makes loud: 82% of codevira's internal imports sit inside function bodies, so a static import graph draws this codebase as disconnected leaves — the arrows below are runtime call edges. The diagram also marks the boundaries that don't hold, rather than pretending the layering is clean.

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:

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

License

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

Available Tools

36 tools
add_phaseA

Add a new upcoming phase to the roadmap. Call when you identify new work during a session — gaps, refactors, follow-ups. High-priority phases are inserted at the front of the queue.

Inputs: name (required), phase (required), description (required), files, +3 more.

apply_skill_outcomeA

v3.1.0 M3: Manually record one outcome for a skill — success or failure. Reinforces the reinforcement loop (resets consecutive_failures on success; auto-archives at 5 consecutive failures unless do_not_revert=True). The canonical signal in M5+ comes from outcomes_writer.py (git-derived, not agent-self-reported); this tool is the manual override.

Inputs: success (required), skill_id (required).

bulk_import_phasesA

v2.1.2 Item 29: backfill multiple historical phases at once. Each item: {number, name, status?='done', completed_at?, key_decisions?, git_ref?, description?}. Idempotent. Useful for adopting codevira on a project that already shipped N phases in git.

Inputs: phases (required).

check_conflictA
Read-onlyIdempotent

Check whether a proposed decision contradicts any do_not_revert=True decision OR duplicates an existing one. A NEGATED restatement is always a conflict, never a duplicate: 'never do X' and 'do X' differ by one token and score as near-identical text, so they are separated explicitly. Returns {status: novel|duplicate|conflict, conflicts, duplicates}. Call BEFORE record_decision to surface conflicts proactively (record_decision also runs this internally and surfaces _conflict_warning unless force=true).

Inputs: decision_text (required), file_path.

complete_phaseA

Mark the current phase as complete and advance to the next upcoming phase. Records key_decisions permanently. Requires phase_number to match current phase (safety check). v2.1.2 Item 10: pass backfill=True + completed_at='YYYY-MM-DD' to retroactively mark a historical phase done without advancing the queue. v2.1.2 Item 12: pass git_ref to link a commit sha or PR ref to the completion.

Inputs: phase_number (required), key_decisions (required), git_ref, backfill, +1 more.

defer_phaseA

Move an upcoming phase to the deferred list. Use when priorities shift or a phase depends on unavailable work.

Inputs: reason (required), phase_number (required).

expandA
Read-onlyIdempotent

E1 (Phase 19): fetch FULL decision records by ID — the expand path for the summary-first search_decisions / list_decisions defaults. Scan the cheap compact rows, then pass the IDs you care about here for complete text + context + origin. Returns {requested, count, decisions, not_found}; never raises on unknown IDs.

Inputs: ids (required).

get_historyA
Read-onlyIdempotent

Get recent decisions touching a file. Default: 5 with truncated context (~500 tokens). Pass full=true for untruncated text. Ordered by most recent first.

Inputs: file_path (required), full, limit.

get_impactA
Read-onlyIdempotent

Get the blast radius for a file before modifying it. Default: returns up to 10 affected files + counts (~400 tokens). Pass summary_only=true for just counts (blast_radius, protected_count, high_stability_count) — ~80 tokens, perfect for gate checks. ALWAYS call before modifying any file.

Inputs: file_path (required), limit, summary_only.

get_nodeA
Read-onlyIdempotent

Get the context graph node for a file. Returns a SUMMARY by default (role, layer, stability, rules_count, deps_count, stale flag) — ~100 tokens. Pass full=true for the complete rules/dependencies/key_functions arrays. Call this INSTEAD of reading the source file.

Inputs: file_path (required), full.

get_phaseA
Read-onlyIdempotent

Get full details of any phase by number — completed, current, or upcoming.

Inputs: phase_number (required).

get_playbookA
Read-onlyIdempotent

Get curated architectural rules for a specific task type. Returns only the 2-3 relevant rule files — not all of them. Valid task types: add_tool | add_service | add_schema | debug_pipeline | commit | write_test

Inputs: task_type (required).

get_roadmapA
Read-onlyIdempotent

Get current project state: phase number, name, status, next action, and upcoming phases. Call at the START of every session.

Inputs: no named parameters.

get_session_contextA
Read-onlyIdempotent

Single 'catch me up' call for cross-tool continuity. Returns current roadmap phase, recent decisions with confidence, learned preferences, and active rules — everything a new session needs. Call this at the START of every session instead of multiple separate calls. recent_decisions is ranked by recency x outcome-confidence (a decision git watched survive outranks one nothing has tested); reverted and outdated ones are hidden entirely. A decision whose file has CHANGED since it was recorded carries 'needs_review': true plus a 'review_hint' — reaffirm_decision if it still holds, supersede_decision or mark_decision_outdated if it does not. Works seamlessly across AI tools: Cursor, Claude Code, Antigravity.

Inputs: no named parameters.

get_skillA
Read-onlyIdempotent

v3.1.0 M3: Composite-ranked search over active skills. score = 0.5 × BM25_norm + 0.3 × tag_jaccard + 0.2 × recency_decay (τ=30d, never-used skills score 0 recency). Returns hits with score_breakdown for debuggability. Pass file_path to filter skills whose trigger file_patterns don't match.

Inputs: query (required), top_k, file_path.

get_working_contextA
Read-onlyIdempotent

v3.1.0 M2: Compact markdown rendering of the top working-memory entries for ReAct-loop injection. Returns {markdown, entries, count}. Capped at ~150 tokens of output (entries truncated at 120 chars each).

Inputs: top_k.

list_decisionsA
Read-onlyIdempotent

v2.1.2 Item 11: enumerate decisions with filters (since_date, file_pattern, protected_only, session_id, tags). Closes the gap that 'codevira can remember things across sessions, but can't list what it remembers.' Default (E1): compact rows — one-line decision summary + key fields; full=true (or CODEVIRA_DECISION_DETAIL=full) for untruncated records, expand(ids=[...]) to fetch specific decisions in full.

Inputs: full, tags, limit, session_id, +5 more.

list_skillsA
Read-onlyIdempotent

v3.1.0 M3: Filtered list of skills. status='active' (default) returns the daily-driver set; 'all' returns every state; any other value filters to that one state. tags filter is set intersection.

Inputs: tags, limit, source, status.

list_tagsA
Read-onlyIdempotent

v2.1.2 Item 27: enumerate all tags in the project with decision counts. Useful for discovery — 'what categories of decisions do we track?'

Inputs: no named parameters.

mark_decision_outdatedA

v3.7.0 staleness read-side: tombstone a decision as OUTDATED so it stops surfacing in get_session_context / search_decisions / list_decisions — without deleting it. Use when a decision is simply no longer true and has NO successor (for a replacement, use supersede_decision to preserve lineage). Reversible via set_decision_flag(is_outdated=false). Writes one amendment to .codevira/decisions.jsonl; audit preserved.

Inputs: decision_id (required), force, reason.

origin_ofB
Read-onlyIdempotent

v3.1.0 M7: Return the M1 origin block attached to a decision ({ide, agent_model, host_hash, ts}) + protection / supersession metadata. Always available regardless of the handshake flag.

Inputs: decision_id (required).

promote_skill_to_playbookA

v3.1.0 M3: Write the skill's procedure as a playbook markdown file at .codevira/playbooks/<task_type>/.md. Refuses on existing file unless force=True so hand-written playbooks aren't clobbered. After promotion the procedure is also discoverable via get_playbook(task_type).

Inputs: skill_id (required), task_type (required), name, force.

query_graphA
Read-onlyIdempotent

Query the function-level call graph. Find callers, callees, tests, or dependents for a specific symbol. Use query_type='symbols' to list all functions in a file.

Inputs: file_path (required), symbol, query_type.

reaffirm_decisionA

v3.2.0: refresh a do_not_revert decision's soft-expire clock. Long-lived locked decisions can grow stale, so search and list output carry 'dnr_soft_expired' and 'dnr_age_days' on every do_not_revert decision — 180 days by default, override via CODEVIRA_DNR_SOFT_EXPIRE_DAYS (0 disables). The lock never auto-flips; the flag is advice. Call this on a soft-expired decision that is still load-bearing — it appends a single 'reaffirmed_at' amendment to .codevira/decisions.jsonl and resets the clock. For semantic rewrites use supersede_decision; for flipping the flag use set_decision_flag.

Inputs: decision_id (required).

record_decisionA

Record one architectural decision. Set do_not_revert=true to lock it across sessions and IDEs. Returns {decision_id, session_id}. To change it later use supersede_decision (preserves the audit trail) or set_decision_flag (toggle do_not_revert / tags).

Inputs: decision (required), tags, force, symbol, +6 more.

record_skillA

v3.1.0 M3: Author a new skill in the canonical store (.codevira/skills.jsonl). Skills encode 'how to do X in this project' as markdown procedures. Calls check_conflict against the SKILLS corpus before writing; near-duplicate warnings can be overridden via force=True. Use supersede_skill to version an existing skill, or promote_skill_to_playbook to promote a skill into the existing playbook system.

Inputs: name (required), procedure (required), force, source, +3 more.

search_decisionsA
Read-onlyIdempotent

Search past decisions across sessions and roadmap phases. Keyword search over an FTS5/BM25 index (Porter-stemmed) — NO semantic/vector matching, so recall depends on sharing keywords with the stored decision; for a concept with no shared words, browse list_decisions or list_tags instead. Default (E1): summary-first rows — {id, decision (one-line ≤140), file_path, do_not_revert, tags, score}, dropping per-row snippet/origin. Pass full=true for untruncated rows, expand(ids=[...]) to fetch specific decisions in full, or summary_only=true for a ~70%-smaller {id, summary, score} payload. Answers 'has anyone decided this before?'

Inputs: query (required), full, limit, session_id, +2 more.

set_decision_flagA

v3.0.0 lightweight flag/tag update for an existing decision. Use this when you only need to toggle do_not_revert or correct a tag list — avoids supersede_decision's mandatory rewrite of the decision text + reason. Writes a single amendment record to .codevira/decisions.jsonl. For semantic rewrites use supersede_decision instead.

Inputs: decision_id (required), tags, force, is_outdated, +1 more.

supersede_decisionA

v2.1.2 Item 26: retire old_id and link to a replacement. Writes the new decision with [supersedes #<old_id>: <reason>] prefix, sets the old row as superseded. Default-hidden in search / list (pass include_superseded=true to opt back in).

Inputs: old_id (required), reason (required), new_decision (required), tags, +3 more.

supersede_skillA

v3.1.0 M3: Version a skill. Writes a new skill that supersedes old_id; amendment-marks the old as 'superseded' with a backref. Triggers inherit from the old skill when not supplied. The old skill no longer surfaces in search after this; it's still retrievable via list_skills(status='superseded') for audit.

Inputs: name (required), old_id (required), procedure (required), reason, +3 more.

update_next_actionA

Update the roadmap's next_action field. Call at session end.

Inputs: next_action (required).

update_phase_statusA

Update the current phase status: pending | in_progress | blocked. Call when starting work on a phase (in_progress) or when blocked.

Inputs: status (required), blocker, started.

working_addA

v3.1.0 M2: Append one observation or goal to working memory (intra-session, bounded, decay-scored scratchpad in .codevira-cache/working.jsonl). 'observation' = a fact the agent saw (file edited, error message, command output). 'goal' = what the agent is currently trying to accomplish. Use working_promote to move an entry to long-term memory (decision/skill/playbook) when it earns its keep.

Inputs: content (required), kind, links, confidence, +2 more.

working_getA
Read-onlyIdempotent

v3.1.0 M2: Top-K live working-memory entries by decay score (importance × exp(-Δt_hours / 6) + 0.5 × access_count). Filters by kind / session_id. Tombstoned (evicted or promoted) entries are excluded.

Inputs: kind, top_k, session_id.

working_promoteB

v3.1.0 M2: Promote a working-memory entry to long-term memory and tombstone the source. to='decision' is the fully wired path (calls check_conflict first; force=true overrides). to='skill' and to='playbook' are reserved for M3+; the call returns {deferred: true, milestone: ...} until those stores ship.

Inputs: entry_id (required), to, tags, force, +3 more.

write_session_logA

Write a structured session log to .agents/logs/YYYY-MM-DD/. Called by the Documenter at the end of every session. Feeds search_decisions() with institutional memory.

Inputs: task (required), phase (required), decisions (required), next_steps (required), +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 36 tools

    Disambiguation5/5

    Each tool targets a distinct operation and resource: roadmap phases, decision records, working memory, skills, and graph queries are cleanly separated. Even related tools like search_decisions vs list_decisions and get_node vs query_graph are clearly differentiated by their descriptions and intended use cases.

    Naming Consistency4/5

    The overwhelming majority of tools follow snake_case verb_noun naming like add_phase, get_roadmap, search_decisions, and record_skill. Minor deviations such as working_add, working_get, expand, and origin_of break the pattern slightly but are still readable and not chaotic.

    Tool Count2/5

    36 tools is well beyond the 25+ threshold that should be considered too many for a coherent MCP surface. While the tools cover multiple subdomains, the sheer number makes the set heavy for an agent to navigate and weigh in context.

    Completeness5/5

    The tool surface provides deep lifecycle coverage for its apparent domain: roadmap phases, decision records, skills, working memory, and file context graph. There are few obvious missing operations — decisions can be recorded, searched, superseded, flagged, and outdated; skills can be created, listed, promoted, and managed; and phases have create, read, update, complete, and bulk-import operations.

    Maintenance

    ActivityStale
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      An MCP server that provides persistent project context, workflow management, and knowledge capture for AI coding agents. It enables agents to maintain structured memory across sessions by tracking project profiles, conventions, skills, and technical debt.
      7
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI coding agents to maintain persistent, cross-session memory of codebase architecture, naming conventions, and decisions through MCP tools. Eliminates repetitive project re-explanation by automatically injecting stored context into every session with local-first SQLite storage and optional team sharing capabilities.
      4
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP memory server for AI coding agents to remember decisions, patterns, and bugs between sessions. Provides persistent memory with 37 MCP tools, multi-session coordination, and token-efficient recall.
      95 npm
      12
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      A shared, persistent MCP memory server for coding agents that enables storing and retrieving project decisions and context across different tools like Claude Code, Codex, and Cursor using semantic vector search.
      8
      MIT