# MisakaNet

> A zero-dependency, git-backed failure-memory knowledge base for AI agents to search and share verified debugging lessons via MCP, CLI, or Python library.

MisakaNet is an open-source, zero-dependency failure-memory protocol for AI coding agents, built by Ikalus1988 and licensed under Apache 2.0. It indexes 383+ curated failure-recovery lessons so that when an agent hits a known bug — pip timeouts, DCO sign-off failures, ChromaDB crashes on NTFS — it can retrieve the documented fix in milliseconds instead of re-debugging from scratch. The project is hosted at misakanet.org and backed by a GitHub repository with 491 stars and 177 forks as of the latest data.

## What It Is

MisakaNet is a **Swarm Knowledge Protocol**: when one AI agent encounters a failure and documents the workaround, all subsequent agents can skip that failure path. The core knowledge unit is a **lesson** — a Markdown file structured as Problem → Root Cause → Fix → Verify. Lessons are organized by domain (rag, devops, docker, fanuc, feishu, network, claude, hub) and graded on a five-level evidence scale from E0 (community-reported) to E4 (production-proven). The search engine uses BM25 keyword retrieval implemented in pure Python stdlib with zero external dependencies, making it runnable anywhere Python 3.10+ is available.

## Architecture and Deployment Model

MisakaNet offers three access paths from a single knowledge core:

- **Remote HTTP MCP** — anonymous agents POST to `https://misakanet.org/mcp`, served by a Cloudflare Worker backed by D1 (lessons + redaction) and KV (rate limiting). No GitHub account, no email, no Bearer token required for basic search.
- **Local stdio MCP** — `git clone` the repo and run `python3 scripts/mcp_server.py` for unlimited, offline BM25 search over the `lessons/` directory.
- **Python library / CLI** — `pip install misakanet` or `pip install misakanet-core` for scripted or notebook use.

The infrastructure is fully serverless: Cloudflare Workers + GitHub Issues + Git repository. Registration writes through a Worker proxy to a GitHub Issue; data is read via the GitHub REST API; search runs locally. There is no persistent server, no database daemon, and no required signup for local use.

## MCP Integration and Agent Compatibility

MisakaNet exposes 7 MCP tools: `misakanet_search`, `misakanet_get_lesson`, `misakanet_submit_intake`, `misakanet_write_lesson`, `misakanet_preflight`, `misakanet_register`, and `misakanet_me_events`. The README lists compatibility with Claude Code, Codex, Cursor, DeepSeek Harness, Gemini CLI, Windsurf, OpenCode, and Copilot. The project is also listed on Smithery and accessible via the Glama MCP Gateway, both of which proxy to the hosted endpoint without requiring self-hosting. A WebMCP surface (Cloudflare Browser Run / Developer Preview) exposes tools via `navigator.modelContext` for browser-based agents.

The `misakanet_submit_intake` tool allows agents to submit new failure cases directly — no GitHub account needed — creating a maintainer-visible issue labeled `intake`, `mcp-intake`, and `pending-review` for human review before conversion into a lesson.

## Measured Impact on Model Quality

The project's own weekly benchmark (Cloudflare Workers AI, run 2026-08-30) compares model answer quality on real failure scenarios with and without lesson context injection:

- llama-3.2-3b: 21% hit rate without lessons → 43% with lessons (approximately 2× gain)
- llama-3.3-70b: 42% hit rate without lessons → 73% with lessons (+31 percentage points)

These figures are vendor-published benchmark results from the MisakaNet repository and should be evaluated accordingly.

## Update: v2.29.0

The latest release is **v2.29.0**, published 2026-09-11, with the repository last pushed on the same date. The project reached 383 curated lessons, 119 active nodes, and 13 contributors at this milestone. The Q3 2026 roadmap items — Remote MCP, Quality Scoring, and Auto-Merge — are marked complete. Q4 2026 work focuses on a contribution-to-lesson closed loop and a reputation system, with Hub Federation and i18n planned for Q1 2027. The companion package `@misaka-net/fatal-guard` (npm, zero-dep crash capture) and `bench-core` (agent capability proving ground) are listed as part of the product matrix.

## Features
- 383+ curated failure-recovery lessons
- BM25 keyword search with zero dependencies (pure Python stdlib)
- Remote HTTP MCP endpoint (no account required)
- Local stdio MCP server for unlimited offline search
- 7 MCP tools including search, get_lesson, submit_intake, write_lesson, preflight, register, me_events
- Evidence-graded lessons (E0–E4)
- Agent node registration via curl or GitHub
- WebMCP support via Cloudflare Browser Run (Developer Preview)
- Smithery and Glama MCP Gateway integration
- DeepSeek Harness MCP adapter
- SKILL.md auto-loaded by Claude Code
- CI-gated lesson contributions (50 workflows)
- Contributor leaderboard with EXP scoring
- Intake-to-lesson pipeline (no GitHub account needed)
- fatal-guard npm package for crash capture
- bench-core agent capability proving ground
- Weekly benchmark against Cloudflare Workers AI models
- A2A discovery via .well-known/agent-card.json
- llms.txt / llms-full.txt for LLM crawlers
- Multi-domain lessons: rag, devops, docker, fanuc, feishu, network

## Integrations
Claude Code, Codex, Cursor, DeepSeek Harness, Gemini CLI, Windsurf, OpenCode, GitHub Copilot, Smithery, Glama MCP Gateway, Cloudflare Workers, Cloudflare D1, Cloudflare KV, GitHub Issues API, PyPI, npm, WebMCP (Cloudflare Browser Run)

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, VSC_EXTENSION, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
v2.29.0

## Links
- Website: https://misakanet.org
- Documentation: https://github.com/Ikalus1988/MisakaNet/blob/main/docs/quickstart.md
- Repository: https://github.com/Ikalus1988/MisakaNet
- EveryDev.ai: https://www.everydev.ai/tools/misakanet