knowledge-worker

A personal knowledge graph that survives between AI conversations.

User-centered, not conversation-centered. Provenance first. Built on boring infrastructure.

Your AI is only as smart as what it remembers about you.

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, preserving the thread of your own reasoning across AI sessions.

Why

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.

Stop dumping context. Build memory. knowledge-worker turns chats, notes, decisions, and sources into a local provenance-backed knowledge graph. Graph analytics then show what matters, what connects, what is weak, and what context an AI should see.

knowledge-worker keeps the useful parts: cited claims, explicit relationships, human review, and a small context snapshot when you need continuity.

How It Compares

knowledge-worker is personal AI memory with source-backed claims, not a team chat-to-wiki system. It keeps reasoning local, reviewable, and tied to literal provenance excerpts before claims become durable graph knowledge.

See Competitive Analysis for the category matrix and Benchmarks for the offline demo-graph checks.

What It Does

• 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.
• Audits memory shape with PageRank, betweenness, k-core, communities, weak claims, and provenance coverage.
• Generates an offline HTML graph viewer for exploration and demos.

Design Principles

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.

Quick Start

Requirements: Python 3.10+ on macOS, Linux, or Windows. The public demo CLI uses only 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

# Audit memory structure and proof coverage
MYGRAPH_PATH=examples/demo_graph.json python3 mygraph/mygraph.py audit --out /tmp/analytics.json --html /tmp/memory_audit.html

# Visualize the graph as a self-contained HTML file
python3 mygraph/mygraph.py viz --graph examples/demo_graph.json --out /tmp/demo.html

Install the CLI

For the shorter mykg command, install the project 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 provenance

Using a virtual environment avoids Homebrew/system Python's externally-managed install errors.

On Windows PowerShell:

py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .

$env:MYGRAPH_PATH = "examples\demo_graph.json"
mykg query provenance
mykg audit --out "$env:TEMP\analytics.json" --html "$env:TEMP\memory_audit.html"

If PowerShell blocks activation scripts, run this for the current terminal session and activate again:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Commands

Command	What it does	Requirements
seed	Populate a fictional demo graph	Core
summary	Show node and edge counts by type	Core
query <term>	Search nodes, neighbors, and provenance	Core
list <type>	List nodes of a given type	Core
path <a> <b>	Find the shortest path between two nodes	Core
ingest <file.md>	Extract, validate, review, merge, and evaluate candidates	Provider extra, or --candidates-file
check --provenance	Flag nodes with missing source citations	Core
export --ttl	Emit Turtle/RDF	.[rdf]
context	Print a compact LLM-ready context snapshot	Core
viz	Generate an offline single-file HTML viewer	Core
audit	Emit graph analytics and optional Memory Audit HTML	Core
discover	Propose derived edges and second-order insights without mutating the graph	Core
state "<entry>"	Append a mood/state sidecar entry	Core
dump	Print the raw graph JSON	Core
reset	Delete the active graph file	Core

Install optional features into the active virtual environment:

python -m pip install -e ".[anthropic]"  # Anthropic-backed ingest
python -m pip install -e ".[openai]"     # OpenAI-backed ingest
python -m pip install -e ".[ollama]"     # Local Ollama ingest
python -m pip install -e ".[rdf]"        # Turtle/RDF export
python -m pip install -e ".[all]"        # All ingest backends and RDF export

Use Your Own Notes

Keep your real graph outside the repository and point the CLI at it:

mkdir -p ~/my-private-graph
export MYGRAPH_PATH=~/my-private-graph/mygraph.json

You can then ingest notes with or without an API key.

Claude or Codex App, No API Key

If a file-capable assistant is already working in this checkout, you do not need an API key. Ask it:

Read path/to/your/notes.md and the EXTRACTION_TOOL schema and PROMPT_TEMPLATE in mygraph/extractor.py. Write path/to/your/notes.candidates.json. Use only literal source excerpts, do not invent personal facts, and add a MENTIONED_IN edge from every new concept to the source node.

Then let the local CLI validate, review, and merge the proposals:

