Purpose
MisakaNet is a Git-backed, zero-dependency micro-lesson library whose goal is to let AI Agents asynchronously share and retrieve debugging experience. Its core idea is "don't debug the same error twice": when an Agent encounters an error, it first retrieves indexed failure experience lessons and directly applies a fix that someone else has already verified, rather than rediscovering it from scratch in every session.
Main Capabilities
- Failure experience library: Each lesson is a Markdown file stored in this repository, reviewed like code (every commit is DCO-signed), graded by evidence level, and retrieved using BM25 based on the Python standard library. There is no vector database, no embedding model, and no server required unless the user deploys one themselves.
- Agent-native interfaces: MCP server (7 tools), WebMCP (browser navigator.modelContext), llms.txt / llms-full.txt, and A2A discovery via .well-known/agent-card.json.
- Hits and misses: On a retrieval hit, it returns the experience lesson; when no match is found, it returns no_match and provides a directly callable intake process—a miss is itself an answer, indicating "we don't know this one yet."
- GitHub Action: Connects the same corpus to CI. When a workflow fails, the Action retrieves experience lessons, comments the closest match on the Pull Request, and (optionally) reports new errors so someone can turn them into experience lessons. The Action is published on the GitHub Marketplace.
- DeepSeek Harness plugin: Version 2.40.0 provides the browser part, and version 2.41.0 adds the rest of the interface. The plugin puts MisakaNet where the session is, with no account or token needed, no Python needed on the plugin path, and the npm package mounts the hosted endpoint.
Usage
- Install (about 30 seconds): In DeepSeek Harness, sidebar plugins (1) → add plugin (2) → enter misakanet (3) → install. The dialog accepts the same package name as the CLI command(its hint is: package name, GitHub URL, or local path).
- Update: dsh plugin --profile web update misakanet@latest; update the installer: npx @misaka-net/misakanet-setup@latest.
- Anonymous reading: Reading is unlimited and anonymous, with the only limit being a per-address burst window (this is rate limiting, not a quota). No account, token, or browser is required.
- Registered writing: Registration is for writing rather than reading, unlocks misakanet_write_lesson and misakanet_preflight, and returns a token valid for about 30 days.
- Verify and uninstall: Use npx @misaka-net/misakanet-setup --verify to check the installation, --uninstall to undo it, and --report to print a redacted environment report.
- Prerequisites: The installer requires Node ≥ 18 (Claude Code and Codex themselves already require Node); the library and stdio server require Python ≥ 3.10. There are no other requirements.
- Submitting a missing experience: Prefer the remote MCP tool misakanet_submit_intake (https://misakanet.org/mcp），无需 GitHub account, email, or Bearer token; do not send keys or raw private logs. For the full protocol, see docs/mcp-intake-guide.md.
Applicable Scenarios
Suitable for AI coding agents to retrieve fixes when encountering specific errors, and also suitable for teams to connect CI failures into an automated retrieval and reporting process, as well as scenarios where you want to accumulate debugging knowledge in a reviewable, rollback-capable way. For example, pip timeouts behind an enterprise proxy, DCO on Windows, SQLite on NTFS mounts, GitHub 401 after token rotation, FANUC error codes, etc.
Limitations and Notes
- MisakaNet only answers failures it has indexed, not general knowledge; BM25 matches words rather than semantics, so describing a failure with wording never seen in the corpus will fail to retrieve it, and corpus gaps cannot be fixed at the retriever level.
- It is only a "failure memory", not a skill marketplace, not an Agent runtime, not a general memory layer, and not a vector database.
- Evidence levels (E0-E4) are used to distinguish community-entered fixes from production-verified fixes, at the cost of record maintenance cost, and most lessons are at E0-E2.
- The weekly benchmark (Cloudflare Workers AI) measures how much the model can reproduce after receiving a lesson (lesson_hit_rate), that is, the "paraphrase" stage of RAG; it does not call retrieval and does not check correctness, so it cannot prove that "search can find the correct lesson for the described failure".
- Experience lessons are contributed by the community; before executing retrieved commands, be sure to sandbox the Agent first and review manually; CI scans all Markdown for dangerous patterns (rm -rf, curl | sh, backtick injection).
- "Zero bounty" is a statement about this repository: MisakaNet pays no compensation; the Opire third-party reward banners appearing on some issues are automatically added by scripts, the repository does not manage these payments, please independently verify any reward promises.
- For more known constraints and non-goals, see LIMITATIONS.md; for the security policy, see SECURITY.md.
- The project uses the Apache-2.0 license, copyright 2026 Ikalus1988, and experience lessons are contributed under the same license.
