I got tired of re-explaining myself to AI. So I built a memory graph

Every AI conversation starts from zero.

You explain your architecture. The next day, you explain it again. You describe the decision you made three weeks ago. You clarify that constraint. You remind the model what your project actually is.

You are not using AI as a thinking partner. You are using it as a very fast search engine that needs a new tour every single session.

I got frustrated with this. So I built something.

The Problem Is Structural

The issue isn't that Claude or GPT are bad models. The issue is that context doesn't persist.

You can dump your whole notes folder into a prompt window, but that's noisy — the model drowns in irrelevant text. You can use RAG, but that's heavy infrastructure for a personal workflow. You can use memory features in chat apps, but those are black boxes with no provenance: you don't know why something was remembered, or whether it's still true.

What I actually wanted was simple:

• A graph of concepts, decisions, goals, and relationships — not a pile of files


• Every claim backed by a source excerpt — so I know where it came from


• 
  Human review before anything becomes durable — LLMs propose, I decide


• A tiny context snapshot I can paste into any chat, any model, anywhere


• 
  Zero cloud. My graph is a JSON file on my machine.

Introducing knowledge-worker

is a local-first personal knowledge graph for carrying context across AI sessions. It turns markdown notes into reviewable concepts, decisions, goals, and relationships — with source excerpts attached — and exports a compact snapshot you can paste into Claude, GPT, Ollama, or whatever you're using next week.

No account. No sync. No telemetry. Just a JSON file and a CLI.

How It Works

The pipeline is five stages:

Markdown note

  → LLM extracts candidate nodes + edges

  → Validator checks shape, provenance, excerpts

  → You review: accept / reject / edit each claim

  → Merger writes to your local graph

  → Eval log records outcomes

Stage 1: Ingest a note

mykg ingest ~/notes/architecture-decision.md

The CLI calls your chosen LLM (Claude, GPT, or local Ollama) and gets back a structured list of candidate nodes and edges. Nothing is written yet.

Stage 2: Review

You see each candidate:

CANDIDATE: decision — "Use JSON first"

  excerpt: "plain JSON until it becomes the limiting factor"

  confidence: high

  [A]ccept / [R]eject / [E]dit > _

The LLM proposes. You decide. Nothing becomes durable memory without your explicit approval.

Stage 3: Query and export

# Search the graph

mykg query "provenance"



# Find paths between ideas

mykg path goal:trusted-ai project:knowledge-worker



# Export a compact LLM-ready context snapshot

mykg context

The context command outputs something like:

[knowledge-worker] project — A local-first knowledge graph for AI session continuity

  → serves: goal:trusted-ai

  → has_idea: idea:provenance-first



[decision] Use JSON first — plain JSON until it becomes the limiting factor

  source: architecture-note.md

  confidence: high

Paste that at the top of any new chat. Instant continuity.

No API Key? No Problem.

If you already have a Claude or ChatGPT subscription, you don't need an API key at all.

Just ask the model to produce a *.candidates.json file from your notes (there's a schema in the repo), then run the local validator and merge:

mykg ingest notes.md --candidates-file notes.candidates.json

Your app subscription does the extraction. The repo keeps graph validation and merge local.

Visualize Your Graph

Generate a self-contained, offline HTML viewer — no D3 CDN, no external requests, no server:

mykg viz --graph examples/demo_graph.json --out /tmp/my-graph.html

Here's what the public demo graph looks like rendered:

Try it: the repo ships a fictional demo graph you can run locally without any API key or install.

CODE Kopieren

git clone https://github.com/rahulmranga/knowledge-worker

cd knowledge-worker

MYGRAPH_PATH=examples/demo_graph.json python3 mygraph/mygraph.py summary

MYGRAPH_PATH=examples/demo_graph.json python3 mygraph/mygraph.py context

python3 mygraph/mygraph.py viz --graph examples/demo_graph.json --out /tmp/demo.html

The Design Principles (Worth Saying Out Loud)

Provenance first. Every durable claim points back to a source document and a literal excerpt. The graph distinguishes grounded claims from guesses.

Review before merge. LLMs hallucinate. Letting an LLM write directly to your memory graph is how you end up with confident nonsense baked into your context. The pipeline enforces human review.

Boring persistence. The graph is a JSON file. No database to stand up, no migration to run, no cloud to authenticate. Add SQL-backed storage when you actually need it.

Local first. Your private graph lives outside the repo, addressed by absolute path. The public repo ships only code, docs, and a fictional demo graph.

Works With Everything

The ollama_proxy/ package also ships an MCP wrapper (server.py) so it plugs into Claude/Cowork-style tool use.

The Thing That Surprised Me

Building this forced me to be honest about what I actually know versus what I assume about my own projects.

The review step — accepting or rejecting each LLM-extracted claim — turns out to be useful on its own, independent of the graph. It's a forcing function to read your own notes carefully and decide: is this actually a decision, or is it still a question? Is this claim grounded in something real, or did I just assert it?

The graph made my thinking legible to me. Which made it legible to the AI. Which made the AI actually useful for the second, third, and fiftieth conversation.

Try It

git clone https://github.com/rahulmranga/knowledge-worker

cd knowledge-worker

MYGRAPH_PATH=examples/demo_graph.json python3 mygraph/mygraph.py query provenance

No API key. No install. Just Python 3.10+.

If you've ever re-explained the same context to an AI three times in a week — this is the thing I built so I'd stop doing that.

GitHub: rahulmranga/knowledge-worker

MIT licensed. Local-first. stdlib-only core.