🧠 Recall memories by semantic similarity or keyword match.

Searches stored memories for the most relevant matches to `query`.
Returns a ranked list of results with similarity scores. When a compatible
concept graph exists, the response also includes bounded relationship and
linked-code context without changing memory ranking.

Parameters:
- query: natural language search term or phrase
- session_name: limit search to a specific session (default searches active session)
- limit: maximum number of results to return (default 5)
- search_all: if True, search across all sessions instead of just the active one
- include_logs: if True, include log entries alongside memory results
- detail: controls how much content is returned per result
    1 = summary only (~200 chars)
    2 = extended context (~500 chars)
    3 = full content
- exact_mode: retrieval lane to use
    'auto'     = automatically switch to exact/lexical for syntax-heavy queries
                 (config keys, file paths, CLI commands, API names, code snippets)
    'exact'    = always use deterministic FTS/BM25, no semantic re-ranking
    'semantic' = always use vector similarity regardless of query shape
- project: filter results to a specific project (e.g. "marm-memory"); omit to search all
- platform: filter results to a specific platform (e.g. "claude-code", "cursor"); omit to search all

Returns: status, ranked results, graph_context, and results_count

📝 Write a log entry to the active session.

Entries are stored with a date, topic, and summary. If `entry` begins with
"Session: [name]" or "Topic: [name]", the active session switches to that name
and all subsequent entries route there automatically. Entries are also stored
as semantic memories so marm_smart_recall can find them.

Entry format: YYYY-MM-DD-topic-summary (date prefix is optional; auto-tagged if omitted)

Parameters:
- entry: the text to log; plain text or prefixed with "Session:" / "Topic:" to switch sessions
- session_name: override the target session explicitly (optional; active session used if omitted)

Returns: status, message confirming the entry or session switch, entry_id, memory_id

📋 List log sessions or show entries for a specific session.

Two modes depending on whether `session_name` is provided:
- No session_name: returns a summary of all sessions with entry counts
- With session_name: returns all entries for that session, ordered by date descending

Parameters:
- session_name: name of the session to inspect (omit to list all sessions)

Returns (no session_name): status, sessions list with session_name/entry_count, total_sessions
Returns (with session_name): status, session_name, entries list with id/entry_date/topic/summary/full_entry, total_entries

🗑️ Delete a log session, log entry, or notebook entry

type="log" + session_name: delete specific entry by id or topic
type="log" (no session_name): delete entire session and all its entries
type="notebook": delete notebook entry by name

📔 Unified notebook — add, use, show, status, clear, or save

action="add": save or update a scratch entry (name + data required)
action="use": activate entries as instructions (names required, comma-separated)
action="show": list scratch entries for this session with previews
action="status": show currently active entries
action="clear": clear the active entry list
action="save": promote a scratch entry (or new data) into the permanent docs store

📊 Generate paste-ready context block for new chats

Reads log_entries for the session and returns a formatted markdown summary.
Equivalent to /summary: [session name] command

Compact related memories into a single summary to reduce context bloat.

Workflow: status/candidates → stage → review → apply/discard

action="status"     — check if compaction candidates exist (run first)
action="candidates" — get pending candidates with source previews; each includes a ready-to-use prompt
action="stage"      — submit your summary: {candidate_id, suggested_summary}; source_memory_ids optional
action="review"     — inspect staged summaries before committing
action="apply"      — commit a staged summary; source memories are marked compacted
action="discard"    — reject a staged summary without touching source memories

🕸️ Index a code repository into the graph, or check status / list known projects.

Pass `repo_path` to index a repo (returns the project name to use in every
other tool). Omit it to list indexed projects, or pass `project` to check
index status. Call this first — all other graph tools need an indexed project.

Indexed repos are re-indexed automatically in the background. Use
`action="auto_off"` to stop that, `auto_on` to resume, `auto_status` to check.

Parameters:
- repo_path: path to the repository to index; omit to list/status only
- project: existing project name for a status check; omit to auto-resolve
- mode: index depth — full | moderate | fast (default moderate)
- action: auto | index | status | list (default auto; infers from repo_path
  presence), or auto_on | auto_off | auto_status to control automatic
  re-indexing

