mini-context-graph

Mini Context Graph Skill

The Core Idea

Standard RAG re-discovers knowledge from scratch on every query. This skill is different:

1. 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.
2. Graph layer — Entities and relations are extracted once and stored as a navigable knowledge graph. BFS traversal answers structural queries without re-reading sources.
3. 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

⚡ Quick Start for Agents

from scripts.contextgraph import ContextGraphSkill
from scripts.tools import wiki_store

Operations

Ingest

When a user provides a new document:

1. Read references/ingestion.md — entity/relation extraction rules.
2. Read references/ontology.md — type normalization rules.
3. Extract entities and relations using your LLM reasoning.
4. Call skill.ingest_with_content(...) — stores raw content + chunks + graph nodes + provenance.
5. Write a wiki summary page using wiki_store.write_page(category="summary", ...).
6. Update entity pages — for each new/updated entity, write or update wiki_store.write_page(category="entity", ...).
7. Update topic pages if the document touches an existing synthesis topic.
8. A single document ingest will typically touch 3–10 wiki pages.

Query

When a user asks a question:

1. Check the wiki first — wiki_store.search_wiki(query) to find relevant pages. Read them.
2. If the wiki has a good answer, synthesize from wiki pages (fast path).
3. If deeper graph traversal is needed, call skill.query_with_evidence(query).
4. Return the answer with evidence citations from supporting_documents.
5. If the answer is valuable, file it back as a new wiki topic page.

Lint

Periodically health-check the wiki:

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

Design Philosophy

"The wiki is a persistent, compounding artifact. The cross-references are already there. The synthesis already reflects everything you've read." — Karpathy

The human curates sources and asks questions. The LLM writes the wiki, extracts the graph, and answers with citations. Python handles all bookkeeping.