Phase 3 — Core Memory Substrate

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 category enum 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_until columns 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 detection/redaction), 3.C.2 (dedup), 3.C.3 (temporal conflict detection), 3.C.4 (multi-label classification)
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.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.5

Key Design Decisions (ADRs)

Phase 2.5 already published ADR-0040–0046 (Anthropic through embedder registry). Temporal memory foundation is ADR-0047. Schema v2 expand is ADR-0052. Further Phase 3 ADRs below are planned titles — assign the next free numbers at write time (do not reuse 0040–0051).

Topic	Status
Memory schema v2 expand (HNSW, quality columns)	ADR-0052 Accepted (`000017`)
Vector store + composite scoring v2	Planned
Temporal-interval-aware conflict detection	Planned (builds on ADR-0047)
Memory service tenant isolation (RLS + app-layer)	Planned
Retrieval-quality benchmark methodology	Planned

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

Memory write pipeline (9 steps) passes all unit + ISO-* integration tests
HNSW recall@10 >= 98% and p99 < 100ms at 1M-row benchmark scale
Temporal-interval-aware conflict detection correctly distinguishes sequential-fact vs. true-contradiction cases, with zero unnecessary LLM calls on non-overlapping intervals
Retrieval-quality benchmark running in CI with a committed baseline
All 10+ ISO-* cross-tenant isolation cases pass, including the memory_relationships cross-org edge case
GDPR delete cascade verified end-to-end
All Phase 1 and Phase 2 security regression tests still pass with zero regressions
make e2e-smoke-p3-memory exits 0
Phase 3 memory ADRs published (next free numbers after ADR-0047; do not reuse 0040–0046) and cross-linked from the phase decision log
No proxy hot-path changes — explicitly re-verified (that is Phase 3.5's boundary)