MisakaNet review: a git-backed failure-memory library for AI coding agents

The problem MisakaNet targets: agents that relearn the same error

A coding agent that hits a failure, works around it, and then loses that workaround when the session ends will hit the same failure next week. MisakaNet is an attempt to make that recovery knowledge durable and shareable. The README frames it as "failure-memory for AI coding agents" and states the goal plainly: search lessons, get a fix path, without storing raw logs or leaking prompts.

The intended user is not a human reading a wiki. It is an agent that can issue a search call mid-task, or a developer wiring such a call into an agent's tool list. That is why every interface in the repository is machine-shaped: an MCP server, a CLI, a Python function, an llms.txt file, and a `.well-known/agent-card.json` for A2A discovery. A human can read the lessons directory directly, but the design assumes the reader is a process.

The scope is deliberately narrow. This is not a general knowledge base, a documentation generator, or a RAG framework. It is a corpus of failure lessons plus the thin machinery to search and extend it.

Git as the database: how lessons, evidence levels and search fit together

The architectural claim is "zero dependencies, zero server, zero database." Lessons live as files in the `lessons/` directory of the repository, which means the storage layer is git itself. Versioning, review and distribution all come from the same mechanism: a pull request adds a lesson, and a clone or fetch retrieves it.

Each lesson carries an evidence level from E0 to E4. The README defines them: E0 is community reported through intake or issues, E1 is CI verified, E2 is PR merged, E3 is maintainer verified, E4 is production proven. This is a useful vocabulary because it lets a caller decide how much to trust a hit. It is also entirely self-declared. A lesson marked E4 is marked that way by whoever wrote it; the repository provides no independent verification of the claim, and the README does not describe an audit process behind the higher levels.

Search is keyword-oriented. The package metadata lists `bm25` among its keywords, and the README offers an optional `semantic` extra that pulls in `sentence-transformers>=2.2` for embedding-based search. So the default path is lexical matching, with semantic search as an opt-in that adds a heavy dependency. For error strings and command names, lexical matching is often the right call: exact tokens like `ERR_PAUSE` or `database is locked` are precisely what a BM25 index handles well.

The core search logic does not live in this repository. `pyproject.toml` declares `misakanet-core>=2.7.0` as a required dependency, and the README's Python example imports from `misakanet.search`. The repo you clone is the corpus plus the interfaces; the ranking implementation is in a separate package.

Installing MisakaNet and running a first search

There are five documented entry points. The fastest requires no install at all, only curl. The README gives this example for submitting a problem intake over remote MCP, and notes that it needs no GitHub account, no email, no Bearer token and no browser:

curl -sS https://misakanet.org/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"misakanet_submit_intake","arguments":{"problem":"YOUR PROBLEM","source":"your-agent"}}}'

Replace `YOUR PROBLEM` with the error text. The response is a JSON-RPC payload; the README does not print an example response, so expect to inspect the returned object yourself on the first call.

For a local install, the PyPI route gives you a CLI named `misakanet`:

pip install misakanet
misakanet "database is locked"

The README also notes `python3 -m search_knowledge "your error here"` as an equivalent invocation. Running the CLI against a real error string from your own logs is the honest first test: if the top hits are unrelated, the corpus does not cover your stack and no amount of configuration will fix that.

If you want the search function inside a script or notebook, the README points at a separate core package and this import:

from misakanet.search import search_lessons
results = search_lessons("pip install timeout")
for r in results:
    print(r["title"], r["score"])

Note the install line for that path is `pip install misakanet-core`, not `misakanet`. Mixing the two up is the most likely first stumble. For Claude Code, Cursor or Codex, the README's local MCP option is a clone followed by `python3 scripts/mcp_server.py`, with the process registered in your MCP client config. A Dockerfile is present and runs the same MCP server on stdio, so no port is exposed.

Where MisakaNet breaks down

The corpus is the product, and its coverage is uneven by construction. The README's own best-practice examples span `rag`, `devops`, `fanuc`, `docker`, `feishu`, `network`, `claude` and `hub`. That is a strange spread: industrial robot controller semantics sit next to WSL terminal behaviour and ChromaDB storage paths. If your stack is not in that list, search returns weak matches, and a weak match presented to an agent as a fix path is worse than no answer.

