folklore GitHub
Peer-to-peer compounding inference

knowledge travels mouth to ear.

Folklore is that — for your agents. Never start your LLM inference from square one.

$ npm install -g @usefolklore/folklorecopy

keeps findings · debug traces · papers read · dead-ends ruled out · syntheses · grounded claims

works with  ·  claude code  ·  cursor  ·  cline  ·  gemini cli  ·  windsurf  ·  zed  ·  continue  ·  aider  ·  roo code  ·  anthropic  ·  openai  ·  gemini  ·  llama  ·  mistral  ·  deepseek  ·  ollama  ·  grok  ·   works with  ·  claude code  ·  cursor  ·  cline  ·  gemini cli  ·  windsurf  ·  zed  ·  continue  ·  aider  ·  roo code  ·  anthropic  ·  openai  ·  gemini  ·  llama  ·  mistral  ·  deepseek  ·  ollama  ·  grok  ·  
Chapter the First — The Problem

agents reason from zero.

The same paper read again. The same dead-ends walked again. The same conclusion re-derived — and re-billed — a thousand times.

You pay OpenAI, Anthropic, every endpoint, per token, to re-run inference over data someone already ground out yesterday. The work was done. Nobody kept the answer.

the work was done. nobody kept it.

Chapter the Second — Alone

Day one, it already pays off.

Folklore sits between your agent and the web. Every research call meets your own graph first. Read it Tuesday? You don't pay Thursday.

tue folklore ask "mxbai vs cross-encoder?"
↳ not in graph — web · 1.8s · 3.2k tokens · saved + signed
thu folklore ask "mxbai vs cross-encoder?"
↳ from your graph · 11 ms · 0 tokens — never paid again
Interlude — From One to Many

alone, it pays. together, it compounds.

One graph spares you the second lookup. A thousand graphs spare the whole network the first. The same motion — kept, signed, passed on — is single-player value and a commons at once.

inherit the reasoning. infer deeper.

Chapter the Third — Together

Peers join. Their reasoning becomes your start.

Graphs answer each other over libp2p. The first hop becomes "what does the network already know?" Every record signed by a named hand.

peer fan-out · libp2p
▸ peer hit · signed @ada-lprz · 3 sources
web fallback   17% ▸ 1%
Chapter the Fourth — The Mechanism

a graph that earns the deny.

  1. iWebSearch

    Intercept

    A hook catches every WebSearch and WebFetch before it leaves. Local tools never touched.

  2. iiyour graph first

    Ask the graph

    Hybrid recall, cross-encoder rerank, graph PPR — your pages first, then the network's.

  3. iii≥ 0.85 · 2 hits

    Deny, or pass

    Score 0.85 with two hits or more, served from memory. Fall short, the fetch proceeds.

  4. ivsigned · filed

    Set it down

    Whatever the web returns is filed and signed, so the next reader pays nothing.

Chapter the Fourth & a Half — A Query, Traced

47-minute debug. 142 ms hit.

One peer pays the cost. The network gets the answer. No server brokers it, no vendor takes a cut.

tue 03:14 · berlin

The work happens once.

$ claude
> long-ctx vllm OOM after fp16 prefix cache;
> raising max_model_len blew the kv budget
[debug session · 47 min]
> root cause: prefix cache page size too small
> fix: --kv-cache-dtype=fp8 + --block-size=32
[folklore · auto-saved trace]
signed · @you · ed25519 3a4b…
wed 18:42 · tokyo

Everyone after skips it.

$ claude
> vllm long-ctx OOM, prefix cache failure
[folklore · asked 3 peers · 142 ms · hit: @you's trace]
> confident answer — web not needed
> 0 web calls. injecting the signed trace.
[claude · reading @you's notes]
> try --kv-cache-dtype=fp8 + --block-size=32
received · @you · verified · 0 web hops

No server brokered it. No vendor took a cut. The trace is now in two graphs. The next query hits three.

Chapter the Fourth & three-quarters — Provenance

anonymous retrieval is a poisoning surface.

Every other AI memory feeds your model unsigned text from nowhere. Folklore signs every record by a verified human, so a model can refuse what it can't trace.

RAG's open wound

5 → 97%

5 poisoned documents can hijack a retrieval system with a 97% attack success rate. The model has no way to tell trustworthy context from an injected lie.

PoisonedRAG, arXiv · Zou et al.

Folklore's answer

59% → 2%

Signed by a verified GitHub identity, with an auditable chain: who curated it, what they grounded on, when. Provenance ranking keeps only signed gold and drops unsigned poison — cutting flip-ASR from 58.9% to 2.4% (24.8×) on the displaced-poison matrix. Trust becomes a property the model can read.

measured · Haiku agent, Opus judge · BEIR SciFact

Chapter the Fifth — The Reckoning

each claim, on disk.

0
tests passing
0
BEIR SciFact NDCG@10
+43%
recall@1, peer-shared
11ms
median retrieval
~140ms
federation-hit P50
24.8×
poison flip-ASR cut · provenance rank
9.1×
fewer paid web trips · 200k queries
77%
fewer model-input tokens · transfer
84.1%
web correctly denied · graph holds answer
2.5%
false-deny rate · 0% on far-miss
90.2%
cooperative cache hit · 64 peers (vs 18% alone)
98.7%
stored-vector self-recall@5
Folklore0.7522
E5-base0.7370
E5-large0.7230
SPLADE0.6990
ColBERT0.6710
BM250.6650

CPU-only retrieval, full stack (hybrid + cross-encoder + graph PPR), on full BEIR SciFact. Baselines are published BEIR SciFact NDCG@10 (BM25, ColBERT, SPLADE, E5) — Folklore leads the production-grade pack; a 3B GPU reranker (InRanker) tops it at 0.783. Poison-defense is real displaced-poison retrieval (Haiku agent, Opus judge). Compounding & token figures are simulator-grade — the hundred-peer pilot is next.

Chapter the Sixth — Join the Telling

one command. that's all.

One folklore onboard wires the daemon, every Claude Code hook, the statusline, your signed identity, and network auto-discovery — and registers the MCP server in every other harness it finds: Cursor, Cline, Windsurf, Zed, Gemini CLI, opencode, Roo. Pure Node — no Python, no build step, no GitHub app to register. Then you just keep using your agent. The graph answers first, new findings file themselves, peers show up on their own.

# one install, one onboard — that's the whole setup
$ npm install -g @usefolklore/folklore
$ folklore onboard

# onboard wires every hook + the statusline and registers the
# MCP server in every harness it detects. pure Node: no Python,
# no submodule, no GitHub app. wire more harnesses anytime:
$ folklore harness install

# then keep asking your agent exactly as before — every
# WebSearch hits your graph and the network's first, and every
# new answer is filed automatically for the next reader.
The Name

the lore is the graph;
the folk are the peers.

knowledge that survives by being passed on — never relearned from scratch

The Store

wear the commons.

Browse the full store →

Prints, posters, pins & more — browse the full store →

The Memes

told and retold.

Folk knowledge always spread as memes. They spread peer to peer — drop yours; the best ones make the store.

more memes · follow @usefolklore