A local, private "second brain" your AI agents can actually read — semantic search + MCP over your own Markdown notes.
Status: early WIP — being extracted and generalized from a working private system. See ROADMAP.md.
HumanAgentWiki turns your own notes (plain Markdown) into a shared, searchable knowledge base that any MCP-compatible AI agent can plug into. Everything runs locally on your machine — your knowledge never leaves your computer.
- 🧠 LLMs don't know your context. HumanAgentWiki gives them retrieval over what you actually wrote and think (RAG), so answers are grounded in your knowledge — not generic web fluff, and far fewer hallucinations.
- 🔒 Local & private. PostgreSQL + pgvector on your own machine. No cloud upload.
- 🌍 Multilingual. Uses BGE-M3 embeddings — excellent for Czech and 100+ languages, not just English.
- 🔌 Agent-native. Exposes an MCP server, so Claude and other MCP clients connect with zero glue code. Multiple agents share one brain.
One line:
curl -fsSL https://raw.githubusercontent.com/petrludwig-collab/HumanAgentWiki/main/install.sh | bashOr clone and run the installer:
git clone https://github.com/petrludwig-collab/HumanAgentWiki.git
cd HumanAgentWiki && ./install.shIt checks prerequisites, creates a virtualenv, installs dependencies, brings up PostgreSQL (Docker if available, otherwise a local instance), writes .env, and creates the schema. Then use the ./haw launcher:
./haw index # index your notes (Markdown under ./notes)
./haw web # web UI at http://127.0.0.1:8808
./haw serve # MCP server for your agentsTry it instantly with the bundled demo:
NOTES_DIR=./sample_notes ./haw index && ./haw web
- Your notes are Markdown files, linked like a wiki with
[[links]]. - They get chunked and embedded — each idea gets a "meaning fingerprint" stored in pgvector.
- Search finds things by meaning, not keywords — search "how not to get dumber from AI" and it finds your note about "cognitive laziness" even without those exact words.
- Incremental indexing — only changed files get re-embedded (seconds, not minutes).
- An MCP server (
brain_search/brain_get/brain_neighbors) lets your agents query it live.
You define your top-level categories right in the app (add/remove with +/–) — e.g. Books, Podcast, Interviews, Notes — and start saving into them. No YAML, no config editing. On first run you get sample notes + a built-in guide so you instantly see how it works.
# 1. Start PostgreSQL + pgvector
docker compose up -d
# 2. Install dependencies (a virtualenv is recommended)
pip install -r requirements.txt
# 3. Configure (copy and edit if needed)
cp .env.example .env && set -a && . ./.env && set +a
# 4. Create the schema
python cli.py init-db
# 5. Index your notes (put Markdown in ./notes — folders are categories;
# or try the bundled demo:)
NOTES_DIR=./sample_notes python cli.py index
# 6. Search from the terminal…
NOTES_DIR=./sample_notes python cli.py search "how do small habits compound"
# 7. …or run the MCP server for your agents
python cli.py serve
# 8. …or open the web UI (manage categories, write/link notes, search)
python cli.py web # then open http://127.0.0.1:8808Then point any MCP client at http://127.0.0.1:8802/mcp. For Claude Code:
claude mcp add --transport http humanagentwiki http://127.0.0.1:8802/mcpTools exposed: brain_search, brain_get, brain_neighbors.
python cli.py web opens a wiki-style interface (no build step, vanilla JS):
- 3D graph — your notes as an interactive 3D graph (rotate / zoom / pan), nodes coloured by category, edges from
[[links]]. Click a node to open it. This is the centerpiece. - Categories — add/remove your top-level categories with +/- (left panel).
- Note editor — slides in on the right: pick a category, write, and link other notes with
[[...]](autocomplete). Saving writes a Markdown file, commits it to git (full history), and re-indexes it. - Search — semantic search across everything.
pip install -r requirements-dev.txt
pytest # unit tests for the pure helpers (no DB needed)See ROADMAP.md.