Detailed Analysis
A developer working with Claude Code encountered a scaling problem common to anyone who leans on markdown files as persistent memory for AI coding assistants: what starts as a single CLAUDE.md file eventually sprawls into hundreds of notes, and at that point the two conventional retrieval strategies both break down. Having Claude re-read the whole folder at session start burns through the context window fast, while grep-based search misses nuance entirely — it can't distinguish a decision record from a task note from prose that happens to contain a matching keyword. The developer's response was to build IWE, an open-source Rust CLI that treats the markdown folder as a queryable knowledge graph rather than a flat pile of text, using frontmatter as schema, file paths as primary keys, and inter-note links as joins. This lets Claude issue structured queries — e.g., "accepted decisions that reference the payments service" — instead of re-reading or blindly grepping.
The significance here lies in the middle path IWE stakes out between two extremes that have become default answers to the "AI memory" problem. On one end is the brute-force approach of just re-feeding documents into context, which doesn't scale and wastes tokens. On the other is the increasingly popular move to vector databases and embeddings-based memory MCPs, which solve the scaling problem but introduce a new one: the memory becomes opaque. You can't open a vector index in a text editor, diff it in git, or eyeball what changed after an agent session. IWE's pitch is that most of what an agent needs from personal or project notes is actually structured data — status fields, references, categories — not semantic similarity, and that BM25 full-text search plus explicit query filters can cover that need while keeping everything as plain, git-diffable markdown.
Several design choices reflect a deliberate attempt to fit how coding agents like Claude Code actually operate rather than how a typical database client would be used. Shipping as a single compiled binary means Claude can just invoke it via bash without any special integration, though an MCP server is offered for those who prefer that route. Rather than pasting a query-language manual into the system prompt, the tool exposes a self-documenting `docs query` command, so the agent teaches itself the syntax on demand — a small but notable pattern for reducing prompt bloat in agentic tooling. Token-budgeted reads (`--max-tokens`) and guarded writes (`--expect 1`, schema validation) directly target failure modes specific to long-running agent sessions: runaway context consumption and silent format drift from repeated automated edits.
More broadly, this fits into a growing wave of tooling built specifically around agentic coding assistants' operational quirks rather than general-purpose developer needs — memory systems, context management utilities, and guardrails designed with an LLM as the primary "user" of the interface. As Claude Code and similar agents get used for longer-horizon, stateful work, the problem of giving them durable, inspectable, cheaply-queryable memory becomes a recurring pain point that the ecosystem is still experimenting with solutions for. The author is explicit that this isn't a semantic-search replacement — embeddings still win for fuzzy "find something like this" queries — and that the tool is overkill for anyone still comfortable with a single CLAUDE.md. But the underlying observation, that structured lookup often beats both raw re-reading and heavyweight vector search for agent memory at moderate scale, is a useful data point in the broader conversation about how to architect memory for tools like Claude Code as usage matures beyond toy projects.
Read original article →