MisakaNet Failure-Memory Library
A zero-dependency, git-backed failure-memory library that lets AI agents search verified debugging lessons and stop re-debugging known errors.
Per-dimension scores and reasoning
SECURITY.md discloses a public PAT (Issues:write only, single repo, 30-day rotation advice); fatal-guard has token-redaction tests (redact-compliance.js); CI scans Markdown for dangerous patterns; sandboxing is advised before executing lessons. Deductions: hex-encoding a PAT in public HTML is fragile design; lesson fix commands are community content with no enforced human-confirmation gate. The auto-draft workflow pushes branches and opens PRs (external write), albeit with review; rollback is only implicit via git with no explicit procedure; publisher identity unverified and lessons lack per-item attribution in the provided files.
fatal-guard CLI contract and crash-scenario tests show specific, actionable error messages (ENOENT/EACCES distinction, timeout naming). Deductions: serious self-contradiction — README advertises v2.16.0 and 'zero dependencies' while package. says 2.28.1, pyproject 2.29.0, and requirements.txt lists mcp/schema/pyyaml; 'zero-dependency' holds only for the core engine and is not consistently stated. Referenced docs (troubleshooting, etc.) are not in evidence.
Audience and scenario coverage is thorough: entry points for developers, agent builders, contributors, and evaluators; 'lessons vs skills' and 'not this' tables clearly delimit capability boundaries. Deductions: trigger precision relies on the agent voluntarily invoking search with no explicit trigger specification; claimed environment coverage (Cursor/Claude Code/Codex, Docker) lacks concrete configuration in evidence files.
Information architecture is excellent: flow diagrams, command tables, domain examples, FAQ/ROADMAP/SECURITY/LIMITATIONS; full Apache-2.0 LICENSE. Deductions: versioning is inconsistent — README showcases v2.16.0 features while package files say 2.28.1/2.29.0, with no CHANGELOG in evidence; install notes and FAQ/examples are mostly external links (docs/quickstart.md not in evidence), so their content cannot be verified.
Lesson structure (problem → root cause → fix → verification) is usable output; BM25+RRF retrieval and a zero-dependency core make a plausible cost/benefit case. Deductions: actual retrieval quality and the correctness of 289 lessons cannot be verified from the evidence; the value claim leans on promotional comparison imagery ('30+ min vs 0.02s') rather than auditable data.
The fatal-guard package has real test files corroborating redaction and CLI behavior, and the chromadb removal decision cites specific GHSAs. Deductions: headline statistics (289 lessons, 59 nodes, 98 bench tasks) are unsupported within evidence; future-dated roadmap items ('2026 Q2/Q3 completed') are mixed with factual claims and marketing copy is not separated from verifiable facts; many key documents (ARCHITECTURE, LIMITATIONS, MCP docs) appear only as links.
- Low trust: never execute lesson-retrieved fix commands directly; review manually and run in a sandbox.
- Versions contradict across files (README v2.16.0 vs package. 2.28.1 vs pyproject 2.29.0); 'zero-dependency' applies only to the core — assess supply-chain risk for mcp/schema/pyyaml.
- A PAT embedded in the public registration form (even scope-limited) is a known attack surface; verify rotation actually happens.
- The auto-draft workflow can be triggered remotely via repository_dispatch and auto-creates PRs; evaluate abuse potential before use.
- Publisher is unverified; headline statistics (289 lessons, etc.) have no independent evidence in the reviewed files.
What does this agent do, and when should you use it?
MisakaNet is a shared failure-memory substrate for AI coding agents, indexing 383+ failure-recovery lessons graded by evidence level (E0-E4) across domains like rag, devops, docker, and fanuc. Each lesson is a Markdown file (problem → root cause → fix → verify) with the git repository as the single source of truth; local retrieval uses a BM25 keyword engine built purely on the Python standard library — no vector DB, no embedding model, no dependencies. It exposes multiple integration surfaces: a local stdio MCP server (scripts/mcp_server.py with 7 tools), a remote HTTP MCP at https://misakanet.org/mcp backed by Cloudflare Worker + D1 + KV, a CLI (search_knowledge.py), PyPI packages (misakanet / misakanet-core), and a DeepSeek Harness adapter. When an agent hits an error it searches lessons for a fix path; if nothing matches, it can submit a redacted intake via misakanet_submit_intake with no account, which maintainers review and convert into a lesson. Weekly benchmarks on Cloudflare Workers AI show lesson context lifts llama-3.3-70b hit rate from 42% to 73%. Licensed Apache-2.0, the deployment boundary is clear: git clone gives unlimited local use, while anonymous remote access is rate-limited to 5 reads/day.
MisakaNet's core operations are retrieval and curation of failure-recovery knowledge. Reads: scans Markdown lesson files under lessons/ (each with problem, root cause, fix, verification) via the BM25 engine in engine.py. Runs: python3 scripts/mcp_server.py starts a local stdio MCP server exposing seven tools — misakanet_search, misakanet_get_lesson, misakanet_submit_intake, misakanet_write_lesson, misakanet_preflight, misakanet_register, misakanet_me_events; or python3 search_knowledge.py "query" for direct CLI search. Calls: in remote mode it hits https://misakanet.org/mcp (a Cloudflare Worker using D1 for lessons/redaction, KV for rate limiting, and the GitHub Issues API for intakes). Produces: search results (title + relevance score), a node_id + token pair from registration, and, after maintainer review, new lessons. Contribution path: intake issues become draft lessons after review; PRs must pass a 50-workflow CI gate.
- A developer using Claude Code or Cursor whose agent is stuck on a known error (pip timeout, DCO sign-off failure, database lock) searches the library first to get a verified fix path instead of re-debugging.
- An agent-framework builder wiring failure memory into their toolchain: git clone locally, run the stdio MCP, and the agent reuses network-curated lessons with zero dependencies.
- A remote agent that cannot use GitHub or register accounts searches anonymously via curl against misakanet.org/mcp, or submits redacted failure reports through misakanet_submit_intake without credentials.
- Engineers maintaining cross-environment infrastructure (WSL, NTFS, FANUC robots) consult devops/fanuc domain lessons to quickly resolve environment-specific pitfalls.
- Researchers evaluating agent learning run the retrieval benchmarks (scripts/retrieval_noisebench.py) to measure how lesson context improves model hit rates.
- A Python/notebook author runs pip install misakanet-core and calls search_lessons() to retrieve fixes inside scripts.
What are this agent's strengths and limitations?
- Zero-dependency architecture: the core engine is pure Python stdlib BM25 — no vector DB, no embedding model, no server to run; git clone gives unlimited local search.
- Dual-surface design: local stdio MCP and remote HTTP MCP (Cloudflare Worker + D1) share one knowledge core; anonymous remote search works instantly, registered local use is unlimited.
- Lessons carry evidence grades (E0 community-reported through E4 production-proven), and PRs pass a 50-workflow CI gate, making content quality auditable.
- Accountless intake loop: agents submit redacted reports via misakanet_submit_intake with no Bearer token; unsolved failure families surface on a public demand board so contributors know what to write.
- Public weekly benchmark data (Cloudflare Workers AI) quantifies the value: lesson context doubles a weak model's hit rate and adds +31% for a strong model.
- Retrieval is BM25 keyword-only — no semantic/vector search; queries whose phrasing misses lesson keywords may return no hits (an optional misakanet[semantic] extra exists).
How do you install or deploy this agent?
Option 1 (remote, zero install): nothing to install — any agent that can make HTTP requests can curl https://misakanet.org/mcp. Option 2 (local MCP): git clone https://github.com/Ikalus1988/MisakaNet.git && cd MisakaNet (requires Python 3.10+), run python3 scripts/mcp_server.py, and register the server in your MCP client config. Option 3 (CLI): pip install misakanet, then run misakanet "database is locked". Option 4 (Python library): pip install misakanet-core. Option 5 (DSH plugin): dsh plugin add misakanet. Anonymous remote HTTP MCP is limited to 5 reads/day/IP; call the misakanet_register tool to get a node_id + token for unlimited access. Local stdio MCP is unlimited.
How do you use this agent?
Local search: python3 search_knowledge.py "pip install timeout". Remote MCP (no account): curl -sS https://misakanet.org/mcp -H "Content-Type: application/" -H "MCP-Protocol-Version: 2025-06-18" -d '{"rpc":"2.0","id":1,"method":"tools/call","params":{"name":"misakanet_submit_intake","arguments":{"problem":"YOUR PROBLEM","source":"your-agent"}}}' (use misakanet_search for searching). Claude Code integration: claude mcp add --transport http misakanet <remote or local endpoint>. Python library: from misakanet.search import search_lessons; results = search_lessons("pip install timeout"). Glama gateway: click Connect on the Glama MisakaNet connector page, then add the generated gateway URL as a remote MCP server in Cursor, VS Code, or ChatGPT desktop. When reporting, use kind="missing_lesson" for failures and kind="question" for how-to questions; never send secrets or raw private logs.
How does this agent compare with similar options?
The README includes a comparison table of similar failure/experience-knowledge MCP projects: deadends.dev (closest relative — also stores failure→solution; MisakaNet adds DCO review, evidence grading, and zero-dependency local search), Prior (verified-solution exchange, not failure-specific), Kira (session/project-level Scars warnings vs MisakaNet's cross-project public auditable lessons), Casebook-MCP (also an agent failure registry; MisakaNet adds the intake loop and evidence grading), knownissue (issue-ticket loop vs curated lesson retrieval), fix-memory-mcp (local-private vs public shared), and cogmem (general memory layer vs purpose-built failure knowledge). MisakaNet's stated edge: git-backed, zero-dependency, purpose-built for failure recovery, and public by default.