BYO-WIKI MCP
A personal LLM wiki with a knowledge graph, cited RAG and memory, served to Claude Code and Cursor by an MCP server
- 276 ★ on the repository
- Last commit
Extended access
Why this level
- The app downloads web pages, writes files to `data/` and sends texts to model and embedding providers
- MCP client mode connects external servers such as Supabase and GitHub: reads are allowed, writes need a separate permission and approval
- The skill pipeline can run Claude Code as a subprocess to author a skill
Install
- Works in
Manual install
pip install -r requirements.txtRun inside the cloned repository and a virtual environment, then cp .env.example .env and add keys.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The app downloads web pages, writes files to `data/` and sends texts to model and embedding providers
- MCP client mode connects external servers such as Supabase and GitHub: reads are allowed, writes need a separate permission and approval
- The skill pipeline can run Claude Code as a subprocess to author a skill
This is third-party code. Review the repository files before installing.
What it does
BYO-WIKI is a Flask app that turns web pages, files and loose notes into a personal wiki. A `deepagents` agent saves passages, extracts entities and relations, merges duplicates, nests topics and writes synthesis pages. All data lives in the `data/` folder as JSON and SQLite, and the cloud is opt-in. Library search is built as contextual retrieval in the spirit of Anthropic: a two-layer HNSW index over section summaries and chunks, then reranking by a model or MMR for multi-document coverage. Answers rest on sources and carry citations. Cross-session memory is recalled before each answer and updated after: observations, ratings and corrections that supersede stale notes. There is also an agent-skill pipeline that builds a new skill from selected context, scores it and sends it to a human for review before it joins the library. The `mcp_server.py` module runs all this as an MCP server over stdio with `python mcp_server.py` or `python runner.py --mode mcp-serve`. Through it a client searches the knowledge graph, gets an entity profile, layer statistics, a cited RAG answer, recalls memory and finds accepted skills. The `skill_build` action only proposes a draft and leaves it in review. Writes to third-party MCP servers are denied by default.
Who it is for. People who accumulate research material and want Claude Code or Claude Desktop to answer from a personal library with citations while data stays on disk.
Good fit when
- Articles, notes and pages are scattered across folders and you want one knowledge graph with topics and summaries
- The agent should answer from your library with citations, not from the model's general memory
- You need long-term memory that takes corrections into account and replaces stale entries
- You want to build a new skill from accumulated material and run it through scoring and manual acceptance
- MCP clients (Claude Desktop, Claude Code, Cursor) need stdio access to the library
Not a fit when
- You have no `OPENAI_API_KEY`: vector search and RAG answers need OpenAI embeddings even with another chat provider
- You want a ready cloud service with accounts: BYO-WIKI runs locally with `python app.py`
- You need a license with explicit usage rights: the repository states no license
- Plain file search is enough: the knowledge graph and RAG pull in Flask, LangChain and an HNSW index
Example request
Search my BYO-WIKI library for notes on contextual retrieval and answer how a two-layer index beats a flat one, with citationsMCP
- Transport
- stdio
- Authentication
- API key
Environment variables
OPENAI_API_KEYrequired, secret- OpenAI key for RAG embeddings, required regardless of the chat provider
MCP_ALLOW_WRITES- A value of 1 allows writes to external MCP servers, denied by default
Limitations
- RAG answers need `OPENAI_API_KEY` for `text-embedding-3-small` embeddings because Anthropic has no embeddings API. This holds for any chat provider.
- The vector library has to be built first, otherwise the `rag_answer` tool returns an error.
- The repository states no license, and the author has not set out rights to reuse the code.
- Writing to connected external MCP servers is off and is enabled only with `MCP_ALLOW_WRITES=1` and explicit human approval.
How to disable. Remove the `byo-wiki` block from your client's MCP config and the server stops launching. The app itself stops when the `python app.py` process ends. All data lives in the `data/` folder (or `KG_DATA_DIR`) and can be deleted separately.
FAQ
How do I connect BYO-WIKI as an MCP server to Claude Desktop or Claude Code?
Install the dependencies and add an `byo-wiki` server to the MCP config with the command `python` and the full path to `mcp_server.py` as the argument. `python runner.py --mode mcp-serve` runs the same server. The transport is stdio.
Which tools does the server expose?
Knowledge graph search, an entity profile, layer statistics, a cited RAG answer, memory recall and a search of accepted skills, plus proposing a new skill through `skill_build`. It only prepares a draft and leaves it in review.
Do I need an OpenAI key?
For RAG yes: `text-embedding-3-small` embeddings come from OpenAI even when chat runs on Claude, Qwen, DeepSeek, Gemini or Mistral. At least one provider key in `.env` is needed.
Where is data stored?
In the `data/` folder: the knowledge graph as JSON, HNSW vectors and SQLite checkpoints. By the project description this is a local mode and the cloud is opt-in.
How do I start the web interface?
Run `pip install -r requirements.txt`, copy `.env.example` to `.env` with your keys, then `python app.py`. The interface opens at `http://localhost:5000`.
Discussion
No questions or reviews yet.
Related
MCP serversA Datalog engine in Rust as an agent's working memory: facts with provenance, inference rules and an MCP server for Claude Code
A CLI and MCP server that builds a local wiki with a knowledge graph from documents, code and links, so the agent searches it instead of scanning files
An MCP memory server for agents built on a knowledge graph: relevance as an evidence path, not just vector similarity
Claude Skills MCP: semantic search for skills
Claude Skills MCP
An MCP server with vector search: the agent describes a task and gets matching skills from the Anthropic and K-Dense collections
Local memory for coding agents: sessions turn into a git-versioned Markdown wiki and come back through an MCP server.
MCP server with long-term memory for agents: atomic notes, semantic search and an auto-linked graph on SQLite or PostgreSQL
README in short
The README lists features: an agentic knowledge graph, contextual RAG, memory, agent skills and MCP in both directions. Then come the architecture diagram, a quick start, how the agent works, evaluation and observability, the web UI, API and CLI modes, connecting external MCP servers and a settings table.