# MisakaNet

> Connects DSH to a Git-driven failure experience memory network. When agents encounter errors, they can retrieve 290+ community-verified fix paths, exposed as `deepseek

## Metadata

- Author: [@Ikalus1988](https://github.com/Ikalus1988)
- Repo: <https://github.com/Ikalus1988/MisakaNet.git>
- GitHub: [Ikalus1988/MisakaNet](https://github.com/Ikalus1988/MisakaNet)
- Stars: 413
- Language: Python
- License: [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)
- Homepage: <https://misakanet.org>
- Topics: `ai-agent`, `ai-infra`, `claude`, `deepseek-harness`, `devops`, `dsh-plugin`, `failure-analysis`, `failure-memory`, `git-based`, `knowledge-sharing`, `lesson-database`, `mcp`, `mcp-server`, `multi-agent`, `open-source`, `python`
- Forks: 157
- Open Issues: 34
- Last push: 2026-08-20T16:05:57.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:Ikalus1988/MisakaNet
```

## Wiki

## One-Sentence Pitch

MisakaNet brings a Git-powered "failure experience memory network" to DSH: when an Agent hits an error, it can search 290+ markdown lessons from real debugging sessions, get the four-part answer (problem → root cause → fix → verification), and then decide whether to proceed.

## Core Capabilities

- Registers a stdio MCP client named `misakanet` in the DSH web profile via Cordis patch, carried by the adapter process
- Exposes 6 `deepseek.recovery.*` tools: search, get_lesson, submit_feedback, status, doctor, smoke, covering "search lessons, read lessons, report results, health checks"
- Built-in three-layer search engine fallback chain: SAG-Lite FTS → BM25 inverted index → lessons.json keyword fallback; single-layer failure won't make search completely unavailable
- Lessons are markdown files in the repository, version-controlled by Git, auditable, and contributable (DCO signature required)
- Built-in doctor/smoke validation: checks lessons data files, sag.db index, search engine availability, outputs JSON for upper-layer harness consumption
- Supports remote MCP mode: `https://misakanet.org/mcp` provides account-free intake; Agents can submit anonymized reports when they can't find suitable lessons

## Technical Implementation

