Muninn — Page-Citable Research Knowledge Base + MCP Server

Named after Odin's raven of memory. From research PDFs → chunked at page level → embedded (BAAI/bge-small-en-v1.5) → Qdrant vector DB → served over MCP so any future Claude session (desktop, web, phone) can query the corpus with exact filename, p. N citations — no re-reading, no chat-context cost.

Note: pdfs/, notes/, and qdrant_db/ are not included in this repo. pdfs/ holds the source papers, notes/ holds Claude's generated reading notes, and qdrant_db/ is the resulting vector DB — all excluded for privacy, since they contain personal research material and its derived content rather than shareable code.

Layout

pdfs/            the source PDFs
notes/           Claude's reading notes (notes*.jsonl) — re-ingestable
ingest.py        PDFs + notes → qdrant_db/  (run once, and after adding PDFs)
muninn_mcp.py    MCP server (stdio locally, Streamable HTTP when hosted)
push_to_cloud.py local qdrant_db/ → Qdrant Cloud (one command)
Dockerfile       Hugging Face Space deployment
qdrant_db/       the vector DB (created by ingest.py)

Data model (collection muninn): type=raw — verbatim chunks, ~1000 chars, never crossing page boundaries → every chunk has exactly one (source_file, page); type=page — full page text (backs get_page, and later page-rendering/highlighting: exact search_for → sentence pieces → fuzzy word alignment → semantic nearest-chunk fallback); type=claude_note — interpretation layer. Raw = ground truth, notes = orientation.

Step 1 — Ingest (your machine, ~2-3 min)

cd <this folder>
uv run ingest.py          # downloads bge-small (~130MB) once, builds qdrant_db/

Step 2 — Use locally right away (optional)

Claude Desktop → claude_desktop_config.json:

{"mcpServers": {"muninn": {"command": "uv",
  "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/THIS/FOLDER", "muninn_mcp.py"]}}}

Claude Code: claude mcp add muninn -- uv run --directory /ABSOLUTE/PATH muninn_mcp.py

Note: Qdrant local mode is single-process — stop the MCP server before re-running ingest.py.

Step 3 — Host it (laptop-off access, $0/mo)

3a. Qdrant Cloud (free tier, 4GB): create a cluster at cloud.qdrant.io, copy URL + API key, then:

QDRANT_URL=https://xxxx.cloud.qdrant.io QDRANT_API_KEY=... uv run push_to_cloud.py

3b. HF Space: create a Space (SDK = Docker), push Dockerfile + muninn_mcp.py to it. In Space Settings → Variables and secrets set:

name	kind	value
MUNINN_PATH_TOKEN	secret	python -c "import secrets; print(secrets.token_urlsafe(24))"
QDRANT_URL	variable	your cluster URL
QDRANT_API_KEY	secret	your cluster key

3c. Connect Claude: Settings → Connectors → Add custom connector → https://<user>-<space>.hf.space/mcp-<TOKEN>

MCP tools

search(query, top_k, doc_id, note_type) → ranked chunks with citation; list_documents() → corpus inventory; get_page(doc_id, page) → full page text. Retrieval tip: if a query misses, try HyDE (in the corpus, doc 322d71209a2f): write a hypothetical paragraph answering the question and search with that.

Adding papers later

Drop PDFs into pdfs/, re-run uv run ingest.py (idempotent per file), then push_to_cloud.py if hosted. Ask Claude to read the new paper and append a note to notes/ for the interpretation layer.