Swarm Knowledge Protocol (SKP)

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

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

Have a failing CI, DCO, pip, token, or agent issue? Search failure lessons before opening a PR.

Stuck on a failure? Search 235+ verified fix lessons before opening a PR:

🔍 Search all lessons →

Project Summary

👋 你是谁？快速导航

Did a lesson help you? We're trying to verify that MisakaNet's lessons are actually useful in practice. If any lesson, search result, or doc saved you time or helped you avoid a mistake, we'd love to hear about it. → Share feedback (5 lines, anonymous OK) → Join the discussion

🧱 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-      │  235+ 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.

Start here: choose your journey

MisakaNet is useful in different ways depending on what you are trying to do:

👉 New here? Search failure lessons →

Lesson vs Skill

MisakaNet lessons are not skills.