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.
- Source repo
- Ikalus1988/MisakaNet
- Stars
- ★ 543
- Last updated
- today
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 64/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformChatGPT · Codex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- 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.
- Not a fit if
- Teams needing semantic or vector search — BM25 matches keywords only
- Users who need verified answers — most lessons sit at E0–E2 evidence
- Anyone who must write lessons — anonymous access is read-only
- Source review
- 64/100 · Some gaps
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.
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.
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 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.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| MisakaNet Failure-Memory Library This agent | 64 · Some gaps | MCP serverFree | ★ 543 | today | Python | ChatGPT · Codex · Claude Code |
| Ori Mnemos | 80 · Good | CLIFree | ★ 334 | 25d ago | TypeScript | Claude Code · OpenAI API · Claude API |
| Mnemo Cortex | 75 · Good | Self-hosted serviceFree | ★ 159 | 2d ago | Python | Codex · Claude Code · Claude.ai |
| Claudex | 69 · Some gaps | CLIFree | ★ 97 | 4mo ago | JavaScript | Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
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.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
[0.7.1](https://github.com/Ikalus1988/MisakaNet/compare/misakanet-setup-v0.7.0...misakanet-setup-v0.7.1) (2026-10-25) Bug Fixes * setup: tier ③ is the state directory, not always a hook ([#3804](https://github.com/Ikalus1988/MisakaNet/issues/3804)) ([4aa0e38](https://github.com/Ikalus1988/MisakaNet/commit/4aa0e38d683fc882d00441271e21084982379422)), closes [#3777](https://github.com/Ikalus1988/MisakaNet/issues/3777) npm: https://www.npmjs.com/package/@misaka-net/misakanet-setup/v/0.7.1 …View on GitHub ↗ -
Release notes excerpt
What's Changed * test(setup): compare the mcode manifest paths in one dialect by @Ikalus1988 in https://github.com/Ikalus1988/MisakaNet/pull/3801 * fix(release): read the linked CHANGELOG headings release-please writes by @Ikalus1988 in https://github.com/Ikalus1988/MisakaNet/pull/3803 * fix(setup): tier ③ is the state directory, not always a hook by @Ikalus1988 in https://github.com/Ikalus1988/MisakaNet/pull/3804 * lessons(contrib): three intake lessons — unexecuted samples, report-only gates, WSL/Docker readiness by @Ikalus1988 in https://github.com/Ikalus1988/MisakaNet/pull/3805 …View on GitHub ↗ -
Release notes excerpt
0.6.0 (2026-10-22) Features * setup: the install says what it is about to write, before it writes it ([#3690](https://github.com/Ikalus1988/MisakaNet/issues/3690)) ([#3709](https://github.com/Ikalus1988/MisakaNet/issues/3709)) ([5647207](https://github.com/Ikalus1988/MisakaNet/commit/5647207dba3d224eb5ea431369049ec69cb8d68b)) Bug Fixes * a degraded read must not be reported as an empty corpus ([#3512](https://github.com/Ikalus1988/MisakaNet/issues/3512)) ([898a63b](https://github.com/Ikalus1988/MisakaNet/commit/898a63b3f833bdbe3b6c1670bc5ceff4439fe441)) …View on GitHub ↗