funes is an open‑source tool from Hugging Face that converts coding agent session traces into a durable, queryable memory usable across agents and machines. It runs locally: embedding and reranking happen on the user’s machine and indexed data are stored as Lance datasets. Optionally, a memory can be published as a Hugging Face dataset (private by default) so it can follow work across hosts or be shared within a team.
The problem addressed
Developers often work on multiple machines and switch coding agents depending on the task. Each agent session ends up as an archive: past decisions and the reasoning behind them are lost between sessions. Earlier analysis titled “Software Forgets: Agent Traces Are the Memory” argued that agents already produce the record we lose, but raw session logs by themselves are not a practical searchable memory. funes fills that gap by providing indexing, retrieval, ranking, and exact provenance for agent traces so agents can actually use past work while they operate.
How it works, briefly
- Installation: funes is a single binary with no ML runtime dependency by default. Install with: curl -fsSL https://huggingface.co/buckets/huggingface/funes/resolve/install.sh | sh
- Add to an agent, for example: funes add claude (also supports: codex, pi, hermes) The add command builds the first index, gives the agent recall and get tools, and installs automation that indexes each completed turn.
- Indexing is incremental: new runs add new turns rather than re‑embedding the entire history. Older content can be backfilled in bounded steps.
What the memory enables
- recall: when a task touches a past decision, rationale, or finding, the agent can retrieve the original passages. recall returns the original text (not a summary) and names the session behind the answer (agent, timestamp, session, turn). Each hit includes a get command that opens the full turn and surrounding context.
- ask: a read‑only, one‑question command for humans. It reads the local memory by default, e.g.: funes ask claude "what did we decide about the streaming parser" Or pointing to a shared memory: funes ask claude "why is funes append-only" --memory huggingface/funes-memory ask does not install an integration or change the agent’s persistent setup; it returns grounded answers that name their sources.
Implementation and design
- Every supported trace is parsed into a uniform turn‑and‑block shape, chunked, embedded with a pinned local model, and written into a local Lance dataset.
- Queries combine vector and BM25 search, fuse rankings, rerank candidates with a cross‑encoder, reweight by recency, and attach neighboring chunks.
This design yields three core properties:
- One memory across agents: Claude Code, Codex, pi, and Hermes write to the same schema. recall spans their histories and reports which agent produced each hit.
- Raw evidence remains intact: nothing is distilled into a fact at write time; a result always links back to the turn that produced it.
- recall is local by default: no account or Hub repository is required to index; embedding and reranking run locally and the coding agent does the reasoning.
Sharing and multi‑host usage
A memory is treated as a dataset, not a hosted memory service. Bind and publish a memory when you add funes to an agent: funes add codex acme/funes-memory The bind publishes your current memory to the given dataset and keeps it current: funes indexes turns locally and publishes at session boundaries. Running the same command on another machine causes the memory to follow you there. Locally, memory is a Lance dataset; the shared copy is a Hugging Face dataset (private by default).
Credentials are redacted during indexing, and publishing re‑scans chunks to withhold anything that still looks like a secret. The scanner’s behavior is documented in SECURITY.md. When reading a remote memory, funes caches the dataset files locally so warm queries run at local speed. The Hub provides ownership, access control, versioning, and distribution; your memory is not moved into a separate memory service and you are not charged back through an API for access.
Practical benefits and scenarios
- Across machines: bind each agent to one memory and recall history from whichever host you’re using.
- Across a team: a new teammate’s agent can retrieve months of decisions on day one, including dead ends and rationale that never entered a pull request.
- For open‑source projects: a maintainer can publish the sessions behind a release. Think of it as a searchable CLAUDE.md that preserves why the project is the way it is, rather than a page someone must constantly rewrite. Public memories carry a dataset card and the funes tag on the Hub, making them discoverable.
Cost comparison: handoff vs. recall vs. compaction
Long investigations can bloat sessions until carrying the full context is more costly than continuing work. The authors measured three approaches on two tasks that require prior session knowledge and cannot be reconstructed from scratch:
- Compaction (summarization) by agents sometimes fails: on one task it arrived, on the other it did not, and where it failed, important findings had been flattened.
- recall returns the passages themselves, avoiding loss through summarization.
- In cost, recall was the cheapest on both tasks: it was 8× cheaper than a written handoff on one task and 4× cheaper on the other.
Where to find it and how to contribute
The funes source code is available at github.com/huggingface/funes. The project builds on open components: open‑source embedding models that can run locally, Lance append‑only datasets, and the Hub’s dataset caching and deduplication. The primary engineering work is assembling these into a memory an agent can use. Open issues can be filed for install problems, missed recalls, or requests for additional agent support.
Conclusion
funes provides a practical, local memory layer that converts agent session traces into a searchable, provenance‑preserving memory. It enables agents and teams to continue previous lines of reasoning without restarting from zero, and offers a path to safely publish and share working memory via the Hugging Face Hub.
