🧠 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)
- project: project scope for this entry, up to 255 characters (optional; the
  server's detected project is 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

Propose durable memories from raw conversation, resolved against the store.

Pass a transcript as `text` and this returns the sentences in it that read
like durable facts, each already checked against what is stored: `new`
(nothing close), `duplicate` (already recorded), or `near` (close to
something stored -- worth your judgement, because an encoder cannot tell
"refines it" from "contradicts it").

With `use_llm=True`, once the operator has enabled local generation, it
composes a self-contained fact, and every generated proposal cites a
VERBATIM span from the transcript, checked against the source before it is
offered.

By default, and whenever no model is enabled and reachable, it SELECTS
sentences: a fact spread over three turns, or implied but never said
plainly, will not be proposed.

NOTHING IS WRITTEN BY `propose`. Proposals are staged for review, and only
`apply` writes one -- the same contract as marm_compaction, for the same
reason: a similarity score is not evidence enough to change memory
unattended.

Parameters:
- action: propose | review | apply | discard (default propose)
- text: the conversation to distil (required for propose)
- session_name: session the proposals belong to (required for propose;
  optional filter for review)
- proposal_id: which proposal to act on (required for apply/discard)
- project: scope name recorded on the memory that `apply` writes
- context_type: memory context type for the write (default general)
- threshold: shape-score floor, default 0.20. Excludes chatter and little
  else; measured against the live store, a higher floor discards real
  memories long before it meaningfully reduces the count
- limit: most proposals to return (default 20). THIS is the volume control
- include_duplicates: also stage what the store already holds (default off,
  because a queue of known facts does not get read)
- use_llm: write facts with the local model (default off; needs the
  operator to have enabled generation, and falls back to selection)

Returns: status plus `proposals` (propose) or `pending` (review), each
carrying content, score, the reasons it scored, verdict, cosine, and the
neighbouring memory when there is one.

🕸️ 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

🧩 Composed code context for a task: ranked symbols + source + memory, in ONE call.

Prefer this over marm_code_lookup when the question is "how does X work",
"where is X handled", or "what would changing X affect" -- it answers with
the symbols that matter, their source read from disk, and what memory
records about them, instead of leaving you to fetch each part yourself.

Ranking is personalised PageRank over the call graph seeded from `task`, so
a result is central *to this task* rather than globally popular or merely
word-matching. Read `markdown` and stop; the structured fields are the same
content for programmatic callers.

Parameters:
- task: what you are trying to do or understand
- project: code-graph project name or repo path; omit to resolve from cwd
- cwd: directory to resolve the project from (optional)
- budget: character budget for the returned source, 500-100000 (default 12000)
- include_graph: also return the ranked call neighbourhood as `graph_edges`;
  off by default because it is several KB of JSON only a visualiser reads
- answer: also answer the task from the composed context with a local
  model, citing the symbols it used. Off by default -- it is the slow step,
  and for an agent that reads code the ranked context IS the answer.
  The operator's analyst profile bounds it. `answer_status` is "ok" when
  every result is verified against the composed context, "unverified"
  when support is incomplete, "rejected" when it cites something the
  context does not contain (`answer_unresolved` names it);
  "unavailable" rather than a failure when generation is off or no model
  is up
- detail: how much to return. 1 is markdown only and is the default,
  because `markdown` already contains the source and the memory text --
  asking for 3 means paying for the same bytes twice. 2 adds symbol and
  memory metadata without repeating bodies; 3 adds them. 0 means "use the
  server default" (MARM_CODE_CONTEXT_DETAIL)

Returns: status, project, markdown, symbols, memories, links, graph_nodes,
notes -- or a no_project/unavailable status carrying the next step to take.
Each symbol carries `label` (the code KIND) and, when it arrived through the
call graph rather than by matching the task, a `provenance` object with hop,
strategy, confidence and risk; `provenance` is null for a seeded symbol

🧭 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