Architecture Decision Records
Architecture Decision Records (ADRs) capture significant design choices made during engram’s development. They are produced via the /adr and capture-adrs workflow — the source of truth is bd decision records, and the files in docs/adr/ are rendered from those records (do not edit them manually).
The list below links directly to the canonical ADR files in the repository. Do not copy or embed ADR bodies here — the files carry a “do not edit manually” banner and are regenerated on re-render.
- Dedicated store_discovery/search_discovery tools, not overloaded store_memory
- SvelteKit adapter-static SPA vendored via go:embed, SSR dropped
- Represent authz Subject as a sealed Go interface
- Deploy docs-site via an in-repo GitHub Actions wrangler workflow
- Trust sealed cookie sub until session TTL; defer per-request IdP refresh
- Discovery is a 5th category in the single Memory collection
- Graceful decay over binary staleness for discovery trust
- engram plugin ships no bundled MCP server; /engram-setup is the sole registration path
- Adopt ConnectRPC and protobuf/buf for the web UI API
- Embed the BFF in the engram Go binary, not a Node runtime
- Enforce per-actor authorization in the store layer, not in handlers
- Export telemetry via OTLP only; omit a Prometheus scrape endpoint
- shadcn-svelte (on bits-ui) + Tailwind v4 as the component layer, re-themed
- Instrument at three seams: HTTP, MCP method, and downstream clients
- Use the stable OIDC sub as the authorization key in a new owner field
- Sharing grants read but never write (read/write gate asymmetry)
- Instrument MCP tools via AddReceivingMiddleware, not per-handler
- Deploy docs-site via Workers Static Assets without an SSR adapter
- Host the docs site inside the engram monorepo at docs-site/
- Stateless encrypted-cookie session, no server-side store
- Telemetry is never a hard server startup dependency
- Return 404 not-found for unauthorized id-addressed operations
Generated index
Section titled “Generated index”The file docs/adr/README.md in the repository is the bd-generated ADR index — it is not an ADR itself.