Skip to main content
Glama

Codevira

One memory layer for every AI coding tool you use. Switch between Claude Code, Cursor, Windsurf, and Antigravity without losing context, decisions, or progress.

PyPI version Python Downloads License: MIT MCP PRs Welcome

Built for solo developers working on local projects with AI agents. Codevira gives every AI tool you use access to the same persistent project memory — so you stop re-explaining your codebase every session, stop losing carefully-made decisions, and stop burning tokens on re-discovery.

Works with: Claude Code · Claude Desktop · Cursor · Windsurf · Google Antigravity · any MCP-compatible AI tool


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.


Related MCP server: Tages

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:

Capability

What it means for you

Zero-config setup

pipx install codevira && codevira register — that's it. No prompts, no JSON editing. Auto-detects language, source dirs, and IDE configs

Cross-tool continuity

One get_session_context() call brings any AI agent up to speed in ~800 tokens — works identically in Claude Code, Cursor, Windsurf, Antigravity

Decision protection

do_not_revert flags + searchable decision log stop AI agents from undoing past architectural choices

Context graph

Every source file has a node: role, rules, dependencies, stability, blast radius. AI calls get_node(path) instead of re-reading the file

Function-level call graph

get_impact(file) answers "what breaks if I change this?" before the AI modifies anything

Semantic code search

Natural-language search across your codebase (search_codebase("auth flow"))

Roadmap + changesets

Multi-file work tracked atomically; sessions resume cleanly after interruption

Adaptive learning

Tracks which past decisions panned out — gives confidence scores and surfaces patterns

Cross-project memory

Learned preferences sync across all your local projects via ~/.codevira/global.db

Auto-init on first call

No codevira init needed — first MCP tool call triggers background project setup

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_codebase(query) — file/symbol pointers only. Pass include_content=true to inline source.

  • search_decisions(query) — 5 truncated matches. Pass full=true for verbatim text.

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


Quick Start

1. Install

# Recommended: global install via pipx (isolated, works everywhere)
pipx install codevira

# Alternative: pip install
pip install codevira

Installs the full toolkit (23 AI-facing MCP tools + 12 admin/CLI tools) out of the box. Semantic search downloads a ~90MB embedding model on first use.

2. Register with your AI tools

codevira register

This one-time global command injects Codevira's MCP config into all detected AI tools — Claude Code, Cursor, Windsurf, Claude Desktop, and Google Antigravity. Run it from anywhere; no project directory needed.

3. Start using

Open any project in your AI tool. On the first MCP tool call, Codevira auto-initializes:

  • Detects language, source directories, and file extensions from project markers

  • Creates the context graph and roadmap

  • Installs a post-commit git hook for automatic reindexing

No explicit codevira init needed — everything happens on demand.

Note: codevira init is still available for explicit per-project setup with custom settings.

4. Verify

Ask your AI agent to call get_roadmap() — it should return your current phase and next action.

Note: Restart your AI tool after running codevira register to pick up the new MCP config.

Customizing what's indexed

Codevira tries to auto-detect your project's source layout, but monorepo or non-standard layouts sometimes slip through — you'll notice when codevira index --full reports 0 chunks indexed and prints a hint pointing you here.

cd your-project
codevira configure

Scans your project (gitignore-aware), shows discovered directories and extensions with file counts, and lets you pick which to watch via a numbered-list prompt. It writes your choices back to .codevira/config.yaml and offers to rebuild the index.

Non-interactive (useful in scripts or CI):

codevira configure --dirs src,packages,apps --extensions .py,.ts,.tsx --no-reindex

After changing watched directories, restart your AI tool — running watchers snapshot the dir set at boot.

