[JayOfTheKeyboard]

The MCP recall tool describes max_tokens as the "Maximum tokens to return in results". The engine counts only each fact's text, as MemoryEngine.recall_async's docstring says ("counts only 'text' field"). Every result also carries its id, tags, scores, dates, document and chunk ids. An agent that sizes its context from the tool description is off by a wide margin.

Measured on 0.10.1 against a real bank (~900 facts), with budget: "low" and the default max_tokens: 4096, two queries returned:

	query 1	query 2
results	117	90
fact text	19,270 chars (~4,800 tokens)	17,582 chars (~4,400 tokens)
whole response	119,494 chars	87,975 chars
of which indent=2 whitespace	26,693	20,270

So the budget works as the engine intends. The response is still about six times what the tool promises, and Claude Code refused both results as over its tool-output limit.

Fix

• Docstring, both copies: max_tokens is now described as the token budget for the facts' text. It says the per-result metadata is extra, so the response is several times larger.
• The bank-id copy returns compact JSON (model_dump_json() instead of model_dump_json(indent=2)). The session-bank copy returns a dict, which FastMCP already serialises compact (pydantic_core.to_json with no indent), so the two copies now send the same shape. This removes about a fifth of the response. Callers already json.loads this string.

Not changed: what max_tokens counts, and which fields a result carries. Either would change the engine's contract or the payload, and that is your call. For example, a separate budget covering the whole response, or leaving out scores unless asked for, could close the rest of the gap. I'm happy to follow up with either.

Test

TestRecallResponseSize in tests/test_mcp_tools.py:

• test_bank_id_recall_returns_compact_json uses a real RecallResult. It checks that the output parses to the same payload and contains no newline.
• test_recall_docs_say_max_tokens_counts_fact_text_only is parametrized over both copies.

All three fail on the parent commit. With only the docstring fixed, the compact test still fails.

tests/test_mcp_*.py pass (436 on current main). The full api-slim suite (without the hs_llm_* markers): 10,020 passed. The 5 failures and 1 error are in test_fact_extraction_output_ratio.py / test_fact_extraction_analysis.py, which need HINDSIGHT_API_LLM_API_KEY and fail the same way on main. Ruff and ty are unchanged from main. The two pre-existing F841s in test_mcp_tools.py and the 15 ty diagnostics are on main too.

[JayOfTheKeyboard]

Thanks for fixing the docs line I missed, and for the merge.