Mini Context Graph Skill
The Core Idea
Standard RAG re-discovers knowledge from scratch on every query. This skill is different:
- Wiki layer — The LLM writes and maintains persistent markdown pages (summaries, entity pages, topic syntheses). Cross-references are already there. The wiki gets richer with every ingest.
- Graph layer — Entities and relations are extracted once and stored as a navigable knowledge graph. BFS traversal answers structural queries without re-reading sources.
- Raw source layer — Original documents are stored immutably with chunks. Provenance links tie every graph node and edge back to the exact text that supports it.
The LLM writes; the Python tools handle all bookkeeping.
Three Layers
| Layer |
Where |
What the LLM does |
What Python does |
| Raw Sources |
data/documents.json |
Reads (never modifies) |
Stores chunks + metadata |
| Wiki |
wiki/ (markdown) |
Writes/updates pages |
Manages index.md + log.md |
| Graph |
data/graph.json |
Extracts entities + relations |
Persists, deduplicates, traverses |
⚡ Quick Start for Agents
A complete runnable version of this workflow is in scripts/template_agent_workflow.py — copy and adapt it.
from scripts.contextgraph import ContextGraphSkill
from scripts.tools import wiki_store
skill = ContextGraphSkill()
# ===== INGEST WITH FULL RAG + WIKI =====
# 1. Read references/ingestion.md and references/ontology.md first
# 2. Extract entities and relations (LLM reasoning step)
entities = [
{"name": "memory leak", "type": "issue", "supporting_text": "memory leaks cause crashes"},
{"name": "system crash", "type": "issue", "supporting_text": "system crashes due to memory leaks"},
]
relations = [
{"source": "memory leak", "target": "system crash", "type": "causes",
"confidence": 1.0, "supporting_text": "System crashes due to memory leaks."},
]
result = skill.ingest_with_content(
doc_id="doc_001",
title="System Crash Analysis",
source="/docs/incident_report.pdf",
raw_content="System crashes due to memory leaks. Memory leaks occur when objects are not released.",
entities=entities,
relations=relations,
)
# result = {"doc_id": "doc_001", "chunk_count": 1, "nodes_added": 2, "edges_added": 1}
# 3. Write a wiki summary page for this document
wiki_store.write_page(
category="summary",
title="System Crash Analysis Summary",
content="""---
title: System Crash Analysis
source_document: doc_001
tags: [summary, incident]
---
# System Crash Analysis
**Source:** incident_report.pdf
## Key Claims
- [[memory-leak]] causes [[system-crash]] (confidence: 1.0)
## Entities
- [[memory-leak]] (issue)
- [[system-crash]] (issue)
""",
summary="Incident report: memory leaks cause system crashes.",
)
# ===== QUERY WITH EVIDENCE =====
result = skill.query_with_evidence("Why does the system crash?")
# Returns: {"query": ..., "subgraph": ..., "supporting_documents": [...], "evidence_chain": ...}
# ===== WIKI SEARCH (read wiki before answering) =====
pages = wiki_store.search_wiki("memory leak")
# Returns: [{slug, category, path, snippet}, ...]
Operations
Ingest
When a user provides a new document:
- Read
references/ingestion.md — entity/relation extraction rules.
- Read
references/ontology.md — type normalization rules.
- Extract entities and relations using your LLM reasoning.
- Call
skill.ingest_with_content(...) — stores raw content + chunks + graph nodes + provenance.
- Write a wiki summary page using
wiki_store.write_page(category="summary", ...).
- Update entity pages — for each new/updated entity, write or update
wiki_store.write_page(category="entity", ...).
- Update topic pages if the document touches an existing synthesis topic.
- A single document ingest will typically touch 3–10 wiki pages.
Query
When a user asks a question:
- Check the wiki first —
wiki_store.search_wiki(query) to find relevant pages. Read them.
- If the wiki has a good answer, synthesize from wiki pages (fast path).
- If deeper graph traversal is needed, call
skill.query_with_evidence(query).
- Return the answer with evidence citations from
supporting_documents.
- If the answer is valuable, file it back as a new wiki topic page.
Lint
Periodically health-check the wiki:
from scripts.tools import wiki_store
issues = wiki_store.lint_wiki()
# Returns: {orphan_pages, missing_pages, broken_wikilinks, isolated_pages}
Ask the LLM to review and fix: broken links, orphan pages, stale claims, missing cross-references. See references/lint.md for full lint workflow.
Ingestion Constraints
- ❌ Do NOT hallucinate entities not present in the text
- ❌ Do NOT add relations without explicit textual evidence
- ❌ Do NOT add edges with confidence < 0.6
- ✅ Provide
supporting_text for every entity and relation — this enables provenance
- ✅ Write a wiki summary page for every ingested document
- ✅ Update existing entity pages when new information arrives
- ✅ Flag contradictions in wiki pages when new data conflicts with old claims
Retrieval Constraints
- 🔒 Traversal depth MUST NOT exceed 2 (config: MAX_GRAPH_DEPTH)
- 🔒 Only edges with confidence ≥ 0.6 (config: MIN_CONFIDENCE)
- 🔒 Maximum 50 nodes returned (config: MAX_NODES)
- ❌ Do NOT fabricate nodes or edges not in the graph
Full Python API Reference
| Method |
Purpose |
When to Use |
skill.ingest_with_content(doc_id, title, source, raw_content, entities, relations) |
Full RAG ingest: raw docs + graph + provenance |
Every new document |
skill.add_node(name, node_type) |
Add single entity (no provenance) |
Quick additions without a source doc |
skill.add_edge(source_name, target_name, relation, confidence) |
Add single relation |
Quick additions without a source doc |
skill.query(query) |
Graph-only retrieval → subgraph |
Structural queries |
skill.query_with_evidence(query) |
Graph + provenance → subgraph + source chunks |
Queries requiring citations |
wiki_store.write_page(category, title, content, summary) |
Write/update a wiki page |
After every ingest; after answering queries |
wiki_store.read_page(category, title) |
Read a wiki page |
Before answering; for cross-referencing |
wiki_store.search_wiki(query) |
Keyword search across wiki |
Fast path before graph traversal |
wiki_store.list_pages(category) |
List all wiki pages |
Getting an overview |
wiki_store.get_log(last_n) |
Read recent operations |
Understanding wiki history |
wiki_store.lint_wiki() |
Health check |
Periodic maintenance |
documents_store.list_documents() |
List all ingested raw sources |
Audit / provenance checking |
documents_store.search_chunks(query) |
Chunk-level search |
Finding specific evidence |
Design Philosophy
"The wiki is a persistent, compounding artifact. The cross-references are already there. The synthesis already reflects everything you've read." — Karpathy
| Layer |
What Happens |
Who Owns It |
| LLM Reasoning |
Extraction, synthesis, writing wiki pages |
Agent (.md guidance files) |
| Wiki Persistence |
Index, log, file I/O |
wiki_store.py |
| Graph Persistence |
Dedup, index, BFS traverse |
graph_store.py, retrieval_engine.py |
| Raw Source Storage |
Immutable docs + chunks + provenance |
documents_store.py |
The human curates sources and asks questions. The LLM writes the wiki, extracts the graph, and answers with citations. Python handles all bookkeeping.
1---
2name: mini-context-graph
3description: |
4 A persistent, compounding knowledge base combining Karpathy's LLM Wiki pattern
5 with a structured knowledge graph. Ingest documents once — the LLM writes wiki
6 pages, extracts entities/relations into the graph, and stores raw content for
7 evidence retrieval. Knowledge accumulates and cross-references; it is never
8 re-derived from scratch.
9metadata:
10 source: https://skillmd.com/skills/gabrielmoreira/mini-context-graph
11---
12
13# Mini Context Graph Skill
14
15## The Core Idea
16
17Standard RAG re-discovers knowledge from scratch on every query. This skill is different:
18
191. **Wiki layer** — The LLM writes and maintains persistent markdown pages (summaries, entity pages, topic syntheses). Cross-references are already there. The wiki gets richer with every ingest.
202. **Graph layer** — Entities and relations are extracted once and stored as a navigable knowledge graph. BFS traversal answers structural queries without re-reading sources.
213. **Raw source layer** — Original documents are stored immutably with chunks. Provenance links tie every graph node and edge back to the exact text that supports it.
22
23> The LLM writes; the Python tools handle all bookkeeping.
24
25---
26
27## Three Layers
28
29| Layer | Where | What the LLM does | What Python does |
30|-------|-------|-------------------|-----------------|
31| **Raw Sources** | `data/documents.json` | Reads (never modifies) | Stores chunks + metadata |
32| **Wiki** | `wiki/` (markdown) | Writes/updates pages | Manages index.md + log.md |
33| **Graph** | `data/graph.json` | Extracts entities + relations | Persists, deduplicates, traverses |
34
35---
36
37## ⚡ Quick Start for Agents
38
39A complete runnable version of this workflow is in `scripts/template_agent_workflow.py` — copy and adapt it.
40
41```python
42from scripts.contextgraph import ContextGraphSkill
43from scripts.tools import wiki_store
44
45skill = ContextGraphSkill()
46
47# ===== INGEST WITH FULL RAG + WIKI =====
48# 1. Read references/ingestion.md and references/ontology.md first
49# 2. Extract entities and relations (LLM reasoning step)
50entities = [
51 {"name": "memory leak", "type": "issue", "supporting_text": "memory leaks cause crashes"},
52 {"name": "system crash", "type": "issue", "supporting_text": "system crashes due to memory leaks"},
53]
54relations = [
55 {"source": "memory leak", "target": "system crash", "type": "causes",
56 "confidence": 1.0, "supporting_text": "System crashes due to memory leaks."},
57]
58
59result = skill.ingest_with_content(
60 doc_id="doc_001",
61 title="System Crash Analysis",
62 source="/docs/incident_report.pdf",
63 raw_content="System crashes due to memory leaks. Memory leaks occur when objects are not released.",
64 entities=entities,
65 relations=relations,
66)
67# result = {"doc_id": "doc_001", "chunk_count": 1, "nodes_added": 2, "edges_added": 1}
68
69# 3. Write a wiki summary page for this document
70wiki_store.write_page(
71 category="summary",
72 title="System Crash Analysis Summary",
73 content="""---
74title: System Crash Analysis
75source_document: doc_001
76tags: [summary, incident]
77---
78
79# System Crash Analysis
80
81**Source:** incident_report.pdf
82
83## Key Claims
84
85- [[memory-leak]] causes [[system-crash]] (confidence: 1.0)
86
87## Entities
88
89- [[memory-leak]] (issue)
90- [[system-crash]] (issue)
91""",
92 summary="Incident report: memory leaks cause system crashes.",
93)
94
95# ===== QUERY WITH EVIDENCE =====
96result = skill.query_with_evidence("Why does the system crash?")
97# Returns: {"query": ..., "subgraph": ..., "supporting_documents": [...], "evidence_chain": ...}
98
99# ===== WIKI SEARCH (read wiki before answering) =====
100pages = wiki_store.search_wiki("memory leak")
101# Returns: [{slug, category, path, snippet}, ...]
102```
103
104---
105
106## Operations
107
108### Ingest
109
110When a user provides a new document:
111
1121. Read `references/ingestion.md` — entity/relation extraction rules.
1132. Read `references/ontology.md` — type normalization rules.
1143. Extract entities and relations using your LLM reasoning.
1154. Call `skill.ingest_with_content(...)` — stores raw content + chunks + graph nodes + provenance.
1165. **Write a wiki summary page** using `wiki_store.write_page(category="summary", ...)`.
1176. **Update entity pages** — for each new/updated entity, write or update `wiki_store.write_page(category="entity", ...)`.
1187. **Update topic pages** if the document touches an existing synthesis topic.
1198. A single document ingest will typically touch 3–10 wiki pages.
120
121### Query
122
123When a user asks a question:
124
1251. **Check the wiki first** — `wiki_store.search_wiki(query)` to find relevant pages. Read them.
1262. If the wiki has a good answer, synthesize from wiki pages (fast path).
1273. If deeper graph traversal is needed, call `skill.query_with_evidence(query)`.
1284. Return the answer with evidence citations from `supporting_documents`.
1295. If the answer is valuable, file it back as a new wiki topic page.
130
131### Lint
132
133Periodically health-check the wiki:
134
135```python
136from scripts.tools import wiki_store
137issues = wiki_store.lint_wiki()
138# Returns: {orphan_pages, missing_pages, broken_wikilinks, isolated_pages}
139```
140
141Ask the LLM to review and fix: broken links, orphan pages, stale claims, missing cross-references. See `references/lint.md` for full lint workflow.
142
143---
144
145## Ingestion Constraints
146
147- ❌ Do NOT hallucinate entities not present in the text
148- ❌ Do NOT add relations without explicit textual evidence
149- ❌ Do NOT add edges with confidence < 0.6
150- ✅ Provide `supporting_text` for every entity and relation — this enables provenance
151- ✅ Write a wiki summary page for every ingested document
152- ✅ Update existing entity pages when new information arrives
153- ✅ Flag contradictions in wiki pages when new data conflicts with old claims
154
155---
156
157## Retrieval Constraints
158
159- 🔒 Traversal depth MUST NOT exceed 2 (config: MAX_GRAPH_DEPTH)
160- 🔒 Only edges with confidence ≥ 0.6 (config: MIN_CONFIDENCE)
161- 🔒 Maximum 50 nodes returned (config: MAX_NODES)
162- ❌ Do NOT fabricate nodes or edges not in the graph
163
164---
165
166## Full Python API Reference
167
168| Method | Purpose | When to Use |
169|--------|---------|-------------|
170| `skill.ingest_with_content(doc_id, title, source, raw_content, entities, relations)` | Full RAG ingest: raw docs + graph + provenance | Every new document |
171| `skill.add_node(name, node_type)` | Add single entity (no provenance) | Quick additions without a source doc |
172| `skill.add_edge(source_name, target_name, relation, confidence)` | Add single relation | Quick additions without a source doc |
173| `skill.query(query)` | Graph-only retrieval → subgraph | Structural queries |
174| `skill.query_with_evidence(query)` | Graph + provenance → subgraph + source chunks | Queries requiring citations |
175| `wiki_store.write_page(category, title, content, summary)` | Write/update a wiki page | After every ingest; after answering queries |
176| `wiki_store.read_page(category, title)` | Read a wiki page | Before answering; for cross-referencing |
177| `wiki_store.search_wiki(query)` | Keyword search across wiki | Fast path before graph traversal |
178| `wiki_store.list_pages(category)` | List all wiki pages | Getting an overview |
179| `wiki_store.get_log(last_n)` | Read recent operations | Understanding wiki history |
180| `wiki_store.lint_wiki()` | Health check | Periodic maintenance |
181| `documents_store.list_documents()` | List all ingested raw sources | Audit / provenance checking |
182| `documents_store.search_chunks(query)` | Chunk-level search | Finding specific evidence |
183
184---
185
186## Design Philosophy
187
188> "The wiki is a persistent, compounding artifact. The cross-references are already there. The synthesis already reflects everything you've read." — Karpathy
189
190| Layer | What Happens | Who Owns It |
191|-------|-----------|-------------|
192| **LLM Reasoning** | Extraction, synthesis, writing wiki pages | Agent (.md guidance files) |
193| **Wiki Persistence** | Index, log, file I/O | `wiki_store.py` |
194| **Graph Persistence** | Dedup, index, BFS traverse | `graph_store.py`, `retrieval_engine.py` |
195| **Raw Source Storage** | Immutable docs + chunks + provenance | `documents_store.py` |
196
197The human curates sources and asks questions. The LLM writes the wiki, extracts the graph, and answers with citations. Python handles all bookkeeping.
198