# Gray Box Gray Box is a local-first, open-source [[Personal Knowledge Management (PKM)]] tool by Aaryan Verma built around three verbs: capture, organize, ask. You dump thoughts into an inbox with zero structure; on demand, an LLM reads the unprocessed notes and extracts people, projects, tasks, decisions, and meetings; then you query the resulting knowledge base and get cited answers pulled only from what you captured. The architecture decisions: - **The LLM reasons, deterministic code writes.** The model extracts entities, but plain Python creates and merges the wiki pages and maintains backlinks. The LLM never touches the filesystem. That's the right division of labor for anyone nervous about models corrupting their notes over time. - **Immutable inbox.** Raw captures are never edited or deleted by the organizer. Mis-extractions can always be audited against your original words. - **Plain Markdown + YAML frontmatter, no database.** Stop using the tool tomorrow and your knowledge base is just a folder of [[Markdown]] files. - **No vector DB by default.** At personal scale (hundreds to low thousands of pages), keyword search plus a real link graph walked one hop covers almost everything. Embeddings are opt-in. - **Any model via LiteLLM** — OpenAI, Anthropic, Gemini, or fully local through [[Ollama]]. The Reddit thread around it is worth the read too. One commenter coined an "uncertainty principle" of [[Personal Knowledge Management (PKM)]]: time spent filing something properly trades off against time spent retrieving it later, and AI organization is most valuable for the non-crucial notes you'd never bother filing. The skeptics pushed back with research on LLMs corrupting documents over time; the immutable-inbox design is a direct answer to exactly that fear. Early-stage, but the design philosophy overlaps heavily with [[Agentic Knowledge Management (AKM)]]: capture without friction, let automation structure, keep the human-readable files as the source of truth. Compare [[Cluing]], which chases the same "AI organizes for you" promise as a hosted commercial product; Gray Box is the local-first, plain-files counterpoint. ## References - GitHub: https://github.com/Aaryanverma/graybox - Reddit announcement (r/PKMS): https://www.reddit.com/r/PKMS/comments/1varu2u/opensource_dump_your_thoughts_let_your_notes/ ## Related - [[Personal Knowledge Management (PKM)]] - [[Agentic Knowledge Management (AKM)]] - [[Cluing]] - [[Markdown]] - [[Ollama]] - [[Use code for control flow, agents for reasoning]]