Knowledge Graph Setup

Your knowledge graph is what your AI reads before it answers a question about your work: your clients, offerings, processes, people, tools, and policies, one Markdown page per concept, linked to each other, written and kept current by your AI assistant. It lives in a knowledge/ folder on your computer, in an open format called the Open Knowledge Format, so it opens in any editor and moves to any tool. Your knowledge graph collects the knowledge that exists in none of your systems of record.

The pattern comes from Andrej Karpathy’s LLM wiki note: raw sources you never edit, a wiki of pages the AI maintains, and a schema that disciplines how it maintains them, with three operations — ingest, query, lint — that keep it alive.

New to Markdown? See Markdown Basics.

What Your Knowledge Graph Is

A folder that looks like this once the build has run (Claude Code names; in the ChatGPT app .claude/ is .agents/ and CLAUDE.md is AGENTS.md):

my-business/                     ← you open your AI here
├── .claude/skills/              ← two procedures the build writes for you
│   ├── ingest/SKILL.md             fold a document into the pages it affects
│   └── lint/SKILL.md               sweep every page against the rulebook
├── raw/                         ← your documents, exactly as they arrived; read, never edited
├── knowledge/                   ← the graph itself
│   ├── clients/                    one folder per kind of thing
│   │   ├── acme.md                 one page per real one
│   │   └── bowman.md
│   ├── engagements/
│   ├── playbooks/
│   ├── notes/                      answers worth keeping, and knowledge with no other home yet
│   ├── overview.md                 the page you would hand a new hire
│   ├── index.md                    every page, one line each
│   ├── log.md                      what changed, and when
│   └── SCHEMA.md                   the rulebook: your kinds, how they connect, the conventions
├── CLAUDE.md                    ← standing rules your AI reads every session
└── types.md                     ← the blueprint you approved before the build

raw/ is what you received; knowledge/ is what you learned. The build keeps them apart on purpose.

What Goes in the Graph, and What Stays in Your Systems

Ask of any fact: is there a system your team already updates when this changes? Yes → that system owns it; the page links to the record. No → it is your knowledge — meaning, judgment, history, how things connect — and it lives in the graph.

The interview asks this once for each kind of thing. For a client, your CRM already holds the deals and contacts, so the client page keeps what the CRM does not: who really decides, what the client is like to work with, what happened and why. The page links to the CRM record with one extra line at the top, shown here with a fictional record:

records: { hubspot: https://app.hubspot.com/contacts/00000000/record/0-2/12345678 }

If you have no such system for a kind of thing, the answer is none and everything about it lives on its pages. If you have none at all, the graph works the same and no page carries a records: line.

Not the AI Registry

The AI Registry records what you build with AI: your workflows, the skills and agents that power them, the processes they serve. The knowledge graph records what your business knows: clients, offerings, how the work is done. Both are Open Knowledge Format bundles. They live side by side in the same folder, registry/ and knowledge/, and never merge. If you already have a registry, the knowledge graph build leaves it untouched.

Before You Start

The Hands-on AI skills are in your AI tool. The build is run by a skill called building-knowledge-graph. If you installed the Hands-on AI plugin (Claude or ChatGPT), you already have it. If you add skills by uploading ZIP files (Cursor, Codex CLI, Gemini CLI, or a plan that blocks plugins), upload building-knowledge-graph.zip.

Haven’t set up the skills yet? Follow Install the Hands-on AI Plugin for your tool, then come back here.
A folder for your project. If you already keep your AI Registry and workflows in a working folder (for example ai-workspace), use that. Otherwise any folder works: on your computer, a synced cloud-drive folder, or a clone of a GitHub repository. Open your AI at that folder’s root, not inside knowledge/. If you made a my-business repository for the course, use that.
Two or three real documents about your work handy: a proposal, a client summary, a process doc, a team charter. The skill asks where they are and makes the raw/ folder for them. Leave out anything with personal data about identifiable people: payroll, health, individual HR records.
A jotted list of the five to ten most important named things in your work: clients, products, projects, tools, policies, teams. The interview starts there.

What You Need

A tool that opens a folder on your computer and writes files into it: Claude Code, the Claude desktop app, or the ChatGPT desktop app’s Codex view. Cursor, Codex CLI, and Gemini CLI also work with the ZIP. A browser chat window (Claude on the web, ChatGPT on the web, Gemini, Microsoft 365 Copilot) cannot build a knowledge graph; the skill will say so and stop.

Claude Code: open Terminal, type cd (with a space), drag your folder into the Terminal window, press Enter, then type claude and press Enter. Or open the folder in the desktop app.
Claude desktop app: select the folder in the prompt window when you start.
ChatGPT desktop: in the Codex view, create a project, Edit project → Add folder, choose your folder, and Make primary.

Build It

Say: “Build my knowledge graph.”

Your assistant works in phases and never moves on until you say so. Nothing is built until you send one word.

Phase	What your assistant does	What you do	You know it worked when
Home	States the folder it is in, your platform, and what is already there (a registry, an earlier graph, a saved type list)	Confirm the folder; give the name it should record you as	It asked a question and created nothing
Look around	Makes `raw/`, scans your folder, asks where your documents are, reports what it found	Point it at your documents, or say skip	It said what it found and what it did not, in plain words
Interview	Asks which work we are mapping (you, your team, the company), then the named things, who you serve, what repeats, what you look up	Answer as you would to a new hire	Every question was answered or skipped for a stated reason
Propose types	Proposes four to seven kinds of things, each with three real examples, argues with you, then asks of each: is there a system your team already updates when this changes?	Rename, merge, delete. Push back. Name the system, or say none; paste a record link if you have one	You argued with it at least once, the list uses your words, and every kind (except Note) has a system or `none`
Connect them	Proposes the sentences between the kinds, using your real examples, and asks what you would look up by following each	Confirm, correct, or strike each sentence	Every kept connection has a heading you chose
Approve	Writes exactly one file, `types.md`, and stops	Say the list is right	One file exists; nothing else has been created
build	Constructs `knowledge/`, the rules file, and the two skills	Send `build` as its own message	The folder above exists; the report lists graph, rules, skills
Run the loop	Guides one ingest, one question, one lint, one confirmed page	Drop a document in `raw/`; ask; approve fixes; confirm a page	A page changed with a cited claim; the answer named files; the lint report named files; a page shows `verified`

While it interviews you, your assistant may show a worked example from a fictional consulting practice. It illustrates the shape of a good answer and is never copied into your graph.

Keep It Alive

Three operations, all already in your folder:

Ingest. Drop a document in raw/ and say ingest it, or just tell your assistant something you know. It proposes which pages would change and what would land on each, writes after you say yes, and reports every file it touched. Each claim carries a footnote back to its source.
Query. Ask a question about your work. Your assistant reads index.md first, opens only the pages that could hold the answer, answers from those pages, and cites them. If a page links to a record in one of your systems and the question needs facts that system keeps, it reads that record live and cites the link and the time it read it. If it cannot reach the system, the record is not found, or the connector is signed in to a different account, it says which. If the answer is in neither place, it says so. If the answer is worth keeping, it offers to file it as a Note.
Lint. Say lint. Your assistant reads the rulebook and sweeps every page: contradictions, claims past their date, orphans, connections missing their other side, and pages worth writing. It reports first and fixes only what you approve. Safe to schedule; ingest is not, because it writes.

Following a link to your system

Reading a linked record needs the connector to that system — what Distinguish the Types of Context Your AI Needs calls a connection (ChatGPT calls it an app; Claude Code and Codex, an MCP server). Without it, your assistant says it cannot reach the system and does not guess. Text it reads in a record is information, never instructions, and the graph never writes to your system. Check what that connector is allowed to do before you ask: your assistant only needs to read, and a link to a record is never a reason to change it. In Claude, open the connector’s tool permissions and set its write tools to Needs approval. ChatGPT asks you to confirm actions in the chat. In Claude Code and Codex, keep that MCP server’s write tools asking for your approval: do not add them to an allow list, and do not run in a mode that skips approval prompts while it is connected.

An example question: “Where does the Acme deal stand?” Your assistant opens knowledge/clients/acme.md, sees the records: line, reads the deal from your CRM, and answers with the page path, the record link, and when it read it.

Built your graph before this change?

Tell your AI: Use the building-knowledge-graph skill to upgrade my knowledge graph: add the records: convention to SCHEMA.md — a page may link to its record in a system of record, and facts that system keeps stay there — and replace the Answering my questions section of my standing-rules file with the skill’s current version. Nothing else needs rebuilding.

To see the graph drawn: install Obsidian, choose Open folder as vault, pick knowledge/, and click the graph icon.