Evidence levels are a labelling scheme, not a guarantee. Nothing in the repository prevents a submitter from marking a lesson E4. Treat the level as a hint about provenance, not as a quality score.

The remote path has a quota. The README states that anonymous browser agents share 5 free reads per day, and that remote HTTP MCP requires registration via `misakanet_register` to get a `node_id` and `token` for unlimited searches. Local stdio MCP is described as unlimited. If your agent makes many searches per task, the local mode is the one that will not rate-limit you mid-run.

The dependency situation is unusual and worth reading carefully. `pyproject.toml` carries a dated note explaining that `chromadb` was removed from the `hub` extras because every published version up to 1.5.9 is affected by four unfixed security advisories, and that the repository has no chromadb imports of its own. That is a defensible decision, but it also means the semantic-search story and the hub story are less turnkey than the headline "zero dependencies" suggests. The zero-dependency claim applies to the core search and lesson management path, not to every optional feature.

MisakaNet compared with a general-purpose RAG stack

The obvious alternative is to point an existing retrieval system at your own documentation and incident notes: a vector store plus an embedding model, with your internal runbooks as the corpus. The difference is in what gets indexed and who writes it. A general RAG stack indexes whatever you feed it, including your private logs and postmortems, and the quality of retrieval depends on how well you chunk and embed that material. MisakaNet instead ships a shared, public, git-versioned corpus of failure lessons, and its ranking is lexical by default with BM25, semantic search being an optional extra.

That trade is concrete. A private RAG setup can answer questions about your own systems and keeps sensitive text inside your boundary. MisakaNet cannot answer questions about your systems, because it has never seen them, and it deliberately stores no raw logs or prompts. What it offers in exchange is coverage you did not have to write: lessons contributed by other people who hit the same class of error. If your failures are mostly environment-specific (path mountings, terminal quirks, toolchain version conflicts), that shared corpus has a real chance of containing your problem. If your failures are domain-specific to your own codebase, it will not.

A second alternative is simply a curated internal wiki or a notes file in the repository. That costs nothing to run and stays accurate, but it has no search interface an agent can call, and it decays silently. MisakaNet's contribution is the interface and the versioning discipline, not the idea of writing down fixes.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-08-28, which is recent. Releases are frequent: v2.23.0 landed on 2026-08-28, with v2.22.0 the day before. Version numbers in `pyproject.toml` and `package.json` both read 2.30.0, ahead of the latest listed release tag, so the manifest and the release history are not perfectly in step. That is worth knowing if you pin versions.

Upgrade cost is low for the core path. The required runtime dependency is `misakanet-core>=2.7.0`, and the package targets Python 3.10 through 3.12 with a minimum of 3.10. The optional extras are where weight appears: `hub` pulls in aiohttp, websocket-client, networkx, PyYAML, numpy and keyring; `semantic` pulls in sentence-transformers; `harvest` pulls in scrapling. Install only the extras you use.

The npm package is a different shape from the Python one. Its description states that it registers the stdio MCP server as `mcp__misakanet__*` tools for the DeepSeek harness, and that the npm skill-only bundle ships no Python server, so live bundle tools require a `git+` install. Its `engines` field requires Node 20 or later. If you are coming from the JavaScript side expecting a self-contained package, that note is the one to read first.

Licensing is Apache-2.0 across `pyproject.toml`, `package.json` and the LICENSE file. That is a permissive licence with an explicit patent grant and a requirement to preserve notices. It says nothing about the accuracy or provenance of contributed lesson text, which is a content question rather than a licence question. If you plan to redistribute the corpus inside a commercial product, read the notices requirement yourself; this is not legal advice.

Editorial conclusion

Adopt MisakaNet if your agents repeatedly hit the same environment-specific errors and you want a searchable, version-controlled memory that needs no server or database. Do not adopt it if you need authoritative, independently audited fixes: lessons carry self-declared evidence levels from E0 to E4, and nothing in the repository verifies an E4 claim for you. Before wiring it into a workflow, run the CLI smoke command against your own error strings, read three or four lessons in the domains you care about, and check whether the remote MCP quota (5 free reads per day for anonymous browser agents, token required beyond that) fits your call volume. Local stdio MCP is unlimited; that is the mode to start with.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes