Sat down with Claude today and laid out the vision. Described the problem, shared arscontexta's post, and asked it to help me design the technical architecture. The central question: when someone asks Iris a question, how does the right knowledge find its way from the database into her response?
Claude nailed the high-level design in one go. We went back and forth on the details, but the core pipeline came together fast.
The pipeline - four steps
Think of it like a librarian helping you research a topic:
-
Find the starting books - The librarian hears your question and pulls the most relevant books off the shelves. We do this with a scoring system that combines keyword matching (did you say "Docker"? There is a Docker node) with meaning matching (you said "containers" - that is semantically close to Docker even if you did not use the word).
-
Follow the references - Good books cite other books. The librarian follows those references to gather related material. We do the same - start at the best-matching nodes, then walk along the connections to grab neighbouring knowledge. Like pulling on a thread and seeing what comes with it.
-
Organise the stack - The librarian does not just dump books on your desk. She organises them: "Here are the core facts, here are the how-to guides, here is background reading." We format the nodes into structured sections.
-
Brief the assistant - Finally, the organised knowledge gets slipped into Iris's instructions before she responds. She reads it as part of her context, naturally weaving it into her answer.
The scoring recipe
How do we decide which nodes are "most relevant"? A blend of three signals:
- 55% keyword match - Did the question contain words found in the node? Fast and precise. Like searching for a book by title.
- 35% meaning match - Even if the exact words differ, is the concept similar? This uses embeddings (mathematical representations of meaning). Like a librarian who knows that "containers" and "Docker" are about the same thing.
- 10% type bonus - Some node types are naturally better starting points. An index node (like a table of contents) is more useful as a seed than a narrow reference note.
Guardrails
Without limits, the system could try to inject half the graph into every response. So we set a budget:
- Start from at most 6 seed nodes (the best matches)
- Follow connections at most 2 hops deep (friend of a friend, but not further)
- Collect at most 14 nodes total
- Stay under 2,500 tokens (roughly 2 pages of text)
Think of it like packing a suitcase: you have limited space, so you bring only what is most important and most relevant to the trip.
Types of knowledge
Not all knowledge is the same. We settled on six flavours:
| Type | What It Is | Analogy |
|---|---|---|
| Index | Entry point for a whole topic | Table of contents |
| Map of Content | Curates and links related nodes | A reading list |
| Skill | How to do something | A recipe card |
| Claim | Personal fact or preference | A sticky note on your monitor |
| Workflow | Step-by-step procedure | An instruction manual |
| Reference | External source or documentation | A bookmark |
What this changes for Iris
Today: Iris gets the same flat context no matter what you ask. Like a student who memorises the entire textbook but cannot find the right chapter during the exam.
With skill graphs: Iris gets a curated, connected subset of knowledge tailored to your question. Like a student who has colour-coded notes with cross-references and can flip to exactly the right page.
The difference is not just relevance - it is coherence. Related ideas arrive together, with their relationships intact.
Architecture is locked in. Time to build.