This page collects the questions that most often come up when installing, pairing, troubleshooting, or contributing to MisakaNet. Commands assume that the shell is running from the root of a MisakaNet checkout unless stated otherwise.
MisakaNet is a searchable, redacted failure-memory layer for AI coding agents and developers. It stores lessons in the repository so an agent can search for a known failure, read the documented root cause, and verify the fix before retrying. A lesson is not an executable skill: it describes a failure and its recovery path.
See the README overview and the architecture guide.
Use Python 3.10 or newer, Git, and the MisakaNet checkout. The core search engine is designed to stay dependency-light, but the command-line entry point uses the separately published misakanet-core package:
git clone https://github.com/Ikalus1988/MisakaNet.git
cd MisakaNet
python3 -m pip install misakanet-core
python3 search_knowledge.py "database locked"The project metadata lists Python >=3.10; optional integrations are described in the quickstart.
The core package is not the same thing as the repository package. Install the PyPI dependency in the active interpreter, then retry:
python3 -m pip install misakanet-core
python3 search_knowledge.py "DCO sign-off"Using python3 -m pip helps ensure that pip installs into the interpreter that will run the search command.
Yes. The quickstart documents the GHCR image:
docker pull ghcr.io/ikalus1988/misakanet:latest
docker run -i ghcr.io/ikalus1988/misakanet:latest search_knowledge.py "database locked"Docker must be installed and running. For an MCP client, use the same image as the command in the client's MCP configuration.
No for searching or for the email intake path. You can send a redacted story to bot@misakanet.org; the email intake guide explains what is accepted and how personal data and secrets are handled. A GitHub account is still recommended for code changes because a PR provides CI, DCO, review, and an auditable history.
The web path is to open misakanet.org, enter a node name, and choose Register. The API and email alternatives are documented in JOIN.md and the CLI reference. Registration is optional for local lesson search.
Open the connect page, choose Generate Code, and add the returned bearer token to the MCP configuration:
{
"mcpServers": {
"misakanet": {
"url": "https://misakanet.org/mcp",
"headers": {"Authorization": "Bearer YOUR_TOKEN"}
}
}
}Restart the client after saving its configuration, then ask it to search for a concrete error. Treat the token like a credential and do not commit it.
Point the MCP client at the repository's scripts/mcp_server.py using an absolute path. For example:
{
"mcpServers": {
"misakanet": {
"command": "python3",
"args": ["/absolute/path/to/MisakaNet/scripts/mcp_server.py"]
}
}
}The same shape works in Claude Code, Claude Desktop, and Cursor; the location of each client's configuration file differs. See the MCP quickstart for client-specific examples.
Start the stdio server with an empty input stream and run a direct search before debugging the MCP client. An empty stream lets the process exit after checking imports; an MCP client keeps stdin open during normal use:
python3 scripts/mcp_server.py </dev/null
python3 search_knowledge.py "DCO sign-off" --top=3If both commands work, restart the MCP client and make a first query through the client. This separates Python/index problems from client configuration problems.
The most common causes are a relative script path, a stale client process, or an invalid JSON configuration. Use an absolute path, validate the JSON, run python3 scripts/mcp_server.py </dev/null from the checkout, and restart the client. The MCP troubleshooting section has the same checklist.
Start with the exact error text or a distinctive phrase, then narrow or widen the result set with the CLI flags:
python3 search_knowledge.py "pip install timeout" --top=5
python3 search_knowledge.py "token expired" --domain=devops --json
python3 search_knowledge.py "database" --broad --titlesThe --json flag is useful for scripts, --titles gives a compact list, --domain filters by domain, and --broad expands matching. The full option list is in the CLI reference.
First confirm that you are in the repository root and have the current lesson files:
git pull --ff-only
python3 -m pip install misakanet-core
python3 search_knowledge.py "a distinctive error phrase" --top=10
python3 search_knowledge.py "timeout" --broad --top=10The CLI uses exit code 1 for no results or an error. A no-result search is a signal to try a more specific phrase, a broader query, or the public lesson index. Do not treat an unverified result as a fix.
The result includes a repository path. Read that file locally, or fetch the corresponding raw file when you are working outside the checkout:
python3 search_knowledge.py "DCO sign-off" --json --top=3
curl -sS https://raw.githubusercontent.com/Ikalus1988/MisakaNet/main/lessons/core/dco-auto-fix-workflow.mdReview the Problem, Root Cause, Solution, and Verification sections before applying commands from a community lesson.
Do not invent a fix from a weak match. Redact secrets and personal data, then submit a small failure note through the lesson-feedback form or use the queue helper:
python3 scripts/queue_lesson.py \
--title "Short error description" \
--domain general \
"Root cause: ... Fix: ... Verification: ..."Maintainers review the draft before it becomes a published lesson.
Include the exact error or symptom, the environment when it matters, the root cause, a copy-pasteable solution, and a verification step. Keep the lesson focused on one failure pattern. Never include access tokens, private logs, email addresses, or other secrets. The lesson checklist has the review criteria.
Create the file under lessons/contrib/, add frontmatter with at least a title, domain, tags, and status, then run the relevant checks before opening a PR:
git checkout -b docs/my-failure-lesson
git add lessons/contrib/my-failure-lesson.md
git commit -s -m "docs: add lesson for my failure"
git push origin docs/my-failure-lessonThe contribution quickstart contains a complete frontmatter example. The -s flag adds the required DCO sign-off.
The commit is missing a Signed-off-by trailer. Amend a single-commit branch and push it safely:
git commit --amend --signoff --no-edit
git push --force-with-leaseFor multiple commits, sign off each commit before pushing. See the DCO troubleshooting entry and the repository's DCO guide for Windows-specific details.
For a reproducible software failure, open a GitHub issue with the command, environment, exact error, and a redacted reproduction. For onboarding or UX friction, use the journey report issue #510 or the email intake path. Do not paste credentials or unredacted logs into an issue.
Revoke or rotate it immediately, remove it from the working tree and history, and then open a clean replacement commit. Do not rely on deleting the latest file alone: Git history and CI logs may still contain the secret. The token/secret troubleshooting guide lists the recovery sequence.