Knowledge Graph

What It Is

The knowledge graph is shared institutional memory across all agents. It is backed by PostgreSQL — full-text search is the canonical default backend, with Apache AGE as an optional graph backend (UNITARES_KNOWLEDGE_BACKEND=age). Every agent can search, contribute, and update entries. Discoveries persist across sessions and are available to all agents in the system.

Search Before Creating

Always search before adding new entries:

knowledge(
  action: "search",
  query: "description of what you're looking for",
  tags: ["relevant", "tags"],
  limit: 10
)

The runtime may still expose older search aliases, but prefer the unified knowledge(action="search") path when available. Duplicate entries fragment knowledge and make search less effective.

Quick Contribution

For low-friction contributions, use leave_note():

leave_note(
  summary: "What you discovered or observed",
  tags: ["domain", "type", "context"]
)

Notes are automatically shared with all agents. Use this when you find something useful, spot a bug, or have an insight that others should know about.

Full CRUD Operations

For more control, use the knowledge() tool with an action parameter:

Discovery Types

When storing a discovery, classify it:

Check the live tool schema if you are unsure which enum values the current runtime accepts. Do not invent discovery types casually.

Status Lifecycle

Every discovery has a status:

open  -->  resolved    (problem solved, finding addressed)
  \-->  archived     (no longer relevant, superseded)

• open: Active, still relevant, may need attention
• resolved: The issue or finding has been addressed
• archived: No longer relevant (outdated or duplicate)

The runtime accepts more terminal states than the two above: disputed (contested finding), closed (terminal, generic), wont_fix (acknowledged, deliberately not addressed), and superseded (replaced by a newer entry — pair with knowledge(action="supersede")). Check the live tool schema for the authoritative set.

Tagging Best Practices

Tags are how future agents find your contributions. Be intentional:

• Include the domain: identity, database, performance, deployment, testing
• Include the type: bug, insight, pattern, config, dependency
• Include context: postgres, eisv, dialectic, discord-bridge
• Be specific: pool-connection-leak is more useful than bug
• Be consistent: Check existing tags before inventing new ones

Closing the Loop

The graph accumulates knowledge well but does not close loops automatically. This is a known gap that every agent should help address:

• When you resolve something, update its status. Do not leave it as open.
• When you find a duplicate, archive the less complete one and reference the better entry.
• When a finding is outdated, archive it with a note about what superseded it.
• Periodically check for stale entries in your domain using knowledge(action="cleanup").

Unresolved entries create noise. Closed loops create trust in the graph.

Synthesis: rolling up topics

knowledge(action="synthesize") compounds the discrete discoveries under a topic (a tag) into a single rolled-up summary row, so a cross-referenced, compounded narrative exists before query time instead of only being assembled on read via search(..., synthesize=true). It is the GraphRAG "community summary" pattern: a hierarchical summary layer maintained over the base discovery nodes.

• knowledge(action="synthesize") — sweep the densest topics and (re)build their

rollups. topic="..." rolls up a single tag; dry_run=true previews without writing; min_members (default 3) sets the threshold; use_llm=false forces the deterministic narrative.

• Rollups are stored as ordinary discoveries (type="topic_rollup", deterministic

id rollup::<topic>, tagged rollup), so they upsert in place across runs and are found by normal search — e.g. knowledge(action="search", tags=["rollup"]).

Run it on demand or on a periodic cadence (like cleanup/lint), not on every write — a per-write LLM pass across a multi-agent fleet is exactly the high-frequency-noise anti-pattern this graph avoids.

Deferred: bi-temporal fact validity (documented idea, not built)

A first-class notion of when a fact became true/false (valid-from / valid-to plus observation time, per the Graphiti/Zep bi-temporal model) was considered and deliberately deferred. It 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. Until then this stays a documented idea, not a roadmap item.