<div align="center"> <img src="assets/folklore-logo.svg" alt="Folklore" width="120" height="120" />

Folklore

A torrent swarm for agent reasoning.

Every peer shares the inference it already paid for, so your agent starts from what the swarm has worked out — not from zero. Like BitTorrent, but the payload is reasoning: debug traces, papers read, dead-ends ruled out. The more agents join, the less anyone re-derives. Local-first and useful alone on day one; compounding the moment a second node appears.

Site · Manifesto · Spec · RFC · Roadmap · npm

<br/> <img src="assets/folklore-desktop.gif" alt="One session, two directions: a question resolves from @sam-rs's tree in 412ms via the notch island, then @tia-async pulls your trace back — reputation ticking live in the menubar client" width="920" />

_{<b>One session, two directions.</b> You ask — the answer is pulled from <code>@sam-rs</code>'s tree in <b>412ms, 0 web calls</b>. Moments later the flow reverses — <code>@tia-async</code> pulls <i>your</i> trace, reputation ticking live in the menubar client. Like torrents, but the payload is reasoning. <a href="examples/desktop-demo/">Reproduce it →</a>}

</div>

Web-search fallback rate, in simulator: 17% → 1% over 2,000 steps. Once anyone resolves a question, no one — you on Thursday, or any peer ever — pays for it again. § Proof

---

The problem

AI agents reason from zero, every single time. The same paper gets read again. The same dead-ends get walked again. The same conclusion gets re-derived — and re-billed — a thousand times across a thousand sessions.

You don't only pay Google. You pay OpenAI, Anthropic, and every paid endpoint, per token, to re-run inference over data someone already ground out yesterday. The work was done. The tokens were spent. Nobody kept the answer where the next agent could find it.

Memory tools exist — mem0, Letta, LangChain-style RAG — but they are single-user silos. They remember your chats. They don't gate the web, they don't carry provenance, and they certainly don't let another peer's hard-won debugging trace — the LLM inference they already paid for — become your starting point.

What Folklore is

A graph of your agent's reasoning that lives on your machine, answers before the web, and federates peer-to-peer.

Two bets, in order:

1. It works alone. Day one, zero peers, it already pays off — your own research, debugging, and grounded conclusions are cached and reused. You never start from zero again.
2. It compounds. Every peer running it works for the next: each one's past LLM inference — the reasoning already paid for in tokens — becomes your starting point, and yours becomes theirs. No teammate or org boundary; the whole network shares resolved inference so nobody re-spends tokens on an answer someone already ground out. The commons gets deeper the more peers draw from it.

Folklore is the name for knowledge that gets passed on — story to story, peer to peer — instead of relearned from scratch.

---

Day one: alone

No network required. Folklore sits between your agent and the web. Every research-shaped call — WebSearch, WebFetch, an arXiv pull, a fresh Read — is checked against your local graph first. If your graph already holds a confident answer, the call is satisfied from memory in milliseconds. If not, the call proceeds, and the result is auto-saved, signed by you, so the next time costs nothing.

This alone clears the bar that kills most memory projects: it is useful to one person, immediately.

folklore ask "how does mxbai-rerank compare to cross-encoder on long contexts?"
# → answered from your own graph if you've researched it; otherwise fetched + saved for next time

Retrieval quality is benchmarked, not asserted: 0.7522 NDCG@10 on full BEIR SciFact, CPU-only, 11 ms median — ahead of standard published BEIR SciFact retrievers (E5-base 0.737, E5-large 0.723, SPLADE 0.699, ColBERT 0.671, BM25 0.665); only a 3B GPU reranker (InRanker, 0.783) scores higher. No LLM grading an LLM.

Day N: together

Add a peer and your graphs become queryable to each other over libp2p. Now the first hop isn't even your graph — it's the question "what does the network already know about this?" Only when nobody holds the answer does anyone pay the web.

Every record carries a provenance chain: signed by its curator's cryptographic identity and verified GitHub handle, timestamped, traceable to the sources it grounded on. Not anonymous Stack-Overflow-grade trust — attributable, named, auditable knowledge.

The result, measured in simulation: web fallback collapses from 17% to 1% as the network warms.

<div align="center"> <img src="assets/live-feed-demo.gif" alt="folklore live: a real-time feed of peers pulling traces from your tree — @sam-rs pulled tokio-rc-send-across-await, @tia-async pulled axum-extractor-order, @leo-k pulled sqlx-offline-prepare, each from your tree just now" width="820" />

_{Run <code>folklore live</code> and watch it happen: every line is a real fetch off your running node — someone else's agent reusing what yours already worked out. <a href="examples/live-feed/">Reproduce it →</a>}

</div>

---

Philosophy

Folklore is a bet about how intelligence should be organized, not just a cache. The long version is the Manifesto; the short version:

Reasoning is labor. Every conclusion an agent reaches was paid for in tokens and electricity. An answer that dies with its context window is labor thrown into the sea — and every re-derivation of it is a tax, billed by the same few companies, for reasoning the world already owns.

Shared memory shrinks the model. The industry's answer to every gap is a bigger model — more parameters, more inference, more dependence on the center. There is another axis: remember more, infer less. An agent that starts from the network's resolved reasoning needs fewer tokens to reach further. Shared memory is the road to smaller, local, decentralized models — intelligence at the edge, not rented from a landlord.

No big brother in the loop. When one company hosts the memory, ranks the answers, and meters the reasoning, you are a tenant. Folklore has no landlord: your graph lives on your disk, your peers are chosen by you, every record is signed by a named hand instead of laundered through a platform. Local-first is sovereignty — if every peer but you vanished tonight, you'd lose nothing you made.

The commons compounds. A torrent gets healthier with every seeder; so does this. Every question resolved anywhere becomes a question nobody pays for again. Serving the network and serving yourself are the same motion.

---

Where it fits

Folklore is not a competitor to MCP or A2A. It's the missing third layer.

| Layer | Standard | Question it answers | |---|---|---| | Tools | MCP | How does an agent call things? | | Communication | A2A | How do agents talk to each other? | | Memory + research | Folklore | What does the agent — and the network — already know, so it doesn't redo the work? |

And against the memory tools you might compare it to:

| | Folklore | mem0 / Letta | LangChain RAG | Web every time | |---|:---:|:---:|:---:|:---:| | Local-first, no server | ✅ | ⚠️ | ⚠️ | ✅ | | Gates the web (answers before fetch) | ✅ | ❌ | ❌ | ❌ | | Federated across peers | ✅ | ❌ | ❌ | — | | Signed provenance per record | ✅ | ❌ | ❌ | ❌ | | CPU-only, no API keys | ✅ | ⚠️ | ⚠️ | ❌ | | Benchmarked retrieval (BEIR SciFact) | 0.7522 | not published | not published | — |

---

How it works

flowchart LR
  subgraph machine["Your machine"]
    H["Harness<br/>Claude Code · Codex · Gemini"] -->|WebSearch / WebFetch| Hook["PreToolUse hook"]
    Hook -->|ask first| G[("Local graph<br/>your reasoning, signed")]
    G -->|satisfied: score ≥ 0.85, ≥ 2 hits| Hook
    Hook -->|inject hits · DENY web call| H
  end
  Hook -. graph can't answer .-> Web["Web · arXiv · paid API"]
  Web -. PostToolUse auto-save .-> G
  G <-->|federation · libp2p| P1[("Peer graph")]
  G <-->|federation · libp2p| P2[("Peer graph")]

Three moving parts:

• A hook at the boundary. A PreToolUse hook intercepts outbound research calls and asks the graph first. A PostToolUse hook saves whatever the web returned. Local tools (Read, Grep, Glob) are never touched — they're cheap and there's nothing to gain by blocking them.
• A retrieval stack that earns the deny. Hybrid lexical + vector recall (BM25 + ONNX embeddings + RRF), then cross-encoder rerank, then graph PPR rerank. A web call is only denied when the result clears a real satisfaction floor — see below.
• A federation mesh. Each peer holds only what it has asked for or contributed. No global graph, no central server. The union of every peer's graph is the commons.

Full technical detail: docs/ARCHITECTURE.md.

What "satisfactory" means

The web is the fallback, not the default — but "satisfied" is concrete, not a vibe. Three conditions, enforced at the hook:

| Knob | Default | Meaning | |---|---|---| | satisfaction_score | ≥ 0.85 | Top result must clear this after the full rerank pipeline. | | min_hits | ≥ 2 | At least two graph hits. One brittle hit never overrides the web. | | decision | = use_memory | The decision layer must affirmatively land on "answer from memory" — not "answer-but-verify", not "search web". |

When all three hold, the hook denies the web call and injects the graph hits as if the fetch had returned them. When any fails, the fetch proceeds and the result lands back in your graph, signed.

export FOLKLORE_DENY_WEBSEARCH=1      # opt in to deny-on-confidence (off by default)
export FOLKLORE_DENY_THRESHOLD=0.85   # satisfaction floor
export FOLKLORE_DENY_MIN_HITS=2       # minimum hits to allow a deny
export FOLKLORE_PREFETCH_PEERS=0      # local-only; skip federated fan-out

The deny pathway is opt-in by design: a false positive (graph says "I've got it" when it doesn't) costs more than a redundant fetch. You turn it on per project once you trust your graph's coverage.

On calibration (honest note). A single fixed satisfaction_score ≥ 0.85 is a blunt instrument: on a real, mixed personal graph the composite satisfaction score is compressed and rarely reaches 0.85, so the fixed-threshold gate tends to stay quiet. The calibrated alternative is the energy gate — it scores admission as a free energy over the hits' embedding similarities (−E(q) = T·logsumexp(simᵢ/T)), so several moderate hits accumulate evidence instead of being clamped under a ceiling, plus a separation guard that rejects the "two-close-answers blur together" case.

export FOLKLORE_ENERGY_GATE=1   # calibrated admission instead of the fixed 0.85 score gate

On a labeled real-query set (36 in-corpus / 22 out-of-corpus over the live graph, bench/bench-energy-gate.mjs) the energy score separates in- from out-of-corpus at AUC 0.78 (the fixed composite manages ~0.52) and fires at 57% true-admit / 0% false-admit at the fitted operating point. It is still opt-in and the defaults are fitted on a small set — re-fit with the bench as your graph g