2026-04-12-01 — Mem0 SOP adopted; entity model and encoding schema defined; clean-slate migration executed

Context. The informal Mem0 scope rule from MEMO -17 was never followed in practice. All 16 live memories sat under user_id=ven with agent_id=null; get_memories({agent_id:“coo”}) returned zero results. Mem0 treats absent scope fields as literal null, not wildcards, so the entire…

Status: active
Supersedes: MEMO 2026-04-11-17 (informal scope rule “always pass user_id=ven and agent_id=coo”); codifies MEMO 2026-04-11-15 Finding A standing guidance into SOP

Context. The informal Mem0 scope rule from MEMO -17 was never followed in practice. All 16 live memories sat under user_id=ven with agent_id=null; get_memories({agent_id:"coo"}) returned zero results. Mem0 treats absent scope fields as literal null, not wildcards, so the entire back-catalog was invisible to correctly-scoped queries. Two noise memories had leaked into the MCP default user_id=mem0-mcp and required manual deletion. No entity existed for the Claude-Code runtime, mixing planner notes into the operator’s memory space. All memories were unstructured narrative prose with no typed metadata, no expiration dates, and no retention discipline.

Decisions.

1. SOP-MEM-001 adopted as coo/mem0_sop.md. This is the authoritative reference for how any VADE agent interacts with Mem0. It defines:

   • Entity model with four classes: operator (user_id only), agent (user_id + agent_id), Claude runtime (user_id + agent_id=claude-code), and session (+ run_id).
   • Memory type schema with four types: semantic, procedural, episodic, reflective — each with a defined metadata structure.
   • Standard metadata fields on every record: created_by, retention (permanent/durable/ephemeral), source_session.
   • Write discipline (default to not writing; Mem0 content rule from MEMO -10 applies; write semantic third-person assertions per MEMO -15 Finding A).
   • Retrieval discipline (always use explicit scoped filters; use get_memory by ID for ground-truth).
   • Session lifecycle (run_id generation, session-start search, session-end summary, noise sweep).

2. claude-code agent entity created. The Claude-Code runtime now has its own memory partition at {user_id:"ven", agent_id:"claude-code"} for reflective lessons and working notes, separate from the COO’s operational knowledge.

3. Clean-slate migration executed. All 16 legacy memories under user_id=ven (agent_id=null) were deleted and recreated with correct scope and typed metadata per the new schema. Stale records (commit hashes, noise deletion logs, file move details already captured in repo files) were not recreated.

4. CLAUDE.md updated. The session-start reading order now includes coo/mem0_sop.md at position 7. The Mem0 search instruction (item 11) specifies scoped filters. The “When you make a decision” and “When you end a session” sections reference the SOP for write and session-end discipline.

What this changes for future sessions: - Every Mem0 write must pass all applicable scope fields and a fully populated metadata object matching one of the four type schemas. - Every Mem0 search must use explicit {AND:[…]} filters. - Session-end produces exactly one episodic summary with retention:"ephemeral" and an expiration_date. - Session-start includes a noise sweep of user_id=mem0-mcp.

Retirement condition. This memo retires when SOP-MEM-001 is itself superseded by a future version (SOP-MEM-002+). The SOP document in coo/mem0_sop.md is the living reference; this memo is the case-law record of its adoption.