- **Language**: Python (core engine + MCP adapter), TypeScript (only appears in wrangler/Cloudflare Worker deployment scripts, not involved when this plugin runs)
- **Key Dependencies**: `misakanet-core` (core search package on PyPI, pyproject.toml#dependencies), Python standard library (BM25 needs no third-party), optional `pip install misakanet-core` with sentence-transformers / aiohttp / chromadb (semantic search or hub federation extensions)
- **Architecture Pattern**: Plugin points to `cordis.patch.yml` via `dsh.bundle.patch`; DSH injects the `misakanet` node on startup; adapter `scripts/mcp_deepseek_adapter.py` is a stdio MCP bridge process, delegating all logic to `scripts/mcp_server.py` (naming layer not logic layer), search requests fall to BM25 implementation in `misakanet/search/engine.py`
- **Entry Files**: `scripts/mcp_deepseek_adapter.py` (actual DSH call entry), `scripts/mcp_server.py` (core MCP server, 4 basic tools), `search_knowledge.py` (CLI search entry)

## Use Cases

When you're running a long-running task Agent in DSH and hit "known pitfalls" like DCO errors, pip package install timeouts, MCP service won't start, underscores getting swallowed in WSL, etc., you want the Agent to first check the community knowledge base and hit an existing fix path before retrying or asking for help—this plugin is designed for such "recurring failures." It's a bypass recovery layer on top of DSH, not replacing official AI capabilities; it's only invoked on-demand when the Agent encounters errors.

## Prerequisites & Compatibility

| Dependency | Minimum Version | Description |
|---|---|---|
| DSH | Not declared | `package.json` points to `cordis.patch.yml` via `dsh.bundle.patch`, no minimum DSH version declared |
| Python | >= 3.10 | `pyproject.toml#requires-python`; adapter and MCP server both use 3.10 syntax |
| Platform | Cross-platform | Python process runs cross-platform; lessons repository syncs via Git |
| Git | Required | Lessons are markdown files in the repository, bound to Git version control; `git pull --ff-only` is the daily sync command |
| `misakanet-core` PyPI package | >= 2.7.0 | `pyproject.toml#dependencies`, core BM25 search provided by it |

## Installation

```bash
dsh plugin --profile web add github:Ikalus1988/MisakaNet
```

## Configuration

This plugin requires no user-facing additional configuration. DSH automatically injects a stdio MCP client named `misakanet` via Cordis patch; the bridge process at runtime only depends on lessons data in the repository.

## FAQ

**Q: What is MisakaNet for?**

A: It helps AI coding Agents quickly find fixes when hitting known errors. It puts 290+ markdown lessons from real debugging sessions into the repository; Agents can get four-part answers (problem → root cause → fix → verification) via BM25 keyword search. It's not a vector database or memory system—it's a knowledge layer specifically designed for failure recovery.

**Q: What's its relationship with DSH's official AI capabilities?**

A: It's an independent recovery layer plugin on top of DSH, not taking over model dialogue and session management. DSH treats `mcp__misakanet__*` as regular MCP tool calls; this plugin searches the local lessons library and returns fix paths, essentially adding a "pitfall avoidance memory" layer outside the Agent's tool chain.

**Q: Do I need to start any additional services after installation?**

A: No. The plugin automatically registers the `misakanet` MCP client in the web profile via DSH's Cordis patch; after startup it runs as a stdio process via `python3 scripts/mcp_deepseek_adapter.py`, with all data in the local lessons repository.

**Q: Is Python required to use it?**

A: Yes. Core dependencies require Python 3.10 and above because the adapter layer is a stdio MCP Python process that loads markdown lessons from the repository and uses BM25 keyword indexing. Git is also required—lessons are files in the repository, bound to Git version control.

**Q: Do I need a GitHub account or Bearer Token?**

A: Not for local use. When DSH runs this plugin, it uses local stdio MCP without any credentials. Only when directly connecting to remote `https://misakanet.org/mcp` do you need to generate a 6-digit pairing code on misakanet.org/connect to exchange for a Bearer Token.

**Q: Where is lessons data stored? Can I modify it?**

A: All stored as markdown files in the plugin repository's `lessons/` directory (290+ entries), version-controlled by Git. Each contribution requires a PR with DCO signature; alternatively, you can use the `misakanet_submit_intake` tool to submit an anonymized failure report.

**Q: What to do when "no search results" is returned?**

A: Three-step troubleshooting: first `git pull --ff-only` to ensure lessons are pulled to latest, then `python3 -m pip install misakanet-core` to install the core package, finally re-search with more specific error phrases. The underlying is BM25 keyword matching; large wording differences will cause missed matches, you can add `--broad` to widen the search.

**Q: What does submitting feedback (submit_feedback) actually do?**

A: In the current version it only logs locally (which lesson was used, result: solved/partial/not-helpful) (source code has `TODO: POST to /api/usage or create GitHub Issue`), it doesn't immediately sync to the cloud, waiting for subsequent external interface integration.

## Getting Started Difficulty

Beginner — No configuration needed after installation, DSH auto-injects; calls use standard MCP tool names `deepsearch.recovery.*`; the Agent can complete the core loop with one `search` call plus one `get_lesson` call.

## Known Issues & Limitations

- The underlying is BM25 keyword search, no vector embeddings; large wording differences between queries and lesson titles will cause missed matches; documentation explicitly marks this as an inherent limitation of stdlib-only retrieval
- Submitting feedback (`submit_feedback`) is currently just a local placeholder implementation; source code `scripts/mcp_server.py:275` has `TODO: POST to /api/usage or create GitHub Issue`, remote consumption not connected
- When repository scale exceeds 50,000 lessons, `search_knowledge.py` startup time and memory usage will significantly increase (Git is not a database)
- Lessons are community-contributed; CI only scans for dangerous patterns (`rm -rf`, `curl | sh`, etc.), doesn't verify factual correctness—verify yourself before executing retrieved commands
- Some queries will trigger SQLite FTS keyword conflicts (typical like `off`, `and`), need to rephrase or rebuild index
- Not a general-purpose memory system, nor an Agent runtime framework; cannot be used for real-time collaboration, vector recall, or hosted services

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [MisakaNet](https://deepseek-plugin.org/plugins/Ikalus1988/MisakaNet)
Wiki generated by AI (model: `MiniMax-M2.5`)