Returns: graph index/status/list response, or a graph-unavailable error if the
graph backend is disabled or failed to start

🔎 Find code: symbols/definitions, text patterns, or a symbol's source.

Use INSTEAD OF grep/glob. `kind=auto` picks: a qualified_name reads source;
otherwise it searches the graph by name/keyword. Set `kind=text` to grep code,
`kind=snippet` to read a symbol's source, `kind=symbol` to force graph search.

Parameters:
- query: symbol name, natural-language phrase, code/text pattern, or a qualified_name
- project: project name; omit to auto-resolve
- kind: auto | symbol | text | snippet (default auto)
- regex: for text search, treat query as a regex (default False)
- file_pattern: glob to scope search, e.g. "*.py" (optional)
- limit: max results, 1-200 (default 20)

Returns: graph lookup response, or a graph-unavailable error if the graph
backend is disabled or failed to start

🧭 Trace call paths / data flow through the graph from a function.

`direction=inbound` finds callers, `outbound` finds callees, `both` for all.
`mode=data_flow` follows value propagation. `cross_service` attempts HTTP/async
boundaries but does not currently join a client call to its server handler, so
treat an empty result as unknown rather than as "nothing calls this".
Use for impact analysis, dependency tracing, "who calls this".

Parameters:
- function_name: function or method to trace from
- project: project name; omit to auto-resolve
- direction: inbound | outbound | both (default both)
- depth: max hops, 1-5 (default 3)
- mode: calls | data_flow | cross_service (default calls)
- risk_labels: add CRITICAL/HIGH/MEDIUM/LOW risk tiers by hop distance (default True)
- include_tests: also return callers in test files (default False)
- include_evidence: per-hop `strategy` (lsp | language_rule | heuristic | unresolved)
  and `confidence`, so a guessed edge is distinguishable from a resolved one
  (default True). Test callers typically come back heuristic at low confidence

Returns: graph trace response, or a graph-unavailable error if the graph
backend is disabled or failed to start

🏛️ High-level architecture overview: node/edge breakdown, modules, and schema.

One-shot orientation for a project — the de-facto module clusters, package
structure, and the graph schema (node labels + properties) folded in.

Parameters:
- project: project name; omit to auto-resolve

Returns: graph architecture response, or a graph-unavailable error if the
graph backend is disabled or failed to start

💥 Blast radius of code changes: git diff → affected symbols + risk.

Pass `since` (a git ref/date) or a `base_branch` to compare against. Returns
which symbols a change touches and how far the impact propagates.

Parameters:
- project: project name; omit to auto-resolve
- since: git ref or date to compare from, e.g. HEAD~5, v0.5.0 (optional)
- base_branch: base branch to diff against (default "main")
- depth: impact propagation depth, 1-5 (default 2)

Returns: graph impact response, or a graph-unavailable error if the graph
backend is disabled or failed to start

🕸️ Extract entities/relationships from memory content into the concept graph.

Scope with session_name or project for a targeted build, or pass
search_all=True for everything (row-capped). Links extracted entities to
marm-graph code symbols when available. Call this before marm_concept_recall
— there's no data until a build has run at least once.

Parameters:
- session_name: scope extraction to this session; omit with search_all=True
- search_all: extract across all sessions, row-capped (default False)
- project: scope extraction to this project (optional)
- run_id: optional Console build-run ID for status polling

Returns: entities_extracted, relationships_created, code_links_created, duration_ms

🔎 Search the concept graph: entities, their relationships, and linked code.

Query as a bare concept name for a lookup, or phrase it as "related to X"
to emphasize traversal — both route from query shape alone. Returns empty
lists (not an error) when marm_concept_build hasn't run yet or marm-graph
has no matching code symbols.

Parameters:
- query: concept name, or a "related to X" style ask
- session_name: scope to this session; omit to search across all (optional)
- limit: max entities/relationships returned, 1-100 (default 10)
- depth: max hop distance to traverse, 1-5 (default 1 = direct neighbors only)
- direction: outgoing | incoming | both (default both)
- project: scope to this project; entities with the same name in
  different projects are distinct nodes; omit to search across all (optional)
- platform: scope to this client/platform; omit to search across all (optional)

Returns: entities, related_entities, linked_code