funes: durable memory layer for coding agents

TL;DR

Hugging Face released funes, a lightweight, locally‑executed memory system that turns coding‑agent session logs into an indexed, searchable dataset, enabling agents such as Claude Code, Codex, pi, and Hermes to recall exact prior turns across machines and models without sending data to a remote service.

One‑command memory integration for existing agents

Key point: Adding funes to an agent requires a single funes add <agent> command, which builds an initial index, injects recall and get tools, and sets up incremental indexing of every completed turn.

curl -fsSL https://huggingface.co/buckets/huggingface/funes/resolve/install.sh | sh
funes add claude   # or codex, pi, hermes
  • The default inference backend has no ML runtime dependency; embeddings and reranking run on the user’s machine.
  • Indexing is incremental: new turns are embedded and added without re‑embedding the entire history.
  • recall returns the original text of a turn together with provenance metadata (agent, timestamp, session, turn) and a get command to open surrounding context.

"With funes added, recall happens inside the conversation. The agent reaches for its memory on its own and names the session behind its answer."

Deterministic pipeline and ranking architecture

Key point: funes normalizes all supported trace formats into a uniform turn‑and‑block representation, then processes them through a deterministic pipeline:

  1. Chunking of each turn.
  2. Embedding with a pinned local model.
  3. Storage in a local Lance append‑only dataset.
  4. Query combines vector similarity and BM25, fuses rankings, reranks with a cross‑encoder, reweights by recency, and attaches neighboring chunks.

This design yields three crucial properties:

  • Unified memory across agents – all supported agents write to the same shape, so recall can span Claude Code, Codex, pi, and Hermes histories.
  • Raw evidence stays intact – no summarization at write time; every result can be traced back to the exact turn that produced it.
  • Local‑by‑default operation – no Hub account or external service is required for indexing, embedding, or reranking.

Memory as a dataset, not a hosted service

Key point: funes treats the memory as a Lance dataset that can be optionally published to a private Hugging Face dataset, enabling seamless portability across machines.

funes add codex acme/funes-memory   # bind to a remote dataset
  • Publishing redacts credentials during indexing; a security scanner (documented in SECURITY.md) removes obvious secrets before upload.
  • Remote memories are cached locally, so subsequent queries run at local speed while the Hub provides ownership, access control, versioning, and distribution.
  • The workflow does not create a separate memory‑as‑a‑service account; the same binary continues to serve both local and remote memories.

ask vs. recall: one‑off queries vs. integrated workflow

Key point: funes ask lets users pose a single question to a memory without installing a persistent agent integration.

funes ask claude "what did we decide about the streaming parser"
# Or against a published memory
funes ask claude "why is funes append‑only" --memory huggingface/funes-memory
  • The command retrieves relevant passages, feeds them to the selected coding agent, and returns a grounded answer that cites its sources.
  • If the retrieved passages do not support an answer, the agent explicitly states the limitation, encouraging re‑phrasing or full integration via funes add.

Cross‑agent continuity without losing context

Key point: Because memories are model‑agnostic datasets, a task started with Claude Code can be continued with Codex (or any supported agent) on a different machine, and the later agent can recall the earlier reasoning.

  • Across machines: Bind each host’s agent to the same remote memory to retain thread continuity.
  • Across teams: New teammates can retrieve months of decisions, dead‑ends, and rationales directly from the shared memory.
  • Open‑source projects: Maintainers can publish a memory alongside a release, creating a searchable, versioned CLAUDE.md that records the full decision‑making trail.

Published memories are discoverable on the Hub via the funes tag, enabling anyone to query public project histories with --memory.

Cost‑effective alternative to session compaction and handoffs

Key point: In the handoff‑vs‑recall benchmark, recall was 8× cheaper than a written handoff on one task and 4× cheaper on another, while preserving raw evidence.

  • Compaction (summarization) often lost critical details, causing failure on one of the two benchmark tasks.
  • Recall returns the original passages, avoiding the need for summarization and reducing token usage.

Weighted tokens per successful task for five channels across two tasks, with recall the shortest bar on both

Open‑source foundation and community involvement

Key point: funes builds on existing open‑source components:

  • Local embedding models (run without external APIs).
  • Lance append‑only datasets for cheap incremental writes.
  • Hugging Face Hub’s dataset caching and deduplication.

The project is fully open source at https://github.com/huggingface/funes. Users are encouraged to open issues for installation problems, missed recalls, or requests for additional agent support.

Bottom line: funes transforms the otherwise static logs of coding agents into an active, searchable memory that works locally, can be shared as a private dataset, and enables seamless cross‑agent, cross‑machine continuity—all with a single command and no external service dependencies.

Sources