mykg ingest path/to/your/notes.md --candidates-file path/to/your/notes.candidates.json

Candidate files are ignored by git. Validation, review, and graph merge remain local.

Automated API-Backed Ingest

If you want the CLI to call an LLM directly, install the matching optional dependency and use a provider API key or local Ollama.

For Anthropic API:

python -m pip install -e ".[anthropic]"
export ANTHROPIC_API_KEY=...

mykg ingest path/to/your/notes.md

The Claude backend also auto-detects Anthropic-compatible provider env:

• Anthropic API: ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN
• Foundry: ANTHROPIC_FOUNDRY_API_KEY plus ANTHROPIC_FOUNDRY_RESOURCE or ANTHROPIC_FOUNDRY_BASE_URL
• Bedrock: AWS_BEARER_TOKEN_BEDROCK, or AWS credentials plus AWS_REGION/AWS_DEFAULT_REGION

For OpenAI API:

python -m pip install -e ".[openai]"
export OPENAI_API_KEY=...

mykg ingest path/to/your/notes.md --backend openai

For local Ollama:

python -m pip install -e ".[ollama]"
ollama list
ollama serve  # run in another terminal if Ollama is not already running

mykg ingest path/to/your/notes.md --backend ollama --model llama3

The traditional python -m pip install -r requirements.txt installs all ingest backends and RDF export support.

Private Graph Workflow

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 context

The default graph and standard sidecar paths under mygraph/ are ignored by git. Custom graph, viewer, TTL, and log paths are not automatically ignored, so keep private outputs outside the repository.

Memory Audit

mykg audit is a read-only layer over the graph. It ranks important concepts with PageRank, bridge ideas with betweenness, structural strength with k-core, communities with deterministic graph splitting, and weak claims from confidence and provenance gaps. It also includes directed idea-flow queues: idea_attractors for concepts that many edges point into, idea_generators for ideas that branch outward, and a weak_claim_queue that asks for human review actions instead of auto-promoting conclusions.

MYGRAPH_PATH=examples/demo_graph.json mykg audit \
  --out /tmp/analytics.json \
  --html /tmp/memory_audit.html

The generated HTML puts ranked panels and legwork queues first, with the graph canvas second. This keeps the feature focused on memory governance instead of making the raw graph view the product.

Discovery Layer

Where audit ranks what the graph already says, mykg discover infers what it implies but does not yet say — and turns every inference into a reviewable proposal:

• Staleness radar: important nodes whose evidence trail has gone cold, scored by importance × days since the graph last touched them.
• Co-mention candidates: pairs that recur together across multiple sources but were never linked (CO_MENTIONED_WITH).
• Goal-alignment candidates: ideas and decisions structurally entangled with a goal they have no contribution path to (SERVES_CANDIDATE).
• Link prediction: Adamic-Adar over the semantic graph (RELATES_TO).
• Question debt: open questions ranked by age, centrality, and missing evidence; answered questions are detected via decision ABOUT edges.
• Corroboration: claims that hang on a single source (SINGLE_SOURCE).
• Bridge finder: cross-community connectors that remain after removing dominant hub "spines" that mask real bridges (BRIDGES).
• Tension detector: claims that are both supported and challenged, and goal contributions that inherit a challenge to the goal (TENSION_WITH).

MYGRAPH_PATH=examples/demo_graph.json mykg discover \
  --out /tmp/discovery.json \
  --candidates /tmp/discovery.candidates.json

Discover never mutates the graph. Derived edges land in a candidates file, a promotion queue for human review. AI proposes, provenance verifies, the owner promotes. Committed sample output: examples/demo_discovery.json.

Local LLM Support

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 for mykg ingest --backend ollama.

See ollama_proxy/README.md for setup.

Verification

Run the full test suite and the public-demo provenance check:

python3 -m unittest
MYGRAPH_PATH=examples/demo_graph.json python3 mygraph/mygraph.py check --provenance

Repository Layout

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
DESIGN.md         Pipeline design notes

Contributing

See CONTRIBUTING.md. The core graph model is intentionally minimal; contributions that preserve that shape are preferred.

License

MIT