convez.ai
MCP Server
sachinshelke

codevira

sachinshelke/codevira

Ver no GitHub
BomPluginScore · de 0 a 100

Stop re-explaining your project to AI agents every session. One memory layer for Claude Code, Cursor, Windsurf, Antigravity — local, MIT, no signup.

Instalação

$npx convez-ai sachinshelke/codevira

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
12
Forks
5
Acompanhando
3
Saúde
100%
Último commit
há 2 meses
Versão
v4.2.0
Issues abertas
1
Contribuidores
3

README

A tradução para o português deste README ainda está na fila.

Codevira

Cross-IDE decision memory for AI coding agents. One in-repo memory layer that every AI tool you use can read — plus PreToolUse hooks that physically block violating edits in Claude Code (other IDEs get the same decisions as AGENTS.md guidance, not a hard block). Local-first, MIT-licensed, ~83 MB pipx install.

PyPI version Python Downloads License: MIT MCP PRs Welcome

Built for solo developers working on local projects with AI agents. Decisions live in <repo>/.codevira/decisions.jsonl — git-committed, team-shareable, visible in git diff. Every modern AI tool reads AGENTS.md, which codevira auto-generates as a slim 5 KB contract. Claude Code gets enforcement: PreToolUse hooks block Edit/Write calls that contradict decisions you marked do_not_revert.

Works with: Claude Code · Claude Desktop · Cursor · Windsurf · Google Antigravity · OpenAI Codex · GitHub Copilot · any MCP-compatible AI tool.


