Phase 3 — Core Memory Substrate
Phase 3 proves memory can be written, deduplicated, conflict-checked, and retrieved correctly and fast — in isolation, testable via direct API calls.
Phase 3 — Core Memory Substrate
Status: Complete
Completed: 2026-08-31
Exit audit: phase3-exit-audit
What Phase 3 Delivers
Phase 3 proves memory can be written, deduplicated, conflict-checked, and retrieved correctly and fast — in isolation, testable via direct API calls. It deliberately does not touch the proxy hot path or auto-extraction; that is Phase 3.5. This mirrors how Phase 1 (auth/proxy plumbing) was kept separate from Phase 2 (actual LLM forwarding).
Why the Original Plan Needed This Rewrite
- IVFFlat replaced by HNSW: The original plan specified IVFFlat (lists=100) with HNSW deferred to Phase 4. Since Phase 3 is greenfield (no existing index to migrate), starting with the better index avoids a costly live-traffic migration later.
- Multi-label categories: The original single
categoryenum cannot represent memories that span multiple categories. A join table (memory_labels) replaces the exclusive enum. - Temporal validity: The original schema had no notion of when a fact was true, causing false contradictions when facts change over time.
valid_from/valid_untilcolumns fix this.
Phase 3 Scope — Five Tracks
| Track | Theme | Key Milestones |
|---|---|---|
| A | Memory Schema & Data Foundation | 3.1.1 (schema v2: HNSW, temporal validity, multi-label) |
| B | Vector Store & Embedding Integration | 3.2.1 (VectorStore interface, pgvector-HNSW impl, composite scoring v2) |
| C | Memory Write Pipeline | 3.C.1 (PII), 3.C.2 (dedup), 3.C.3 (temporal conflict), 3.C.5 (write persistence / orchestration), 3.C.4 (multi-label) |
| D | Read/Ranking Pipeline & Hot Cache | 3.D.1 (semantic search), 3.D.2 (category-conditional decay), 3.D.3 (Redis hot cache) |
| E | Exit Gate | 3.E.1 (security integration), 3.E.2 (e2e lifecycle test), 3.E.3 (retrieval benchmark sign-off), 3.E.4 (ADR consolidation), 3.E.5 (exit audit) |
New services (Phase 3 only)
| Service | Language | Path | Purpose |
|---|---|---|---|
| Memory Service | Python 3.12 | services/memory/ | Memory CRUD, dedup, vector search, hot cache |
Embedding service, context assembly, worker, API server, and dashboard are not in Phase 3 scope.
Recommended Execution Order
Track A (Schema — start immediately):
3.1.1 (memory schema v2)
Track B (Vector store — after Track A):
3.2.1 (VectorStore + pgvector-HNSW + composite scoring v2)
Track C (Write pipeline — after Track A + B):
3.C.1 (PII) → 3.C.2 (dedup) → 3.C.3 (temporal conflict) → 3.C.5 (write orchestration) → 3.C.4 (multi-label)
Track D (Read/ranking — after Track B):
3.D.1 (semantic search) → 3.D.2 (category-conditional decay) → 3.D.3 (hot cache)
Track E (Exit gate — after all):
3.E.1 → 3.E.2 → 3.E.3 → 3.E.4 → 3.E.5Key Design Decisions (ADRs)
Phase 2.5 published ADR-0040–ADR-0046. Phase 3 memory ADRs span ADR-0047–ADR-0049 and ADR-0052–ADR-0061 (excluding ADR-0051, published in Phase 2.5).
| Topic | ADR | Status |
|---|---|---|
| Memory schema v2 expand (HNSW, quality columns) | ADR-0052 | Accepted |
| Vector store + composite scoring v2 | ADR-0053 | Accepted |
| Temporal-interval-aware conflict detection | ADR-0056 | Accepted |
| Hot cache read path (Redis sorted set) | ADR-0059 | Accepted |
| Memory service tenant isolation (RLS + app-layer) | ADR-0060 | Accepted |
| Retrieval-quality benchmark methodology | ADR-0061 | Accepted |
Phase 3 Latency Budgets
| Operation | Budget | Notes |
|---|---|---|
| Memory write (full pipeline) | p95 < 200ms | Including embedding call |
| pgvector HNSW search | p95 < 30ms | 1M vectors, ef_search=40 |
| Hot cache read | p99 < 5ms | Redis sorted set ZREVRANGE |
| Composite scoring (70 candidates) | p95 < 10ms | Category-conditional decay |
Phase 3 Exit Criteria
Verified in phase3-exit-audit (45696a2):
- Memory write pipeline (9 steps) passes all unit + ISO-* integration tests
- HNSW recall@10 ≥ 98% on committed CI profile (
has_1moptional on smoke/fast per ADR-0061) - Temporal-interval-aware conflict detection: sequential-fact auto-supersedes; overlapping intervals escalate; zero LLM on non-overlapping intervals
- Retrieval-quality benchmarks in CI with committed baselines (HNSW, ranking-quality, write-pipeline)
- All 12 ISO-* cross-tenant isolation cases pass, including
memory_relationshipscross-org edge case - Per-memory FK cascade verified (ISO-2.1); org-scope GDPR + MinIO deferred to Phase 4.A.2
- Phase 1 and Phase 2 security regression tests pass (
security-integration) make e2e-smoke-p3-memoryexits 0- Phase 3 memory ADRs published (0047–0049, 0052–0061) and cross-linked from the decision log
- No proxy hot-path changes — handler/middleware unchanged during Phase 3 (Phase 3.5 boundary)
Relocated to Phase 3.5.E.2: MCP search_memory/write_memory E2E with ClickHouse tracing (stubs only in Phase 3 per ADR-0050).
Last updated on