Codevira MCP
The Codevira MCP server provides a persistent, local-first memory layer for AI coding agents, enabling cross-tool decision sharing, enforcement, and contextual understanding of a codebase.
Decision Management
Record, search, list, expand, supersede, mark outdated, reaffirm, and conflict-check architectural decisions
Optional
do_not_revertlock prevents AI agents from undoing critical decisionsToggle flags/tags, browse per-file history, and list all tags with counts
Session Context & Roadmap
get_session_contextdelivers a ~500-token catch-up (phase, decisions, preferences, rules) for cross-tool continuityAdd, update, complete, defer, and bulk-import project phases; log structured session records and next actions
Code Graph & Navigation
Query function-level callers, callees, tests, dependents, and symbols
Get file metadata, blast radius impact, file skeletons (signatures/docstrings), and individual symbol source
Retrieve curated architectural playbooks for task types (e.g.,
add_tool,commit,debug_pipeline)
Working Memory
Intra-session decay-scored scratchpad for observations and goals (
working_add,working_get,working_promote)Promote scratchpad entries to long-term decisions when warranted
Skill Library
Record, search, version, and supersede reusable procedural skills with BM25 + tag + recency ranking
Track outcomes to reinforce or auto-archive skills; promote skills to permanent playbooks
Spatial / Code-as-Space
Find topologically nearby files, activity heatmaps, folder-tree neighborhoods, and per-file task affordances
Cross-IDE Consensus & Provenance
Detect cross-IDE conflicts, propose and resolve supersession handshakes, and look up the origin IDE of any decision
Preferences & Reflections
Distill user prompts into durable cross-project preferences (communication, workflow, formatting)
Generate and retrieve LLM-powered reflections over recent decisions and sessions
Enforcement
In Claude Code, PreToolUse hooks hard-block edits violating locked decisions, anti-regression rules, or high-fan-in file constraints; other IDEs receive advisory context via AGENTS.md
Local-first Design
Operates entirely locally with no cloud or ML dependencies, using
jsonlfiles and SQLite for storage
Integrates with Git to bootstrap project roadmaps from commit history and uses post-commit hooks to automatically trigger reindexing of the codebase.
Provides Google Antigravity agents with access to a persistent context graph and roadmap, ensuring continuity and reducing token overhead in coding tasks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Codevira MCP Show me the current project roadmap and any pending changesets."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 machineWhat 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 |
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. |
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 |
Enforcement, not notes |
|
One-command setup |
|
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; |
Concurrent-safe | Every write is a crash-safe atomic write behind a Posix |
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-hookStep 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.jsonlTeam 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 |
"Local-first" is enforced, not promised |
|
Adversarial testing |
|
No destructive MCP tools | Every MCP tool carries |
Reversible memory | After a default |
What's solid, what's not
Production-stable | Known-limited |
Cross-IDE decision memory via in-repo JSONL | Hard |
| Graph tools cover Python / TS / JS / Go / Rust; other languages → the AI |
FTS5/BM25 decision search | Real-time multi-machine sync — by design local-first; for team sharing, run |
Per-project + cross-machine project inventory ( | No web UI — use the |
36 MCP tools advertised in | The HTTP server ( |
Concurrent-safe storage (Posix | Windows sentinel fallback is verified in unit tests but not yet load-tested on real Windows |
Anti-Regression on small | Anti-Regression does not yet detect full-file |
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_IDEMCP 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_logReads — the memory surface
Tool | Description |
| THE "catch me up" call. ~500 tokens: current phase, next action, recent decisions, top tags, last session brief. |
| FTS5/BM25 over |
| Fetch full records for just the ids you care about — the summary-first complement to |
| Paginate / filter: |
| All tags with decision counts. |
| Recent decisions touching a file. |
| Surface duplicate / contradictory decisions BEFORE you write. |
Writes — capturing decisions
Tool | Description |
| Capture a decision. |
| Retire an old decision, link to its replacement, keep the audit trail. |
| Retire a decision that's simply no longer true (no successor) so it stops surfacing. Reversible via |
| Re-confirm a soft-expired |
| Toggle |
| 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) |
| Intra-session scratchpad, decay-scored ( |
Skill library (6) |
| Reusable procedures; FTS5 composite ranking (BM25 + tag-Jaccard + recency); auto-archive at 5 consecutive failures or 90 unused days ( |
Provenance (1) |
| Which IDE, which machine, when — what attributes an amendment across a two-host merge. ( |
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 |
|
|
| — |
|
|
| the |
| 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 |
Anti-Regression | PreToolUse | Blocks edits that look like reverts of previously-fixed bugs. Fix-history is scanned from |
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 |
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 |
| Opt this project in: |
| Detect installed AI tools + write MCP configs + Claude Code hooks |
| Health checks (read-only; ✓/⚠/✗ + a fix command each) |
| Index health + project state |
| List tracked projects with staleness; |
| Remove one stray or temporary project entry |
| Build / refresh the code-graph cache |
| Regenerate AGENTS.md + manifest + digest from |
| Detect/repair cross-engineer decision-id collisions ( |
| Classify past decisions as kept/modified/reverted from git history |
| Browse the decisions timeline (terminal / markdown / HTML) |
| Search decisions from the terminal (FTS5/BM25); |
| Render an interactive, offline HTML viewer of decision memory |
|
|
| Back up / restore project memory + global learning across machines |
|
|
| Remove orphaned project dirs, dead |
| Destructive cleanup of this project's memory (auto-exports first; requires a typed confirmation) |
| Reverse every system write codevira made — |
| 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 |
| 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 | ✓ | ✓ | ✓ | ✓ | — |
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 registeredIf 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 dirRead 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-allRestart 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:
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.
Available Tools
36 toolsadd_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_conflictARead-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).
expandARead-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_historyARead-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_impactARead-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_nodeARead-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_phaseARead-onlyIdempotent
Get full details of any phase by number — completed, current, or upcoming.
Inputs: phase_number (required).
get_playbookARead-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_roadmapARead-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_contextARead-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_skillARead-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_contextARead-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_decisionsARead-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_skillsARead-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_tagsARead-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_ofBRead-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_graphARead-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_decisionsARead-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_getARead-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
Scored across 36 tools
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.
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.
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.
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
Related MCP Connectors
Long-term memory for AI coding agents: durable project facts, recalled by every MCP client.
Persistent engineering memory designed to follow developers across coding agents.
Hosted MCP memory for coding agents: persistent across sessions, editable markdown, team sharing.
Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceAn 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-
- AlicenseNot gradedqualityBmaintenanceEnables 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.4MIT
- AlicenseNot gradedqualityCmaintenanceMCP 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 npm12MIT
- AlicenseBqualityBmaintenanceA 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.8MIT