loletranga/Personal-Knowledge-Graph

Personal Knowledge Graph (File-based, Iterative)

Turn a collection of Markdown documents into a "recallable, traceable" knowledge network: add a layer of frontmatter metadata to each document, connect them with three types of relationships into a graph, and use scripts to rebuild the distillation layer (decision register + graph adjacency list), so that the Agent can retrieve past reasoning and historical context before analysis and decision-making.

Core Philosophy (Read before acting)

1. The source document is the single source of truth. The graph is not an independent system; frontmatter and wiki links live inside the user's Markdown files. The graph/ directory is purely generated and can be rebuilt at any time. All modifications happen only on the source documents.
2. Write only after confirmation. You draft the frontmatter, but before batch-writing back, you must show the user a sample and get confirmation; judgmental relationships like supersedes (who overrides whom) must be listed for confirmation—no silent writes.
3. Demote rather than fabricate. If a document's conclusion cannot be read, mark status: reference. Do not invent a conclusion. An incorrect "one-line conclusion" can mislead the user during decision-making, doing more harm than its absence.

This skill directory contains two companion files (located in the same directory as this SKILL.md):

• scripts/gen_kb_graph.py — Graph generation script (pure standard library, works offline)
• references/schema.md — Full frontmatter specification, semantics of the three edge types, output templates, and recall output format. Read this first when setting up a new base or when unsure about a field.

---

Workflow

Step 0: Determine scope and explain what will happen

• User provides a folder → That folder is the knowledge base root.
• User provides one or several files → Ask: Should we use the folder containing these files as the knowledge base root (recommended, so historical documents can connect into a graph), or create a new independent knowledge base folder?
• User has no files and wants to create a base → Go to Step 2 "Empty Base Skeleton".
• Before starting, confirm with the user in two or three sentences: which directory is the root, which files will be modified (source document frontmatter + newly created graph/ directory), and that document body text will not be touched.

Step 1: Detect knowledge base status

Read the root directory:

• If <root>/gen_kb_graph.py or <root>/graph/INDEX.md exists → Iteration mode (existing base)
• Otherwise → Creation mode (new base)

Step 2 A: Creation mode (including empty base skeleton)

1. Empty base skeleton (if the user has no historical files): Create the following files, then skip to Step 3 to inform the user—
   • <root>/Knowledge Base Quick Reference.md: Extract the frontmatter template and three core rules from references/schema.md, so users can refer to it when writing (with status: reference)
   • <root>/Template-Analysis Document.md: A blank template with full frontmatter (same as above, with its own frontmatter)
2. Install script: Copy scripts/gen_kb_graph.py from the skill directory to <root>/gen_kb_graph.py (skip if already exists). Placing it inside the knowledge base makes it self-contained—the user or other Agents can rebuild the graph without depending on this skill.
3. Test run: python3 <root>/gen_kb_graph.py <root>. Read the overview in <root>/graph/report.md and report the scale to the user (how many documents, how many missing frontmatter).
4. Draft metadata (core effort): First read references/schema.md, then process by subdirectory or domain in batches:
   • Read each document, draft frontmatter: date (date of conclusion), domain, status (active/superseded/reference), conclusion (one-line conclusion—only state "what does this document ultimately advocate?" not a content summary)
   • Show a sample first: Pick 2-3 representative documents (one decision document, one reference) and show the frontmatter you will write. After the user confirms the format, proceed with the batch.
   • Identify evolution relationships: document pairs where filenames contain v2/new version/copy/revision, or content suggests one overrides another. Propose supersedes links, list them for user confirmation before writing.
   • Report progress after each batch; do not modify a single word of the body, only add frontmatter.
5. Rebuild and deliver: Re-run the script (it automatically generates the graph/kb-graph.html visualization page). Show the user the first few lines of INDEX.md, the remaining gaps in report.md, and tell them they can open kb-graph.html in a browser to view the interactive graph.

Step 2 B: Iteration mode (existing base)

1. Run the existing <root>/gen_kb_graph.py (if missing, copy it from the skill directory again)
2. Read graph/report.md, process only the delta: new documents missing frontmatter, documents missing date/conclusion, broken links. Draft → confirm → write back.
3. Semantic edge addition: For new documents, after a thorough read, propose relationships with existing documents: related ("two sides of the same thing") and supersedes ("this document revises that one"), including a one-sentence justification, confirm, then write.
4. Rebuild (including refreshing the kb-graph.html visualization page). Report the changes to the user (number of new nodes/edges, remaining gaps).

Step 3: Tell the user how to use it

At the end of each creation/iteration cycle, prompt the user on how to proceed going forward (feel free to paraphrase):

Next time before an analysis or decision, simply tell me: "Recall my thoughts and conclusions on XX." I'll retrieve the graph, trace the evolution chain, check topicality, and give you a reference report. To view the graph visually, open graph/kb-graph.html in your browser (searchable, filterable, click nodes for details, double-click to open the source file). Continue writing your documents as usual; when you're done, just say "Update the knowledge base", and I'll automatically add metadata and relationships for new documents.

---

Recall Mode (Retrieval before decision)

When the user asks to recall past reasoning, and the target directory already has graph/ artifacts, execute this workflow, read-only:

1. Read graph/INDEX.md. Match the topic keywords against document titles and conclusions for initial screening (better to include too many than too few).
2. If expansion is needed, read graph/GRAPH.md: follow the supersedes evolution chain and related neighbors of the initially screened documents to fill in context.
3. Read the frontmatter and conclusion sections of relevant documents (no need to read the entire document).
4. Output in a fixed format (full example in references/schema.md):
   • List of relevant ideas: Each entry = date | one-line conclusion | status | document link
   • Evolution chain: The trajectory of thought changes on this issue, noting when something was overturned/revised
   • Reference points for the current issue: Which conclusions can be directly carried over, which are outdated and must be noted
   • No precedent statement: If the graph contains no historical decision on this issue, explicitly say "This is a new decision with no prior precedent to rely on"—this is also valuable output.

---

User Confirmation Checkpoints (Must Stop)

1. Before building the base: root directory scope, ignore rules (use <root>/.kbignore to exclude directories, one glob per line)
2. Before batch-writing frontmatter: confirm with 2-3 sample documents
3. Before writing supersedes relationships: confirm with a list of pairs
4. Any modification to body text: disallowed by default; only do so if the user explicitly requests

Script Usage

python3 gen_kb_graph.py <knowledge_base_root> [--output graph] [--ignore "books,old,*_old"] [--no-html]

Default ignores: hidden directories, .venv, venv, node_modules, pycache, .git, the output directory itself. Idempotent—can be re-run at any time. Outputs 5 files (INDEX.md / GRAPH.md / kb-graph.json / report.md / kb-graph.html), format defined in references/schema.md. kb-graph.html is a zero-dependency single-file visualization page (force-directed graph + decision list table, searchable, filterable, clickable for details, double-click to open source file). If the environment allows, you can open it directly in a browser to show the user.

Upgrade Boundary

When documents exceed approximately 500, GRAPH.md cannot be read in one go, or frequent multi-hop reasoning is required, the file-based graph reaches its limit. Recommend that the user migrate to LightRAG (graph + vector hybrid retrieval)—the frontmatter and wiki links are the best migration corpus; migration is lossless. Before that point, do not introduce a database or external service.