# folklore

Adopt this skill: https://proskills.md/skills/other/usefolklore-folklore-claude-skills-folklore

Page: https://proskills.md/skills/other/usefolklore-folklore-claude-skills-folklore
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .claude/skills/folklore/SKILL.md
size: 7247
sha: 9ce26d08b3a0d0038c79dbed07370f7f4f717f23
upstream: https://github.com/usefolklore/folklore/blob/main/.claude/skills/folklore/SKILL.md

````text
---
name: folklore
description: Knowledge graph research skill. Trigger with /folklore or when the user asks about research, sources, rooms, tunnels, or their knowledge graph. Also triggers when PreToolUse hook reports "folklore: Knowledge graph exists."
---

# folklore — Agent Skill

You have access to the folklore knowledge graph via MCP tools. Use this skill to narrate operations with full visibility.

## When to Activate

- User types `/folklore`
- User asks "what do I know about X", "search my research", "what did I read"
- User asks to trigger, discover, index, or manage rooms/sources
- PreToolUse hook fires with "folklore:" prefix
- User asks about architecture, dependencies, or prior research
- **PROACTIVE:** When answering ANY technical question, check the graph FIRST
- **PROACTIVE:** When reviewing code, search for related nodes before giving advice
- **PROACTIVE:** When the user mentions a technology or concept, search the graph for context
- **PROACTIVE:** At the START of every conversation, call `graph_stats` to show the user their graph is alive

## Proactive Behavior (CRITICAL)

**folklore is NOT passive.** Don't wait for the user to ask. Search the graph whenever:

1. You're about to answer a technical question → call `search` first
2. You're about to write code in a file → call `search` with the module/concept name
3. The user mentions a library, framework, or concept → call `search` to see if it's in the graph
4. The user starts a new conversation → call `graph_stats` and mention the graph

**Pattern for every response involving research or code:**
```
1. User asks something
2. YOU call search("relevant terms") BEFORE answering
3. If results found → weave them into your answer with citations
4. If no results → answer normally, then suggest: "Want me to trigger a fetch for this topic?"
```

**NEVER say "I don't have information about X" if you haven't searched the graph first.**

## Operation Visibility Rules

**ALWAYS narrate what you're doing.** Don't silently call MCP tools. Show the user each step.

### Search Operations

When searching the graph, show the pipeline:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 folklore ► SEARCHING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

◆ Embedding query: "{query}"
◆ Searching room: {room} ({node_count} nodes)
◆ k-NN over {vector_count} vectors...

Results:
  1. {title} — distance: {d} — {source_type}
  2. {title} — distance: {d} — {source_type}
  3. {title} — distance: {d} — {source_type}
```

### Trigger Operations

When triggering a room, spawn a **named background agent** for visibility:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 folklore ► TRIGGERING room={room}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

◆ Loading sources for room '{room}'...
◆ Found {n} enabled sources

  ◆ Fetching: {source_id} ({kind})...
  ✓ {source_id}: {seen} items, {new} new, {skipped} skipped

  ◆ Fetching: {source_id} ({kind})...
  ✓ {source_id}: {seen} items, {new} new

Summary: +{total_new} nodes, {total_skipped} skipped
```

### Discovery Loop

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 folklore ► DISCOVERY LOOP room={room}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

◆ Iteration 1:
  → Discovering sources from keywords: {keywords}
  → Found {n} new sources
  → Triggering ingest...
  → Extracting new keywords from content...
  → New keywords: {kw1}, {kw2}, {kw3}

◆ Iteration 2:
  → Discovering with expanded keywords...
  → Found {n} new sources
  → No new keywords extracted

✓ Converged after 2 iterations
  Total: +{sources} sources, +{nodes} nodes
```

### Index Operations

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 folklore ► INDEXING PROJECT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

◆ Scanning codebase: {root}
  → {n} source files found
  → {n} new, {n} unchanged (skipped)

◆ Reading package.json
  → {n} dependencies

◆ Parsing .gitmodules
  → {n} submodules

◆ Reading git log
  → {n} recent commits

✓ Index complete: +{new} nodes, {skipped} skipped
```

### Tunnel Detection

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 folklore ► TUNNEL DETECTION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

◆ Loading vectors from {n} rooms...
◆ Computing cross-room similarities (threshold={t})...

Tunnels found:
  🚇 {node_a} ↔ {node_b}
     rooms: {room_a} / {room_b}
     distance: {d}
     why: both discuss {topic}
```

## How to Use MCP Tools

### Quick reference

| Tool | When | Show |
|------|------|------|
| `search` | "What do I know about X?" | Narrate: embedding → k-NN → results |
| `ask` | "Give me context on X" | Narrate: search → context assembly |
| `get_node` | "Tell me about this source" | Show full node attributes |
| `get_neighbors` | "What connects to X?" | Show graph traversal |
| `find_tunnels` | "Any cross-domain connections?" | Narrate similarity scan |
| `trigger_room` | "Refresh my research" | Narrate per-source progress |
| `discover_loop` | "Find more sources" | Narrate iterations + convergence |
| `graph_stats` | "How big is my graph?" | Show stats with breakdown |
| `room_create` | "Start tracking X" | Confirm room + suggest sources |
| `room_list` | "What rooms do I have?" | List with counts |
| `sources_list` | "What feeds am I pulling?" | List with kinds + configs |

### Before answering research questions

1. Call `graph_stats` to know the current state
2. Call `search` with the user's question
3. If results found → cite them with source_uri
4. If no results → suggest `trigger_room` or `discover_loop`

### Proactive graph use

When the PreToolUse hook fires, BEFORE grepping:
1. Call `search` with the relevant keywords
2. If the graph has good results, use them instead of raw files
3. Tell the user: "Found this in your knowledge graph:" + cite

## Status Display

After any operation, show the current state:

```
───────────────────────────────────────
folklore • {room}
{nodes} nodes | {edges} edges | {vectors} vectors | {sources} sources
───────────────────────────────────────
```
````

## File: README.md
upstream: https://github.com/usefolklore/folklore/blob/main/README.md

````text
<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](https://usefolklore.com)** · **[Manifesto](docs/MANIFESTO.md)** · **[Spec](docs/WHITEPAPER.md)** · **[RFC](docs/rfc/)** · **[Roadmap](docs/PROJECT-PLAN-FOLKLORE.md)** · **[npm](https://www.npmjs.com/package/@usefolklore/folklore)**

![tests](https://img.shields.io/badge/tests-942%20passing-brightgreen)
![BEIR SciFact NDCG@10](https://img.shields.io/badge/BEIR%20SciFact%20NDCG%4010-0.7522-blue)
![poison defense](https://img.shields.io/badge/poison%20flip--ASR-58.9%25%E2%86%922.4%25-blue)
![runtime](https://img.shields.io/badge/runtime-CPU--only-orange)
![spec](https://img.shields.io/badge/spec-0.1.0--draft-blue)
![status](https://img.shields.io/badge/status-pre--launch-yellow)
![license](https://img.shields.io/badge/license-MIT-green)

<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" />

<sub><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></sub>

</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](#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.

```bash
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" />

<sub>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></sub>
</div>

---

## Philosophy

Folklore is a bet about *how intelligence should be organized*, not just a cache. The long version is the **[Manifesto](docs/MANIFESTO.md)**; 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 |
|---|:---:|:---:|:---:|:--
````
