misakanet

English | 日本語 | 简体中文

MisakaNet

mcp-name: io.github.Ikalus1988/misakanet

Stop debugging the same error twice. MisakaNet searches 411+ failure lessons so an agent skips the bugs someone already paid for, instead of rediscovering them one session at a time.

Agent-native interfaces: MCP server (7 tools), WebMCP (browser navigator.modelContext), llms.txt / llms-full.txt, and A2A discovery through .well-known/agent-card.json.

Core   

Install   

Ecosystem   

---

What is MisakaNet?

Git-backed failure memory for AI coding agents. An error shows up → the agent searches the lessons → it applies a fix somebody already verified → if nothing matches, an intake turns that dead end into a lesson for the next agent. Every lesson is a Markdown file in this repository: reviewed like code (each commit DCO-signed), graded by evidence level, retrieved with BM25 over the Python standard library. No vector database, no embedding model, 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 levels	E0 intake → E1 CI → E2 merged PR → E3 maintainer → E4 production reuse

Registry listings (Glama, Smithery, MCP Toplist) proxy the hosted endpoint, which serves 411+ indexed failure-recovery lessons — indexed, never "verified": evidence level is what says how much a lesson has been proven.

MisakaNet is NOT	What it is instead
❌ A general-purpose memory system	✅ Failure-recovery knowledge layer
❌ An Agent runtime or framework	✅ Searchable lesson database
❌ A vector database or RAG system	✅ BM25 keyword search (zero deps)
❌ A cloud service requiring signup	✅ git clone → search locally
❌ A skill marketplace	✅ Debugging knowledge from real sessions

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: not a skill marketplace, not an agent runtime, not a general memory layer, not a vector database. → FAQ

Benchmark: does lesson context actually help?

Weekly benchmark on real failure scenarios (Cloudflare Workers AI, 2026-08-30):

Model	Without lesson context	With lesson context	Gain
llama-3.2-3b (light)	21% hit	43% hit	2× — lesson context doubles a weak model
llama-3.3-70b (strong)	42% hit	73% hit	+31%

Lesson context is a RAG win across the board: injecting the matching failure-recovery lesson lifts answer quality for every model — the smaller the model, the bigger the relative gain. Details: benchmark-2026-08-30

→ Full changelog · Release notes

Beware of a single number. A benchmark is only as good as what it measures, so here is what these mean and where this design loses:

Metric	What it measures	Why it matters here
Hit rate	share of failure questions answered correctly	the only number that decides whether this corpus is worth a search
Gain (with − without)	lift from injecting the matching lesson	separates "retrieval works" from "the model got lucky"
Cost / latency	tokens and wall-clock per answer	the whole premise is cheaper than re-debugging, so it has to stay cheap

Where it loses on purpose: BM25 matches words, not meaning. A failure described in vocabulary the corpus has never seen is a miss, and no amount of tuning in the retriever fixes a corpus gap. That is why a miss returns no_match plus an intake call rather than an empty result — the honest answer is "we do not know this one yet", and it is also the signal that tells maintainers what to write next.

Why failure-memory?

Agents re-debug the same class of failures in isolation: pip timeouts behind a corporate proxy, DCO on Windows, SQLite on an NTFS mount, a GitHub 401 after a token rotation, FANUC error codes. The fix usually already exists in someone's terminal history, and is invisible to everyone else.

Three deliberate engineering choices, each of which trades something:

• Git is the source of truth. A lesson is a file, so it diffs, reverts, forks and reviews like code. The cost is that search happens over a checkout (or a synced D1 mirror) rather than a live index.
• Zero dependencies by default. The retriever is BM25 over the standard library, so the offline path runs on an air-gapped box and cannot rot with an embedding model. The cost is recall on paraphrases.
• Evidence is graded, not asserted. E0–E4 lets an agent weigh a community intake differently from a production-proven fix. The cost is bookkeeping, and most lessons sit at E0–E2.

How to use it

Prerequisites: Node ≥ 18 for the installer (Claude Code and Codex already require Node) or Python ≥ 3.10 for the library and the stdio server. Nothing else.

Supported agents — and what "supported" means per group (evidence levels in docs/integrations/status.md):

