Two problems I observed during agent mcp usage of iwe

[LumenYoung]

1. do we have partial update tool in iwe for agent to update the document. currently for a long note, it has always to rewrite the whole document to update, which is wasteful.
2. can we confine how much text we return each time we use find? Because sometimes when find term is vague and returns huge amount of text and suddenly blown up the whole context size. Can we limit for example to only give how many notes and how much text from each?

I think currently the iwe find as the only way to find content is a bit weak. But maybe there is a better way to do it and I am happy to hear any suggestion.

[VectorPeak]

Both points make sense.

For partial updates: iwe_update currently supports replacing the full document body, plus frontmatter $set / $unset style updates. There is not currently a body-level patch tool for “replace this section / insert after this heading / update this block only”. For long notes, the intended workaround today is to split stable sections into smaller referenced notes using iwe_extract, then update the smaller note. That avoids rewriting a very large document, but it is not the same as a true partial update API.

A partial body update tool would be a reasonable addition. The safest shape would probably be something explicit and structural, for example key + section path/heading + operation, rather than arbitrary byte offsets, because IWE already understands markdown structure. Something like “replace section”, “append to section”, or “insert before/after section” would also be easier for agents to use correctly.

For find: limiting the number of notes is already supported via limit / --limit. The better agent workflow is usually:

iwe find "term" --limit 5 -f keys
iwe retrieve -k selected-note -d 0 -c 0

That said, limiting “how much text per result” is a separate issue. If find is returning enough preview/context to blow up the model context, then adding something like snippet_limit, max_chars_per_result, or content=false/metadata-only behavior for MCP responses would be useful. find should stay a discovery tool; retrieve should be the tool that intentionally pulls document content, ideally after the agent has narrowed the candidate set.

---

If my answer solved your problem, you can click answered the question. I'm really here to help, and along the way I'm also collecting Galaxy Brain badges haha 😆

[gimalay]

Hey @VectorPeak, thanks for the great answer! Much appreciated.

[gimalay]

Hey @LumenYoung ! Thanks for the feedback!

Both items are very reasonable

1. Partial update exists for metadata only, there is a way for targeted updates for the frontmatter fields but not for the content. I want to add this capability soon.
2. I'll check how we can add more controls around find results. The main use case for find is discovery of the documents (searching) while the content retrieval can be done using retrieve tool/cli. Let me double-check that this delineation is clear and find doesn't return text by default.

One more thing I want to add is the ability to return only the "contents" of the documents so agent can pick into the document and add only the section headers to the context instead of the entirety of the document.

[gimalay]

@LumenYoung I added token limits to better control the output size as well as compact for of find command in Markdown format (enabled by default). Here is the PR: #336

Please let me know if this address the limits issues for you.

[LumenYoung]

Hi @gimalay thanks again for the prompt reply.

I got time test it today and here is what I think would be nice:

1. Should we do this on invocation only or we should have that as a server side behavior (default): because we are talking about potential accidental overflow of content, to ensure that agent never accidentally overflow its context, a better way to ensure this is to make the max_token_limit also a default value on the mcp server side. this makes it not the agent chooce everytime how much it retrieves, rather when large chunk of article accidentally got retrieved, it is only showing some of them.
2. maybe make the amount of token available as the meta data retrieved so that the agent know the size.

Some other ideas I have:

1. context retrieved for find, maybe instead of give back the content, we can have a server side default that whenever a match is found, we can show in the return of the find, retrieve_segment_token_budget of context, we can have some default amount of segments to return and also default to make it non overlapping.

The overall idea is that when find matches some keyword, both full content or meta data only can be something incomplete or an overkill, a good tradeoff inbetween would be nice to have so agent knows what is matched here, without exploding its context.

2. retrieve tool to able to retrieve line number range or section (which I see you already mentioned): The reason I was starting this conversation is partially due to the fact that I have added some ingested paper content (in markdown) into the iwe knowledge base and sometimes such huge body of content is causing the context explosion.

But I still think high value content like paper that are long still should be considered a valid possible content. But for the retrieve, we need to be smart about long, structured content like this.

One idea is that we return the ToC of such long contents when find, or retrieve we give agent prior the retrieve (which we can assume find is invoked, the total number of token and number of lines of this node and content), this way the agent can try to retrieve only the first 100 lines or first 2000 tokens for overview. useful retrieve mode I can think of:

1. retrieve via section: markdown section that are relevant. Agent would know how to do this if find returns the ToC.
2. retrieve via line number range: agent can know this if the line number (together with the section) can be provided by find.
3. retrieve via a token budget: this can be combined with section start or line number to retrieve content.

Overall I think the current retrieve tool and find tool are too simple. I am happy to help implement some ideas I mentioned if you were interested but don't want to do it. But overall I think there are plenty of things we can do that doesn't involve complicated embedding but also able to provide agent better context to work on the knowledge base.

[gimalay]

Makes sense, there is a huge room for improvements. I want to create a benchmark to measure how efficient iwe works as an agent memory/context provider. One of the measurements can be the handling of a long content (which is a valid use-case).

With the benchmark we can measure current performance on a set of scenarios, implement the improvements and see how the change affects the benchmarks and continue with iterative improvements (avoiding degradations on the way).

I would love to get your input on the scenarios we want to optimize for.

[gimalay]

This change makes find much more useful for the agents, it adds BM25 search (was fuzzy before) and it's searching agains the full document text not the titles only. #338 (still work in progress, I'm testing different options)

[gimalay]

Hey @LumenYoung here is the benchmark details and the story behind it. I added quite a lot of tools to iwe as part of this journey. Including fully text search, structured edits, and document schema validation.

https://iwe.md/blog/the-benchmark-that-built-the-tools/

[LumenYoung]

Overall thanks for the very fast response, we can continue our discussion here if you were interested, but we can also close this because you really helped me solving this issue. Thanks @gimalay!

[gimalay]

No problem, let's keep it open.