funes: persistent memory for code agents that runs locally and you own it

Every code agent meets projects like a stranger. Last Tuesday's conversation disappears when the session closes, and the next agent, on another machine, starts from scratch. That's the pain that funes, announced by Hugging Face on the official blog, tries to solve: a durable memory layer for agents that runs locally and turns the sessions already on your machine into something the next agent can query.

The post, written by David Corvoysier, starts from a premise that matters to builders: session traces (the codebase searches, the attempts, the errors, the course changes) are already a dense record not just of what changed, but of why. The problem is that this record stays locked in logs. As the text puts it, "you can't grep your way to 'why did we abandon the streaming parser?' across ten thousand turns." To actually become memory, traces need indexing, retrieval, ranking, and exact provenance. That's the pipeline funes delivers.

What changes for builders

The core proposal, and the reason the editor picked up this story, is data ownership. funes isn't a memory service you rent back through an API. Local memory is a Lance dataset on your machine; shared memory is a Hugging Face Hub dataset, private by default, that belongs to you. In the post's words: "your memory doesn't become an account in a separate memory service, and you don't rent it back through an API".

In practice this means embedding and reranking run locally. The default binary has no ML runtime dependency, and no hosted model processes your sessions to index them. The reasoning is still done by your code agent. For the Brazilian developer, this has two concrete effects: sensitive context (credentials, proprietary logic) doesn't need to leave the machine to be indexed, and the recurring cost of an external service disappears.

How it works under the hood

Installation is a single binary:

curl -fsSL https://huggingface.co/buckets/huggingface/funes/resolve/install.sh | sh

Then, you add it to an agent:

funes add claude # or: codex, pi, hermes

This single command builds the first index, gives the agent the recall and get tools, and installs the automation that indexes every completed turn. Indexing is incremental: new runs add new turns instead of reprocessing the whole history, and older content is backfilled in bounded steps.

The pipeline is deterministic and shared across all supported agents. It parses each trace in the same turn-and-block format, chunks it, generates embeddings with a pinned local model, and writes to the local Lance dataset. A query combines vector search with BM25, fuses the two rankings, reranks the candidates with a cross-encoder, reweighs by recency, and attaches neighboring chunks.

This design yields three properties worth highlighting:

| Property | What it means in practice | |---|---| | One memory across agents | Claude Code, Codex, pi, and Hermes write in the same format; recall cross-references the histories and each result states which agent produced it | | Raw evidence stays intact | Nothing is distilled into a "fact" at write time; every result leads back to the original turn | | Local by default | Requires no account or Hub repository to work |

An important detail for security: recall returns the original text, not a summary, and shows exactly where it came from (agent, timestamp, session, and turn). Every result includes a get command that opens the full turn with surrounding context.

When memory travels

To make memory follow the work across machines or people, just link a dataset when adding the agent:

funes add codex acme/funes-memory

The link publishes the current memory to that dataset and keeps it updated, indexing each turn locally and publishing at session boundaries. Running the same command on another machine brings the memory along. When an agent reads a remote memory, funes caches the files locally, so hot queries return at local speed.

Here's a caveat the developer needs to weigh: publishing sessions to the Hub means exposing the raw reasoning. funes redacts credentials during indexing and, before anything is uploaded, re-scans every chunk, holding back anything that still looks like a secret. The scanner's scope (what it covers and what it doesn't) is documented in SECURITY.md. It's worth reading before making a memory public, because "looks like a secret" is a heuristic, not a guarantee.

The use case that usually goes unnoticed: long-session cost

A long investigation swells the session until loading the context for each turn costs more than doing the work itself. The usual ways out are letting the agent compact and continue, or writing a handoff and starting fresh. funes proposes a third: retrieving on demand.

Hugging Face measured all three in the handoff-vs-recall benchmark, using two tasks whose answers can't be reconstructed without prior knowledge of the session. The reported numbers:

• Compaction was the only one with a split result: it reached the answer on one task and missed on the other, because the summary flattened the findings that mattered.
• Recall was the cheapest of the three on both tasks: 8x cheaper than a written handoff on one, and 4x on the other.

Recall's structural advantage is that it returns the passages themselves, so a finding doesn't need to survive summarization to remain available. One caveat is worth noting: these numbers come from Hugging Face's own benchmark, with only two tasks. It's evidence in favor, not definitive proof, and behavior on large, noisy codebases is still an open question.

Where it's not worth it

funes isn't a silver bullet. If the work happens on a single machine with short sessions, the gain over the agent's own default compaction is marginal. Publishing memory for a team or an open source project is where it shines ("a searchable CLAUDE.md that keeps the history of why the project is the way it is," the post says), but that requires serious security governance over what goes up to the Hub. And there's a dependency on the quality of local embeddings: a retrieval miss isn't disguised, the agent says the passages don't support the answer, which is honest, but still leaves you without the information.

"Thinking is forgetting differences, generalizing, abstracting."

>

-- Jorge Luis Borges, Funes, the Memorious

funes is open source and relies on open pieces: embedding models good enough to run locally, Lance's append-only datasets with cheap incremental writes, and the Hub's caching and content dedup. The work, as the announcement itself admits, was fitting these pieces into something an agent can actually use. For those building with agents in Brazil, it's the first serious proposal for persistent memory that doesn't ask you to hand your sessions over to a third party.