Architecture
RememberStack is a DAG across three planes, not a single ladder. The plane a component lives in fixes its rules: triggers, authority, mutability, rebuild semantics.
At a glance
inputs (files, mail, web, audio, video, images)
│
▼
E0 files ─→ E1 chunks ─→ E2 claims ─→ E3 facts Plane E — evidence spine
│ │ (Postgres + object storage)
│ ┌─────────────────────┤
▼ ▼ ▼
P3 corpus fs P1 search live graph Read models
indexes (Postgres)
K knowledge pages (git) Plane K — compiled + authored
| Plane | Trigger | Source of truth | Mutability | Rebuild |
|---|---|---|---|---|
| E | Per-document chain | Postgres (+ object bytes) | Append-only; windows close | n/a — is truth |
| K | Debounced evidence change | Git | Compiled rewrite / authored edit | Recompile (semantic) |
| P / read models | Inline or scheduled | None | P1 and graph are live; P3 is immutable | P1 maintenance / P3 rebuild |
Hard rule: validity and invalidation live only in PostgreSQL. P1 search indexes are derived state beside the authority rows; SQL/PGQ and recursive graph helpers read live PostgreSQL rows. Neither can become independent truth.
Plane E — evidence spine
Every input walks one durable, inspectable pipeline. Stages are idempotent workers on a work ledger (retries, dead-letter, budgets).
| Stage | Name | Job |
|---|---|---|
| E0 | Files | Store raw bytes; convert to Markdown via registered routes (smoke profile: Markdown passthrough; OCR/ASR/VLM when those routes are composed); structure sections; preserve locators |
| E1 | Chunks | Deterministic blocks → retrieval-sized chunks with context prefixes |
| E2 | Claims | Atomic grounded assertions (immutable) |
| E3 | Facts | Entity resolution + relation/observation adjudication, supersession, contradictions |
Postgres holds metadata, claims, entities, facts, evidence links, processing state. Object storage holds raw originals and converted representations.
Exhaustive write path: Ingestion · Pipeline stages · Lifecycle.
Plane K — compiled and authored knowledge
Git repository of knowledge pages:
- Compiled — LLM writers produce citation-bearing prose; a deterministic driver owns staleness, routing, and commits.
- Authored — human/agent commitments (principles, plans). Evidence changes flag them; nothing rewrites them silently.
K is never a structural input to P1 or graph reads. K pages and P3 cross-link as consumers of each other.
Agent contract and scopes: Knowledge (Plane K).
Plane P — projections agents use for speed
| Projection | Store | Serves |
|---|---|---|
| P1 | PostgreSQL 19 (pgvector + pg_textsearch) | Vector + BM25 over chunks and claims; semantic search over fact labels and entities |
| Live graph | PostgreSQL 19 SQL/PGQ + recursive SQL | Immediate neighborhood / path / as-of graph served directly from committed entity and relation authority |
| P3 | Object tree / mount | Browsable corpus filesystem (ls / cat / grep) |
P1 can be repaired from authority and P3 can be rebuilt. The graph is a live relational view plus catalog metadata, so there is no graph snapshot to rebuild.
Stores and authority
| Store | Role | Authority |
|---|---|---|
| PostgreSQL | Spine plus derived P1 vectors and BM25 indexes | E source of truth for natural rows; P1 state is rebuildable |
| Object storage — raw | Original bytes | Byte authority |
| Object storage — artifacts | Converted Markdown, structure, media sidecars | Representation authority (replay, not regenerate-in-place) |
| PostgreSQL SQL/PGQ graph | Live views over the E authority | Derived read model; no copied rows |
| Git | Plane K | K source of truth (authored + compile history) |
Write path vs read path
Writes may call models (conversion helpers, claim extraction, adjudication, K compilation). Work is ledgered, versioned, and replayable.
Reads use no LLM completion (semantic paths may still embed the query). Projections nominate; Postgres confirms; the envelope accounts for grain, freshness, contradictions, truncation, and typed negatives.
Exhaustive read path: Retrieval.
Consumption architecture
Four surfaces, one precedence rule:
- Mounts (when available) — prefer for navigate/read/grep
- API — enforcement point for query-engine reads; open SQL + assured ops
- CLI — same operations for shell agents
- MCP — same operations for tool-using harnesses
Deployment-rendered consumption skill teaches the two-layer model and is checked by cold-agent evals. See Mounts and skill.
Registries (shared control data)
| Registry | Why it exists |
|---|---|
| Entities | Canonical IDs + aliases; merge transcripts |
| Predicates | Governed vocabulary with escape values |
| Operations / saved queries | Versioned query compositions; MCP renders from registry |
| Ontology packs | Domain extensions without forking the core |
Adding a operation is inserting a row — surfaces stay in lockstep.
Scale posture
- Content-addressed reuse: identical bytes paid once.
- Edit-proportional reprocessing: unchanged chunks reuse claims/vectors.
- P3 builds are whole-corpus; P1 updates incrementally and graph reads are live.
- Spike-tested search and hub pagination at large row/edge counts (see project status / design spikes) — not a hosted SLA.
Where deeper design lives
This site documents what ships. Extended architecture notes for implementers live in the repository under plan/designs/ (optional reading — not required to use the product).