What you get

  • 🧠 One memory across every AI tool. A decision logged in Claude Code is visible to Cursor, Windsurf, Antigravity — all of them read the same .codevira/decisions.jsonl in your repo. No per-tool re-onboarding, no cloud sync.
  • 🛡️ Hard enforcement, not soft hints. Decisions you mark do_not_revert get a PreToolUse hook (Claude Code) that physically refuses any Edit/Write call violating them. Other IDEs see the decision in AGENTS.md; Claude Code is the only one with hard hooks today.
  • ⚡ One-command setup. pipx install codevira && codevira setup. Auto-detects installed AI tools (strong signals: binary on PATH + valid config file); only configures what's actually installed. Pass --force when the detector misses an install.
  • 🔒 Local-first, MIT-licensed. Decisions in <repo>/.codevira/*.jsonl, code graph in .codevira-cache/ (rebuildable, gitignored), nothing leaves your machine. No SaaS, no account, no telemetry.
  • 📦 Slim install (~83 MB pipx venv). No ChromaDB, no sentence-transformers, no torch. FTS5 SQLite for decision search, individual tree-sitter grammars (TS/JS/Go/Rust) for the code graph. MCP server starts in <100 ms.
  • 🔐 Concurrent-safe under multi-IDE load. Every on-disk write goes through mcp_server/storage/atomic.py — crash-safe atomic writes + Posix fcntl.flock (Windows sentinel fallback). Two IDEs hitting the same project don't race on manifest.yaml / roadmap.yaml / AGENTS.md. Pinned by an in-process 50-thread stress test, a 20-subprocess cross-process stress test, and an adversarial chaos harness (scripts/chaos_smoke.py — 29 attacks including SIGKILL during lock, symlink traversal, malformed MCP payloads). See docs/architecture.md § "Concurrent-write safety".

The Problem (Four Pains Codevira Solves)

If you code with AI agents on a project longer than a week, you've felt all of these:

1. Re-explaining your codebase every session

Every new chat starts from zero. The AI doesn't know your architecture, your conventions, your "we don't do it that way" decisions. You waste the first 10 minutes (and thousands of tokens) catching it up — only to do it again tomorrow.

2. AI undoing your careful decisions

Last week you debugged a tricky retry policy for 3 hours. Today's AI session refactors it to a simpler version because it has no idea why the complexity exists. Now it's broken again.

3. Cross-tool amnesia

You started planning in Claude Code. Switched to Cursor for autocomplete. Opened Antigravity to run tests. Three different agents, three different blind copies of your project state. Nothing carries over.

4. Token budget burned on re-discovery

Your AI agent reads the same 12 files every session before doing any actual work. You're paying API costs for the same lookups, over and over.

Codevira is a persistent memory layer that fixes all four — for every AI tool, on every project, on your local machine.


What's new in v3.4.0 — reliable project binding + honest docs

The headline fix: one user-scope codevira server now binds the right project instead of silently contaminating memory across projects. Upgrade and restart your MCP server to pick this up.

AreaWhat you get
Project binding fixedA shared, user-scope server (launched with no cwd / --project-dir) used to fall through to cwd discovery and resolve the wrong project — reading decisions from project A while you worked in project B. It now resolves the active project from the MCP client's workspace roots (Claude Code, Cursor, Windsurf all expose these), re-binding only to an already-initialized .codevira project; explicit pins always win; bounded by a timeout so dispatch can't hang.
Windows / UNC + HTTP isolationfile:///C:/... and file://host/share/... roots now parse correctly (was POSIX-only — Cursor/Windsurf on Windows). The HTTP transport is isolated from the process-global binding. Brand-new projects bind without creating .codevira in the wrong directory.
Claude Desktop: memory follows the fileThe single global server resolves the active project per tool call from the call's file_path, so memory tracks whichever project you're working in.
Honest search_decisions docsThe tool description claimed "hybrid BM25 + semantic"; the implementation is pure FTS5 keyword/BM25. Corrected so calling agents aren't misled into expecting semantic recall.
codevira projects + doctorprojects gains a staleness column (today / 5d ago / stale 45d), an ephemeral-path guard, and projects archive <name>. doctor gains a project_binding check showing how the project resolved.
Engine false-positive fixedA purely-additive full-file Write is no longer hard-blocked by decision_lock / blast_radius (the --- before / --- after diff envelope is now synthesized for Write too). A Write that removes or changes existing lines still blocks.

Since the v3.0.0 lean reset: 3.1 added five memory subsystems (working memory, skills, spatial, consensus, reflections), 3.3 added LLM-distilled preferences. Full history is in the CHANGELOG; what's coming next is in the Roadmap.

Full v3.4.0 release notes: CHANGELOG.md.


What's new in v3.0.0 — audited, lean, opinionated

Major version. v3.0.0 is the biggest API contraction since v2.0 shipped: 21 MCP tools deleted, 8 CLI subcommands deleted, per-IDE nudge file matrix collapsed to AGENTS.md only, IDE detection hardened from "directory exists" to "binary on PATH + valid config file." Full plan + rationale in docs/audit-2026-05-22.md; per-item kill list in docs/surface-cuts-2026-05-22.md.

AreaWhat changed
Decision storageMoved into <repo>/.codevira/decisions.jsonl (git-tracked, one decision per line). v2.x stored decisions in ~/.codevira/projects/<key>/graph/graph.db (a SQLite blob nobody could read).
AGENTS.md is the nudge filePer-IDE nudges (CLAUDE.md / GEMINI.md / .windsurfrules / .cursor/rules/codevira.mdc / .github/copilot-instructions.md) all deleted. Every modern AI tool reads AGENTS.md natively. Slim 5 KB cap; auto-regenerated from decisions; user content outside the <!-- codevira:begin -->...<!-- codevira:end --> markers preserved byte-for-byte.
MCP tool surface46 → 24 tools (-48%; 23 surfaced to AI clients, 1 admin-only). The audit found 22 tools that nobody called in real usage (preferences, learned_rules, changesets, project_maturity, list_nodes / add_node / update_node / export_graph, etc.). All deleted. (v3.1.0 later added 24 memory-subsystem tools, and v3.3.0 brought preferences back redesigned — distill_preferences / search_preferences, LLM-distilled from real prompts instead of the unused v2.x CRUD.)
CLI surface23 → 15 commands (-35%). Deleted: heal (use reset), budget, agents, hooks, register, configure, report (folded into doctor), calibrate, insights.
IDE detection hardenedNo more false-positives from stale ~/.cursor/ dirs. Each IDE needs a STRONG signal (binary on PATH, or verified config file). Pass --ide X --force to override when the detector misses an install.
codevira uninstallNew command. Reverses every system write made by init/setup: drops the MCP entry from ~/.claude.json, deletes ~/.claude/hooks/codevira-*.sh, strips codevira-tagged registrations from ~/.claude/settings.json, removes per-project .codevira/ + .codevira-cache/, strips the codevira block from AGENTS.md. Optional --keep-data.
Install size~83 MB pipx venv (was ~450 MB in v2.1.2 with ChromaDB + sentence-transformers + torch). MCP server starts in <100 ms (was 1-3 s).

Full v3.0.0 release notes: CHANGELOG.md.

Upgrading from v2.x? See the Migration notes section.


Quick Start — three commands

# 1. Install
pipx install codevira

# 2. Bootstrap the project (writes .codevira/, AGENTS.md, .gitignore)
cd ~/Projects/my-project
codevira init

# 3. Wire codevira into every AI tool detected on this machine
codevira setup

Then commit .codevira/ + AGENTS.md + .gitignore to git so your teammates inherit the project memory. Open any IDE; codevira's MCP server is ready.

Verify:

codevira doctor          # 11-ish health checks, ✓/⚠/✗
codevira list-decisions  # any decisions recorded yet?
codevira sync            # regen AGENTS.md from current decisions.jsonl

Try it. In your AI tool, ask: "Use get_session_context to brief me on this project." You'll get a structured project state in one tool call instead of the AI re-reading docs.

What codevira setup actually does

The one command above replaces what used to take 5+ steps in v1.x:

  • Detects installed AI tools via STRONG signals:
    • Claude Code: claude on PATH
    • Claude Desktop: ~/Library/Application Support/Claude/config.json exists + parses
    • Cursor: ~/.cursor/ + (cursor on PATH OR mcp.json exists)
    • Windsurf: mcp_config.json in ~/.windsurf/ or ~/.codeium/windsurf/
    • Antigravity: ~/.gemini/antigravity/mcp_config.json
  • Injects MCP server config into each detected tool's config file (per-IDE schema handled automatically; no JSON to hand-edit).
  • Installs Claude Code lifecycle hooks (SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, Stop) — these are what turn codevira from passive memory into the active guardian that blocks edits violating do_not_revert decisions.
  • Writes AGENTS.md with the slim codevira-managed block (5 KB cap; preserves user content outside the marker boundaries).

Flags:

  • --dry-run — preview without writing
  • --ide <name> — narrow to one IDE (claude, claude_desktop, cursor, windsurf, antigravity, agents_md)
  • --force — configure an --ide value even if codevira didn't auto-detect it (escape hatch for portable binaries / unusual config locations)
  • -y / --yes — skip the confirmation prompt
  • --no-hooks / --no-mcp / --no-nudge-files — scope-narrow the steps

What codevira doctor reports

11 health checks in one run, each with a concrete fix_command for any WARN or FAIL. Read-only — never modifies anything.

$ codevira doctor
Codevira health check
────────────────────────────────────────────────────────────
✓  python_version         Python 3.13 (≥ 3.10 required)
✓  codevira_data_dir      /Users/you/.codevira exists and is writable
✓  project_root           /Users/you/Projects/my-project is a valid project root
✓  codevira_dir           .codevira/ present (4 decision(s))
✓  agents_md_size         AGENTS.md is 1,234 bytes (≤10 KB safety threshold)
✓  graph_db               graph.db has all 4 expected tables
✓  global_db              ~/.codevira/global.db opens cleanly
✓  detected_ides          2 AI tool(s) detected: claude, cursor
✓  nudge_files            AGENTS.md present with codevira block
✓  watcher_circuit        watcher circuit clean (no recent failures)
✓  engine_kill_switch     engine ON (default; CODEVIRA_ENGINE not set)
✓  claude_mcp_visibility  codevira visible to Claude Code
✓  crash_log_size         no crash log (clean state)
────────────────────────────────────────────────────────────
summary: 13 pass · 0 warn · 0 fail

Daily-use commands

The CLI surface is 21 commands (the daily-use ones below):

CommandWhat it does
codevira initBootstrap .codevira/ + AGENTS.md + .gitignore in this project
codevira setupDetect installed AI tools + write MCP configs + Claude Code hooks
codevira doctorHealth check (read-only; ✓/⚠/✗ + fix commands)
codevira statusShow index health + project state
codevira projectsList tracked projects with staleness (today / 5d ago / stale 45d); projects archive <name> drops one from the registry
codevira indexBuild / refresh the code graph cache
codevira syncRegenerate AGENTS.md + manifest + digest from decisions.jsonl
codevira observe-gitClassify past decisions as kept/modified/reverted from git history
codevira replayBrowse the decisions timeline (terminal / markdown / HTML)
codevira cleanRemove orphaned project data
codevira resetDestructive cleanup (auto-exports decisions first)
codevira exportStandalone decision backup (JSON / SQL); export setup bundles project memory + global learning for machine transfer
codevira importRestore a codevira export setup archive on a new machine (merges global learning)
codevira graphRender an interactive, self-contained HTML viewer of decision memory (offline, queryable)
codevira uninstallReverse every system write codevira made (see "Uninstall")
codevira serveStart MCP HTTP server (single-project; stdio is the daily mode)
codevira engineInternal — invoked by Claude Code lifecycle hook scripts

Run codevira <cmd> --help for the full flag list on any subcommand.

Uninstall

# Reverse every system write made by init/setup. Preserves user content
# outside codevira marker blocks byte-for-byte.
codevira uninstall

# Common flags:
codevira uninstall --dry-run     # preview the plan; touch nothing
codevira uninstall --yes          # skip confirmation
codevira uninstall --keep-data    # uninstall the binary's footprint but
                                  # leave ~/.codevira/ and per-project
                                  # .codevira/ dirs alone
# Then remove the binary:
pipx uninstall codevira

Uninstall also strips legacy v2.1.x per-IDE nudge files (CLAUDE.md / GEMINI.md / .windsurfrules / .cursor/rules/codevira.mdc / .github/copilot-instructions.md) for users upgrading from older versions. User content outside the codevira markers stays.


How It Works

Codevira is a Model Context Protocol server that runs locally and gives any AI tool a structured, queryable memory of your codebase.

┌─────────────────────────────────────────────────────────────────┐
│  IN THE PROJECT REPO (committed to git)                         │
│                                                                 │
│   AGENTS.md                  ≤5 KB slim contract, auto-generated │
│      ↑                                                          │
│      │                                                          │
│   .codevira/                                                    │
│     decisions.jsonl          full text + metadata (append-only) │
│     digest.jsonl             slim summary for prompt injection  │
│     outcomes.jsonl           kept/reverted from git observation │
│     manifest.yaml            tag→ids, file→ids index (regen)    │
│     enforcement.yaml         which decisions hard-block         │
│     config.yaml              project settings                   │
│     sessions.jsonl           session events                     │
│     roadmap.yaml             phase tracking                     │
│                                                                 │
│   .codevira-cache/           gitignored, rebuildable             │
│     graph.sqlite             code graph (tree-sitter)           │
│     fts5.sqlite              FTS5 index over decisions.jsonl    │
│     hash-cache.db            file change detection              │
└─────────────────────────────────────────────────────────────────┘
                              ↑ MCP / hooks
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  PIPX INSTALL (~83 MB venv, ~/.local/pipx/venvs/codevira)       │
│                                                                 │
│   codevira (CLI + MCP server)                                   │
│      - pure Python, <100 ms startup                             │
│      - no chromadb / sentence-transformers / torch              │
└─────────────────────────────────────────────────────────────────┘
                              ↑ stdio MCP
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  IDE (Claude Code / Cursor / Windsurf / Antigravity / Codex /…) │
│                                                                 │
│   UserPromptSubmit → codevira hook → relevance-gated inject     │
│   Edit / Write → PreToolUse → block if do_not_revert violated   │
│   Stop → PostToolUse → optional outcome tracking                 │
└─────────────────────────────────────────────────────────────────┘

Token-efficient by design

Codevira is built around the principle that AI agent context windows are precious. Tools return summaries by default with opt-in full data:

  • get_node(path) — ~100 tokens by default (counts + flags). Pass full=true for the entire rules array.
  • get_impact(path) — 10 affected files. Pass summary_only=true for just counts (~80 tokens) before deciding to dig deeper.
  • search_decisions(query) / list_decisions() — truncated matches by default. Pass full=true for verbatim text; pass summary_only=true for just IDs and one-line summaries.

The agent always asks for what it needs, in the size it needs.

Shrink the tool surface itself. The advertised MCP tools/list is a fixed per-session cost (~4K tokens for the full 24-tool surface). Set CODEVIRA_TOOL_PROFILE=lean in the MCP server's env block to advertise only the 11 daily-driver tools (~46% smaller); hidden tools still work when called explicitly. Bigger wins usually come from disabling MCP servers you aren't actively using.


MCP Tools

49 tools surfaced to AI clients via tools/list (token-optimized, summary-first): the core decision/roadmap/graph surface plus the v3.1.0 memory subsystems (working memory, skills, spatial, consensus, reflections) and the v3.3.0 preference tools. One additional admin tool (refresh_graph) is registered but hidden from tools/list because it runs automatically in the background — humans invoke it via codevira sync. Set CODEVIRA_TOOL_PROFILE=lean to advertise only the daily-driver subset. v3.0.0 cut 21 v2.x tools that produced noise or had no real users — see CHANGELOG.md for the full kill list.

Reads — the memory surface

ToolDescription
get_session_contextTHE main "catch me up" call. Returns ~500 tokens: current phase, next action, recent decisions, top tags, last session brief.
search_decisions(query)FTS5 BM25 search over decisions.jsonl. Default: top 5 truncated; pass full=true or summary_only=true.
list_decisionsPaginate / filter: since_date, file_pattern, protected_only, tags, include_superseded.
list_tagsEnumerate 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

ToolDescription
record_decisionCapture an architectural decision. Optional do_not_revert=true triggers hard enforcement at the Claude Code PreToolUse hook. Supports tags, force, session_id.
supersede_decision(old_id, new_decision, reason)Retire an old decision and link to its replacement. Audit trail preserved.
reaffirm_decision(decision_id)Re-confirm a soft-expired do_not_revert lock is still wanted.
set_decision_flag(decision_id, ...)Toggle do_not_revert / tags on an existing decision.
write_session_logStructured session record.

Roadmap

ToolDescription
get_roadmapCurrent phase, next action, upcoming phases.
get_phase(number)Full details of any phase.
add_phaseQueue new upcoming work.
update_phase_statusMark in_progress / blocked.
update_next_actionSet what the next agent should do.
complete_phaseMark done + record key_decisions.
defer_phaseMove a phase to the deferred list.
bulk_import_phasesOne-call import of multi-phase git history.

Code graph (Python + TS/JS + Go + Rust via tree-sitter)

ToolDescription
get_node(file_path)File-level metadata (role, layer, stability, dependencies).
get_impact(file_path)Blast radius — who depends on this file.
query_graph(file_path, query_type)Function-level: callers, callees, tests, dependents, symbols.
refresh_graph(file_paths?)Background reindex (fire-and-forget).
get_signature(file_path)All public symbols, signatures, line numbers.
get_code(file_path, symbol)Full source of one function or class.
get_playbook(task_type)Curated rules for: add_tool, add_service, add_schema, debug_pipeline, commit, write_test.

Memory subsystems (v3.1.0)

SubsystemToolsWhat it covers
Working memoryworking_add, working_get, working_promote, get_working_contextIntra-session scratchpad (decay-scored, capacity-bounded).
Skill libraryrecord_skill, get_skill, apply_skill_outcome, list_skills, supersede_skill, promote_skill_to_playbookReusable procedures with composite-ranked retrieval and git-driven reinforcement.
Spatialspatial_nearby, spatial_heat, spatial_neighborhood, spatial_affordancesCode-as-space: activity heatmap, neighborhoods, what task types apply where.
Consensusconsensus_check, consensus_status, consensus_propose_supersession, consensus_resolve, origin_ofCross-IDE conflict detection + provenance.
Reflectionsreflect, get_reflections, list_reflectionsLLM-generated abstractions over recent decisions + sessions (MCP sampling).

Preferences (v3.3.0)

ToolDescription
distill_preferencesSession-end LLM distillation of captured prompts into durable, user-scoped preferences (~/.codevira/global.db).
search_preferences(category?)Retrieve learned preferences — communication style, workflow habits — across all projects.

MCP Workflow Prompts

PromptDescription
onboard_sessionFull project context catch-up for new sessions. Wraps get_session_context().

v3.0.0 removed 4 v2.x prompts (review_changes, debug_issue, pre_commit_check, architecture_overview) because they referenced deleted MCP tools. The slim surface means the AI can synthesize these workflows from the kept tools directly.


Language support

FeaturePythonTS/JSGoRustOthers
Decision capture + search✓✓✓✓✓
Cross-IDE memory via AGENTS.md✓✓✓✓✓
Roadmap / sessions✓✓✓✓✓
Code graph + blast radius✓✓✓✓—
get_signature / get_code✓✓✓✓—

Decisions / AGENTS.md / roadmap are language-agnostic. Code-graph features require a tree-sitter grammar; v3.0.0 ships TS, JS, Go, Rust. The opt-in extra pip install 'codevira[all-languages]' re-adds the 17-grammar pack for Java, Ruby, PHP, C, C++, Kotlin, Swift, etc.


Production-stable vs known-limited

Production-stableKnown-limited
Cross-IDE decision memory via in-repo JSONLThe PreToolUse hook enforcement is Claude Code only today. Other IDEs read AGENTS.md (soft signal), but don't have hard blocks
do_not_revert enforcement at Claude Code PreToolUseMulti-language code graph for languages outside Python / TS / JS / Go / Rust — use the [all-languages] extra
FTS5 decision search with BM25 rankingReal-time multi-machine sync — by design, codevira is local-first; for team sharing, commit .codevira/ to git
Per-project + cross-machine project inventory (global.db)Web UI for browsing decisions — use the codevira://decisions MCP resource in Claude Desktop, or codevira replay --format html for a static file
All 49 surfaced MCP tools + 21 CLI commands + 8 engine policiesThe HTTP server (codevira serve) is single-project per launch — for daily use, stick with stdio via codevira setup
Concurrent-safe storage layer (Posix fcntl.flock + Windows sentinel fallback). Proven against 50-thread + 20-subprocess stress + 29-attack chaos harnessThe cross-process file-lock contract has been exercised on macOS + Linux CI; the Windows sentinel-file fallback is verified via unit-test simulation but hasn't been load-tested on real Windows yet
Code graph data store is functional but the v3.0.0 spec target (<project>/.codevira-cache/graph.sqlite) and the actual location (<data_dir>/graph/graph.db) drifted during the surface-cut audit. Tracked for v3.1 reconciliationn/a (functional today; spec-truthfulness gap only)

Background

Want to understand the full story behind why this was built, the design decisions, what didn't work, and how it compares to other tools in the ecosystem?

Read the full write-up: How I Built Persistent Memory for AI Coding Agents


Contributing

Contributions are welcome. Read CONTRIBUTING.md for the full guide.


FAQ

Common questions about setup, usage, architecture, and troubleshooting — see FAQ.md.

Roadmap

Current release: v3.4.0 — one user-scope server now binds the right project per call (no more cross-project memory contamination), Windows/UNC workspace roots, and a codevira doctor binding check.

Next up (directional, not dated):

  • Summary-first payloads + session-transcript ingest — leaner responses, and memory that learns from how sessions actually went
  • Eval harness — measurable recall + enforcement quality in CI
  • Managed memory files beyond AGENTS.md — CLAUDE.md, .cursor/rules, GEMINI.md
  • Optional [semantic] recall — off by default; the base install stays pure-keyword, no vectors, no model download
  • TypeScript get_signature, finer-grained decision locking, learned hot-path tuning

What's built, the full upcoming list, and the long-term vision — ROADMAP.md.

Star History

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

License

MIT — free to use, modify, and distribute.

Ver o original no GitHub

Bom para

Relacionados