Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR-049: A composable operational knowledge framework

Date: 2026-10-12 Status: Accepted (design; implementation tracked separately) Author: Rômulo Febasi

Context

Synapse stores typed Markdown, indexes it in disposable SQLite and exposes one core through CLI/MCP. It is used as a knowledge dependency, not a replacement for note tools, Git, MCP or other memory/retrieval engines. Agents and Soma need budgeted source-linked queries, source evolution and reviewable updates to shared knowledge.

Positioning: Operational memory for agents, with governed changes, preserved history, and explicit integrity checks.

ADR-043 keeps acquisition in agent-composed MCP tools. Explicit source-revision monitoring is now requested, so an optional ingestion adapter seam amends that decision without making connectors part of pure core.

Decision

Expose a versioned KnowledgeClient contract over the existing core, initially through CLI JSON and MCP. Keep acquisition/retrieval/decision adapters outside the core, and represent external sources as revisioned, access-scoped references. Automatic detection proposes changes; acceptance remains governed.

Consequences

  • Positive: Soma and third parties consume the same knowledge surface, with existing tools remaining canonical.
  • Negative: lineage, source ACL changes and reconciliation are additional obligations.
  • Scope amendment: optional adapter workers are allowed at edges; default agent-composed capture remains supported.
  • Limit: cached remote data cannot be made safely available offline without an explicit access lease/policy.

Alternatives considered

  • Own a new all-purpose documentation UI: duplicates established products.
  • Replicate every remote document as accepted truth: creates stale copies and loses authority.
  • Embed every connector in core: breaks layering and burdens local users.
  • Treat another memory engine’s output as verified Synapse evidence: a provider bridge must disclose provenance/trust differences.

Implementation contract

Read contract: query + workspace/project/source scope + purpose + time/version/environment + token/latency budget; return bounded evidence passages with source revisions, freshness, confidence class, omissions and verification profile. ACL filtering occurs before candidate retrieval/model calls and again before output. Cache keys include policy/ACL revision, model revision and source digest. Optional grounded summaries cite retrieved passages and abstain when evidence is missing.

Write contract: propose with expected revision, source digests, run/context references and idempotency key; review/accept verifies current authority and stale-source preconditions. Credentials stay in connector secret storage. Read-only adapters precede write-back; write-back requires a scoped capability, explicit review and optimistic concurrency.

Implement Git/Markdown plus one remote connector first. Represent Notion/Jira/Confluence/Obsidian as adapters, not promised ready integrations. QMD/Mem0/Zep can be retrieval/memory providers with explicit trust mapping; Synapse-owned acceptance evidence remains separate.

References