Skip to main content
Glama
Lyellr88

marm-memory

by Lyellr88
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

marm_code_context

Compose ranked, task-focused code context in one call: symbols, source, and related memory to answer how code works and what changes affect.

Instructions

🧩 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
- analyst_mode: with `answer`, "read_only" (default) returns the verified
  answer only; "manual_review" also stages its verified results as
  marm_distill proposals for approval; "guardrails" lets MARM apply the
  ones it can prove mechanically, only where the operator switched
  auto-apply on. The model never applies anything
- 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

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
cwdNo
taskYes
answerNo
budgetNo
detailNo
projectNo
analyst_modeNoread_only
include_graphNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.57.0
    • addedInput schema / properties / analyst_mode
      Added value: +{
+  "default": "read_only",
+  "title": "Analyst Mode",
+  "type": "string"
+}
  2. Changed1 schema field changedv2.52.0
    • addedInput schema / properties / answer
      Added value: +{
+  "default": false,
+  "title": "Answer",
+  "type": "boolean"
+}
  3. Addedv2.50.1

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so: it documents the ranking mechanism (personalised PageRank over the call graph seeded from task), the answer_status state machine (ok/unverified/rejected/unavailable), the side effects of analyst_mode (staging marm_distill proposals, guardrails auto-apply only where the operator enabled it, 'The model never applies anything'), and the failure statuses (no_project/unavailable). This is unusually rich disclosure of behaviour beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the one-line purpose and the sibling-routing rule, then parameters, then returns – a sensible order. It is long, and the deeply nested answer/analyst_mode prose runs several lines per bullet, but nearly every sentence carries information an agent would otherwise have to infer. Slightly verbose rather than wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter tool with no output schema and no annotations, the description covers selection, parameter semantics, cost trade-offs, side effects, and the returned field list (status, project, markdown, symbols, memories, links, graph_nodes, notes) plus symbol-level fields (label, provenance). Nothing material is left for the agent to guess.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and all 8 parameters are documented in the description with semantics the schema lacks: budget range and default, include_graph's cost rationale, answer's status outcomes, analyst_mode's enum meanings, and detail's 0/1/2/3 levels including why 1 is the default. It fully compensates for the missing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a concrete verb+resource ('Composed code context for a task: ranked symbols + source + memory, in ONE call') and explicitly distinguishes itself from the sibling marm_code_lookup by naming the question types it answers ('how does X work', 'where is X handled'). An agent can route between the two tools without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit prefer-this-over rule with the triggering conditions, plus when-not guidance for the expensive options ('include_graph ... off by default because it is several KB of JSON only a visualiser reads'; 'answer ... the slow step'). Defaults for detail and the reason for each default are spelled out, so selection is unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools