Mini Context Graph

Mini Context Graph Skill

When to invoke

• "Ingest these documents into a persistent knowledge graph."
• "Query the mini context graph with evidence."
• "Write wiki pages from extracted entities and relations."
• "Lint the local wiki for broken wikilinks."

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

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:

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:

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

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.

Progressive disclosure and bundled resources

At discovery time, only name and description are loaded. Read or execute bundled resources only when the current task needs them.

• references/ingestion.md, references/ontology.md, references/retrieval.md, and references/lint.md: extraction, normalization, retrieval, and lint guidance.
• scripts/template_agent_workflow.py, scripts/contextgraph.py, scripts/config.py, and scripts/tools/: runnable workflow and storage APIs.

Output template

## Mini context graph result

**Status:** ingested | answered | linted | blocked
**Operation:** <ingest | query | lint>
**Source/query:** `<doc_id, source path, or user question>`

### Evidence
- Documents: <supporting_documents or ingested sources>
- Entities: <entity names and types>
- Relations: <source -> relation -> target with confidence>

### Wiki updates
- `<wiki page>`: <created | updated | read | unchanged>

Quality gate

• Every entity and relation includes explicit supporting_text.
• No relation below MIN_CONFIDENCE or confidence 0.6 was added.
• Every new document called skill.ingest_with_content(...) and wrote a summary page.
• Query answers searched the wiki before graph traversal and cite evidence.