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

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

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.

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.

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

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.