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

| 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

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 g