Source-backed memory for AI work. Local files in, durable context out.
knowledge-worker is a local-first personal knowledge graph for carrying context across AI sessions. It turns notes into reviewable concepts, decisions, goals, and relationships, keeps source excerpts attached, and exports compact context you can paste into Claude, GPT, Ollama, or any other LLM workflow.
Your private graph stays on your machine.
AI conversations usually start from zero. You clarify a decision, name a constraint, sketch a goal, and then the next session forgets it. RAG can be heavy, full-note prompts are noisy, and most note apps do not plug cleanly into chat workflows.
knowledge-worker keeps the useful parts: cited claims, explicit relationships, human review, and a small context snapshot when you need continuity.
- Ingests markdown notes into candidate graph nodes and edges.
- Requires provenance excerpts before claims become durable memory.
- Lets you review, accept, reject, or edit LLM proposals before merge.
- Searches by term, lists nodes by type, and finds paths between ideas.
- Exports an LLM-ready context snapshot for a fresh chat session.
- Generates an offline HTML graph viewer for exploration and demos.
Requirements: Python 3.10+ on macOS or Linux. The core demo CLI has no runtime dependencies beyond the standard library and does not need a package install.
git clone https://github.com/rahulmranga/knowledge-worker
cd knowledge-worker
# Run the public demo graph, no API key needed
MYGRAPH_PATH=examples/demo_graph.json python3 mygraph/mygraph.py summary
MYGRAPH_PATH=examples/demo_graph.json python3 mygraph/mygraph.py query "provenance"
# Generate an LLM-ready context snapshot
MYGRAPH_PATH=examples/demo_graph.json python3 mygraph/mygraph.py context
# Visualize the graph as a self-contained HTML file
python3 mygraph/mygraph.py viz --graph examples/demo_graph.json --out /tmp/demo.htmlOne-command smoke test:
MYGRAPH_PATH=examples/demo_graph.json python3 mygraph/mygraph.py query provenanceIf you want the shorter mykg command, install it inside a virtual environment:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
MYGRAPH_PATH=examples/demo_graph.json mykg query provenanceUsing a virtual environment avoids Homebrew/system Python's externally-managed install errors.
Run the test suite with:
python3 -m unittestYou can ingest your notes with or without an API key.
If you are already working with Claude, Codex, or ChatGPT in an app session, you do not need an API key. Ask the assistant to produce a *.candidates.json file that follows the schema in mygraph/extractor.py, then let the local CLI validate, review, and merge it:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
mykg ingest path/to/your/notes.md --candidates-file path/to/your/notes.candidates.jsonThe app subscription helps you create the candidates file. The repo still keeps graph validation and merge local.
If you want the CLI to call an LLM directly, use a provider API key or local Ollama.
For Anthropic API:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[anthropic]"
export ANTHROPIC_API_KEY=...
mykg ingest path/to/your/notes.mdFor OpenAI API:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[openai]"
export OPENAI_API_KEY=...
mykg ingest path/to/your/notes.md --backend openai --model gpt-5.2For local Ollama:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[ollama]"
mykg ingest notes.md --backend ollama --model llama3If you prefer a traditional requirements file, activate a virtual environment first, then run python -m pip install -r requirements.txt. That installs the CLI plus optional dependencies for Anthropic API ingest, OpenAI API ingest, Ollama ingest, and Turtle/RDF export.
The public repo ships code, docs, and a fictional demo graph. Your real graph should live outside the repo or in the ignored default path, then be loaded explicitly:
MYGRAPH_PATH=~/my-private-graph/mygraph.json mykg summary
MYGRAPH_PATH=~/my-private-graph/mygraph.json mykg query "architecture"
MYGRAPH_PATH=~/my-private-graph/mygraph.json mykg contextYour private mygraph.json, generated private viewers, TTL exports, eval logs, state logs, and local env files are ignored by default.
| Command | What it does |
|---|---|
seed |
Populate a fictional demo graph |
summary |
Show node and edge counts by type |
query <term> |
Search nodes, neighbors, and provenance |
list <type> |
List nodes of a given type |
path <a> <b> |
Find the shortest path between two nodes |
ingest <file.md> |
Extract, validate, review, merge, and eval candidates |
check --provenance |
Flag nodes with missing source citations |
export --ttl |
Emit Turtle/RDF |
context |
Print a compact LLM-ready context snapshot |
viz |
Generate an offline single-file HTML viewer |
state "<entry>" |
Append a mood/state sidecar entry |
The ollama_proxy/ package adds three local-model surfaces:
server.py: MCP wrapper for Claude/Cowork-style tool use.proxy.py: Ollama-compatible logging passthrough for HTTP clients.extractor_adapter.py: drop-in extraction backend formykg ingest --backend ollama.
See ollama_proxy/README.md for setup.
Provenance first. Every durable claim points back to a source document and literal excerpt.
Local first. The graph is a file on your machine. No cloud sync, accounts, or telemetry.
Review before merge. The LLM proposes. You decide. Deterministic validation runs before anything enters the graph.
Boring persistence. Plain JSON until it becomes the limiting factor. The schema stays stable across storage backends.
mygraph/ Core CLI and pipeline modules
examples/ Fictional demo graph, TTL, and HTML viewer
docs/ Roadmap and public assets
ollama_proxy/ Adapter, MCP server, and proxy for local Ollama workflows
tests/ CLI smoke tests
SPEC.md Graph model specification
V1_DESIGN.md Pipeline design notes
See CONTRIBUTING.md. The core graph model is intentionally minimal; contributions that preserve that shape are preferred.
MIT