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.

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.

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

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

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.

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

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

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.

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.

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?'

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.

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

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.

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).

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.

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.

v3.2.0: refresh a do_not_revert decision's soft-expire clock. Long-lived locked decisions can grow stale; v3.2.0 surfaces a 'dnr_soft_expired' flag on search/list output (default 180 days, override via CODEVIRA_DNR_SOFT_EXPIRE_DAYS). Call this on a still-load-bearing soft-expired decision to reset the clock — appends a single 'reaffirmed_at' amendment to .codevira/decisions.jsonl. For semantic rewrites use supersede_decision; for flipping the flag use set_decision_flag.

Check whether a proposed decision contradicts any do_not_revert=True decision OR duplicates an existing one. 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).

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

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).

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.

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

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

Get the skeleton of a Python file — all public function and class names, their signatures, docstrings, and line ranges. Call this after get_node() to understand file structure before deciding which symbol to read with get_code(). Much cheaper than reading the full file. Note: Python files only. For other languages, read the file directly.

Get the full source of a single function or class by name. Always reads from disk — always current, never stale. Call get_signature() first to discover available symbol names and line ranges. Omit symbol to get module-level constants and assignments only. Note: Python files only. For other languages, read the file directly.

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. Works seamlessly across AI tools: Cursor, Claude Code, Windsurf, Antigravity.

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.

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.

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.

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).

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.

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.

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.

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.

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.

v3.1.0 M3: Write the skill's procedure as a playbook markdown file at .codevira/playbooks//.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).

v3.1.0 M4: Files topologically near a given file, ranked by recent activity. Candidate set = BFS distance ≤ 2 over the indexer graph (imports + call edges) ∪ same-neighborhood files. Ranking: (1 / (1 + bfs_dist)) × log(1 + visit_count_30d). Falls back to neighborhood-only if the indexer graph isn't built.

v3.1.0 M4: Top-K most-touched files in a time window by weighted activity (edits + decision_refs). Useful for 'where has attention been this week?' queries. Pass since_days to limit the window; omit for all-time.

v3.1.0 M4: Return the neighborhood id + members for a file. Folder-tree default (top-2 dir components, e.g., 'mcp_server/storage'); overridable via .codevira/neighborhoods.yaml.

v3.1.0 M4: Return the affordance keys (task_types) applicable to a file based on the bundled + project affordances.yaml. E.g., a file under mcp_server/tools/ typically affords {add_tool, write_test}. Use the returned keys with get_playbook(task_type) for relevant rules.

v3.1.0 M6 Phase B: Scan decisions written since this IDE's checkpoint, surface cross-IDE conflicts to .codevira/pending_conflicts.jsonl, advance the checkpoint. Read-only — no automatic resolution. The Phase C handshake protocol (one IDE proposing supersession to another) is M7 and ships disabled by default.

v3.1.0 M6: Return the count of pending cross-IDE conflicts + top-K rows (default 3). Useful as a status check from inside the agent loop; the get_session_context payload also carries a 'consensus' panel based on this data.

v3.1.0 M7 Phase C: Open a cross-IDE supersession proposal. Writes a 'proposed_supersession' row to pending_conflicts.jsonl with expires_at = ts + handshake_timeout_days (default 14). Opt-in: returns {disabled: True} unless memory.consensus.handshake_enabled is set in .codevira/config.yaml. Same-author fast-path returns {fast_path: True} so the caller can route to supersede_decision directly.

v3.1.0 M7 Phase C: Approve, reject, or withdraw a pending supersession proposal. Opt-in via memory.consensus.handshake_enabled. The approving IDE should match the target decision's origin IDE (or be 'unknown') for cross-IDE proposals; withdrawals come from the proposing IDE.

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.

v3.3.0: Distill captured user prompts into durable preferences (communication style, workflow habits) via the host LLM (sampling/createMessage). Call at SESSION END when the Stop-hook nudge fires, with dry_run=false to persist into cross-project memory (~/.codevira/global.db) and clear the capture file. Degrades to {rendered_prompt} when the host doesn't support sampling.

v3.3.0: Search learned user preferences (cross-project, LLM-distilled). Filter by category: 'communication', 'workflow', 'formatting'. Use before adopting a tone or workflow the user may have expressed opinions about. Highest-frequency first.

v3.1.0 M8: Build the source context + rendered prompt for an LLM abstraction over recent decisions + sessions. v3.1.0 returns {sampling_supported: False, rendered_prompt, source_context} so callers can feed the prompt to a locally-available LLM. The MCP sampling/createMessage RPC integration is the v3.2 deliverable; until then, use codevira reflect --from-file to commit an LLM-supplied abstraction.

v3.1.0 M8: Top-K most recent reflections (newest first).

v3.1.0 M8: Filtered reflection list. 'since' is an ISO 8601 timestamp cutoff; 'tags' is set intersection (every requested tag must appear).

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.