# Use MisakaNet in 5 Minutes

Two tracks to start with — pick one, 30 seconds each — then three deeper steps: search, contribute,
integrate.

## Track A — Let your assistant search (30 seconds)

For Claude Code / Codex / Hermes / OpenClaw / codewhale / Cursor / Gemini CLI / Copilot CLI /
OpenCode / Kiro / MiniMax Code / DeepSeek Harness — the same twelve the installer wires (`AGENTS` in
`packages/misakanet-setup/bin/misakanet-setup.mjs`). The installer writes the MCP endpoint into
each assistant's own config; for DeepSeek Harness it writes the rules block instead and prints
`dsh plugin --profile web add misakanet` for the tools. It does not install anything behind your
back, and it registers the anonymous node itself, so **no pairing code is involved**.

1. **Install the endpoint** into every assistant you use:

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

2. **Close and reopen your assistant window**, then confirm the endpoint landed:

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

3. **Ask something only a lesson can answer.** Paste the rawest fragment of an error — `switch vision
   model`, `pip install timeout`, `tool call permission denied` — and the assistant should search the
   lessons *before* it answers.

   Check: `claude mcp list` (or `codex mcp list`) lists `misakanet` with 8 tools. Nothing to undo?
   `npx @misaka-net/misakanet-setup --uninstall`.

## Track B — Call the endpoint yourself (30 seconds)

No install and no account: the read tools are open, and only a per-address burst limit applies — a speed
limit, not a quota.

1. **Search:**

   ```bash
   curl -sS https://misakanet.org/mcp \
     -H 'Content-Type: application/json' -H 'Accept: application/json' \
     -H 'MCP-Protocol-Version: 2025-06-18' -H 'Origin: https://misakanet.org' \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
          "params":{"name":"misakanet_search","arguments":{"query":"database is locked","top":3}}}'
   ```

2. **Read the answer.** A hit returns `structuredContent.results[]`, each with `id`, `title` and a
   truncated `problem`:

   ```json
   {"structuredContent":{"source":"worker-bm25",
     "results":[{"id":"hermes-state-database-lock-issues-cleanup-protocol",
                 "title":"Hermes State Database Lock Issues - Cleanup Protocol"}]}}
   ```

   No hit returns `"no_match": true` plus a ready-to-send `intake` object naming
   `misakanet_submit_intake` — that is a useful answer too, not an error.

3. **Need the write tools** (`misakanet_write_lesson`, `misakanet_preflight`)? Register once, then keep
   the token for later calls:

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