Group	Agents	What you get
Installer-managed	Claude Code · Codex · Hermes · OpenClaw · codewhale · Cursor · Gemini CLI · Copilot CLI · OpenCode · Kiro	npx @misaka-net/misakanet-setup writes each client's own MCP config, a rules block where the client has one, and (Claude Code only) a turn-counting hook — the five JSON-file clients (Cursor, Gemini CLI, Copilot CLI, OpenCode, Kiro) get the MCP entry alone; --verify checks whatever was written
MCP by hand	Cursor · Gemini CLI · Windsurf · OpenCode · Copilot · DeepSeek Harness	the endpoint is standard MCP over HTTP; add the URL in that client's own config. Cursor also has a rules-file mode
Anything else that speaks MCP over HTTP	—	the endpoint is public, reads are anonymous and unmetered

Pick one channel — they are independent, and none of them needs an account:

I want…	Command	What it touches
my assistant to search the lessons	npx @misaka-net/misakanet-setup	writes the MCP endpoint into each assistant's own config; optionally a rules block and a hook
to call the endpoint myself	the curl below	nothing to install
the library in my own code	pip install misakanet-core	nothing

The two-package trap (this one cost a real install failure, #1849):

Looks like	Actually is	Use it for
@misaka-net/misakanet-setup (npm)	the installer — has bin, no plugin entry	teaching your assistant to search
misakanet (npm)	the DSH / Codex plugin (index.js, SKILL.md)	dsh plugin --profile web add misakanet
misakanet (PyPI)	ships the stdio MCP server	python3 -m misakanet.server
misakanet-core (PyPI)	the library (zero-dep BM25)	from misakanet.search import search_lessons

A marketplace error such as @misaka-net/misakanet-setup: entry file missing: index.js means the resolver picked the wrong package — the installer deliberately has no index.js.

One anonymous read — no account, no token, no browser:

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}}}'

Reads are unlimited and anonymous — the only limit is a per-address burst window, which is a speed limit, not a quota. Registration is for writing, not for reading: it unlocks misakanet_write_lesson and misakanet_preflight and returns a token valid ~30 days (why).

Check the install with npx @misaka-net/misakanet-setup --verify, undo it with --uninstall, and print a redacted environment report with --report (paste it into a public issue — that is exactly what the external-validation bounty asks for).

→ Quickstart · Install guide · MCP docs · what the installer writes · WebMCP setup

Use it as a GitHub Action

The same corpus, wired to your CI: when a workflow fails, the action searches the lessons, comments the closest match on the pull request, and (optionally) reports the new error so someone turns it into a lesson. Published on GitHub Marketplace.

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 · why actions: read is not optional

See it in 8 seconds

Documentation

Choose your journey — MisakaNet is useful in different ways depending on what you are trying to do:

I am...	Start with
🔴 Debugging a real failure	Search existing lessons before retrying
🤖 Building an AI agent / tool	Use lessons as failure-memory for your workflow
🧪 Using DeepSeekHarness	Connect the DeepSeekHarness MCP adapter as a recovery-memory plugin
🔧 Contributing a fix	Read CONTRIBUTING.md for code style + PR checklist, check related lessons, then open a small PR
📝 Sharing a failure case	Submit a 5-line failure note — no polished PR required
📊 Evaluating agent learning	Run the benchmarks and compare reuse behavior
💬 Reporting friction	MCP intake or journey report #510
❓ New to MisakaNet	Read the FAQ for installation, MCP pairing, troubleshooting, and contribution answers

👉 New here? Search failure lessons →

No GitHub account? Submit via MCP intake (no auth needed) → MCP Intake Guide

Understanding the system → Label system · Troubleshooting

The rest of the map:

Topic	Where
Open the network in a browser	·
Install, verify, uninstall	docs/quickstart.md ·
MCP: protocol, tool reference, transports	docs/mcp.md · API.md
CLI	docs/cli-reference.md · python3 search_knowledge.py "…"
Architecture and the three paths	ARCHITECTURE.md · docs/CONCEPTS.md
Submitting an intake (for agents and humans)	docs/mcp-intake-guide.md
What the label