Knowledge Tree

A knowledge tree organizes an agent’s domain knowledge as a hierarchy of verified entries. Each node is a KnowledgeEntry compiled to Vein binary, with parent-child relationships forming a tree that can be distributed and verified across agent instances.

Schema: KnowledgeEntry

knowledge-entry-v1.lode


{
  "schema": "lode",
  "version": 1,
  "name": "KnowledgeEntry",
  "fields": [
    { "id": 1, "name": "entryId",    "type": "string",             "required": true },
    { "id": 2, "name": "parentId",   "type": "string",             "required": false },
    { "id": 3, "name": "label",      "type": "string",             "required": true },
    { "id": 4, "name": "content",    "type": "string",             "required": true },
    { "id": 5, "name": "children",   "type": "string[]",           "required": false },
    { "id": 6, "name": "tags",       "type": "string[]",           "required": false },
    { "id": 7, "name": "embeddings", "type": "map<string,string>", "required": false },
    { "id": 8, "name": "sourceUrl",  "type": "string",             "required": false }
  ]
}

TypeScript Interface


interface KnowledgeEntry {
  entryId: string;                          // Unique node ID
  parentId?: string;                        // Parent node (null for root)
  label: string;                            // Human-readable title
  content: string;                          // Entry body text
  children?: string[];                      // Child entry IDs
  tags?: string[];                          // Categorization labels
  embeddings?: Record<string, string>;      // Model → embedding hash
  sourceUrl?: string;                       // Original source reference
}

Example: Compliance Knowledge Tree

root.json


{
  "entryId": "compliance-root",
  "label": "Compliance Frameworks",
  "content": "Top-level index of all supported regulatory frameworks.",
  "children": ["finra", "sec", "sox"],
  "tags": ["compliance", "regulatory"]
}

finra.json


{
  "entryId": "finra",
  "parentId": "compliance-root",
  "label": "FINRA Regulations",
  "content": "Financial Industry Regulatory Authority rules covering broker-dealer conduct, trade reporting, and market integrity.",
  "children": ["finra-rule-2111", "finra-rule-3110"],
  "tags": ["compliance", "financial", "finra"],
  "embeddings": {
    "nomic-embed-text": "e8f2a1b3..."
  },
  "sourceUrl": "https://www.finra.org/rules-guidance"
}

Compilation


$ lodec compile root.json -s knowledge-entry-v1.lode -o knowledge/root.vein
Compiled root.json → knowledge/root.vein (142 bytes)
Fingerprint: a1b2c3d4...
 
$ lodec compile finra.json -s knowledge-entry-v1.lode -o knowledge/finra.vein
Fingerprint: e5f6a7b8...

Tree Traversal

Load and verify nodes on demand as the agent navigates the tree:


async function loadEntry(entryId: string): Promise<KnowledgeEntry> {
  const res = await fetch(`${registry}/v1/knowledge/${entryId}/vein`);
  const vein = new Uint8Array(await res.arrayBuffer());
  const expected = res.headers.get("X-Lode-Fingerprint");
  const schema = loadLode("knowledge-entry-v1.lode");
 
  if (!verify(vein, expected, schema)) {
    throw new Error(`Knowledge entry "${entryId}" failed verification`);
  }
  return decode(vein, schema);
}
 
async function getChildren(entry: KnowledgeEntry): Promise<KnowledgeEntry[]> {
  return Promise.all((entry.children ?? []).map(loadEntry));
}

Embedding-Based Search

The embeddings map stores pre-computed embedding hashes per model, enabling verified semantic search:


async function searchKnowledge(query: string, model: string): Promise<KnowledgeEntry[]> {
  const queryEmbed = await embed(query, model);
  const entries = await loadAllEntries();
 
  return entries
    .filter(e => e.embeddings?.[model])
    .sort((a, b) => cosineSimilarity(queryEmbed, a.embeddings![model]) -
                     cosineSimilarity(queryEmbed, b.embeddings![model]))
    .slice(0, 10);
}

Because embeddings are part of the verified payload, you can trust that the search index hasn’t been manipulated.