Store a semantic memory with an optional source label.

The response includes a conflicts list — existing learnings with high word-overlap to the new text. A non-empty list means a potentially contradictory memory already exists; use supersede_learning to replace it rather than letting both co-exist.

repo_path: optional absolute path to the target repository. When omitted, defaults to the server's configured project directory.

Deprecate an existing memory (by ID from store_memory conflicts list) and replace it with corrected text. Use when store_memory returns a conflict that contains incorrect or outdated information.

old_id is the ChromaDB document ID returned in the conflicts list. Returns: {found_old: bool, new_id: str}

repo_path: optional absolute path to the target repository.

Retrieve the top-k memories most similar to the query. If include_org=True, also queries sibling repositories in the same organization.

repo_path: optional absolute path to the target repository. When omitted, defaults to the server's configured project directory.

Record an architectural decision, bug fix rationale, or 'why we did X'. Stored in episodic memory — retrievable via episodic_search in future sessions. Call when a non-obvious architectural decision is made, a bug root-cause is understood, or the user says to 'remember' something. Do NOT call for routine changes — only decisions where WHY is non-obvious. Returns: {stored: True, searchable_via: 'episodic_search'}

FALLBACK ONLY — use org_wide_search first. Text-match search across org repos when org_wide_search returns nothing. Do NOT call as primary cross-repo search — org_wide_search has broader coverage.

Use when: org_wide_search returned 0 results, or the index is sparse. Returns a list of results annotated with source repository.

PRIMARY tool for cross-repo queries. Searches memories across ALL registered repos. Use this by default when a query spans multiple services or the answer may live in any repo. Prefer this over org_search (legacy fallback).

Use cross_repo_search when you need explicit scope control (project vs org). Use org_search only as a fallback when this returns empty.

Returns {results, count, repos_searched, repos_skipped} — check repos_skipped if an expected service is missing from results.

Claude: use this as the default cross-repo search.

Search knowledge from sibling repositories.

scope="project" — only repos in same project (recommended, high relevance). scope="org" — all repos in organization (broader, use sparingly).

Requires repos linked via cognirepo init (written to org graph). Returns empty results if no sibling repos are registered.

Claude: call this when:

• lookup_symbol returned empty and the symbol may live in a sibling repo

• The architecture question spans multiple services in the same project

• User asks "how does X work across the system" or "what does repo Y do"

• Importing from a sibling repo and need context on its internals

Show what org, project, and sibling repositories the current repo belongs to.

Claude: call this FIRST when the user asks about cross-service or cross-repo topics. Use the returned context to decide whether to call cross_repo_search, and which scope (project vs org) is appropriate.

Return the bidirectional inter-repo dependency graph for the current organization.

Shows which services this repo depends on (dependencies) and which services depend on this repo (dependents), up to depth hops. Edge kinds: IMPORTS — manifest-declared package dependency (auto-detected) CALLS_API — HTTP client calls to another service's endpoint SHARES_SCHEMA — shared models/proto repo

Claude: call this when the user asks about service dependencies, "what depends on X", or when investigating cross-service call chains.

Record a dependency relationship between two repos in the org graph. Call this when you discover that one repo imports from or calls another.

relationship: 'imports' | 'calls_api' | 'shares_schema' | 'discovered' | 'child_of' src_repo / dst_repo: absolute filesystem paths to the repos. service_type: optional — 'rest_api', 'grpc', 'worker', 'frontend', 'library' port: optional — port number the destination service listens on api_base_url: optional — base URL/path prefix for the destination's API

Do NOT call for repos not yet registered via cognirepo init. Returns: {linked: True, edge: {src, dst, kind}}

Traverse the org dependency graph from a repo or symbol to find cross-service relationships.

direction="dependencies" — what does this repo depend on? direction="dependents" — which services depend on this repo? direction="both" — return both directions (default)

If symbol is provided, also reports where that symbol exists in each traversed repo. Requires repos linked via cognirepo init (written to org graph). Returns empty if no sibling repos are registered.

Claude: use this when the user asks "which services use X?", "what does auth-service depend on?", or when tracing a bug across service boundaries.

Return all locations where a symbol is defined or called, with file, line, and type. If include_org=True, also searches sibling repositories in the same organization. Do NOT call for broad concepts — only exact or near-exact symbol names. For concept queries use semantic_search_code instead.

repo_path: optional absolute path to the target repository. When omitted, defaults to the server's configured project directory.

Word-level reverse-index search.

Unlike lookup_symbol() which only matches defined symbol names, search_token() finds any word that appears in symbol names, docstrings, or inline comments across the indexed codebase.

