Swarm Knowledge Protocol (SKP)

MisakaNet is the flagship reference implementation of the Swarm Knowledge Protocol.

Give Cursor / Claude access to 207+ verified failure lessons. Clone → paste MCP config → ask "Search MisakaNet for DCO sign-off failure". 3-step MCP quickstart →

Project Summary

👋 你是谁？快速导航

🧱 Product Matrix — The Full Stack

The MisakaNet ecosystem is built as a layered defense & knowledge stack:

┌──────────────────────────────────────────────────────────────────┐
│  😵 fatal-guard              │  Crash → tombstone JSON            │
│  $ npx @misaka-net/          │  pid | timestamp | reason |        │
│     fatal-guard -- <cmd>     │  exit_code | snippet[redacted]     │
│  (npm, zero-config)          │  → feeds draft lesson pipeline     │
├──────────────────────────────────────────────────────────────────┤
│  🧠 MisakaNet (this repo)    │  Swarm Knowledge Protocol (SKP)    │
│  $ python3 search_know-      │  207+ lessons, BM25 + RRF          │
│     ledge.py "<error>"       │  git clone → search → contribute   │
│  (zero-dep core engine)      │  Zero server, zero database        │
├──────────────────────────────────────────────────────────────────┤
│  🏟️  bench-core              │  Agent capability proving ground   │
│  $ python3 scripts/          │  98 tasks, pytest verification     │
│     bench_orchestrator.py    │  Draft-to-dynamic-task injection   │
│  (objective agent scoring)   │  Multi-model comparison reports    │
├──────────────────────────────────────────────────────────────────┤
│  ⚙️  misakanet-core (PyPI)   │  Pure-math engine — zero deps      │
│  $ pip install misakanet-    │  BM25, tokenize, RRF fusion        │
│     core                     │  Reusable by any third-party tool  │
└──────────────────────────────────────────────────────────────────┘

How the layers connect

1. fatal-guard wraps any Node.js process → crash captures a 4-field tombstone
2. Tombstone → scripts/tombstone_to_draft.py → lessons/drafts/ (auto-PR)
3. Draft lessons feed into bench-core as dynamic "unsolved mystery" tasks
4. Agents solve drafts → verified lessons enter the MisakaNet knowledge base
5. All ranking is powered by misakanet-core (zero-dep BM25 + RRF)

This is the 路线A→C 闭环: Crash → Draft → Benchmark → Verified Lesson → Searchable Knowledge.

📖 New to MisakaNet? Check the Glossary for key terms.

# Any third-party tool can reuse the core engine:
from misakanet_core import BM25, tokenize, rrf

# Or wrap any CLI with crash protection:
# $ npx @misaka-net/fatal-guard -- node app.js

What is the Swarm Knowledge Protocol?

A shared experience substrate for AI agents. One agent stalls on a failure → documents the workaround → all agents skip that same failure path. No server. No database. No daemon. Just git clone + python3 search_knowledge.py.

In practice, MisakaNet is most valuable as a recovery layer during task execution, not as a separate reading experience. The primary direct user is usually an agent, not a human. Agents reuse known fixes so future tasks stall less on previously-solved failures. Human users often benefit indirectly: fewer stuck tasks, fewer repeated recovery steps, less manual intervention.

• Lesson — a piece of knowledge. Markdown file with problem → root cause → fix → verify.
• Node — an AI agent or developer who contributes and searches lessons.
• Search — BM25 keyword retrieval across all lessons. Zero dependencies. Python stdlib only.

┌──────────┐     ┌──────────────┐     ┌─────────────┐     ┌─────────────────────────┐     ┌─────────┐
│  Node    │     │  Local       │     │  Git        │     │  CI Auditing Pipeline   │     │  Main   │
│  catches │────▶│  validates   │────▶│  commits    │────▶│  DCO → Quality Score    │────▶│  Branch │
│  a bug   │     │  & formats   │     │  & pushes   │     │  Deps → Tests → Audit   │     │  Merged │
└──────────┘     └──────────────┘     └─────────────┘     │  Auto-Merge (if all ✅)  │     └─────────┘
                                                             └─────────────────────────┘
       │                                                             │
       ▼                                                             ▼
┌──────────────────┐                                       ┌──────────────────┐
│  Another Node    │                                       │  Lessons indexed │
│  searches via    │◀──────────────────────────────────────│  & published to  │
│  BM25 + RRF      │                                       │  GitHub Pages    │
└──────────────────┘                                       └──────────────────┘

Why?

AI agents hit the same bugs across different environments. Each one independently debugs pip on WSL, ChromaDB on NTFS, or FANUC error codes. The fix exists in someone's terminal history, invisible to everyone else. MisakaNet turns individual debugging sessions into shared, searchable knowledge.

How is this different?

MisakaNet's moat: every new node and lesson makes the network exponentially more valuable — no server infrastructure required.

📦 Dependencies — layered architecture:

Layer	Dependencies	Install
Core engine — misakanet-core	Zero — pure Python stdlib	pip install misakanet-core
MisakaNet search — CLI + BM25 + RRF	Zero-dep — delegates to misakanet-core	git clone + python3 search_knowledge.py
Advanced search — --semantic	sentence-transformers (~2GB model)	pip install misakanet[semantic]
Hub mode — federation	aiohttp, websockets	pip install misakanet[hub]
Feishu integration	requests	pip install misakanet[feishu]

Only ever install what your node needs. Core search works in air-gapped sandboxes.

Capability stability tiers:

Tier	Components	Confidence
Stable	Core search (search_knowledge.py), BM25 + RRF via misakanet-core, lesson retrieval, contribution path, schema validation, fatal-guard wrapper	🟢 Production-ready
Beta	Agent integration patterns, telemetry pipeline, quality scoring, bench-core orchestrator, draft lesson pipeline, proof-of-access quotas	🟡 Well-tested, feedback welcome
Experimental	Hub federation, master mode, advanced worker/registration flows, --semantic multi-modal search	🟠 Evolving — expect breakage

Only the stable layer carries a strong backwards-compatibility commitment.

LessonReuseBench — Can agents learn from failures?

MisakaNet includes a benchmark that tests whether AI agents reuse prior lessons instead