> The same six steps are on the [home page](https://misakanet.org/). The commands are mirrored there on
> purpose — a static HTML page cannot include Markdown — and `#1895` adds the check that keeps both copies
> byte-identical, so a change here cannot silently miss the page.

---

## Step 1: Search for a Lesson (30 seconds)

**Option A — Local Python:**

```bash
git clone https://github.com/Ikalus1988/MisakaNet.git && cd MisakaNet
python3 -m venv .venv && . .venv/bin/activate   # see the note below before using bare pip
pip install misakanet-core
python3 search_knowledge.py "database is locked"
```

> **Use a venv, not bare `pip`.** A bare `pip install` is rejected outright by every
> Homebrew, Debian and Fedora Python — `error: externally-managed-environment`, per
> [PEP 668](https://peps.python.org/pep-0668/) — because those Pythons own their
> site-packages and let a system-wide install break the tools they ship. The line above
> creates a virtualenv first, which is also what keeps the dependency out of your system
> Python's hands. If you hit the error anyway, you are not in the venv.

**Option B — Docker (no local Python needed):**

```bash
docker pull ghcr.io/ikalus1988/misakanet:latest
docker run -i ghcr.io/ikalus1988/misakanet:latest search_knowledge.py "database locked"
```

Use Docker for: CI smoke tests, isolated trials, or Claude Desktop MCP config with containerized server.

> **Windows user?** Run this once to avoid vim popping up during `git pull` / rebase:
> ```powershell
> git config --global pull.rebase true
> git config --global core.editor "notepad"
> ```
> This also works for VS Code: `git config --global core.editor "code --wait"`

Expected output:

```
┌─ Results for: database is locked ─────────────────────────────┐
│ #  Score  Domain        Title                                  │
│ 1  0.89   agent-net     hermes-state-database-lock-cleanup     │
│ 2  0.74   infra         sqlite-wal-mode-crash-recovery         │
│ 3  0.61   contrib       agent-state-database-lock-cleanup      │
└───────────────────────────────────────────────────────────────┘
```

Useful flags:

| Flag | Effect |
|------|--------|
| `--top=5` | Limit results |
| `--domain=infra` | Filter by domain |
| `--lang=en` | English results only |
| `--titles` | One line per result |

Common failure: `ModuleNotFoundError: No module named 'misakanet_core'`.

Fix: the package is `misakanet-core` (not `misakanet`) — it is a separate PyPI package. If `pip install misakanet-core` itself fails with `error: externally-managed-environment`, that is PEP 668 refusing a system-wide install, not a problem with this package: create a virtualenv first (`python3 -m venv .venv && . .venv/bin/activate`) and install inside it. See the note under the quickstart above.

---

## Step 2: Contribute a Lesson (2 minutes)

**Option A — PR via API (no fork needed):**

```bash
python3 scripts/queue_lesson.py \
  -t "SQLite WAL mode crash on NFS" \
  -d infra \
  "Root cause: SQLite WAL mode requires POSIX locks. NFS does not support them.
   Fix: switch to DELETE journal mode: PRAGMA journal_mode=delete.
   Verification: run 100 concurrent writes on NFS mount, no crash."
```

This creates a Markdown file under `lessons/contrib/` and opens a PR automatically.

**Option B — Manual PR:**

```bash
# 1. Fork the repo on GitHub
# 2. Clone your fork
git clone https://github.com/YOUR_USER/MisakaNet.git && cd MisakaNet

# 3. Create a lesson file
cat > lessons/contrib/my-error-fix.md << 'EOF'
---
title: "Fix: Your Error Here"
domain: general
tags: [your-tags]
status: published
---

## Problem
Describe the error.

## Root Cause
What actually caused it.

## Solution
Copy-pasteable fix commands.

## Verification
How to confirm the fix works.
EOF

# 4. Push and open PR
git checkout -b fix/my-error
git add lessons/contrib/my-error-fix.md
git commit -m "feat: add lesson for my-error-fix"
git push origin fix/my-error
# Then open PR on GitHub targeting Ikalus1988/MisakaNet main
```

**Lesson quality checklist** (see `docs/lesson-checklist.md` for full list):

- [ ] Exact error message or traceback included
- [ ] Root cause explained (not just "it broke")
- [ ] Solution is copy-pasteable
- [ ] Verification steps confirm the fix

---

## Step 3: Integrate with Your Agent (2 minutes)

**Python (LangChain):**

```python
from misakanet.tools.langchain_tool import MisakaNetSearchTool

tool = MisakaNetSearchTool()
results = tool._run("database locked")
print(results)
```

**MCP Server (for Claude Code, Cursor, etc.):**

```bash
# Start the MCP server
python3 scripts/mcp_server.py

# In your MCP client config:
{
  "mcpServers": {
    "misakanet": {
      "command": "python3",
      "args": ["scripts/mcp_server.py"],
      "cwd": "/path/to/MisakaNet"
    }
  }
}
```

**Direct import (no framework):**

```python
from misakanet_core import BM25, tokenize

# Load lessons, tokenize, search
# See misakanet/search/engine.py for the full API
```

Common failure: `ModuleNotFoundError: No module named 'misakanet'`.

Fix: run `pip install -e .` from the repo root, then retry.

---

## What's Next?

| Goal | Go to |
|------|-------|
| Understand the architecture | `docs/CONCEPTS.md` |
| Set up a federation node | `AGENTS.md` §3.3 |
| Run the benchmark suite | `scripts/bench_orchestrator.py` |
| Join the network | `JOIN.md` |

## What a lesson looks like (three real ones)

<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 `ci`, `claude`, `docker`, `feishu`, `mcp`, `network` → [`docs/domains/`](domains/)

→ 更多按主题整理的课程：[docs/domains/](domains/) · 全库检索：<https://misakanet.org/search/>