Aaryanverma/graybox: A local-first, long-term memory for anything you'd otherwise forget.

A local-first, long-term memory for anything you'd otherwise forget. - Aaryanverma/graybox

Summary

Gray Box is a local-first, Python-based personal knowledge tool that captures free-form notes, organizes them into cross-linked Markdown wiki pages via an organize command, and answers questions with cited sources. All content lives as plain .md files with YAML frontmatter — no database — and the LLM is pluggable through LiteLLM, so it can point at OpenAI, Anthropic, Gemini, Mistral, Ollama, or any self-hosted model.

What it is useful for

Engineers who want a single, durable place to capture the decisions, tasks, names, and snippets that surface across meetings, code reviews, and side projects — without committing to a cloud SaaS or a proprietary format. Notes are written verbatim to an immutable inbox/ first, then the organizer extracts typed entities (e.g. project, meeting, decision, task, action, person, topic, event, journal) into a cross-linked wiki, with each page recording which inbox items it came from via sources links. When you ask a question, retrieval does keyword (and optionally semantic) search, expands one hop through related and backlinks (governed by retrieval.graph_max_hops), and produces a cited answer like [person/aaryan] — or admits it doesn't know. Because everything is plain Markdown, the vault stays greppable, diffable, and editable in any editor, and an existing Obsidian vault can be imported with graybox migrate-vault.

How engineers can use it

Install with pip install graybox (Python 3.10+), place the example config.yaml in the working directory, and supply an LLM API key through the configured env_file or the GRAYBOX_LLM_API_KEY environment variable. A typical loop:

graybox capture "Talked to Aaryan about the Atlas migration; he owns the DB cutover, due next Friday"
graybox organize
graybox ask "who owns the Atlas DB cutover and when is it due?"

organize --dry-run previews writes without applying them; running graybox with no arguments opens the Textual-based TUI. Curation stays CLI-only and never invokes the LLM — dupes flags likely-duplicate pages, while merge, edit, and delete rewire backlinks and report which inbox items they touched. Workspaces are fully isolated; graybox workspace-create work adds a separate KB, and --all on ask/chat/search opts in to cross-workspace lookup. Documented limits: capture accepts only text or UTF-8 files (no PDF or DOCX), and merge/edit/delete/forget are not exposed in the TUI because their arguments don't map to keystrokes.