myśloodsiewnia

A local knowledge vault that gives AI agents access to your private documents, manuals, contacts, and notes — without sending your data anywhere.

Your data stays on your machine. Always.

---

What it is

A local Python HTTP server that:

• Indexes your PDFs, notes, and contacts into a local SQLite database
• Exposes a simple search API that AI agents can query
• Integrates with humanMCP via query_vault tool
• Works offline — agents get "unavailable" instead of crashing when your Mac is off

Agent (Claude, GPT, etc.)
    ↓  query_vault("VTEC solenoid torque")
humanMCP  (Fly.io)
    ↓  POST /query
myśloodsiewnia  (your Mac, localhost:7331)
    ↓  BM25 search over your indexed documents
    ←  excerpts + page numbers + source citations

---

Quick start

# 1. Clone
git clone https://github.com/kapoost/mysloodsiewnia
cd mysloodsiewnia

# 2. Setup
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 3. Start
zsh start.zsh

# 4. Add a document
python cli.py add-pdf ~/your-manual.pdf my-manual "My Manual Title"

# 5. Search
python cli.py search "your query"

# 6. Open search UI
open http://localhost:7331/search

---

Search UI

Three display modes designed for different conditions:

Mode	Use case
DAY	Normal indoor use — warm paper tones
NIGHT	Low light — dark background, amber accent
WATCH	Complete darkness — pure black + red, night-vision safe

Results show source, page number, and a direct button to open the PDF at the exact page.

---

Document types

Type	Command	What gets indexed
PDF	add-pdf	Text per page, tables, measure specs
Note / inspiration	add-note	Any markdown or plain text
Contact	add-contact	Name, birthday, memories, tags

Measure values are indexed separately for precise lookup — torque specs, pressures, clearances, temperatures, volumes, RPM values all have dedicated chunks tagged [MIARA:TORQUE], [MIARA:PRESSURE] etc.

---

Vault API contract

Any server implementing these three endpoints is compatible with humanMCP:

GET  /health
     → {"status": "ok"}

GET  /documents
     → [{slug, title, doc_type, chunk_count, created_at}]

POST /query
     body: {"query": "string", "limit": 5, "doc_slug": "optional"}
     → {"found": N, "results": [{title, body, page, citation, doc_slug}], "summary": "string"}

Optional endpoints (for local file opening):

POST /ingest/pdf        — upload + index PDF
POST /ingest/note       — index text/markdown
POST /ingest/contact    — index contact with memories
GET  /pdf/{slug}        — serve raw PDF
GET  /open-pdf/{slug}?page=N  — open in Preview via AppleScript (macOS)
GET  /search            — search UI (HTML)

Set VAULT_URL=http://localhost:7331 in your humanMCP config to connect.

---

Connect to humanMCP

fly secrets set VAULT_URL=http://YOUR_LOCAL_IP:7331 --app your-humanmcp-app

When your Mac is offline, query_vault returns a graceful "unavailable" message instead of an error.

---

Privacy model

~/mysloodsiewnia/
├── pdfs/        ← your files, .gitignored
├── db/          ← sqlite index, .gitignored  
├── contacts/    ← your contacts, .gitignored
├── notes/       ← your notes, .gitignored
├── main.py      ← server code, public
├── ingest.py    ← indexing pipeline, public
├── db.py        ← search layer, public
├── cli.py       ← CLI tool, public
└── config.py    ← configuration, public

The code is open. The data is yours.

---

Run tests

source .venv/bin/activate
pip install pytest httpx
python -m pytest test_mysloodsiewnia.py -v

38 tests covering: SQLite store, BM25 search, measure extraction, chunking, FastAPI endpoints.

---

Stack

• Python 3.10+
• FastAPI + uvicorn
• pdfplumber (PDF text extraction with x_tolerance tuning for scanned documents)
• SQLite FTS5 (BM25 full-text search, zero external dependencies)
• Ollama (optional — USE_EMBEDDINGS=true for semantic search)

---

License

MIT — fork it, fill it with your own knowledge, keep your data private.