<div align="right">

[English](README.md) | [日本語](README.ja.md)

</div>

# MisakaNet

mcp-name: io.github.Ikalus1988/misakanet

> **Stop debugging the same error twice.**
>
> MisakaNet searches 393+ failure lessons so your agent skips known bugs.
>
> **Using MisakaNet?** Give us a ⭐ — it helps other agents find indexed failure lessons.
> **Agent-native interfaces** — [MCP server](https://misakanet.org/mcp) with 7 tools (`misakanet_search`, `misakanet_get_lesson`, `misakanet_submit_intake`, `misakanet_write_lesson`, `misakanet_preflight`, `misakanet_register`, `misakanet_me_events`), **WebMCP** (browser `document.modelContext`), `llms.txt` / `llms-full.txt`, and A2A discovery via `.well-known/agent-card.json`.

## 装到你自己的助手（Claude Code / Codex）

**一行命令**（需要 Node，Claude Code / Codex 本身就依赖它）：

```bash
npx @misaka-net/misakanet-setup
```

装完**把助手窗口关掉再打开一次**，然后随便挑一句带报错原文的片段问它（例如「switch vision model」
「context window exceeded」「tool call permission denied」——用错误原文里最独特的片段，别用整句自然语言），
它应该先去查经验库再回答。状态自检 `npx @misaka-net/misakanet-setup --verify`，卸载 `--uninstall`；想把本机环境回报给我们（外部验证悬赏要的就是这个）：`--report` 会打印一段**已脱敏**的 YAML，可直接粘到公开 issue。
（支持 Claude Code / Codex / Hermes / OpenClaw / codewhale；codewhale 额外两步：token 走环境变量
`export MISAKANET_TOKEN=…`、规则块只对受信任的项目生效。想让命中/未命中时**出声**：加 `--voice`
（默认关，静音 `MISAKANET_VOICE=0`）。）

### 三层结构：能力 / 接入 / 触发（读一遍就懂它到底做了什么）

| 层 | 是什么 | 缺了它会怎样 |
|---|---|---|
| **① 服务** | `https://misakanet.org/mcp`（Streamable HTTP，7 个工具，匿名 5 次/天/IP）或**本地 stdio**（clone 后 `python3 scripts/mcp_server.py`，无限额）| 没有可查的地方 |
| **② 接入** | `npx @misaka-net/misakanet-setup`：把服务写进每个助手**自己的**配置文件（Claude Code / Codex / Hermes / OpenClaw / codewhale 各一套）| 你得自己知道 5 种配置文件分别怎么写 |
| **③ 触发** | 规则块（「遇到报错先查经验库」）+ 检查点钩子（约 20 轮提醒沉淀）+ 14 天升级提示 | **端点在，但没有任何人会去调用它** |

分工要说清楚：**MCP 工具是 pull 型，端点永远不会主动调用**——"要不要查"始终由助手决定。
setup 保证的是"工具确实在"和"该查的时刻更容易被抓住"，不是"自动查询"。

> 容易混淆的两个同名包：**PyPI 的 `misakanet` / `misakanet-core` 是 Python 库**（本地索引或
> `--remote` 查服务），不负责把工具接进助手；**npm 的 `misakanet` 是 skill/插件包**
> （`SKILL.md` + DSH 插件入口），早期它只有说明书、没有工具——工具来自第 ① 层的服务。

### 装完你得到什么（逐条可自检）

1. **7 个 `misakanet_*` 工具出现在助手里** —— `codex mcp list` / `codewhale mcp tools` /
   `claude mcp list` / `hermes mcp list`；**证据**：列表里有 `misakanet` 且 7 个工具；
2. **助手被要求「遇错先查」** —— 问一句「switch vision model」「context window exceeded」这类片段，它应该先说查过经验库；
   **证据**：事件流里出现 `misakanet_search`（claude/codewhale 用 `--output-format stream-json`，codex 用 `--json`）；
3. **长会话会提醒沉淀** —— 约 20 轮后提醒把本次「失败 → 根因 → 修复 → 验证」变成一条课程
   （Claude Code 有真钩子；**Codex 没有用户级钩子**，靠规则）；
4. **每 14 天最多一行升级提示** —— 只提示，绝不在背后安装任何东西；
5. **随时可撤** —— `--verify` 看状态，`--uninstall` 还原（改写前会留 `.misakanet.bak` 备份）。

**不想用命令行、不知道配置文件在哪？** 把下面这句话**复制粘贴给助手**，它会自己装好、自己验证、用大白话回报：

```text
帮我接入 MisakaNet 失败记忆库：请读取 https://raw.githubusercontent.com/Ikalus1988/MisakaNet/main/integrations/agent-autostart/INSTALL_FOR_ME.md ，按里面的「第 2 部分：给你的要求」执行，做完用中文简单告诉我结果。
```

网络打不开上面那条网址时（部分网络会拦 `raw.githubusercontent.com`），把开头换 CDN 镜像：

```text
帮我接入 MisakaNet 失败记忆库：请读取 https://cdn.jsdelivr.net/gh/Ikalus1988/MisakaNet@main/integrations/agent-autostart/INSTALL_FOR_ME.md ，按里面的「第 2 部分：给你的要求」执行，做完用中文简单告诉我结果。
```

装的是三件事：① 注册 MCP 端点（读不限次，写入类工具需 token，安装器会顺手注册匿名节点）；
② 在助手的规则文件里写清"何时该查"；③ 装一个钩子，让"每 20 轮沉淀一次"真的会触发
（**只写规则不会触发**——助手不记账）。细节与支持度矩阵见
[integrations/agent-autostart/README.md](integrations/agent-autostart/README.md)，
非技术用户看 [INSTALL_FOR_ME.md](integrations/agent-autostart/INSTALL_FOR_ME.md)。

---

<p align="center">
  <img src="promotional/misaka-compare.jpg" width="720" alt="MisakaNet — Before: 30+ min manual debugging vs After: 0.02s with MCP"/>
</p>

<p align="center">
  <em>Core</em>
  &nbsp;&nbsp;
  <a href="https://github.com/Ikalus1988/MisakaNet/actions/workflows/pr-quality-gate.yml"><img src="https://github.com/Ikalus1988/MisakaNet/actions/workflows/pr-quality-gate.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/Ikalus1988/MisakaNet/tree/main/lessons"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Ikalus1988/MisakaNet/data/badges/lessons.json" alt="Lessons"></a>
  <a href="https://github.com/Ikalus1988/MisakaNet/blob/main/scripts/mcp_server.py"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Ikalus1988/MisakaNet/data/badges/tools.json" alt="MCP Tools"></a>
  <a href="https://github.com/Ikalus1988/MisakaNet/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Ikalus1988/MisakaNet?color=blueviolet" alt="License"></a>
  <a href="https://github.com/Ikalus1988/MisakaNet/stargazers"><img src="https://img.shields.io/github/stars/Ikalus1988/MisakaNet?style=social" alt="Stars"></a>
</p>

<p align="center">
  <em>Install</em>
  &nbsp;&nbsp;
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue" alt="Python"></a>
  <a href="https://pypi.org/project/misakanet/"><img src="https://img.shields.io/pypi/v/misakanet" alt="PyPI"></a>
  <a href="https://www.npmjs.com/package/misakanet"><img src="https://img.shields.io/npm/v/misakanet" alt="npm"></a>
  <a href="https://dsh-plugin.org/plugins/ikalus1988/misakanet"><img src="https://dsh-plugin.org/badges/listed.svg" alt="Listed on dsh-plugin.org"></a>
  <a href="https://dsh.directory/plugins/ikalus1988/misakanet"><img src="https://dsh.directory/badges/listed.svg" alt="Listed on DSH Directory"></a>
  <a href="https://www.dsh.so/artifact/misakanet/"><img src="https://www.dsh.so/badge/install/misakanet.svg" alt="dsh.so install"></a>
</p>

<p align="center">
  <em>Ecosystem</em>
  &nbsp;&nbsp;
  <a href="https://glama.ai/mcp/servers/Ikalus1988/MisakaNet/score"><img src="https://glama.ai/mcp/servers/Ikalus1988/MisakaNet/badges/score.svg" alt="Glama score"></a>
  <a href="https://glama.ai/mcp/connectors/org.misakanet/misaka-net"><img src="https://glama.ai/mcp/connectors/org.misakanet/misaka-net/badges/score.svg" alt="MisakaNet MCP connector – tool definition quality and endpoint health on Glama"></a>
  <a href="https://mcptoplist.com/server/io.github.Ikalus1988%2Fmisakanet"><img src="https://mcptoplist.com/badge/io.github.Ikalus1988%2Fmisakanet.svg" alt="MCP Toplist"></a>
  <!-- Smithery badge uses a shields.io 'endpoint' badge that dynamically reads the Kin
       score from data/badges/smithery.json -- updated daily by the update-smithery-badge
       workflow, so it stays in sync without manual PRs. -->
  <a href="https://smithery.ai/servers/misakanet/misakanet"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Ikalus1988/MisakaNet/refs/heads/data/badges/smithery.json" alt="Smithery"></a>
  <!-- HOL badge: the link still points at hol.org (its listing detector looks for the badge
       in the README, worth +2% trust), but the image is a static flat shield — the live
       hol.org/api/... endpoint is slow/unstable through shields.io and rendered as
       "inaccessible" / a mismatched for-the-badge style. -->
  <a href="https://hol.org/registry/plugins/Ikalus1988%2FMisakaNet"><img src="https://img.shields.io/badge/HOL%20Registry-listed-5599FE?style=flat" alt="MisakaNet on HOL Registry"></a>
  <a href="https://github.com/Ikalus1988/MisakaNet/tree/main/docs/benchmarks"><img src="https://img.shields.io/badge/Benchmark-Weekly%20Workers%20AI-blue" alt="Benchmark"></a>
</p>

---

## AI Agent Friendly

MisakaNet is optimized for AI agents:

- ✅ **MCP Server** — 7 tools for search, lessons, intake, reuse evidence
- ✅ **Smithery Deployed** — One-click install for AI agents
- ✅ **robots.txt** — AI crawlers allowed on public content
- ✅ **JSON-LD Schema** — Structured data for search engines
- ✅ **Content Signals** — Clear access policies for AI agents

→ [Full AI Agent Configuration](docs/cloudflare-waf-rules.md)

---

## Quick Start: Connect your agent

**Option 1 — Remote MCP (no install, no account):**

If your agent can make HTTP requests, it can use MisakaNet right now:

```bash
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"}}}'
```

No GitHub account. No email. No Bearer token. No browser. Just curl.

**Option 2 — Local MCP (for Claude Code / Cursor / Codex):**
```bash
git clone https://github.com/Ikalus1988/MisakaNet.git && cd MisakaNet
python3 scripts/mcp_server.py
# Add to your MCP config, then ask: "Search MisakaNet for tool call permission denied"
```

**Option 3 — PyPI (pip install):**
```bash
pip install misakanet
misakanet "database is locked"
# Or: python3 -m search_knowledge "your error here"
```

**Option 4 — Python library (for scripts/notebooks):**
```bash
pip install misakanet-core
```
```python
from misakanet.search import search_lessons
results = search_lessons("pip install timeout")
for r in results:
    print(r["title"], r["score"])
```

**Option 5 — DeepSeek Harness (DSH plugin):**
```bash
# Install from npm (recommended — published as misakanet@2.30.2)
# `dsh plugin` forwards to pnpm in the profile directory and requires --profile.
dsh plugin --profile web add misakanet@2.30.2

# Or install directly from git (same bundle, plus the repo's own python MCP server)
# dsh plugin --profile web add git+https://github.com/Ikalus1988/MisakaNet.git

# Make the failure-memory SKILL discoverable by agents
# (DSH scans ~/.dsh/skills and project .dsh/skills)
mkdir -p ~/.dsh/skills
cp -r skills/misakanet ~/.dsh/skills/

# Or run adapter directly
python3 scripts/mcp_deepseek_adapter.py
```

> **DSH bundle tools (`mcp__misakanet__*`)** are served by the public endpoint
> `https://misakanet.org/mcp` (Streamable HTTP), which the bundle row declares — so an
> **npm install is enough** and no local python is required. A profile that prefers the
> repo's own stdio server can override the row (`transport: stdio`, `command: python3`,
> `args: [scripts/mcp_server.py]`).
>
> Two install gotchas (#1734): `dsh plugin` needs `--profile <name>`, and a profile whose
> lockfile predates the release will silently keep an older copy — pin the version
> (`@2.30.1`) if no `mcp__misakanet__*` tools appear.

### Already installed? One command brings you current

```bash
npx @misaka-net/misakanet-setup@latest
```

Worth doing **once by hand** if you installed before **0.4.1**: those releases shipped no upgrade
notice *and* their installer skipped an existing hook, so re-running it could report success and
change nothing. Running the command above once (a) replaces that hook with the current one and
(b) from then on your assistant mentions an upgrade **at most once every 14 days**, in one line —
it never installs anything behind your back. Everything else about your setup is left alone: the
installer is idempotent, `--verify` shows the current state, and `--uninstall` reverses it.

> What is in the hook: the checkpoint reminder that asks your agent to distil a session's
> failure → root cause → fix → verification into an intake after ~20 turns, and the upgrade nudge.

### Try it now

| Method | Command | Time |
|---|---|---|
| Remote MCP | `curl -sS https://misakanet.org/mcp ...` | 10s |
| Local MCP | `git clone ... && python3 scripts/mcp_server.py` | 30s |
| Python lib | `pip install misakanet-core` | 15s |
| CLI smoke | `python3 scripts/misakanet_cli.py smoke` | 5s |

→ [Full quickstart (Remote MCP, CLI, Docker)](docs/quickstart.md) · [Troubleshooting](docs/troubleshooting.md)

### Register for unlimited access

Local stdio MCP is unlimited. For remote HTTP MCP, register to get a token:

```bash
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_register","arguments":{"agent_type":"your-agent"}}}'
```

Returns `node_id` + `token`. Use token for unlimited remote searches.

**Debug logging:** Set `MISAKA_DEBUG=1` (auth errors include debug context) or `MISAKA_DEBUG=2` (request/response logging). Debug context is stripped by default; only shown when enabled.

### WebMCP (Browser-based AI Agents)

MisakaNet's MCP server is exposed via [WebMCP](https://blog.cloudflare.com/webmcp/) — browser-based AI agents can use MisakaNet tools directly from the page, no install, no account:

1. **Server-side (already enabled)** — the Cloudflare **Site MCP Server** toolset points at `https://misakanet.org/mcp`.
2. **Visitor-side (zero config)** — open misakanet.org with a WebMCP-capable browser agent and MisakaNet tools are auto-discovered via `navigator.modelContext`.

> ⚠️ WebMCP is a **Developer Preview** — it currently requires a WebMCP-capable browser agent (Chrome beta / Cloudflare Browser Run lab). Anonymous browser agents share the 5 free reads/day quota; [register](docs/quickstart.md) for unlimited access.

→ [WebMCP Configuration Guide](docs/cloudflare-worker.md)

## What is this?

**Git-backed failure-memory for AI coding agents.** Zero dependencies. Zero server. Zero database.

Agent hits an error → search lessons → get a fix path. No prompt leaking, no raw logs stored.

### What you get

| Metric | Value | Description |
|---|---|---|
| **Lessons** | [![Lessons](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Ikalus1988/MisakaNet/data/badges/lessons.json)](https://github.com/Ikalus1988/MisakaNet/tree/main/lessons) | Failure-recovery knowledge base |
| **Domains** | [![Domains](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Ikalus1988/MisakaNet/data/badges/domains.json)](https://github.com/Ikalus1988/MisakaNet/tree/main/lessons) | rag, devops, fanuc, docker, feishu... |
| **Evidence Levels** | E0-E4 | Verified by humans, PRs, or agents |

### Evidence Levels

| Level | Meaning | Source |
|---|---|---|
| E0 | Community reported | Intake, issues |
| E1 | CI verified | Automated tests |
| E2 | PR merged | Code review |
| E3 | Maintainer verified | Human review |
| E4 | Production proven | Real-world usage |

### Best Practices

<details>
<summary>rag — ChromaDB crash on NTFS</summary>

**Problem:** ChromaDB SQLite backend fails on NTFS-mounted WSL paths.
**Fix:** Move DB to ext4: `mv ~/.chromadb /mnt/ext4/`.
**Verify:** `python3 -c "import chromadb; c=chromadb.Client(); print(c.heartbeat())"`.
</details>

<details>
<summary>devops — WSL terminal underscore corruption</summary>

**Problem:** WSL terminal paste swallows underscores under high load.
**Fix:** Use tmux or pipe stdin via temp script files.
**Verify:** `echo "test_underscore_command"` shows correct output.
</details>

<details>
<summary>fanuc — Karel ERR_ABORT vs ERR_PAUSE</summary>

**Problem:** Robot hard-aborts instead of pausing on error.
**Fix:** Use `POST_ERR(..., ERR_PAUSE)` (value 1) instead of `ERR_ABORT` (value 2).
**Verify:** Robot pauses, system stays responsive.
</details>

> More best practices for `docker`, `feishu`, `network`, `claude`, `hub` → [`docs/domains/`](docs/domains/)

### Integration surfaces

| Surface | What it does | Entry point |
|---|---|---|
| MCP | Search, get lesson, submit intake | `python3 scripts/mcp_server.py` |
| CLI | Direct commands | `python3 search_knowledge.py` |
| SKILL.md | Agent guidance | Auto-loaded by Claude Code |
| Remote MCP | HTTP endpoint | https://misakanet.org/mcp |
| DSH Adapter | Harness integration | `python3 scripts/mcp_deepseek_adapter.py` |
| Glama Connector | MCP via Glama gateway (no self-hosting) | https://glama.ai/mcp/connectors/org.misakanet/misaka-net |
| Smithery | MCP via Smithery registry | https://smithery.ai/servers/misakanet/misakanet |

**Use MisakaNet in Claude Code / Cursor / VS Code via Glama — 3 steps**

> Your agent hits an error (DCO failure, pip timeout, token leak…). MisakaNet
> gives it 393+ **indexed failure-recovery lessons** so it finds the fix
> instead of re-debugging. No self-hosting — the Glama gateway proxies to
> our hosted endpoint.

1. Open the [Glama connector page](https://glama.ai/mcp/connectors/org.misakanet/misaka-net)
   and click **Connect through Glama MCP Gateway** (sign in if prompted).
2. Glama generates your personal gateway URL:
   `https://glama.ai/endpoints/<your-connection-profile>/mcp`.
3. Add it to your client as a **remote MCP server**:
   - **Claude Code**: `claude mcp add --transport http misakanet <URL>`
   - **Cursor**: Settings → MCP → Add → URL type → paste
   - **VS Code**: install an MCP extension, add a remote server → paste
   - **ChatGPT (desktop)**: Settings → Connectors → paste URL

Every call is logged in your Glama analytics.

**Or via Smithery** (also no self-hosting):

```bash
npx -y smithery mcp add misakanet/misakanet
```

Runs the same hosted endpoint through the [Smithery registry](https://smithery.ai/servers/misakanet/misakanet).

### Agent compatibility

| Agent | Integration | Status |
|---|---|---|
| Claude Code | MCP + SKILL.md | ✅ Supported |
| Codex | MCP + AGENTS.md | ✅ Supported |
| Cursor | MCP + rules | ✅ Supported |
| DeepSeek Harness | MCP adapter | ✅ Supported |
| Gemini CLI | MCP | ✅ Supported |
| Windsurf | MCP | ✅ Supported |
| OpenCode | MCP | ✅ Supported |
| Copilot | MCP | ✅ Supported |

**🔥 New: No-account MCP intake.** If your agent finds no good lesson, submit a failure case directly — see [Quick Start Option 1](#quick-start-connect-your-agent) above for the curl command.

**No GitHub account. No email. No Bearer token. No browser.** The intake becomes a maintainer-visible GitHub issue for review.

### See it in 8 seconds

![Search lesson demo](promotional/search%20lesson.gif)

### Contribute in 3 minutes

1. Run `python3 scripts/misakanet_cli.py smoke` — verify it works
2. Search for a failure you've hit: `python3 search_knowledge.py "your error here"`
3. Found nothing? [Submit a 5-line failure note →](https://github.com/Ikalus1988/MisakaNet/issues/new?template=lesson-feedback.yml)

→ [CONTRIBUTING.md](CONTRIBUTING.md) · [Good first issues](https://github.com/Ikalus1988/MisakaNet/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)

### What this is NOT

| MisakaNet is NOT | What it is instead |
|------------------|-------------------|
| ❌ A general-purpose memory system | ✅ Failure-recovery knowledge layer |
| ❌ An Agent runtime or framework | ✅ Searchable lesson database |
| ❌ A vector database or RAG system | ✅ BM25 keyword search (zero deps) |
| ❌ A cloud service requiring signup | ✅ `git clone` → search locally |
| ❌ A skill marketplace | ✅ Debugging knowledge from real sessions |

> **MisakaNet is purpose-built for one thing:** helping agents avoid repeating known failures.
> It is not a general memory layer, not a runtime, and not a vector database.

### Measured: lessons make models smarter

Weekly benchmark on real failure scenarios (Cloudflare Workers AI, 2026-08-30):

| Model | Without lesson context | With lesson context | Gain |
|---|---|---|---|
| llama-3.2-3b (light) | 21% hit | **43% hit** | **2× — lesson context doubles a weak model** |
| llama-3.3-70b (strong) | 42% hit | **73% hit** | **+31%** |

Lesson context is a **RAG win across the board**: injecting the matching
failure-recovery lesson lifts answer quality for every model — the smaller
the model, the bigger the relative gain. Details:
[benchmark-2026-08-30](docs/benchmarks/benchmark-2026-08-30.json)

→ [Full changelog](CHANGELOG.md) · [Release notes](https://github.com/Ikalus1988/MisakaNet/releases)

### How it works

```
1. Agent hits an error (DCO, pip, token, MCP, encoding, CI)
        ↓
2. Search MisakaNet for matching failure-recovery lessons
        ↓
3. Read the matching lesson
        ↓
4. Apply the documented fix
        ↓
5. If no lesson matches, opt in to capture a redacted failure report
        ↓
6. Maintainers review accepted contributions and convert them into draft lessons
```

**Stuck on a failure?** Search the lessons before opening a PR:

| Problem | Lesson |
|---|---|
| 🔴 DCO sign-off fails on Windows | [→ dco-auto-fix-workflow](lessons/core/dco-auto-fix-workflow.md) |
| 🔴 pip install timeout / SSL error | [→ pip-install-timeout-ssl](lessons/contrib/pip-install-timeout-ssl.md) |
| 🔴 Secret scan / token in commit | [→ codeql-alert-dismissal-false-positive](lessons/contrib/codeql-alert-dismissal-false-positive.md) |
| 🔴 GitHub API 401 / token expired | [→ github-401-credential-lookup](lessons/contrib/github-401-credential-lookup.md) |

[🔍 Search all lessons →](https://ikalus1988.github.io/MisakaNet/search/)

Didn't find a fix? [📮 Share your failure lesson →](https://github.com/Ikalus1988/MisakaNet/issues/new?template=lesson-feedback.yml) — unsolved failure families show up on the public [demand board](workers/README.md#insights-endpoints-issue-591) so contributors know what to write next.

**Agent-only intake (no GitHub account, no email, no browser pairing):**

If an agent cannot find a good lesson, it can submit a redacted intake directly through the remote MCP endpoint. `misakanet_submit_intake` does not require a Bearer token; it creates a maintainer-visible GitHub issue labeled `intake`, `mcp-intake`, and `pending-review`.

**Questions vs failures:** reporting a failure → `kind="missing_lesson"`; asking a how-to / knowledge question → `kind="question"` (opens a `[Question]` issue that maintainers answer or fold into an FAQ, instead of scoring it as a lesson). If `kind` is omitted, question-shaped content (question phrasing with no error/fix/verification) is auto-routed to `question`.

```bash
curl -sS https://misakanet.org/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Origin: https://claude.ai" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"misakanet_submit_intake","arguments":{"kind":"missing_lesson","problem":"SHORT REDACTED PROBLEM","error":"OPTIONAL REDACTED ERROR","what_tried":"OPTIONAL","fix":"OPTIONAL","verification":"OPTIONAL","source":"remote-agent"}}}'
```

Do not send secrets or raw private logs. Intake is **not auto-published**; maintainers review it before turning it into a lesson.

---

## What is the failure-memory protocol?

A **shared experience substrate** for AI agents. One agent stalls on a failure → documents the workaround → all agents *skip that same failure path*. **Two surfaces, one knowledge core:** a local stdio MCP (`git clone` + `python3 search_knowledge.py`, zero-dependency BM25) and a remote HTTP MCP (`misakanet.org/mcp`, Cloudflare Worker + D1, anonymous search).

> In practice, MisakaNet is most valuable as a recovery layer *during* task execution, not as a separate reading experience. The primary direct user is usually an **agent**, not a human. Agents reuse known fixes so future tasks stall less on previously-solved failures. Human users often benefit indirectly: fewer stuck tasks, fewer repeated recovery steps, less manual intervention.

- **Lesson** — a piece of knowledge. Markdown file with problem → root cause → fix → verify.
- **Node** — an AI agent or developer who contributes and searches lessons.
- **Search** — BM25 keyword retrieval across all lessons. Zero dependencies. Python stdlib only.

```mermaid
flowchart LR
    subgraph Edge["☁️ Cloudflare Edge"]
        Worker["Cloudflare Worker<br/>(misakanet-register-proxy)"]
        D1[("D1 — lessons + redaction")]
        KV[("KV — rate-limit")]
        Intake["GitHub Issues API<br/>intake → issue"]
    end

    subgraph Local["💻 Local Node (git clone)"]
        User["Local Agent / Dev"]
        CLI["CLI — search_knowledge.py"]
        MCP["MCP stdio — scripts/mcp_server.py<br/>(misakanet == 2.30.2)"]
        Engine["BM25 Engine — engine.py"]
        Lessons[("lessons/ — git source of truth")]
        Profile[("profile.json — node profile")]
    end

    Crawler["🤖 Remote Agent / Crawler<br/>(anonymous)"]
    CI["⚙️ GitHub CI<br/>(50 workflows)"]

    Crawler -- "POST /mcp" --> Worker
    Worker -- "lessons" --> D1
    Worker -- "rate-limit" --> KV
    Worker -- "submit_intake" --> Intake
    Intake -. "review → lesson" .-> Lessons

    User -- "shell" --> CLI
    User -- "JSON-RPC" --> MCP
    CLI -- "query" --> Engine
    MCP -- "search / get_lesson" --> Engine
    Engine -- "BM25 scan" --> Lessons
    Engine -- "stage lookup" --> Profile

    CI -- "PR gate" --> Lessons
    Lessons -. "deploy Worker on release" .-> Worker
```

> **Three paths:** ① **Remote HTTP MCP** — anonymous agent → `misakanet.org/mcp` → Worker → D1 (lessons + redaction) + KV (5 reads/day/IP) + intake → GitHub issue. ② **Local stdio MCP** — `scripts/mcp_server.py` → BM25 engine over `lessons/` (unlimited). ③ **Contribution** — PRs pass 50 workflows; intake issues become lessons after maintainer review.

### Why?

AI agents hit the same bugs across different environments. Each one independently debugs pip on WSL, ChromaDB on NTFS, or FANUC error codes. The fix exists in someone's terminal history, invisible to everyone else. MisakaNet turns individual debugging sessions into shared, searchable knowledge.

### Start here: choose your journey

MisakaNet is useful in different ways depending on what you are trying to do:

| I am... | Start with |
|---|---|
| 🔴 Debugging a real failure | [Search existing lessons](https://ikalus1988.github.io/MisakaNet/search/) before retrying |
| 🤖 Building an AI agent / tool | Use lessons as [failure-memory](docs/mcp-quickstart.md) for your workflow |
| 🧪 Using DeepSeekHarness | Connect the [DeepSeekHarness MCP adapter](docs/integration/deepseek-harness.md) as a recovery-memory plugin |
| 🔧 Contributing a fix | Read [CONTRIBUTING.md](CONTRIBUTING.md) for code style + PR checklist, check [related lessons](https://ikalus1988.github.io/MisakaNet/search/), then open a small PR |
| 📝 Sharing a failure case | Submit a [5-line failure note](https://github.com/Ikalus1988/MisakaNet/issues/new?template=lesson-feedback.yml) — no polished PR required |
| 📊 Evaluating agent learning | Run the [benchmarks](scripts/retrieval_noisebench.py) and compare reuse behavior |
| 💬 Reporting friction | [MCP intake](docs/integrations/mcp-remote.md) or [journey report #510](https://github.com/Ikalus1988/MisakaNet/issues/510) |
| ❓ New to MisakaNet | Read the [FAQ](FAQ.md) for installation, MCP pairing, troubleshooting, and contribution answers |

> 👉 **New here?** [Search failure lessons →](https://ikalus1988.github.io/MisakaNet/search/)
>
> No GitHub account? Submit via MCP intake (no auth needed) → [MCP Intake Guide](docs/integrations/mcp-remote.md)
>
> Understanding the system → [Label system](docs/label-system.md) · [Troubleshooting](docs/troubleshooting.md)

### Lesson vs Skill

MisakaNet lessons are **not** skills.

| | Lesson | Skill |
|---|---|---|
| **What it is** | Failure experience / debugging knowledge | Executable capability / workflow / tool |
| **Goal** | Help an agent or developer avoid repeating a known failure | Help an agent complete a task |
| **Content** | Problem → root cause → fix → verification | Instructions, scripts, templates, tools |
| **When to use** | Before or after something goes wrong | When executing a task |
| **Granularity** | One specific failure pattern | A complete capability or workflow |
| **Value** | Avoid repeated failures | Improve execution efficiency |

**One line:** Skill teaches an agent *how to do something*. Lesson teaches an agent *what went wrong before and how not to fail again*.

> **MisakaNet is not another skill marketplace. It is a shared failure-memory layer for developers and agents.**
> Lessons come from real debug sessions, colleague-shared memory dumps, agent failure logs, and public contributor feedback.

```
Tools / MCP / Skills  →  do things
MisakaNet Lessons     →  avoid known failures
Benchmarks            →  measure reuse and robustness
```

Use skills when you want an agent to do something. Use MisakaNet when you want an agent or developer to avoid repeating known failures.

---

## How is this different?

MisakaNet is **not** a general memory system (Mem0 / agentmemory / Memorix etc. are
a different category — see [What this is NOT](#what-this-is-not) above). The closest
relatives are *failure/experience knowledge* MCP servers for AI agents (Glama-listed):

| Project | ⭐ | 定位（shared model） | 与 MisakaNet 差异 |
|---------|-----|---------------------|-------------------|
| **MisakaNet** | ![stars](https://img.shields.io/github/stars/Ikalus1988/MisakaNet?style=social) | Public Git-backed failure memory — indexed failure lessons, searchable by agents & humans | — |
| [deadends.dev](https://github.com/dbwls99706/deadends.dev) | ![stars](https://img.shields.io/github/stars/dbwls99706/deadends.dev?style=social) | Structured failure knowledge — dead ends, workarounds, error chains | 同类最接近：同样存"失败→解法"；差异：我们的 lesson 走 DCO 审校 + 证据分级 + 可全文搜索/基准护栏，且零依赖本地可查 |
| [Prior](https://github.com/cg3inc/prior_mcp) (io.cg3) | ![stars](https://img.shields.io/github/stars/cg3inc/prior_mcp?style=social) | Shared knowledge base of *proven solutions* for Claude/Cursor/etc. | 偏"已验证方案"经验交换，非专门失败记忆；我们按失败原语组织、命中可量化 |
| [Kira](https://github.com/aibenyclaude-coder/Kira) | ![stars](https://img.shields.io/github/stars/aibenyclaude-coder/Kira?style=social) | Auto-manages Skills & Scars (persistent failure warnings) for agents | Scars 偏"本次会话/项目级警告"；我们是跨项目、公开、可审计的失败课程库 |
| [Casebook-MCP](https://github.com/AgentPostmortem/Casebook-MCP) | ![stars](https://img.shields.io/github/stars/AgentPostmortem/Casebook-MCP?style=social) | Remote MCP over AgentPostmortem — registry of documented AI-agent failures | 同为 agent 故障复盘库；差异：我们带 intake 闭环 + 证据分级 + 课程可升格 contrib |
| [knownissue](https://github.com/gong8/knownissue) | ![stars](https://img.shields.io/github/stars/gong8/knownissue?style=social) | Shared debugging memory — search/report/patch/verify issues | 同为调试记忆共享；我们侧重"已审校 lesson 可检索复用"，非 issue 工单闭环 |
| [fix-memory-mcp](https://github.com/l111403717-cloud/fix-memory-mcp) | ![stars](https://img.shields.io/github/stars/l111403717-cloud/fix-memory-mcp?style=social) | Local-first coding fix memory for agents | 本地私有 fix 记忆；我们是公开共享 + 网络化检索 |
| [cogmem](https://github.com/dcondrey/cogmem) | ![stars](https://img.shields.io/github/stars/dcondrey/cogmem?style=social) | Self-improving, verifiable memory layer for coding agents | 通用 agent 记忆层；我们是失败知识专库，非会话/状态记忆 |

> Glama 目录上还可见 AskAgent（错误原文→根因→修复档案）、Civis（结构化方案/构建日志检索）、
> FixFlow 等条目，但未发现公开 GitHub 仓库，未列入上表（避免引用无法核验的链接）。
> 上表仅收录可核验仓库；⭐ 为写时快照。

> **MisakaNet is not the only shared failure-memory system.** Its edge is:
> - **Git-backed** — every lesson is a Markdown file, fully auditable, version-controlled
> - **Zero-dependency** — pure Python stdlib, no vector DB, no embedding model, no server
> - **Purpose-built** — failure-recovery knowledge, not general memory
> - **Public by default** — lessons are open, contributions are DCO-gated
>
> General-memory systems (Mem0, Agent-KB, agentmemory) offer stronger semantic recall /
> state management, but require heavier deployment. MisakaNet is lighter, more auditable,
> and purpose-built for failure-recovery.

> 📦 Core engine is **zero-dep** (pure Python stdlib). Optional extras: `pip install misakanet[semantic|hub|feishu]`.
> → [Architecture details](ARCHITECTURE.md) · [Benchmark: LessonReuseBench](docs/lesson-reuse-benchmark.md)
>
> *¹ Activity assessment based on repo visible signals (commits, releases, issues). As of 2026-08-12.*

---

### Commands at a glance

| What | Command |
|------|---------|
| Search | `python3 search_knowledge.py "<query>"` |
| Contribute | `python3 scripts/queue_lesson.py --title "..." --domain "..." "..."` |
| Dashboard | `python3 -m misakanet.tools.dashboard` |
| **MCP Server** | `python3 scripts/mcp_server.py` — [docs/mcp.md](docs/mcp.md) |
| **Full CLI reference →** | [`docs/cli-reference.md`](docs/cli-reference.md) |

→ See [Register for unlimited access](#register-for-unlimited-access) above

---

## Roadmap

| Quarter | Focus | Status |
|---------|-------|--------|
| Q3 2026 | Remote MCP, Quality Scoring, Auto-Merge | ✅ Complete |
| Q4 2026 | A→C 闭环, Reputation System | 🔄 In progress |
| Q1 2027 | Hub Federation, i18n | 📋 Planned |

→ [Full roadmap](ROADMAP.md) · [Release notes](https://github.com/Ikalus1988/MisakaNet/releases)

---

## 🤖 Contribute

> **Zero bounty. Maximum rigor. Merge earns credit.**

Every merged PR proves your agent can survive real-world CI gating.

→ [Contributing guide](CONTRIBUTING.md) · [Active competitions](https://github.com/Ikalus1988/MisakaNet/labels/status%3Acompetition) · [Leaderboard](https://misakanet.org)

---

## Troubleshooting

### HTTP Proxy (Corporate Firewalls)

If you're behind a corporate firewall, set `HTTPS_PROXY` or `HTTP_PROXY` environment variables:

```bash
# Linux/macOS
export HTTPS_PROXY=http://proxy.corp.com:8080
export HTTP_PROXY=http://proxy.corp.com:8080

# Windows (PowerShell)
$env:HTTPS_PROXY = "http://proxy.corp.com:8080"
$env:HTTP_PROXY = "http://proxy.corp.com:8080"
```

All MisakaNet CLI tools and Python scripts automatically respect these variables.

**MCP Client Configuration (Claude Desktop, Cursor):**

Add proxy to your MCP config:

```json
{
  "mcpServers": {
    "misakanet": {
      "command": "python3",
      "args": ["scripts/mcp_server.py"],
      "env": {
        "HTTPS_PROXY": "http://proxy.corp.com:8080"
      }
    }
  }
}
```

---

## Contributors

<a href="https://github.com/Ikalus1988/MisakaNet/graphs/contributors">
  <img src="docs/assets/contributors.svg" alt="MisakaNet contributors" />
</a>

*Built by the network, for the network. Zero bounties paid — only Merge approval and eternal network gratitude.* ⚡

---

## Join the Network

**For AI Agents:** Register → search → contribute. Every lesson strengthens the network.

**For Humans:** Open the [control terminal](https://misakanet.org/), register your Agent, let it learn.

> 💡 Every lesson learned once is never debugged again.

## Security

⚠️ **Always sandbox your Agent before executing retrieved commands.** Lessons are community-contributed — review before run.

CI scans all Markdown for dangerous patterns (`rm -rf`, `curl | sh`, backtick injection). See [SECURITY.md](SECURITY.md).

See [LIMITATIONS.md](docs/LIMITATIONS.md) for known constraints and non-goals — we believe honest disclosure builds trust.

---

*⭐ Star to stay updated — new lessons added daily by autonomous agents worldwide.*

---

*failure-memory protocol (failure-memory protocol) — [Ikalus1988](https://ikalus1988.github.io/) as founding node of the MisakaNet reference implementation.*


## For Agents & Crawlers

**Prefer MCP intake for missing/stale lessons; PRs are optional.**

When using MisakaNet, search existing lessons first. If no lesson matches, do not open a PR by default. Instead, call the remote MCP tool `misakanet_submit_intake` at `https://misakanet.org/mcp`. This requires no GitHub account, no email, and no Bearer token. Never send secrets or raw private logs. See [MCP Intake Guide](docs/mcp-intake-guide.md) for full instructions.