Examples: search_token("background") → files containing 'background' in names/docs search_token("validate") → all functions whose docs mention validation search_token("github") → files where GitHub is referenced in comments

Returns a list of {file, line} dicts sorted by file path.

repo_path: optional absolute path to the target repository.

Return every caller of a function across the indexed repo.

First searches the call graph (AST-indexed edges). If empty, falls back to string-literal grep for dynamic dispatch patterns (APScheduler add_job, Django signals, Flask routes, Celery tasks, etc.). Dynamic hits are labelled with found_via=dynamic_dispatch_fallback. Do NOT call if you already know the callers. Expensive on large graphs.

repo_path: optional absolute path to the target repository.

Find the shortest call-graph path between two symbols, crossing service boundaries via the org graph when needed.

Uses weighted Dijkstra (w=1.0→cost 1, w=0.75→1.3, w=0.5→2.0, cross-service org edge→5) to prefer traversal through core entry-point symbols over indirect paths.

from_symbol : Name of the source symbol. to_symbol : Name of the destination symbol. from_repo : Absolute path to source repo (auto-detected if omitted). to_repo : Absolute path to destination repo (auto-detected if omitted).

Returns {path, hops, crosses_services, services_traversed} or {error}.

Return the HTTP endpoint registry for a service (from endpoints.json).

Endpoints are populated by cognirepo index-repo and include method, path pattern, handler function name, file, and framework.

repo_path: absolute path to the target repo (defaults to current project).

Returns {endpoints, count, scanned_at} or {endpoints: [], count: 0}.

Return the local neighbourhood of a concept or symbol as {nodes, edges}.

repo_path: optional absolute path to the target repository.

Return past episodic events matching a keyword query.

include_archived: also search events rotated out of the live store (episodic_archive.json). Default False — live store only. Archived hits are tagged {"archived": True}. repo_path: optional absolute path to the target repository.

Log a structured episodic event to the episodic memory store. Use to record what happened: bugs found, code explored, agent actions. Retrievable via episodic_search in future sessions. Do NOT use for architectural decisions — use record_decision instead.

Return a health summary of the current graph state.

repo_path: optional absolute path to the target repository.

Semantic vector search over indexed code symbols only (no episodic memory mixed in). Optionally filter by language: "python", "typescript", "go", etc. Do NOT call for exact string matches — use search_token or grep instead. Use for concepts and natural-language queries about what code does.

repo_path: optional absolute path to the target repository.

Search indexed documentation files (*.md, *.rst, *.txt) by semantic similarity. Use for: README explanations, architecture docs, decision logs. Do NOT use for code — use semantic_search_code instead.

repo_path: optional absolute path to the target repository.

Return import/dependency relationships for a module. direction: "imports" | "imported_by" | "both". depth: transitive traversal depth (1 = direct only).

repo_path: optional absolute path to the target repository.

Explain what changed in a file or function recently by cross-referencing git history with episodic memory events mentioning the same target.

repo_path: optional absolute path to the target repository.

Retrieve pre-computed architectural summaries. scope: 'root' for repo summary, a directory path, or a file path.

repo_path: optional absolute path to the target repository.

Budget-pack the most relevant code + episodic context into a token-bounded block ready for injection into the next prompt. Call this BEFORE reading any source file to avoid wasting tokens on raw file reads. Returns at most max_tokens (default 2000) tokens — much smaller than raw files. Do NOT call for known short files (< 50 lines) — use Read directly instead.

file: optional relative path to scope retrieval to a single file. repo_path: optional absolute path to the target repository. When omitted, defaults to the server's configured project directory.

Return recent conversation session exchanges for context continuity.

Each entry has: session_id, created_at, message_count, and last_exchange (the final user/assistant pair). Call at session start to resume context.

limit: number of most-recent sessions to return (default 10). repo_path: optional absolute path to the target repository.

Single-call session bootstrap for AI agents. Replaces the 4-call sequence (get_session_brief → get_last_context → get_user_profile → get_error_patterns) with one ~300-token payload.

Returns: repo — project name architecture — 600-char architecture summary hot_symbols — ["fn:file:line", ...] top 8 symbols by behaviour weight last_focus — {files, query, agent} from last agent's context_pack framing — {depth, vocabulary} from user profile (empty if tracking off) mood — {state, evidence, suggested_adaptation}; neutral/empty on sparse data error_patterns — top 3 recurring errors with prevention hints index_health — {symbols, files, status} recent_timeline — last 5 entries (past 7 days) merged across sessions, episodes, decisions, and errors — {ts, kind, summary, ref} each; see data/memory/timeline.py::merge() for the full query surface (since/include_archived/limit)

Claude: call this ONCE at session start instead of the 4 individual calls. Use individual tools only when you need the full detail each provides.

repo_path: optional absolute path to the target repository.

Return the most recent context snapshot written by context_pack.

Call this at the START of a session to resume where the previous agent left off. Returns: query, sections, token_count, generated_at, agent, org_graph_summary. Returns {"status": "no_context"} if no snapshot exists.

Claude: call this automatically at session start when starting work on a known project. It shows what the last agent was looking at, preventing duplicate exploration and token waste.

Do NOT call on a fresh project that has never run context_pack.

repo_path: optional absolute path to the target repository.

Generate a session bootstrap brief for agent orientation.

Returns: architecture summary, entry points (most-called symbols), recent decisions from learning store, hot symbols from behaviour tracker, index health (symbol count, file count, last_indexed).

Claude: call this at the START of a session on an unfamiliar project, or when resuming after a long break. Gives you the full project map in one call — faster than reading files or running grep.

Do NOT call this repeatedly; call once at session start only.

repo_path: optional absolute path to the target repository.

Generate/update the repo insights HTML report — a human-readable "what happened in this repo" summary (timeline, decisions, challenges, branch/ commit activity, index health), sourced only from real stored records.

Returns a small pointer, NOT the report content: {status, path, sections, updated_at}. Claude: surface the path/link in your reply — do not quote or reconstruct the report body from this tool's output.

since: history window, e.g. "90d" (default). repo_path: optional absolute path to the target repository.

Return the user's interaction style profile for Claude to adapt its responses.

Includes: depth preference, dominant question types, domain vocabulary, code-focus percentage, framing hints, and a mood signal ({state, evidence, suggested_adaptation} — neutral/empty on sparse data) Claude should apply. Precedence: explicit user request > persona > framing_hints/mood. If the user has opted into a persona (COGNIREPO-402, via record_user_preference), the payload additionally carries active_persona + persona_behavior — absent entirely when no persona is set (byte-identical to pre-402 output otherwise). Caveman persona additionally carries output_contract (COGNIREPO-403) — served ONLY when active. After sustained QUICK-tier query usage, the payload may also carry a one-line, dismissible persona_suggestion nudging toward caveman — never auto-enabled.

Call this at the start of a session to calibrate response style.

repo_path: optional absolute path to the target repository.

Store an explicit user preference or query-rewrite correction.

Standard preferences (preference_key = any label): Store as: record_user_preference("response_format", "code-first, then explanation") Surfaced via get_user_profile()['explicit_preferences'].

Query-rewrite corrections (preference_key = "query_rewrite"): Use when you asked for X but user says they actually meant Y. Store the wrong phrasing as preference_value, intent in context: record_user_preference("query_rewrite", "deploy model", context="user means: update the ML model weights in production, not software deploy") Stored in query_rewrites list; agents apply these before retrieval so future similar queries hit the right code even when phrasing is off.

Persona selection (preference_key = "persona", COGNIREPO-402): Opt-in only — never enable a persona without the user explicitly asking. Valid values: "mentor" (deeper retrieval + full explanations + links to history), "pair" (default-equivalent, mood-aware phrasing), "caveman" (economy/telegraphic output, see COGNIREPO-403). "none" clears a previously-set persona (COGNIREPO-400-D01) — not a 4th persona. An unknown value is rejected, not stored — response includes {"recorded": false, "error": "..."}. Surfaced via get_user_profile()['active_persona'] / ['persona_behavior']. Precedence: explicit user request > persona > framing_hints/mood (see CLAUDE.md).

Claude: call this when:

• User corrects your interpretation ("no, I meant X not Y")

• User expresses a repeated preference ("always show code first")

• User clarifies what a query actually means in this codebase

Do NOT call for one-off answers — only for durable preferences that should persist across sessions.

Return recurring error patterns with prevention hints to avoid repeating mistakes.

Each entry has: error_type, count, affected files, last_seen, prevention_hint, and the most recent error message for context.

Use this to guide Claude away from solutions that have historically failed.

min_count: only return errors seen at least this many times (default 1). repo_path: optional absolute path to the target repository.

Record an error Claude or the user encountered so future sessions can avoid it.

error_type: exception class name or short label (e.g. "TypeError", "build_failed"). message: error message text (truncated to 300 chars). file_path: source file where the error occurred (optional). query_context: the query or action that triggered the error (optional). repo_path: optional absolute path to the target repository.

Returns: the prevention hint for this error type.