Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

MCP tools

contexere init registers Contexere as an MCP server, which gives the agent tools it can call itself without going through you. This page describes all 25. Your host is told about a subset.

What your host is told about

Tool definitions sit in the prefix of every request, so a tool nobody calls is re-read on every request of every session rather than paid for once. Contexere advertises the set your host’s tier can use:

tieradvertised
Fullcontexere_retrieve, contexere_explain_savings
Handoff-first, and any host Contexere does not recognisethose two, plus contexere_remember, contexere_recall, contexere_run, contexere_find_noise, contexere_context_breakdown, contexere_history
MCP-onlycontexere_remember, contexere_recall, contexere_retrieve, contexere_knowledge, plus contexere_run: no hook means the host’s own tool output is never rewritten, so contexere_run is the only path by which the model reads less

Full-tier hosts get the shortest list because they are the ones whose shell Contexere already hooks. Measured across 256 recorded sessions, those two tools carry 138 of the 149 calls in 467 bytes, while the other six cost 1,631 bytes for 11 calls in the life of the corpus. A Handoff-first host never has its built-in tool output rewritten, so MCP is the only door Contexere has there and nothing is priced away.

On Claude Code the shortest list is still not free, and the bytes are the smaller half of why: the host discards the whole prompt cache when an MCP server connects or disconnects with its tools loaded. Supported agents has what that means and how to run the hooks without it.

An unadvertised tool is not callable on that tier either, so the way back is the CLI or the override:

toolon a Full-tier host
contexere_runcontexere exec <command>
contexere_remembercontexere remember '<fact>'
contexere_context_breakdowncontexere stats --view context
contexere_historycontexere stats --view detail, which folds repeated commands into one row with a count instead of listing every call
contexere_recall, contexere_find_noiseno CLI equivalent; CONTEXERE_MCP_TOOLS=all

CONTEXERE_MCP_TOOLS=all advertises all 25, and contexere doctor says which set is in force and which host it resolved:

  MCP tools:      2 of 25 advertised to claude_code (CONTEXERE_MCP_TOOLS=all restores the rest)

Confirm the list against your own binary rather than this page:

{ echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"p","version":"1"}}}'
  echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'
  echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'; } \
| contexere --mcp | tail -1 | jq -r '.result.tools[].name'

Getting content back

toolwhat it does
contexere_retrieveRetrieve full content a marker omitted, by its handle
contexere_runRun a shell command and return distilled output
contexere_signal_extractExtract signal from raw text, without the hook pipeline

contexere_run matters most on hosts that cannot rewrite their built-in shell tool. There, it is the only path to distilled output, which is why contexere init --cursor installs a rule telling the agent to prefer it.

Understanding what Contexere did

toolwhat it does
contexere_explain_savingsRoute, filter, input and output bytes, savings % per recent command
contexere_historyRecent distillations with per-call savings and ratios
contexere_context_breakdownToken breakdown by source for the current turn
contexere_densityHow much signal against noise in a piece of text
contexere_budgetToken budget usage and compression efficiency for this session

These four are the right answer to “is Contexere helping here”. Pull the numbers rather than forming an impression.

Memory

toolwhat it does
contexere_rememberStore a decision, gotcha or constraint
contexere_recallSearch across stored knowledge
contexere_knowledgeQuery or store cross-session project knowledge
contexere_insightTop recurring issues and error patterns across the project
contexere_adaptive_insightsRetrieval patterns, as a judgement on distillation effectiveness
contexere_handoffExport session state as portable markdown, no network needed

contexere_handoff is MCP only. The CLI subcommand of that name was removed.

toolwhat it does
contexere_sessionSession state: status, context, clear
contexere_searchSearch this session’s history
contexere_queryQuery distillation history with the fixed query forms
contexere_agentsOther agents currently active on this project

Tuning

toolwhat it does
contexere_find_noiseAnalyse recent raw traces for repetitive noise

Advisory only, and the learner treats “repeated” as “noise”. It has suggested stripping ^metadata:, ^spec:, code fences and ^\[stderr\], which are structure and the error channel. Never paste its output anywhere without reading it line by line.

Loops

toolwhat it does
contexere_loop_statusOne-call status check for an orchestrator before each iteration
contexere_loop_memoryRead and write loop memory that survives session restarts
contexere_set_loop_contextUpdate loop context dynamically
contexere_budget_statusBudget status for this iteration. Call before expensive work.
contexere_verifyAs a checker sub-agent, evaluate the maker agent’s recent work

See Loop engineering.

A tool that is not one

omni_auto_noise appears as a string in the server source and is not a tool. It is a filter name passed to the TOML generator. Calling it returns -32602 tool not found.

It has been miscounted before: a source grep for "omni_*" returns 27, and 27 is therefore wrong wherever it appears. Run the tools/list call above for the count.

What left the surface

contexere_context was advertised until 0.7.7 and had never been called once across 253 recorded sessions, so it cost 189 bytes in the prefix of every request for a capability nobody reached for. It is contexere context <file> now, which costs nothing per request:

contexere context crates/contexere-reduce/src/ledger/mod.rs

An agent can still reach it through contexere_run.