Design records
Applies to OML v0.6.x · Status: Generated · Last verified 2026-11-06
Each decision about how OML works is a record in the repository, with the alternatives it rejected. The records are not part of this site. This page lists the 54 accepted records that describe the current release, by subject, and each row links to the record on GitHub.
Generated by scripts/gen_design_records.py; edit the source, not this page.
Trust and governance
The rules that make a write held, reviewed by someone else and signed.
Decision
The constitution: four rules, one bounded development exception
Tenancy is first-class
The status ladder: development, committed, validated; forward only; medallion words stay in the lake
Roles and keys: reader, writer, dreamer, admin, operator
Admission and review: external crews, serve binding, policy objects
An in-progress workarea serves unreviewed memories inside it, a curator agent may only narrow them, and nothing leaves until a person commits it
A person reviews a listed set of held items in one act, each item judged and signed as one verdict
The scan is a versioned, compiled-in rule set that vetoes leaked keys and holds what a reviewer should judge
Storage and data
Where memory lives, how it is encrypted, drained to the lake and erased.
Decision
PostgreSQL is the system of record: one commit point, per-tenant signed chains, a synchronous journal domain
Delta Lake is the derived body lakehouse: outbox-fed, single-writer, never the authority
Bodies and attachments: content-addressed, per-artifact encryption, digest-only journal
Erasure by crypto-shredding, with a named inventory and an honest boundary
Reconciliation is an incremental, journalled fold with a closed finding vocabulary
The lake writer drains the outbox it has, seals what it materializes, and answers only the operator
Search and recall
How recall finds, ranks and filters memories.
Decision
Reads are served from Postgres, journalled: one serving tier, a logged read path, steering ahead of hits
Text search reads integer postings, which row security lets an index serve, and says when it pruned a word or scanned
Reranking is a local cross-encoder stage after fusion, off by default until it fits the latency budget
Recall is measured by what readers do next, and only other readers' use moves a rank, within a bound
A memory states when it is true, recall hides what has ended, and recall searches the dates a query names without a model
Writing and review
What a write may carry and how review judges it.
Sources and sync
Where a memory came from and how a workarea follows a repository or a chat.
Integrations and agents
The API, the MCP tools, the plugin and the hooks agents use.
Decision
One versioned JSON HTTP API; MCP streamable HTTP as a stateless facade
The two-ring API: v1 memory provider, v2 memory lab
One key writes and recalls through grants, and an agent reads back, budgets, supersedes and retires its own memory only through admission
The CLI issues an agent's key in one call with its reader grant by default, and an admin skill runs it without the key value entering a transcript
The agent plugin starts every session from what OML holds for its key, through oml hook session-start
Claude's hosted apps reach the agent plugin over OAuth, through a connection that a one-time connect code binds to one agent key
A guardrail is a claim of its own kind, ratified under its workarea's review policy, that the agent plugin loads at every session start within the scope an admin set on its key, and whose optional rule a local hook checks before each tool call
The agent recalls for itself, and a failed command recalls only when the user opted in
The API is rewritten for v0.4.0 while OML is pre-release: three task-shaped MCP tools, a contract that declares only what is served, one URL and one key to start, and nothing lost
The plugin takes its server URL and its key through Claude Code's plugin configuration, keeps the key in the keychain, and falls back to OML_URL and OML_API_KEY only in its hooks
A directory reviewer reaches a demo workarea through a connect code that lives longer, and the tools and instructions describe instead of command
Operations and security
Deployment, identity, observability and the web pages.
Decision
The CLI is the administration surface; a web console is declined
Kubernetes workloads, two Helm profiles, deployment identity replaces volume identity
Three install profiles, one conformance bar; cluster-mode lead/follower
Workareas, crews, keys and tenants are named by unique, immutable keys that every surface accepts in place of their ids
The lead migrates as an owner role and serves as a role that owns nothing; _sqlx_migrations is the one table without row-level security
A quick start in one command per role: an installer that checks what it downloads, oml login, oml setup claude-code and oml quickstart
Every request logs one line under an id the caller may name, metrics stay off the public port, and trace export is opt-in
What OML releases defaults to the maintainer's public server, so an agent needs only its key; only oml setup claude-code among the CLI's verbs takes that default
Every user works under a root of their own beneath universe, and universe serves only curated claims, without their source
People sign in with Google or GitHub to a user page and an admin page that the lead serves on its own origin, and every act there is a session key's
The lifecycle, claim edges and the brief ship in v0.5.2 inside user roots, with no new tool
A public server runs to stated SLOs with an error budget
The stack, the workarea tree and how decisions are recorded.