Add names-only format to search_beliefs for 6.5x token savings

Open Beginner friendly
#1 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
88/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
ai, tooling

Research direction

Start in tools.py at _search_beliefs() and inspect the BELIEF_TOOLS schema for the existing search_beliefs definition. Update the documented system prompts in EDITOR_SYSTEM_PREFIX and PROMPT_SYSTEM_PREFIX, then verify that full remains the default and names-only returns only the truth value and belief ID.

Written by the indexing model from the issue text.

Description

Summary

Add a format parameter to search_beliefs supporting names-only mode. Belief names carry 90%+ of functional value at 11% of token cost (E_coord evidence). For a 64K context window, this is a significant budget savings.

Current behavior

search_beliefs returns [IN] belief-id: first 120 chars of text -- approximately 130 tokens per result. With 20 results, that's ~2,600 tokens (4% of a 64K context window).

Proposed change

Add format parameter to search_beliefs:

Format Output Tokens per 20 results
full (current default) [IN] belief-id: text[:120] ~2,600
names-only [IN] belief-id ~400

Names-only uses 6.5x fewer tokens for the same search. The bee can search more broadly and then use show_belief for the specific beliefs it needs full text on.

Why this matters for worker-bee specifically

Worker-bee runs small models (Qwen 27B) on small context windows (64K). Every token matters. Names-only search lets the bee:

  • See 6x more results per search (orientation)
  • Spend context budget on investigation rather than belief text
  • Use show_belief selectively for the 2-3 beliefs it actually needs
Where names-only works well for small models
  • The bee's own brain beliefs -- the bee chose the names, so they're maximally informative to it
  • Well-known programming concepts -- atomic-write-requires-fsync, redis-uses-pubsub. A 27B code model has these in its parameters
  • Orientation searches -- "what does this EEM know about X?" Names give the landscape cheaply
Where names-only needs follow-up for small models
  • Codebase-specific jargon -- keeper-sprinkling-prevents-tool-pair-split needs a show_belief call for a 27B model that hasn't seen the source
  • A 27B model has less parametric knowledge than Opus/Sonnet, so more names will need description follow-up. But even with 50% needing show_belief, total tokens are still lower than loading all descriptions upfront

System prompt update

Add to EDITOR_SYSTEM_PREFIX / PROMPT_SYSTEM_PREFIX:

When searching beliefs, use format="names-only" for broad orientation.
Use show_belief for full text on specific beliefs you need to reason about.

Evidence

  • E_coord: names-only Haiku +55pp, full beliefs all-at-once -5.8pp
  • 0.615 median cosine similarity between name and description embeddings (same neighborhood)
  • 900x compression ratio for names-only vs source documents
  • See: beliefs-pi ftl-reasons#265 for the corresponding reasons CLI changes

Implementation

Minimal change to _search_beliefs() in tools.py:

def _search_beliefs(query, limit=20, format="full"):
    ...
    for r in all_results:
        if format == "names-only":
            lines.append(f"[{r.get('truth_value', '?')}] {r['id']}")
        else:
            lines.append(f"[{r.get('truth_value', '?')}] {r['id']}: {r.get('text', '')[:120]}")

And add format to the tool schema in BELIEF_TOOLS.

Dominant language
Python
Stars
0
Forks
0
PR merge metrics
No merged PRs in 30d

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.