Manual config (only if auto-inject didn't detect your tool)

Codevira supports two transports. Use the right one for your client:

Client

Transport

Config file

Claude Desktop (app)

stdio

~/Library/Application Support/Claude/claude_desktop_config.json

Claude Code (CLI)

stdio or HTTP

.claude/settings.json

Cursor

stdio

.cursor/mcp.json

Windsurf

stdio

.windsurf/mcp.json

Google Antigravity

stdio

~/.gemini/antigravity/mcp_config.json

Stdio transport — Claude Desktop, Cursor, Windsurf (.claude/settings.json / .cursor/mcp.json / .windsurf/mcp.json):

{
  "mcpServers": {
    "codevira": {
      "command": "codevira",
      "args": [],
      "cwd": "/path/to/your-project"
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "codevira": {
      "command": "/path/to/codevira",
      "args": ["--project-dir", "/path/to/your-project"]
    }
  }
}

Tip: find the full binary path with which codevira

HTTP/HTTPS transport — Preview in v1.7, single-project only. The HTTP server binds to one project at startup and cannot switch contexts per request. Multi-project HTTPS is planned for v1.8. For multi-project work today, use stdio via codevira register (above).

First start the HTTP server in a terminal:

codevira serve --port 7007 --project-dir /path/to/your-project
# For HTTPS (required by some clients):
codevira serve --https --port 7443 --project-dir /path/to/your-project

Then register the URL:

{
  "mcpServers": {
    "codevira": {
      "url": "https://localhost:7443/mcp"
    }
  }
}

HTTPS note: Claude Code uses Node.js, which requires a trusted CA for HTTPS. Run once to trust the mkcert CA:

brew install mkcert && mkcert -install
launchctl setenv NODE_EXTRA_CA_CERTS "$(mkcert -CAROOT)/rootCA.pem"
echo 'export NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem"' >> ~/.zshrc

Then restart Claude Code.

Auto-start on login (macOS):

codevira serve --install-service    # start server automatically on login
codevira serve --uninstall-service  # remove auto-start

Google Antigravity (~/.gemini/antigravity/mcp_config.json):

{
  "mcpServers": {
    "codevira": {
      "$typeName": "exa.cascade_plugins_pb.CascadePluginCommandTemplate",
      "command": "codevira",
      "args": []
    }
  }
}

Codevira data layout (v1.6)

~/.codevira/                         <- global Codevira home
├── global.db                        <- cross-project intelligence
├── projects/
│   └── <project-key>/               <- per-project data (keyed by path)
│       ├── config.yaml
│       ├── metadata.json
│       ├── graph/
│       │   ├── graph.db
│       │   └── changesets/
│       ├── codeindex/               <- semantic search (optional)
│       └── logs/
└── certs/                           <- HTTPS certs (if using --https)

Legacy .codevira/ directories inside project repos are auto-migrated to centralized storage on first server start.

Configuration

Each project has a config.yaml at ~/.codevira/projects/<project-key>/config.yaml. It's auto-generated on first use with sensible defaults, but you can edit it to customize what Codevira indexes:

project:
  name: my-project
  language: python
  collection_name: my_project
  # Which directories to scan for source files
  watched_dirs:
    - src
    - tests
    - scripts
  # Which file extensions count as "source" for indexing + change detection
  file_extensions:
    - .py
    - .ts
    - .tsx
  # Directories to skip even if inside watched_dirs
  skip_dirs:
    - node_modules
    - .venv
    - __pycache__
    - dist
    - build
logs:
  # 0 = keep sessions/decisions forever (default).
  # Only set > 0 if you have privacy reasons to time-bound history.
  retention_days: 0

Common gotchas:

  • file_extensions must be a proper YAML list — each extension on its own line. This is wrong:

    file_extensions:
      - .py, .md, .html    # ❌ one item containing commas, not three extensions

    This is correct:

    file_extensions:
      - .py
      - .md
      - .html

    Or inline:

    file_extensions: [.py, .md, .html]
  • file_extensions is intended for source code (Python, TypeScript, Go, Rust, etc.). Codevira uses tree-sitter AST parsing — putting .md or .html here may produce malformed graph nodes since tree-sitter parsers for those languages are different.

  • Files are only scanned if they live inside watched_dirs. Adding an extension alone isn't enough — make sure the directory is listed too.

After editing the config, run codevira index --full to rebuild the graph from scratch, or codevira index for incremental changes.

Uninstall / Reset

codevira clean              # remove global data + IDE configs + launchd service
codevira clean --all        # also remove per-project artifacts
codevira clean --dry-run    # preview what would be removed

How It Works

Setup Flow

flowchart LR

A["pipx install codevira"] --> B["codevira register"]
B --> C["Open project in\nClaude Code / Cursor /\nWindsurf / Antigravity"]
C --> D["First MCP tool call\ntriggers auto-init"]
D --> E["✓ Config written\n✓ Graph built\n✓ Roadmap created\n✓ Ready"]

Agent Session Lifecycle

flowchart TB

Start([Start Session])

subgraph "Orientation (single call)"
A["get_session_context()\nroadmap + changesets +\ndecisions + global intelligence"]
end

subgraph "Work"
B[get_node / get_impact\nbefore touching files]
C[Plan + Implement + Test]
D[refresh_index\nafter changes]
end

subgraph "Session End"
E[update_node — record changes]
F[write_session_log — decisions]
G[update_next_action — handoff]
end

Start --> A
A --> B
B --> C
C --> D
D --> E
E --> F
F --> G

Architecture

flowchart TB

A[Source Code\n15+ languages]

subgraph "Indexing Pipeline"
B[Tree-sitter AST Parser]
C[Function / Class / Call Extraction]
D[Background File Watcher\nauto-reindex on save]
end

subgraph "Centralized Storage — ~/.codevira/"
E[(Context Graph + Call Graph\nSQLite DB)]
F[(Semantic Index\nChromaDB — optional)]
G[(Global Memory\ncross-project intelligence)]
H[(Session Logs + Decisions\nsearchable history)]
end

subgraph "Adaptive Learning"
I[Outcome Tracking]
J[Rule Inference]
K[Preference Learning]
end

subgraph "MCP Server"
L[36 Tools + 5 Prompts\nstdio or HTTP transport]
end

M[AI Coding Agent\nClaude Code · Cursor · Windsurf · Antigravity]

A --> B
B --> C
C --> E
C --> F
D --> B

E --> L
F --> L
G --> L
H --> L

I --> G
J --> G
K --> G

E --> I

L --> M

Session Protocol

Every agent session follows a simple protocol. Set it up once in your agent's system prompt — then your agents handle the rest.

Session start (mandatory):

list_open_changesets()      -> resume any unfinished work first
get_roadmap()               -> current phase, next action
search_decisions("topic")   -> check what's already been decided
get_node("src/service.py")  -> read rules before touching a file
get_impact("src/service.py") -> check blast radius

Session end (mandatory):

complete_changeset(id, decisions=[...])
update_node(file_path, changes)
update_next_action("what the next agent should do")
write_session_log(...)

This loop keeps every session fast, focused, and resumable.


MCP Tools + 5 Prompts

23 tools exposed to AI agents (token-optimized, summary-first). The remaining 12 tools are admin/dashboard tools that work via dispatch but aren't advertised in list_tools() — humans access them via the CLI or via specific MCP prompts. Tools marked (admin) below.

Graph Tools

Tool

Description

get_node(file_path, full?)

Summary by default (counts + flags); full=true for rules/dependencies arrays

get_impact(file_path, summary_only?)

Blast radius — summary_only=true returns just counts (~80 tokens)

update_node(file_path, changes)

Append rules, connections, key_functions

query_graph(file_path, symbol?, query_type)

Function-level: callers, callees, tests, dependents, symbols

list_nodes(...) (admin)

Bulk node listing — agents should use targeted queries instead

add_node(...) (admin)

Register a new file (auto-generated by refresh_graph)

refresh_graph(file_paths?) (admin)

Auto-generate stubs (background/automatic)

refresh_index(file_paths?) (admin)

Background reindex (fire-and-forget)

export_graph(format, scope?) (admin)

Mermaid/DOT export — large dump

get_graph_diff(base_ref?, head_ref?) (admin)

PR review — use review_changes prompt

analyze_changes(base_ref?, head_ref?) (admin)

Risk scoring — use pre_commit_check prompt

find_hotspots(threshold?) (admin)

Complexity dashboard

Roadmap Tools

Tool

Description

get_roadmap()

Current phase, next action, open changesets

get_phase(number)

Full details of any phase by number

update_next_action(text)

Set what the next agent should do

update_phase_status(status)

Mark phase in_progress / blocked

add_phase(phase, name, description, ...)

Queue new upcoming work

complete_phase(number, key_decisions)

Mark done, auto-advance to next

defer_phase(number, reason)

Move a phase to the deferred list

get_full_roadmap(include_decisions?) (admin)

Full history with all decisions inline

Changeset Tools

Tool

Description

list_open_changesets()

All in-progress changesets

start_changeset(id, description, files)

Open a multi-file changeset

complete_changeset(id, decisions)

Close and record decisions

update_changeset_progress(id, last_file, blocker?)

Mid-session checkpoint

Search Tools

Tool

Description

search_codebase(query, limit?, include_content?)

Semantic search — pointers only by default

search_decisions(query, limit?, full?)

Past decisions (default 5, truncated context)

get_history(file_path, limit?, full?)

Recent decisions touching a file (default 5)

write_session_log(...)

Write structured session record

Adaptive Learning Tools

Tool

Description

get_session_context()

THE main "catch me up" call — start every session here (~800 tokens)

get_decision_confidence(file_path?, pattern?)

Outcome-based reliability scores

get_preferences(category?) (admin)

Already in get_session_context

get_learned_rules(file_path?, category?) (admin)

Already in get_session_context

get_project_maturity() (admin)

Dashboard metric — use architecture_overview prompt

Code Reader Tools

Tool

Description

get_signature(file_path)

All public symbols, signatures, line numbers (Python, TypeScript, Go, Rust)

get_code(file_path, symbol)

Full source of one function or class

Playbook Tool

Tool

Description

get_playbook(task_type)

Curated rules for: add_tool, add_service, add_schema, debug_pipeline, commit, write_test

MCP Workflow Prompts (v1.5)

Prompt

Description

review_changes

Staged diff + blast radius + risk score

debug_issue

Symptom -> affected files -> call chain -> hypothesis

onboard_session

Full project context catch-up for new sessions

pre_commit_check

Test coverage gaps + high-risk functions before commit

architecture_overview

Module map + hotspots + dependency summary


Language Support

Feature

Python

TypeScript

Go

Rust

12+ Others

Context graph + blast radius

Y

Y

Y

Y

Y

Semantic code search

Y

Y

Y

Y

Y

Function-level call graph

Y

Y

Y

Y

get_signature / get_code

Y

Y

Y

Y

AST-based chunking

Y

Y

Y

Y

Auto-generated graph stubs

Y

Y

Y

Y

Roadmap + changesets

Y

Y

Y

Y

Y

Session logs + decision search

Y

Y

Y

Y

Y

Supported languages: Python, TypeScript, JavaScript, Go, Rust, Java, Kotlin, C#, Ruby, PHP, C, C++, Swift, Solidity, Vue.


Requirements

  • Python 3.10+

  • ~500MB install (includes ChromaDB + sentence-transformers for semantic search)

  • ~90MB model download on first search_codebase() call

pip install codevira includes the full toolkit out of the box — graph, roadmap, changesets, code reader, learning, call graph, and semantic search.

If you want to skip the ML stack and use only graph-based tools (semantic search disabled), install without the search deps:

pip install codevira --no-deps
pip install pyyaml mcp watchdog tree-sitter tree-sitter-language-pack rich uvicorn starlette pathspec

The search_codebase tool will be hidden from your AI agent; all other tools work normally.


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 We Cut AI Coding Agent Token Usage by 92%


Contributing

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

Reporting a bug? Open a bug report Requesting a feature? Open a feature request Found a security issue? Read SECURITY.md — please don't use public issues for vulnerabilities.

Testing a release candidate locally? See docs/local-pypi-https.md for setting up a Docker-based HTTPS PyPI registry that mirrors the real PyPI install flow without touching public PyPI.


FAQ

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

Roadmap

See what's built, what's next, and the long-term vision — see ROADMAP.md.

Star History

If Codevira saves you tokens or sanity, a star helps other developers find it. Tracking growth keeps me focused on what's working.

License

MIT — free to use, modify, and distribute.

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