feat(kg): on-demand topic synthesis (close the loop, #44)

[cirwel]

Summary

Addresses the two KG gaps surfaced by the LLM-wiki comparison (#44 / PR #45), but scoped down after review rather than building both as proposed:

• Gap 1 — synthesis (built, reframed): adds knowledge(action="synthesize"), a periodic/on-demand pass that compounds discrete discovery rows into rolled-up topic summaries, so a cross-referenced, compounded narrative exists before query time — not only on read via search(..., synthesize=true). This closes the loop the knowledge-graph skill admits is open ("does not close loops automatically"), using the GraphRAG community-summary pattern.
• Gap 2 — bi-temporal temporal edges (deferred, documented): considered and not built. See rationale below.

Why synthesis is on-demand, not on-write

The original issue framed this as a "post-write synthesis pass". For a multi-agent fleet that writes constantly, running an LLM pass on every store/note is the auto-checkin-on-every-trivial-write anti-pattern UNITARES lists as a non-goal — per-write latency, LLM cost, and a fresh noise source (stale auto-generated rollups racing live writes). So synthesis runs like cleanup/lint: on demand, or wired to a periodic trigger, reusing the existing store + LLM-delegation machinery. No per-write cost.

Why no schema change

Rollups are persisted as ordinary discovery rows — type="topic_rollup", deterministic id rollup::<topic>, tagged rollup. They upsert in place (compounding across runs, never duplicating) via the existing ON CONFLICT (id) DO UPDATE write path, are queryable through normal search, and are lifecycle-managed like any other discovery. Zero migration. Falls back to a deterministic narrative when no LLM is reachable, so it works headless.

Usage

knowledge(action="synthesize")                       # sweep densest topics, build rollups
knowledge(action="synthesize", topic="identity")     # one topic
knowledge(action="synthesize", dry_run=true)          # preview, no writes
knowledge(action="synthesize", use_llm=false)         # deterministic narrative only
knowledge(action="search", tags=["rollup"])           # read the rollups back

Why Gap 2 (bi-temporal validity) was deferred

A first-class notion of when a fact became true/false (valid-from / valid-to + observation time, per the Graphiti/Zep model) is a substrate-level change: migration, AGE query rewrites, and every read path having to reason about time — for a payoff (point-in-time reconstruction, automatic invalidation) that is speculative for current usage. The existing superseded status + created_at is an ~80% substitute. The signal to build it is a concrete failure (an agent acting on a stale fact in a way that actually bites). It is recorded as a deliberately deferred idea in skills/knowledge-graph/SKILL.md, not a roadmap item.

Changes

• src/mcp_handlers/knowledge/synthesis.py — rollup construction + the synthesis pass (pure helpers + orchestration)
• src/mcp_handlers/knowledge/handlers.py — handle_synthesize_knowledge_graph; register topic_rollup type
• src/mcp_handlers/consolidated.py, schemas/knowledge.py, __init__.py — wire the synthesize action + params (topic, min_members, use_llm)
• src/db/mixins/knowledge_graph.py — kg_topic_candidates read-only aggregate (densest tags)
• skills/knowledge-graph/SKILL.md — document synthesize; record the temporal-edges deferral
• tests/test_kg_synthesis.py — 14 tests (pure logic + orchestration, no live DB/LLM)

Testing

• New suite: 14/14 pass.
• No regressions across knowledge/migration/handler/schema/router suites (test_knowledge_graph_*, test_migration_registry_versions, test_kg_*, test_decorators, test_tool_stability, test_handler_registry, test_pydantic_schemas, test_extracted_handlers, test_admin_handlers, test_remaining_modules, test_tool_modes — all green).
• Full DB-backed integration (live Postgres + AGE) wasn't runnable in this environment; CI is the final gate.

https://claude.ai/code/session_01Dz2VWo4AxPyE7eoNzHRo9U

---

Generated by Claude Code

[github-actions]

✅ Documentation Validation Passed

Tool Count: 7 tools tools
Version: 2.13.0

All documentation is synchronized with the codebase.

[github-actions]

✅ Documentation Validation Passed

Tool Count: 7 tools tools
Version: 2.13.0

All documentation is synchronized with the codebase.