[English](README.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)
# MisakaNet mcp-name: io.github.Ikalus1988/misakanet > **The same failure, paid for twice.** > > A `pip install` times out behind a corporate proxy. An agent finds the fix. Days later the same > timeout appears on another machine, under another model — and is debugged from scratch, because the > fix was never written down anywhere the next agent looks. > > MisakaNet is that place: a git-backed **failure memory**. Every lesson is a Markdown file in this > repository — graded by evidence, reviewed like code, retrieved by an agent instead of guessed at. > You fail once; the next agent does not. Agent-native interfaces: [MCP server](https://misakanet.org/mcp) (8 tools), WebMCP, `llms.txt`, A2A discovery via `.well-known/agent-card.json`. The **local** stdio server (`pip install misakanet`) ships **11** — the hosted endpoint is a subset; [docs/mcp.md](docs/mcp.md) has both rows.

MisakaNet — Before: 30+ min manual debugging vs After: 0.02s with MCP

Core    CI Lessons MCP Tools Retrieval backend (today) License Stars

Install    Python PyPI npm GitHub Marketplace

Ecosystem    MisakaNet MCP connector on Glama MCP Toplist DSH plugin downloads on dshfind

--- ## Install (30 seconds) The point of an install is a first **successful search**, not the install. None of these needs an account or a token. | Your host | Command | |---|---| | **DeepSeek Harness** | `dsh plugin --profile web add misakanet` — or type `misakanet` in **Add plugin** | | **Claude Code** | `/plugin marketplace add Ikalus1988/MisakaNet` then `/plugin install misakanet@misakanet` | | Installer-managed | Claude Code · Codex · Hermes · OpenClaw · codewhale · Cursor · Gemini CLI · Copilot CLI · OpenCode · Kiro · MiniMax Code · DeepSeek Harness | | **Any other MCP client** | point it at `https://misakanet.org/mcp` — public endpoint, anonymous reads | | **Your own code** | `pip install misakanet-core` (library) · `pip install misakanet` (stdio server) | The installer-managed row is what `npx @misaka-net/misakanet-setup` writes into each host's config. For DeepSeek Harness that is the **rules half only** (`$DSH_HOME/AGENTS.md`): its tools come from the plugin in the row above, which the installer prints as the one manual step. Updates: `dsh plugin --profile web update misakanet@latest`. Installer updates: `npx @misaka-net/misakanet-setup@latest`. Full prerequisites and the two-package trap: [How to use it](#how-to-use-it). ## Your first five minutes **1. Ask it something you have actually broken.** No client installed? This `curl` is the whole interface: ```bash curl -sS https://misakanet.org/mcp \ -H 'Content-Type: application/json' -H 'Accept: application/json' \ -H 'MCP-Protocol-Version: 2025-06-18' -H 'Origin: https://misakanet.org' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call", "params":{"name":"misakanet_search","arguments":{"query":"database is locked","top":3}}}' ``` **2. Read what came back.** A hit returns the lesson, its `evidence_level`, and its path — open the file and read the fix before running any command in it. A miss returns `no_match` plus a ready-to-call intake: the corpus saying it does not know this one yet. **3. Check the trust signal, not the tone.** `E0`–`E3` say how far a lesson was verified; `E4` is the one nobody can write or vote into. ## What is MisakaNet? **Git-backed failure memory for AI coding agents.** An error shows up → the agent searches → it applies a fix somebody already verified → if nothing matches, the miss becomes an intake, and the intake becomes a lesson for the next agent. Every lesson is a Markdown file: reviewed like code, graded by evidence, retrieved with BM25 over the Python standard library. The hosted MCP endpoint adds an **optional semantic fallback** (bge-m3 + Vectorize) only when BM25 returns no match; `MISAKANET_SEMANTIC=0` disables it. No vector database is required locally, and no server unless you want one. | | | |---|---| | **Lessons** | failure-recovery knowledge base, open and auditable under `lessons/` | | **Domains** | rag · devops · fanuc · docker · feishu · mcp · network · ci · wsl · windows … | | **Evidence** | E0 intake → E1 reviewed → E2 reproduced → E3 CI verified → **E4 observed reuse by two or more distinct clients** | | It is not | It is | |---|---| | ❌ a general memory system | ✅ a failure-recovery knowledge layer | | ❌ an agent runtime | ✅ a searchable lesson database | | ❌ a mandatory vector database / RAG stack | ✅ BM25 first; optional, disable-able semantic fallback on the hosted endpoint | | ❌ a skill marketplace | ✅ debugging knowledge from real sessions | | ❌ a general-purpose benchmark platform | ✅ a corpus graded by evidence; a 267-query retrieval run is published, and the older recitation benchmark is paused | ### What it answers — and what it does not ![Four-panel comic: an agent asks about a failure, gets an indexed lesson back, or gets "no_match" and a ready-to-call intake form](promotional/misakanet-scope-comic.webp) MisakaNet answers for the failures it has indexed, and only those. When nothing matches the reply is `no_match` plus a ready-to-call `intake` — the corpus saying "not this one yet", not a dead end. ### Lesson vs Skill A **skill** teaches an agent how to do something; a **lesson** records what went wrong before and how not to fail again. MisakaNet is only the second thing. → [FAQ](FAQ.md) ## Where it is today - **The numbers that move are badges**, on purpose: the Lessons badge renders `data/badges/lessons.json`, regenerated by `update-badges.yml`, so it can lag a run but is never a hand-typed total. - **The top of the evidence ladder is empty, and this page says so.** `E4` needs an observation — two distinct clients actually retrieving a lesson — and the corpus has none yet ([distribution](docs/trust-semantics.md), regenerated and checked by CI). - **Search is BM25 first; the hosted endpoint can fall back to embeddings.** Local/offline remains stdlib BM25; the fallback runs only when BM25 returns no match, and `MISAKANET_SEMANTIC=0` turns it off. A corpus gap is still a miss: the reply is `no_match` plus an intake, not an empty page. - **Reported gaps arrive faster than they are triaged.** The intake queue is the honest bottleneck. - **The corpus is downloadable and citable.** `data.misakanet.org` publishes a versioned bundle — the full corpus, the benchmark query set, and every run artifact — with a per-file SHA-256 and an explicit license per file ([DATASET.md](DATASET.md)). The counts live in each version's `manifest.json`, not in prose. ## Retrieval benchmark: 267 queries, BM25 vs semantic fallback On 2026-10-27 the hosted endpoint's retrieval path was evaluated on **267 queries, one per lesson** generated by Workers AI 70B. Both arms used the same eval worker and corpus; only `MISAKANET_SEMANTIC` changed. | arm | R@1 | R@5 | no_match | |---|---|---|---| | BM25 | 0.210 | 0.225 | 0.712 | | semantic fallback | **0.446** | **0.472** | **0.453** | The fallback improves R@1 by **23.6 points** and cuts `no_match` by **25.9 points**. It does **not** meet the R@1 half of the target (`0.446 < 0.46`); `no_match` is within the target (`0.453 ≤ 0.50`). A 113-query subset reaches 0.460/0.460, while 250 reaches 0.404/0.504: the sample is large enough to show the fallback works, not large enough to call R@1 solved. This is 267 queries from the 300-entry pool, not the full 650; 33 pool entries yielded no query, 2 semantic requests errored, and the eval corpus was not refreshed. → [full report](docs/benchmarks/retrieval-l1-267-2026-10-27.md) ### What changed since: the gate, not the model The table above measures a configuration production no longer uses. Until 2026-10-28 the semantic path ran **only when BM25 returned nothing**, so a confident-but-wrong lexical hit suppressed it — 13 of the 20 recorded misses were exactly that. For queries containing CJK characters the two ranked lists are now **fused** (reciprocal-rank) instead of one gating the other. Measured on the live endpoint, 64 Chinese queries, 0 transport failures: | bucket | n | before | after | |---|---|---|---| | zh → zh | 31 | 0.710 | **0.774** | | **zh → en** | 33 | 0.455 | **0.697** | | zh → en, low overlap | 14 | 0.214 | **0.500** | For scale: `bge-m3` pure cosine already reached 0.636 on the cross-lingual bucket, and a `gemini` embedding 0.727 — so most of the gap was the decision to consult the vector path, not the model. English queries are untouched (the fuse is gated on CJK characters) and sit at 15/20 against a floor of 16, which is where they were before this change. → [full report](docs/benchmarks/cjk-fusion-2026-10-28.md) ## Recitation benchmark: what it measured, and why it is paused One narrow question: **when you hand a model a lesson, how much of that lesson comes back?** The metric is `lesson_hit_rate` — the share of the injected lesson's commands reproduced in the answer. Read the setup before the number: the scenario in this benchmark is each lesson's own title, the injected lesson is *that same lesson*, no retrieval call is made, and correctness is not checked. It measures the **recitation** half of RAG: necessary for MisakaNet to help, and **not evidence that search finds anything**. The run is **paused**. Two independent runs of ≈500 scenarios each on 2026-09-22: **46.1%** with the lesson pasted in, **23.3%** without. What remains is the last snapshot plus its dated record — [`docs/benchmarks/latest.json`](docs/benchmarks/latest.json). The table below is generated by [`scripts/update_readme_benchmark.py`](scripts/update_readme_benchmark.py); do not hand-edit it. | Date | with_lesson hit rate | plain hit rate | n | |---|---|---|---| | 2026-08-30 | 46.4% | 23.9% | 358 | | 2026-08-31 | 49.1% | 25.1% | 398 | | 2026-09-06 | 48.3% | 24.1% | 455 | | 2026-09-14 | 46.6% | 23.4% | 494 | | 2026-09-21 | 46.1% | 23.3% | 512 | | 2026-10-12 | 43.8% | 26.1% | 34 | _1155 run(s) in `latest.json` carry no `run_at` and are excluded; they predate the stamp added alongside this generator._ ``` with_lesson hit rate (per run date) 43.8% │ ▁ 46.1% │ ▄ 46.6% │ ▄ 48.3% │ ▆ 49.1% │ █ └────────────────── 08 09 09 09 10 31 06 14 21 12 ``` Per-run files: [`docs/benchmarks/`](docs/benchmarks/) · metric definition: `METRIC_DEFINITION` in [`scripts/benchmark_workers_ai.py`](scripts/benchmark_workers_ai.py). ## Take part **1. Report a failure the corpus does not have.** Search first, then call `misakanet_submit_intake` — no account, no email, no token, a five-line report is enough. It becomes a tracked issue. **2. Reuse a lesson and leave the trace.** A "this helped" vote is recorded as an `E3` hint, not as proof. The proof is quieter: your retrieval is counted, anonymously, as one more distinct client. **What you get back: attribution.** A lesson cites the intake that produced it (`source:`, `provenance.issue:`), and the pipeline can emit a receipt naming the lesson and its evidence level. Nothing here is a bounty: this repository pays nothing and promises nothing. Some issues carry third-party reward banners added by our own automation; we do not administer them — see [Contributing](#contributing). ## How to use it `npx @misaka-net/misakanet-setup` installs MisakaNet into your assistant's own config — the same command for every client. The ten supported clients, and what each one gets, are in [the install page](https://misakanet.org/install/). Verify an install with `npx @misaka-net/misakanet-setup --verify`; undo it with `--uninstall`. Reads are anonymous and unlimited; registration is for writing ([why](AGENTS.md#33-注册与配额)). Node ≥ 18 for the installer, Python ≥ 3.11 for the library and stdio server. Python 3.10 reached end-of-life on 2026-10-01, so this release needs 3.11 or newer — upgrade the interpreter before upgrading the package. ### Other channels - **Claude Code, as a plugin** — `/plugin marketplace add Ikalus1988/MisakaNet`, then `/plugin install misakanet@misakanet`: the hosted MCP tools, no installer, no local process. - **DeepSeek Harness** — `dsh plugin --profile web add misakanet`: `mcp__misakanet__*` tools plus the session panel. The rules half (the "search before you act" block) is written by the installer into `$DSH_HOME/AGENTS.md`; dsh has no plugin extension point for it, so the two halves stay separate. - **Call the endpoint yourself** — the `curl` in [Your first five minutes](#your-first-five-minutes). - **The library in your own code** — `pip install misakanet-core`. ### The two-package trap (it cost a real install failure, #1849) - `@misaka-net/misakanet-setup` (npm) is the **installer** — it has a `bin`, no plugin entry. Use it to teach your assistant to search. - `misakanet` (npm) is the **DSH / Codex plugin** — `dsh plugin --profile web add misakanet`. - This repository (git) is also a **Claude Code plugin marketplace** — `/plugin marketplace add Ikalus1988/MisakaNet`. - `misakanet` (PyPI) is the stdio **MCP server** — `python3 -m misakanet.server`. - `misakanet-core` (PyPI) is the **library** (stdlib-only BM25; the hosted endpoint's semantic fallback is server-side) — `from misakanet.search import search_lessons`. ### Use it as a GitHub Action When a workflow fails, the action searches the lessons and comments the closest match on the pull request (optionally reporting the new error). Published on [GitHub Marketplace](https://github.com/marketplace/actions/misakanet-intake-bot). ```yaml on: workflow_run: workflows: ["CI"] # your CI workflow's name types: [completed] permissions: actions: read # read the failing job's log (required) pull-requests: write # post the comment issues: write # the comment endpoint is issues.createComment jobs: intake: if: ${{ github.event.workflow_run.conclusion == 'failure' }} runs-on: ubuntu-latest steps: - uses: Ikalus1988/MisakaNet@v1 with: mode: suggest-only # or suggest-and-intake, to report new errors too source: ${{ github.repository }} ``` → [inputs and outputs](docs/agents/external-usage.md) ## Documentation | Topic | Where | |---|---| | Install, verify, uninstall | [docs/quickstart.md](docs/quickstart.md) · | | MCP: protocol, tools, transports | [docs/mcp.md](docs/mcp.md) · [API.md](API.md) | | CLI | [docs/cli-reference.md](docs/cli-reference.md) · `python3 search_knowledge.py "…"` | | Architecture | [ARCHITECTURE.md](ARCHITECTURE.md) · [docs/CONCEPTS.md](docs/CONCEPTS.md) | | Contributing a fix | [CONTRIBUTING.md](CONTRIBUTING.md) · [label system](docs/label-system.md) | | Submitting an intake | [docs/mcp-intake-guide.md](docs/mcp-intake-guide.md) · [mcp-remote](docs/integrations/mcp-remote.md) | | Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) | | Known limitations | [docs/LIMITATIONS.md](docs/LIMITATIONS.md) | | Benchmarks | [docs/benchmarks/](docs/benchmarks/) | | Dataset (corpus + query sets, downloadable) | [DATASET.md](DATASET.md) · | | Roadmap / changelog | [ROADMAP.md](ROADMAP.md) · [CHANGELOG.md](CHANGELOG.md) | | Competitors, domains, crawler policy | [competitive](docs/competitive-analysis.md) · [domains](docs/domains/) · [robots](docs/cloudflare-robots-txt.md) | ## Contributing > **Zero bounty. Maximum rigor. Merge earns credit.** "Zero bounty" is a statement about *this repository*: MisakaNet pays nothing and promises nothing. It is not a statement about the issue you are looking at. Some issues carry an **Opire** banner advertising a third-party reward, added automatically by our own [`scripts/question_autopilot.py`](scripts/question_autopilot.py) — we do not administer those payouts, and Opire is not mentioned in `CONTRIBUTING.md`. **Verify any reward offer independently** before you plan work around it. The only thing this repository has ever honoured is a merged PR. ([#2903](https://github.com/Ikalus1988/MisakaNet/issues/2903)) 1. Check the checkout: `python3 scripts/misakanet_cli.py smoke` 2. Search before writing: `python3 search_knowledge.py "your error here"` 3. Found nothing? [Share your failure lesson](https://github.com/Ikalus1988/MisakaNet/issues/new?template=lesson-feedback.yml) — five lines is enough **This month's good first issue (Oct 26 – Nov 26):** [Bring one real failure](https://github.com/Ikalus1988/MisakaNet/issues/3901) — no code; the MCP intake needs no account; we help with the format. → [CONTRIBUTING.md](CONTRIBUTING.md) · [good first issues](https://github.com/Ikalus1988/MisakaNet/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) · [code of conduct](CODE_OF_CONDUCT.md) ## Security ⚠️ **Sandbox your agent before executing retrieved commands.** Lessons are community-contributed — review before running. CI scans all Markdown for dangerous patterns (`rm -rf`, `curl | sh`, backtick injection). See [SECURITY.md](SECURITY.md) and [LIMITATIONS.md](docs/LIMITATIONS.md). ## Troubleshooting | Symptom | Where | |---|---| | DCO · leaked token · pip timeout · `database locked` · Windows/GBK · WSL permission · FANUC codes | [docs/troubleshooting.md](docs/troubleshooting.md) | | MCP returns 403/405, or a client shows no tools | [docs/mcp.md](docs/mcp.md) · [FAQ.md](FAQ.md) | | Behind a corporate proxy | [docs/troubleshooting.md](docs/troubleshooting.md#behind-a-corporate-proxy) | ## For Agents & Crawlers **Prefer MCP intake for missing or stale lessons; PRs are optional.** Search first; if nothing matches, call `misakanet_submit_intake` at `https://misakanet.org/mcp` — no account, no token. Never send secrets or raw private logs. Protocol: [docs/mcp-intake-guide.md](docs/mcp-intake-guide.md). ## Contributors MisakaNet contributors *Built by the network, for the network. Zero bounties paid — only merge approval and eternal network gratitude.* ⚡ ## License [Apache-2.0](LICENSE) — Copyright 2026 Ikalus1988. Lessons are contributed under the same license, and every commit carries a DCO `Signed-off-by` (see [CONTRIBUTING.md](CONTRIBUTING.md)).