docs(adr): 0003 — Memory contract (v1)

[EmersonBraun]

Summary

Third ADR of Phase 0 — formalizes Memory as two independent contracts (ChatMemory + VectorMemory) plus a standalone EmbedFn primitive.

Builds on ADR 0001 (Adapter) and ADR 0002 (Tool).

Merge note: this PR's docs/architecture/adrs/README.md will conflict with #267's. Recommended order: merge #267 → #270 → #271 (rebasing each onto main as merged).

What's included

• docs/architecture/adrs/0003-memory-contract.md — 17 invariants total (6 chat + 8 vector + 3 embed), stability tier stable, rationale, trade-offs.
• ADR index updated.

Key decision: split, don't unify

LangChain's unified Memory interface produces implementations that half-fulfill both chat and vector concerns. Real backends are asymmetric — Redis great for chat, mediocre for vectors; pgvector the opposite. We split them so a backend implements only what it does well.

Highlight invariants

ChatMemory

• CM2 Save is replace-all — append-with-dedup leaks complexity into every consumer; replace-all = "flush current state"
• CM4 Atomic from consumer view — partial save is a contract violation
• CM5 Empty returns [] — never null, never throw

VectorMemory

• VM1 Store is upsert by id — no duplicate-id errors, makes re-indexing cheap
• VM2 Dimensionality is a constructor concern — not in contract; trying to standardize it is bikeshedding
• VM3 Descending sort + VM5 threshold exclusive — reproducibility tiebreakers
• VM7 Delete is opt-in — compliance scenarios may legitimately refuse

EmbedFn

• E1 Stable output per input+model — randomness is a violation
• Separate from VectorMemory so adapters can ship their own embedders

Trade-offs accepted

• No native streaming/pagination of chat history (custom solutions for the rare giant sessions)
• No standardized metadata filtering — every backend has one but specs differ; v2 ADR if needed
• Embedding-model lock-in within a vector store is userland responsibility (good adapters log model name in metadata)

Unlocks

• 8 new memory backends in Fase 3 ([F3] #65 — Memory with client-side encryption #178): pgvector, Pinecone, Qdrant, Chroma, Weaviate, Turso, Cloudflare Vectorize, Upstash
• Stable RAG package ([F3] #62 — Browser Agent tool (Playwright + visão) #175) substrate
• Cross-backend migration via load → save for chat, search(topK=large) → store for vectors
• Memory graph ([F3] #67 — Personalization layer (persisted profile) #180) as a third contract — does not replace these

Test plan

• Doc renders on GitHub
• ADR index updated
• No code changes — pure documentation
• Reviewer: 17 invariants match current backends (file-vector, sqlite, redis-chat, redis-vector)?
• Reviewer: split convincing, or argue for unification?

Refs #214 #211