Failure-memory layer for coding agents: search evidence-rated failure lessons by error text.
MisakaNet MCP Server (io.github.Ikalus1988/misakanet)
MisakaNet is a failure-memory layer for coding agents that searches verified debugging lessons by error text. It provides an MCP server interface and an agent-native way to retrieve failure lessons and related data, backed by a knowledge base and documentation.
🛠️ Key Features
Failure-memory for coding agents: search verified failure lessons by error text
MCP server with 7 tools: misakanet_search, misakanet_get_lesson, misakanet_submit_intake, misakanet_write_lesson, misakanet_preflight, misakanet_register, misakanet_me_events
WebMCP support via browser document.modelContext
Topics include MCP, agents, knowledge-base, LLM, SQLite, and Cloudflare Workers
🚀 Use Cases
Look up known bugs based on the observed error text
Retrieve specific failure lessons for debugging workflows
Integrate agent behavior using MCP and WebMCP interfaces
⚡ Developer Benefits
Agent-native interfaces for searching and getting lessons
Tooling covers search, lesson retrieval, intake/lesson writing, and registration/events
Repository includes English and Japanese documentation links
⚠️ Limitations
The server’s advertised capability is limited to searching and providing “310+ failure lessons” via the error-text lookup approach
[ONBOARDING] Get a Bearer token for authenticated access (unlocks misakanet_write_lesson and higher rate limits). Reading needs no registration and has no daily cap: misakanet_search / misakanet_get_lesson work anonymously (a per-address burst limit protects the index; it is a speed limit, not a quota). No GitHub account or email needed, and no personal data is collected — the node is a pseudonym, not an account.
Token lifetime: valid ~30 days. Pass client_id (a random UUID you generate once and keep private) to get the SAME node_id and token back on every later call and to renew them; without client_id every call creates a new node, which means your reuse evidence, receipts and history start over. `client_id` is a *name*, not the key: to renew a node, send the token it was given as `Authorization: Bearer` along with the same client_id. A renewal that presents only the name still works during a deprecation window, returns `deprecated`, and is refused once strict mode is on (`client_id_proof_required`). A fresh client_id registers as before. Still generate it randomly and keep it private — the name is how the node is found, and the token is how the caller proves it is the one that owns it.
Returns: object {node_id: string, token: string, registered_at: string, agent_type: string, reused: boolean} — reused=true means an existing node was found for this client_id; reused=false means this call created a new node (so a client_id you expected to be recognised was not, and the identity you had is not attached to this token).
Example: misakanet_register(agent_type='claude-code', client_id='8f14e45f-2b1c-4f3a-9d2e-7c6b5a4d3e2f')
Optional referral_code: the code of the node that invited you (`misakanet` referral code, 4-16 letters/digits). Recorded against your node and counted for that code — the only place a referral has ever been recorded, since the invitation otherwise never leaves the inviting machine. Counted once per new node: calling register again with the same client_id renews the same node and does not add to the count.
Parameters2
agent_type
string
optional
Agent type (e.g. claude-code, codex, cursor, dsh, other). Optional: an omitted value is recorded as "unknown", the same default the local surface has always used.
client_id
string
optional
Optional stable identifier for this client (8-64 chars of A-Z a-z 0-9 . _ : -). Generate it once and reuse it so later calls return the same node instead of a new one.
Raw schema
{
"type": "object",
"properties": {
"agent_type": {
"type": "string",
"description": "Agent type (e.g. claude-code, codex, cursor, dsh, other). Optional: an omitted value is recorded as \"unknown\", the same default the local surface has always used."
},
"client_id": {
"type": "string",
"description": "Optional stable identifier for this client (8-64 chars of A-Z a-z 0-9 . _ : -). Generate it once and reuse it so later calls return the same node instead of a new one."
}
}
}
misakanet_search
[RETRIEVAL / READ] Search MisakaNet's public failure-lesson index by error text, keyword, or topic. This is the primary read path — run it first when you hit an error, before deciding to submit anything. Choosing among the retrieval tools: an actual error or keyword in hand → this one; something risky about to run and no error yet → misakanet_preflight (the third, misakanet_memory_context, is stdio-only and covers the before-you-start case). For a known lesson ID or path, prefer misakanet_get_lesson — it skips ranking and returns the full content. detail controls progressive disclosure: compact (default, ~80 tok/lesson) for broad scans, summary (~200 tok) adds domain/tags/fix, full returns complete lesson data.
FAQ: results may also include answered questions (type="faq", issue_url + answer) — if a maintainer already answered the same question, the answer surfaces here.
Returns: object {results: [compact: {id, title, problem, freshness, evidence_level, score} | summary: + {domain, tags, fix} | full: the record], source, detail, query}; `score` is the ranker's relevance for that result and is omitted on the unranked fallback path. On no match: {no_match: true, suggestion, intake}. When the answer is degraded — no index loaded, or the live store refused the read and the corpus came from the snapshot — the response also carries `degraded: true`, `degraded_reasons` and a one-sentence `notice`; read it before concluding that no lesson exists.
Example: misakanet_search(query='pip install timeout', domain='python', top=3)
Parameters8
query
string
required
Required redacted error message, keyword, or topic (e.g. 'pip install timeout' or 'DCO sign-off failed').
domain
string
optional
Optional domain filter such as devops, python, network, feishu, rag, fanuc, or mcp.
top
integer
optional
Maximum ranked results to return. Defaults to 5; keep small for MCP context and latency.
detail
string
optional
Progressive disclosure: compact (default, ~80 tok) includes id/title/problem/freshness/score; summary (~200 tok) adds domain/tags/fix; full returns complete lesson data with path.
kind
string
optional
Filter by kind: 'lessons' (lesson files only), 'evidence' (results with evidence_refs or verification), 'related' (cross-referenced/tag-overlap), 'all' (default). Auto-detected from query intent when omitted.
bm25_weight
number
optional
Override BM25 keyword weight (0-1). Higher favors exact keyword match. Default: 0.65. All weights must sum to 1.0.
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Required redacted error message, keyword, or topic (e.g. 'pip install timeout' or 'DCO sign-off failed')."
},
"domain": {
"type": "string",
"description": "Optional domain filter such as devops, python, network, feishu, rag, fanuc, or mcp."
},
"top": {
"type": "integer",
"description": "Maximum ranked results to return. Defaults to 5; keep small for MCP context and latency."
},
"detail": {
"type": "string",
"enum": [
"compact",
"summary",
"full"
],
"description": "Progressive disclosure: compact (default, ~80 tok) includes id/title/problem/freshness/score; summary (~200 tok) adds domain/tags/fix; full returns complete lesson data with path."
},
"kind": {
"type": "string",
"enum": [
"all",
"lessons",
"evidence",
"related"
],
"description": "Filter by kind: 'lessons' (lesson files only), 'evidence' (results with evidence_refs or verification), 'related' (cross-referenced/tag-overlap), 'all' (default). Auto-detected from query intent when omitted."
},
"bm25_weight": {
"type": "number",
"description": "Override BM25 keyword weight (0-1). Higher favors exact keyword match. Default: 0.65. All weights must sum to 1.0."
},
"metadata_weight": {
"type": "number",
"description": "Override metadata bonus weight (0-1). Higher favors matching domain/tags. Default: 0.20."
},
"baseline_weight": {
"type": "number",
"description": "Override baseline score weight (0-1). Higher favors proven/popular lessons. Default: 0.15."
}
},
"required": [
"query"
]
}
misakanet_get_lesson
[RETRIEVAL / READ] Fetch one public MisakaNet lesson by repository path or lesson ID. Use after misakanet_search returns a promising result to pull the full fix content. Pass `path` or `id` (path wins if both are supplied); at least one is required, and the empty call returns {error, code}. `path` must be a lesson file (lessons/<topic>/<slug>.md) — anything else is refused with code=invalid_lesson_path rather than read.
Returns: object {path: string, content: string} — lesson markdown body, capped at 5000 chars per call; or {error, code}. The code says which: lesson_not_found (no such lesson — do not retry, search instead), invalid_lesson_path (the argument is not a lesson reference — fix the argument), internal_error (a service fault — retrying is reasonable). When the lesson is longer than the cap the response says so instead of pretending to be complete: {truncated: true, content_length: <full chars>, content_returned: <chars here>, full_content_url: <raw markdown>} — fetch that URL when the tail matters (the cut can fall before the Verification section).
Example: misakanet_get_lesson(id='auto-merge-ci-pipeline')
Parameters2
path
string
optional
Lesson path relative to the repository, e.g. lessons/core/auto-merge-ci-pipeline.md — must be a file under lessons/ ending in .md (other repository files are not readable through this tool). Either path or id is required.
id
string
optional
Lesson ID, usually the filename without .md, e.g. auto-merge-ci-pipeline. Either id or path is required.
Raw schema
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Lesson path relative to the repository, e.g. lessons/core/auto-merge-ci-pipeline.md — must be a file under lessons/ ending in .md (other repository files are not readable through this tool). Either path or id is required."
},
"id": {
"type": "string",
"description": "Lesson ID, usually the filename without .md, e.g. auto-merge-ci-pipeline. Either id or path is required."
}
}
}
misakanet_submit_intake
[OPEN TRIAGE / INTAKE] Use misakanet_submit_intake when you only have a partial failure description or want to ask a question; use misakanet_write_lesson (Bearer required) once you already have structured title/domain/problem/root_cause/fix. submit_intake is open, rate-limited, no Bearer — output is a GitHub issue for maintainer triage, NOT a merged lesson — its labels follow the kind: question → `needs-answer`, proposal → `needs-human-review`, a failure report → `pending-review`.
Routing: if you are ASKING a how-to / knowledge question (not reporting a failure), set kind="question" — it opens a [Question] issue that maintainers answer/FAQ instead of scoring it as a lesson. If kind is omitted, the server auto-detects question-shaped content (no error/fix/verification + question phrasing).
Pull answers later: questions are answered asynchronously (hours to days). Re-call this tool with the SAME problem text later and follow the returned poll_hint — the dedup response returns the maintainer's answer once it exists ({answered:true, answer}), and once your report has become a lesson it returns a conversion receipt ({converted:true, receipt, events}) naming the lesson, its path and its evidence_level; or re-run misakanet_search on the topic for FAQ hits. Every response also carries dedup_key, and poll_hint.recheck_after_seconds says when re-checking is worth it (21600s for questions, 86400s for failure reports).
Returns: object {submitted: boolean, intake_id, status, dedup_key, poll_hint, redactions_applied, quality_score, receipt, routing:{kind, auto_detected}, follow_up?}; `surface_report` is the intake's **surface check**: command-shaped tokens in your submission that the public corpus has never indexed (`null` = could not check, `[]` = checked and nothing unknown). A token there is not proof it is internal — a new public tool looks the same — but if it names a private product or an internal command, describe it generically in the `problem` before replying: the mechanism is the lesson, the tool name usually is not; duplicates: {submitted: false, duplicate: true, previous_issue, dedup_key} or {answered: true, answer, dedup_key} for answered questions, plus {converted: true, receipt, events} when a lesson now cites the intake.
Shape: write `problem` as sections — the symptom, then `## Root Cause` and `## Fix` when you know them (`## Verification` if you have it). A report without a root cause is still filed, but it cannot become a lesson automatically: it waits for a person, and the queue is long. **If you do have a root cause or a fix, the submission is lesson-shaped and needs two more fields**, because every new lesson in this corpus must carry them (`lessons/TEMPLATE.md`): `trigger` — the error fragment or keywords a future search would use, <=160 chars, not the title again; and `verification` — how a reader confirms the fix, as a checkable pass/fail. Without them nothing is filed (and nothing is deduped), and the response names what is missing; with them the intake is convertible.
Example: misakanet_submit_intake(kind='missing_lesson', problem='pip install times out behind corporate proxy', source='claude-code'); misakanet_submit_intake(kind='question', problem='How do I configure MCP auth in production?', source='claude-code')
Parameters11
kind
string
optional
missing_lesson (knowledge gap), stale_lesson (outdated lesson), new_lesson_candidate (new failure mode), question (ask for help), or proposal (a plan / product request that is explicitly not a failure report — decided, never converted to a lesson).
problem
string
required
Required: the symptom first, then `## Root Cause` and `## Fix` sections when known (max 2000 chars). Reports with those sections can become lessons automatically.
error
string
optional
Optional: short error message (auto-redacted).
what_tried
string
optional
Optional: what was attempted.
fix
string
optional
Optional: how it was resolved.
trigger
string
optional
Required for a lesson-shaped submission (one with a `## Root Cause`/`## Fix`, or a `fix`): the error fragment or keywords a future search would use, <= 160 chars. This is the lesson's `trigger:` frontmatter (`lessons/TEMPLATE.md`, #1783) — what makes it findable rather than a story about one project. The server refuses a lesson-shaped submission without it instead of filing one the corpus can never accept.
verification
string
optional
Required for a lesson-shaped submission: how a reader confirms the fix worked, as a checkable pass/fail (<= 200 chars). This becomes the lesson's `verify:` field; without it the claim is unverifiable and the corpus will not take it.
matched_lesson_id
string
optional
Optional: lesson ID that was checked but didn't help.
source
string
optional
Calling client: codex, claude-code, cursor, dsh, curl, cindy, or other.
contributor
string
optional
Optional: contributor identity (GitHub username, agent name, or email). Included in issue body for attribution.
notify_email
string
optional
Optional: an email for the ANSWER only, and only for kind="question". Ask the user first — never invent it. It is used to send one confirmation message now and, once confirmed, one notification when the answer is ready (the issue URL; never the reporter's text). Omit it and the pull path (me_inbox / FAQ) is unchanged.
Raw schema
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "missing_lesson (knowledge gap), stale_lesson (outdated lesson), new_lesson_candidate (new failure mode), question (ask for help), or proposal (a plan / product request that is explicitly not a failure report — decided, never converted to a lesson)."
},
"problem": {
"type": "string",
"description": "Required: the symptom first, then `## Root Cause` and `## Fix` sections when known (max 2000 chars). Reports with those sections can become lessons automatically."
},
"error": {
"type": "string",
"description": "Optional: short error message (auto-redacted)."
},
"what_tried": {
"type": "string",
"description": "Optional: what was attempted."
},
"fix": {
"type": "string",
"description": "Optional: how it was resolved."
},
"trigger": {
"type": "string",
"description": "Required for a lesson-shaped submission (one with a `## Root Cause`/`## Fix`, or a `fix`): the error fragment or keywords a future search would use, <= 160 chars. This is the lesson's `trigger:` frontmatter (`lessons/TEMPLATE.md`, #1783) — what makes it findable rather than a story about one project. The server refuses a lesson-shaped submission without it instead of filing one the corpus can never accept."
},
"verification": {
"type": "string",
"description": "Required for a lesson-shaped submission: how a reader confirms the fix worked, as a checkable pass/fail (<= 200 chars). This becomes the lesson's `verify:` field; without it the claim is unverifiable and the corpus will not take it."
},
"matched_lesson_id": {
"type": "string",
"description": "Optional: lesson ID that was checked but didn't help."
},
"source": {
"type": "string",
"description": "Calling client: codex, claude-code, cursor, dsh, curl, cindy, or other."
},
"contributor": {
"type": "string",
"description": "Optional: contributor identity (GitHub username, agent name, or email). Included in issue body for attribution."
},
"notify_email": {
"type": "string",
"description": "Optional: an email for the ANSWER only, and only for kind=\"question\". Ask the user first — never invent it. It is used to send one confirmation message now and, once confirmed, one notification when the answer is ready (the issue URL; never the reporter's text). Omit it and the pull path (me_inbox / FAQ) is unchanged."
}
},
"required": [
"problem"
]
}
misakanet_write_lesson
[STRUCTURED COMMIT / VALIDATED SUBMISSION] Submit a complete, structured failure lesson (title/domain/problem/root_cause/fix) as a formal submission. Requires authentication (Bearer token in header) — this is the 'validated author' path, not open triage. Output goes through lesson-gate/lint/review and becomes a versioned lesson in the git repo. For quick open reports when you only have a partial failure description, use misakanet_submit_intake instead (no Bearer). Lessons are immutable once merged — corrections go through a new intake/PR, so there is intentionally no misakanet_update_lesson/misakanet_delete_lesson.
Returns: object {lesson_id: string, status: 'pending_review', quality_score: number}; or {submitted: false, error}.
Example: misakanet_write_lesson(title='pip timeout behind proxy', domain='python', problem='...', root_cause='...', fix='...')
Parameters9
title
string
required
Short descriptive title.
domain
string
required
Domain: devops, python, network, feishu, rag, fanuc, mcp, etc.
problem
string
required
What failed (required).
root_cause
string
required
Why it failed (required).
fix
string
required
How to fix it (required).
verification
string
optional
How to confirm the fix works.
tags
string
optional
Comma-separated tags.
source
string
optional
Source: codex, claude-code, cursor, dsh, curl, cindy, etc.
contributor
string
optional
Optional: contributor identity (GitHub username, agent name, or email). Included in lesson frontmatter for attribution.
[GUARD / RISK CHECK] Check risk level before executing high-risk operations. Matches agent intent against lesson triggers to provide proactive warnings. Use before RAG builds, WSL/GPU tasks, bulk imports, or any operation that might fail. Choosing among the retrieval tools: no error yet and a task about to start → misakanet_memory_context (stdio-only); an actual error or keyword in hand → misakanet_search; something risky about to run and no error yet → this one, which returns a risk verdict and guards, not lesson content. No side effects — safe to call multiple times before acting. **Open, read-only:** anonymous calls are rate-limited; `misakanet_register` lifts the limit.
Returns: object {risk_level: 'low'|'medium'|'high', intent, matched_lessons: [{id, title, domain, relevance}], guards: [string]}.
Example: misakanet_preflight(intent='build RAG pipeline with ChromaDB')
Parameters2
intent
string
required
Required: what you plan to do (e.g. 'build RAG pipeline with ChromaDB').
context
string
optional
Optional: additional context about the environment or setup.
Raw schema
{
"type": "object",
"properties": {
"intent": {
"type": "string",
"description": "Required: what you plan to do (e.g. 'build RAG pipeline with ChromaDB')."
},
"context": {
"type": "string",
"description": "Optional: additional context about the environment or setup."
}
},
"required": [
"intent"
]
}
misakanet_me_events
[READ-ONLY EVIDENCE] Return evidence of a lesson being reused. E4 is observed reuse: `search_signals` shows two or more distinct clients actually retrieved the lesson — a count of requests, never of prose. Regression-benchmark citations, helpful votes and a lesson's own `verified by:` line are E3 hints: a citation is sandbox-level evidence, a vote is one person's opinion, and a provenance line is the lesson talking about itself, so none of them can confer E4. Use to check whether a lesson is proven by real usage, not just self-reported. Provide lesson_id or lesson_path — if neither is supplied the tool returns {error}. Semantically 'misakanet_get_my_events' (evidence for the lessons your node submitted/used); kept as me_events for backward compatibility. No auth required (read-only, rate-limited).
Returns: object {lesson_id, events: [{type, count|queries|sources, evidence_level}], evidence: 'E0'|'E3'|'E4', note}.
Example: misakanet_me_events(lesson_id='dco-auto-fix-workflow')
Parameters2
lesson_id
string
optional
Lesson ID (filename stem), e.g. dco-auto-fix-workflow. Either lesson_id or lesson_path is required.
lesson_path
string
optional
Optional full path, e.g. lessons/core/dco-auto-fix-workflow.md. Either lesson_id or lesson_path is required.
Raw schema
{
"type": "object",
"properties": {
"lesson_id": {
"type": "string",
"description": "Lesson ID (filename stem), e.g. dco-auto-fix-workflow. Either lesson_id or lesson_path is required."
},
"lesson_path": {
"type": "string",
"description": "Optional full path, e.g. lessons/core/dco-auto-fix-workflow.md. Either lesson_id or lesson_path is required."
}
}
}
misakanet_me_inbox
[AGENT READABLE INBOX] Check the status of a previously submitted intake (question, missing_lesson, etc.) without re-submitting. Accepts an intake_id (e.g. 'issue-1234' or '1234') for question intakes, or a dedup_key (the 8-char FNV-1a key from a prior submit_intake response) for any intake. Returns: {status: 'answered'|'pending'|'converted'|'unknown', ...} — 'answered' includes the maintainer's answer, 'converted' includes the lesson_id this intake became, and 'unknown' means the lookup could not determine it, which is not the same answer as 'never happened'. Read-only, rate-limited, no auth required.
Returns: object {intake_id, status, answer?, lesson_id?, issue_url?, note}.
Example: misakanet_me_inbox(intake_id='issue-1528') or misakanet_me_inbox(dedup_key='9f8e7d6c')
Parameters2
intake_id
string
optional
Question intake ID from a prior submit_intake response, e.g. 'issue-1528' or '1528'; for non-question intakes use dedup_key. Either intake_id or dedup_key is required.
dedup_key
string
optional
The dedup_key (8-char FNV-1a hex key) from a prior submit_intake response. Either intake_id or dedup_key is required.
Raw schema
{
"type": "object",
"properties": {
"intake_id": {
"type": "string",
"description": "Question intake ID from a prior submit_intake response, e.g. 'issue-1528' or '1528'; for non-question intakes use dedup_key. Either intake_id or dedup_key is required."
},
"dedup_key": {
"type": "string",
"description": "The dedup_key (8-char FNV-1a hex key) from a prior submit_intake response. Either intake_id or dedup_key is required."
}
}
}
A pip install times out behind a corporate proxy. An agent finds the fix. Days later the same
timeout appears on another machine, under another model — and is debugged from scratch, because the
fix was never written down anywhere the next agent looks.
MisakaNet is that place: a git-backed failure memory. Every lesson is a Markdown file in this
repository — graded by evidence, reviewed like code, retrieved by an agent instead of guessed at.
You fail once; the next agent does not.
Agent-native interfaces: MCP server (8 tools), WebMCP, llms.txt,
A2A discovery via .well-known/agent-card.json. The local stdio server (pip install misakanet)
ships 11 — the hosted endpoint is a subset; docs/mcp.md has both rows.
The installer-managed row is what npx @misaka-net/misakanet-setup writes into each host's config.
For DeepSeek Harness that is the rules half only ($DSH_HOME/AGENTS.md): its tools come from the
plugin in the row above, which the installer prints as the one manual step.
Updates: dsh plugin --profile web update misakanet@latest.
Installer updates: npx @misaka-net/misakanet-setup@latest.
Full prerequisites and the two-package trap: How to use it.
Your first five minutes
1. Ask it something you have actually broken. No client installed? This curl is the whole interface:
2. Read what came back. A hit returns the lesson, its evidence_level, and its path — open the
file and read the fix before running any command in it. A miss returns no_match plus a ready-to-call
intake: the corpus saying it does not know this one yet.
3. Check the trust signal, not the tone.E0–E3 say how far a lesson was verified; E4 is the
one nobody can write or vote into.
What is MisakaNet?
Git-backed failure memory for AI coding agents. An error shows up → the agent searches → it
applies a fix somebody already verified → if nothing matches, the miss becomes an intake, and the
intake becomes a lesson for the next agent.
Every lesson is a Markdown file: reviewed like code, graded by evidence, retrieved with BM25 over the
Python standard library. The hosted MCP endpoint adds an optional semantic fallback (bge-m3 +
Vectorize) only when BM25 returns no match; MISAKANET_SEMANTIC=0 disables it. No vector database is
required locally, and 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
E0 intake → E1 reviewed → E2 reproduced → E3 CI verified → E4 observed reuse by two or more distinct clients
It is not
It is
❌ a general memory system
✅ a failure-recovery knowledge layer
❌ an agent runtime
✅ a searchable lesson database
❌ a mandatory vector database / RAG stack
✅ BM25 first; optional, disable-able semantic fallback on the hosted endpoint
❌ a skill marketplace
✅ debugging knowledge from real sessions
❌ a general-purpose benchmark platform
✅ a corpus graded by evidence; a 267-query retrieval run is published, and the older recitation benchmark is paused
What it answers — and what it does not
MisakaNet answers for the failures it has indexed, and only those. When nothing matches the reply is
no_match plus a ready-to-call intake — the corpus saying "not this one yet", not a dead end.
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. → FAQ
Where it is today
The numbers that move are badges, on purpose: the Lessons badge renders
data/badges/lessons.json, regenerated by update-badges.yml, so it can lag a run but is never a
hand-typed total.
The top of the evidence ladder is observed, not declared.E4 needs an observation — two
distinct clients actually retrieving a lesson — so no lesson file can carry it: the corpus declares
none (declared distribution, regenerated and checked by CI), and the
number that exists is the worker's daily reading of search_signals, published in the
heartbeat.
Search is BM25 first; the hosted endpoint can fall back to embeddings. Local/offline remains
stdlib BM25; the fallback runs only when BM25 returns no match, and MISAKANET_SEMANTIC=0 turns it
off. A corpus gap is still a miss: the reply is no_match plus an intake, not an empty page.
Reported gaps arrive faster than they are triaged. The intake queue is the honest bottleneck.
The corpus is downloadable and citable.data.misakanet.org publishes a versioned
bundle — the full corpus, the benchmark query set, and every run artifact — with a
per-file SHA-256 and an explicit license per file (DATASET.md). The counts
live in each version's manifest.json, not in prose.
Retrieval benchmark: 267 queries, BM25 vs semantic fallback
On 2026-10-27 the hosted endpoint's retrieval path was evaluated on 267 queries, one per lesson
generated by Workers AI 70B. Both arms used the same eval worker and corpus; only
MISAKANET_SEMANTIC changed.
arm
R@1
R@5
no_match
BM25
0.210
0.225
0.712
semantic fallback
0.446
0.472
0.453
The fallback improves R@1 by 23.6 points and cuts no_match by 25.9 points. It does not
meet the R@1 half of the target (0.446 < 0.46); no_match is within the target
(0.453 ≤ 0.50). A 113-query subset reaches 0.460/0.460, while 250 reaches 0.404/0.504: the sample is
large enough to show the fallback works, not large enough to call R@1 solved.
This is 267 queries from the 300-entry pool, not the full 650; 33 pool entries yielded no query, 2 semantic requests
errored, and the eval corpus was not refreshed. → full report
Reproduce it yourself: the gate's 42 queries against the live endpoint, in a Colab notebook. It clones the repository, runs scripts/bench_production_recall.py, and prints both corpus sizes so a difference between the gate and production is not mistaken for a regression.
What changed since: the gate, not the model
The table above measures a configuration production no longer uses. Until 2026-10-28 the semantic path
ran only when BM25 returned nothing, so a confident-but-wrong lexical hit suppressed it — 13 of the
20 recorded misses were exactly that. For queries containing CJK characters the two ranked lists are now
fused (reciprocal-rank) instead of one gating the other.
Measured on the live endpoint, 64 Chinese queries, 0 transport failures:
bucket
n
before
after
zh → zh
31
0.710
0.774
zh → en
33
0.455
0.697
zh → en, low overlap
14
0.214
0.500
For scale: bge-m3 pure cosine already reached 0.636 on the cross-lingual bucket, and a gemini
embedding 0.727 — so most of the gap was the decision to consult the vector path, not the model.
English queries are untouched (the fuse is gated on CJK characters) and sit at 15/20 against a floor of
16, which is where they were before this change. → full report
Recitation benchmark: what it measured, and why it is paused
One narrow question: when you hand a model a lesson, how much of that lesson comes back? The
metric is lesson_hit_rate — the share of the injected lesson's commands reproduced in the answer.
Read the setup before the number: the scenario in this benchmark is each lesson's own title, the injected
lesson is that same lesson,
no retrieval call is made, and correctness is not checked. It measures the recitation half of RAG:
necessary for MisakaNet to help, and not evidence that search finds anything.
The run is paused. Two independent runs of ≈500 scenarios each on 2026-09-22: 46.1% with the
lesson pasted in, 23.3% without. What remains is the last snapshot plus its dated record —
docs/benchmarks/latest.json.
1. Report a failure the corpus does not have. Search first, then call misakanet_submit_intake —
no account, no email, no token, a five-line report is enough. It becomes a tracked issue.
2. Reuse a lesson and leave the trace. A "this helped" vote is recorded as an E3 hint, not as
proof. The proof is quieter: your retrieval is counted, anonymously, as one more distinct client.
3. Translate this page. The README ships in three languages; a fourth is one merged PR away —
the open i18n tasks
carry the exact acceptance criteria.
What you get back: attribution. A lesson cites the intake that produced it (source:,
provenance.issue:), and the pipeline can emit a receipt naming the lesson and its evidence level.
Nothing here is a bounty: this repository pays nothing and promises nothing. Some issues carry
third-party reward banners added by our own automation; we do not administer them — see
Contributing.
How to use it
npx @misaka-net/misakanet-setup installs MisakaNet into your assistant's own config — the same
command for every client. The ten supported clients, and what each one gets, are in
the install page. Verify an install with
npx @misaka-net/misakanet-setup --verify; undo it with --uninstall.
Reads are anonymous and unlimited; registration is for writing (why).
Node ≥ 18 for the installer, Python ≥ 3.11 for the library and stdio server. Python 3.10 reached end-of-life on 2026-10-01, so this release needs 3.11 or newer — upgrade the interpreter before upgrading the package.
Other channels
Claude Code, as a plugin — /plugin marketplace add Ikalus1988/MisakaNet, then
/plugin install misakanet@misakanet: the hosted MCP tools, no installer, no local process.
DeepSeek Harness — dsh plugin --profile web add misakanet: mcp__misakanet__* tools plus the
session panel. The rules half (the "search before you act" block) is written by the installer into
$DSH_HOME/AGENTS.md; dsh has no plugin extension point for it, so the two halves stay separate.
The library in your own code — pip install misakanet-core.
The two-package trap (it cost a real install failure, #1849)
@misaka-net/misakanet-setup (npm) is the installer — it has a bin, no plugin entry. Use it
to teach your assistant to search.
misakanet (npm) is the DSH / Codex plugin — dsh plugin --profile web add misakanet.
This repository (git) is also a Claude Code plugin marketplace —
/plugin marketplace add Ikalus1988/MisakaNet.
misakanet (PyPI) is the stdio MCP server — python3 -m misakanet.server.
misakanet-core (PyPI) is the library (stdlib-only BM25; the hosted endpoint's semantic fallback is server-side) —
from misakanet.search import search_lessons.
Use it as a GitHub Action
When a workflow fails, the action searches the lessons and comments the closest match on the pull
request (optionally reporting the new error). Published on
GitHub Marketplace.
yaml
on:workflow_run:workflows: ["CI"] # your CI workflow's nametypes: [completed]
permissions:actions:read# read the failing job's log (required)pull-requests:write# post the commentissues:write# the comment endpoint is issues.createCommentjobs:intake:if:${{github.event.workflow_run.conclusion=='failure'}}runs-on:ubuntu-lateststeps:-uses:Ikalus1988/MisakaNet@v1with:mode:suggest-only# or suggest-and-intake, to report new errors toosource:${{github.repository}}
"Zero bounty" is a statement about this repository: MisakaNet pays nothing and promises nothing. It
is not a statement about the issue you are looking at. Some issues carry an Opire banner
advertising a third-party reward, added automatically by our own
scripts/question_autopilot.py — we do not administer those payouts,
and Opire is not mentioned in CONTRIBUTING.md. Verify any reward offer independently before you
plan work around it. The only thing this repository has ever honoured is a merged PR.
(#2903)
Check the checkout: python3 scripts/misakanet_cli.py smoke
Search before writing: python3 search_knowledge.py "your error here"
⚠️ Sandbox your agent before executing retrieved commands. Lessons are community-contributed —
review before running. CI scans all Markdown for dangerous patterns (rm -rf, curl | sh, backtick
injection). See SECURITY.md and LIMITATIONS.md.
Prefer MCP intake for missing or stale lessons; PRs are optional. Search first; if nothing matches,
call misakanet_submit_intake at https://misakanet.org/mcp — no account, no token. Never send
secrets or raw private logs. Protocol: docs/mcp-intake-guide.md.
Contributors
Built by the network, for the network. Zero bounties paid — only merge approval and eternal network gratitude. ⚡
License
Apache-2.0 — Copyright 2026 Ikalus1988. Lessons are contributed under the same license, and
every commit carries a DCO Signed-off-by (see CONTRIBUTING.md).