Funes Agent Memory Tested: Codex Recall, Stale Memory, and Local Privacy Boundaries

Short answer: Funes is interesting because it does not try to make Claude Code or Codex “remember everything” by adding a larger prompt. It turns the session traces those agents already produced into a searchable, provenance-aware, local-first memory layer. A later agent can retrieve why a parser was rejected, which workaround failed, or which test changed a decision without manually reopening weeks of chat history.

This page now includes a complete local recall benchmark rather than only vendor documentation. On September 9, XBSTACK ran Funes 1.3.0+dev against a small curated local memory: all five known-target queries ranked the expected session first, producing Hit@1=5/5 and Hit@5=5/5. Aggregate query latency was about 2.47–5.43 seconds with a 3.14-second mean. Direct access to huggingface.co remained unreliable, so the embedding/reranker model files were obtained through a mirror and cached locally; that is an environment workaround, not a Funes requirement.

The failure controls matter more than the perfect hit rate. Three unrelated queries still returned candidates, although the top scores fell to 0.001, 0.001 and 0.000. In a synthetic stale/conflict control, the September 8 corrected value ranked first but the September 1 value explicitly marked obsolete still ranked second. Funes can retrieve relevant history without automatically deciding whether that history is still valid. A production consumer therefore needs abstention thresholds, conflict handling, effective-date/version metadata and provenance policy. This Mac still has no Claude Code session, so Claude Code→Codex cross-agent recall remains a documented capability rather than an XBSTACK-tested result.

What problem is Funes actually trying to solve?

Coding agents are becoming better at acting, but a fresh session can still behave like a new engineer joining the repository. The important information from prior work is not only the final code. It is the reason a path was rejected, which version caused an error, why a test exists, and which workaround was meant to be temporary.

Those details may never enter a Git diff, README or issue. Teams usually compensate by maintaining CLAUDE.md/AGENTS.md, compacting long conversations or writing handoffs. All three are useful, but each loses something: documentation requires maintenance, compaction summarizes, and a handoff preserves only what the writer believed mattered at that moment.

Funes takes a different position: the session trace itself is valuable engineering history. Index it first, then retrieve the original evidence when the next agent needs it.

Official overview: https://huggingface.co/blog/funes

How does Funes integrate with Claude Code and Codex?

Hugging Face currently documents a single-binary install:

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

Then add the integration for a supported coding agent:

funes add claude
funes add codex
funes add pi
funes add hermes

The official description says add performs an initial index, installs recall and get tools, and configures incremental indexing so new turns can be appended rather than rebuilding the full history.

The official install.sh itself did not complete on this Mac. On September 7, requests to huggingface.co still timed out on port 443. XBSTACK therefore cloned the GitHub repository, installed Rust 1.98.1 with rustup, used an isolated temporary protobuf toolchain, and completed cargo build --release, producing a working funes 1.3.0+dev binary. That verifies source build and CLI execution on this machine; it does not claim the official installer works through the current network path.

To make the benchmark numbers interpretable, the final test environment was fixed to macOS arm64, Funes 1.3.0+dev, Rust 1.98.1, protoc 28.3, BAAI/bge-small-en-v1.5 as the embedder, BAAI/bge-reranker-base as the reranker, and trufflehog 3.97.4 as the secret scanner. The final test set contained five real Codex sessions plus two synthetic stale/conflict sessions. The real sessions contributed 1,044 indexed chunks; the stale/conflict controls added four chunks.

Direct access to huggingface.co still timed out in this environment, so both model files were downloaded through hf-mirror.com into the local Hugging Face cache. That is a network workaround for this machine, not a runtime requirement of Funes.

The observed local evidence looks like this:

Local check	Result
funes index --harness codex	Built a local Lance memory; the early verification indexed 3 sessions, and the final benchmark expanded to 5 real Codex sessions plus 2 synthetic control sessions
funes sessions	Listed real Codex sessions with dates, turn counts and session IDs
funes scan <Chinese term meaning model> <session>	Returned 52 literal hits from one real Codex session and emitted get ranges
funes get ... --from 1828 --to 1832	Reopened the original turn containing the “Manifest → download → verify → install → Runtime Ready” decision
funes sketch <session>	Returned 8 distinctive session passages with provenance
funes scrub with trufflehog 3.97.4	Scanned 5,148 blocks and rewrote 8,473 rows; 0 secrets were directly redacted and 13 rows across 4 blocks were dropped because they could not be safely redacted
funes recall	Complete: five known-target queries produced Hit@1=5/5 and Hit@5=5/5; aggregate latency was about 2.47–5.43s, mean 3.14s
Unrelated-query negative controls	Three unrelated queries still returned candidates, with top scores 0.001 / 0.001 / 0.000; this test path did not auto-abstain
Stale/conflict control	Corrected memory ranked #1; explicitly obsolete memory still ranked #2, so conflict/validity governance remains an application concern
Claude Code → Codex cross-agent recall	Incomplete: there is no Claude Code session on this machine to index

The sections below therefore continue to separate vendor-documented design from behavior independently verified by XBSTACK.

Why is this more than another vector database?

The retrieval pipeline described by Hugging Face is hybrid:

agent traces
  -> parse / normalize
  -> turn + block chunks
  -> local embeddings
  -> vector search + BM25
  -> rank fusion
  -> cross-encoder rerank
  -> recency reweight
  -> neighboring chunks
  -> result + provenance

Coding history contains both exact symbols and fuzzy intent. A query such as “why did we stop using the streaming parser?” may depend on a literal parser name as well as a semantically related performance investigation. BM25 helps exact-term retrieval, embeddings cover semantic similarity, and a reranker can reorder the combined candidates.

The other important design choice is provenance. Funes says recall returns raw text rather than an ingestion-time fact summary, along with agent, timestamp, session and turn metadata. get can then open the full turn and neighboring context.

That gives this page a different search intent from XBSTACK’s existing AI Agent Memory System architecture page. The older page asks how a production memory system should be layered; this one asks whether a specific coding-agent trace-memory implementation can recover real engineering decisions across agents.

Local memory vs a Hugging Face Dataset

Funes stores local memory as a Lance dataset. The official blog says embeddings and reranking run on the user’s machine and local recall does not require a Hugging Face account or remote memory service.

For cross-machine sharing, a user can bind a memory to their own Hugging Face Dataset, for example:

funes add codex acme/funes-memory

Hugging Face says shared memory datasets are private by default. Session updates can be synchronized, while the remote data is also cached locally for normal querying.

This has an attractive ownership property: the memory can remain in a dataset the user controls instead of requiring a separate memory SaaS. But “private by default” is not the same as “safe to upload every coding session.” Traces can contain customer names, internal URLs, pre-release product details, credential fragments and debug output. Data classification still matters.

Does secret redaction solve the privacy problem?

No single scanner can be treated as a complete privacy guarantee.

Hugging Face says credentials are redacted during indexing and that a second publish-time scan blocks chunks that still resemble secrets. The project points readers to SECURITY.md for scanner behavior and limitations.

That should be understood as a defensive layer against accidental credential exposure, not proof that every sensitive business fact will be detected. A project codename, customer name, internal schema or confidential architectural decision may not resemble an API key at all.

This article verifies that the scrub and trufflehog scanning path actually runs, but it does not amount to a complete enterprise privacy assessment. A claim such as “safe to sync company sessions” would require an additional synthetic privacy corpus containing fake API keys, fake emails, internal-looking paths, project codenames and ordinary sensitive prose, followed by inspection of local indexing, redaction and remote publish output. The evidence here supports “secret scanning works,” not “all sensitive data is automatically handled.”

recall, get and ask

The three interfaces serve different jobs:

• recall: retrieve relevant historical traces while the agent is working;
• get: open a complete turn and surrounding context from a recall result;
• ask: run a read-only question against a memory from the terminal without installing a persistent agent integration.

Hugging Face’s examples include:

funes ask claude "what did we decide about the streaming parser"

and querying a shared memory:

funes ask claude "why is funes append-only" --memory huggingface/funes-memory

This makes Funes potentially useful as an auditable engineering-history search layer even when an agent is not automatically consuming the memory.

Funes vs compaction, handoff and project documentation

They solve overlapping but different problems:

Method	Strength	Main cost/risk	Best fit
Project docs	Explicit, reviewable, versioned	Manual maintenance	Stable rules and architecture contracts
Compaction	Keeps a long active session moving	Summary can remove details	Same long-running task
Handoff	Explicit current-state transfer	Preserves selected information	Agent/person task transfer
Funes recall	Original trace, cross-session/agent retrieval	Retrieval noise, privacy, stale facts	Long-term decision/history recall

Hugging Face includes its own handoff-vs-recall benchmark and reports lower costs for recall on the presented tasks. That remains a project benchmark, not an XBSTACK result; this article does not reuse those cost numbers as if they were independently reproduced.

How I tested Funes locally

Instead of collecting a dozen shallow demos, I split the verification into three groups: can it find a known decision, does it know when not to answer, and what happens when an old memory conflicts with a newer one?

1. Known-target Codex recall

The local set contained five real Codex sessions with 1,044 indexed real-session chunks. Each query had a manually known target session and covered a different intent: redirect behavior, WebView image preview, analytics flags, signing configuration and provisioning configuration. The specific project names are not necessary to interpret the retrieval result, so they are omitted here.

All five queries ranked the expected session first: Hit@1=5/5 and Hit@5=5/5. The 100% result applies only to this small curated local set; it should not be generalized to arbitrary projects or languages.

2. Unrelated queries and abstention

I then issued three queries deliberately unrelated to the indexed memory. Funes still returned ranked candidates, but the top scores were only 0.001, 0.001 and 0.000.

That means “a result was returned” is not equivalent to “the memory is relevant.” An agent integration needs an application-level abstention/no-answer policy based on score distribution or another confidence rule, otherwise low-quality candidates can still be passed downstream.

3. Stale and conflicting memory

The synthetic control used two contradictory Project Apollo deployment records. The September 1 record said us-east-1; the September 8 record changed the production region to ap-southeast-1 and explicitly marked the old value obsolete.

For the query about the current production region, the corrected record ranked #1, but the obsolete record still ranked #2. Recency weighting promoted the new fact without removing the old evidence. The dangerous failure mode for long-term memory is not only forgetting; it is retrieving something that used to be correct and is no longer current.

The local scrub path was also exercised with trufflehog 3.97.4: 5,148 blocks were scanned, 8,473 rows rewritten, and 13 rows across four blocks were dropped because they could not be safely redacted. That verifies the scanning path, not universal detection of every kind of sensitive business data.

The three boundaries I care about most

First, retrieval noise. Raw traces are richer than curated docs, but they also contain abandoned paths, repeated output and temporary logs.

Second, time validity. Provenance makes historical evidence auditable, but old evidence is not the same thing as current truth. A version upgrade can invalidate a once-correct workaround.

Third, permission and data boundaries. A personal open-source repository and a corporate private codebase have very different tolerances for synchronizing coding history to a private remote dataset.

A serious memory system therefore needs more than recall(query). It needs source, time, version, confidence/validity cues and a way to return to the original trace. Funes already exposes some provenance; the final production judgment depends on how well stale knowledge can be governed.

Current decision: where Funes fits today

Based on this local test, I would treat Funes as a promising coding-history retrieval layer, not as an authoritative database of current truth.

It already demonstrates two useful properties: real Codex traces can be indexed and retrieved effectively through hybrid search, and provenance lets a developer return to the original session/turn instead of trusting a compressed memory summary.

But production use still needs policy above retrieval. Low-relevance queries can return candidates, and obsolete evidence can remain visible after a corrected memory is indexed. At minimum, an integration needs abstention thresholds, conflict detection, effective-date/version metadata, and a distinction between historical evidence and current facts.

Hugging Face documents Claude Code, Codex, pi and Hermes support, but this Mac has no Claude Code session. Claude Code→Codex cross-agent memory therefore remains a documented capability, not an XBSTACK-tested claim in this article. A future cross-agent test should be treated as a separate experiment rather than blended into this completed Codex benchmark.

When is Funes worth using?

Funes becomes more compelling when a repository lives for months or years and multiple coding agents repeatedly enter the same project. Historical debugging context, failed alternatives, migration rationale and one-off technical decisions do not all need to be manually promoted into permanent documentation for later agents to rediscover them.

For a small project with few sessions, or for a codebase where all durable rules are already captured in CLAUDE.md, AGENTS.md, ADRs and explicit configuration, an additional trace-memory layer may add more operational cost than value. The same caution applies to sensitive company code: “private by default” is not a substitute for data classification, retention and synchronization policy.

Architecturally, I would use Funes as a second memory layer. Stable rules remain in project documentation and explicit configuration; Funes retrieves what happened and why; anything that can change current execution should still pass through version, time and policy checks before being treated as current truth. That is safer than allowing an agent to consume every recalled fragment as authoritative state.

FAQ

What is Funes?

Funes is an open-source coding-agent memory tool from Hugging Face. It reads session traces from agents such as Claude Code and Codex, indexes them locally and exposes recall/get so later sessions can recover original working history.

Does Funes upload coding sessions by default?

Hugging Face describes it as local-first. Local memory does not require a Hub account. Remote sharing occurs only after a user binds a Hugging Face Dataset, which is private by default. Sensitive-data review is still the user’s responsibility.

Is Funes just a vector database?

It stores local memory in Lance, but the documented retrieval path combines vector search, BM25, rank fusion, cross-encoder reranking, recency weighting and neighboring chunks.

Can Funes share memory between Claude Code and Codex?

Hugging Face explicitly describes multi-agent trace ingestion and recall. XBSTACK has independently verified local Codex recall, unrelated-query behavior, stale/conflict retrieval and scrub, but not Claude Code→Codex recall on this machine.

Does Funes replace CLAUDE.md or AGENTS.md?

No. Project docs are better for durable explicit rules and contracts. Funes is better understood as a retrieval layer for historical traces, investigations, failed paths and decision rationale.

Official sources

• Hugging Face: Give Your Coding Agents a Memory You Own
• GitHub: huggingface/funes
• Funes handoff-vs-recall benchmark dataset
• Hugging Face public Funes memory dataset

Continue reading

• AI Agent Memory System
• AI Agent Memory Architecture
• LangGraph memory and checkpointing in production
• Production AI agent governance

Topic path / AI Agents

Continue from one agent pattern to the complete production system

The AI Agent hub organizes architecture, memory, tool use, evaluation, security, deployment and multi-agent coordination into a single learning path.

Open AI Agent hub → Review the architecture guide Subscribe