# Brain Maintenance: Notion Agent Memory Database Schema
*Prep work for Move 2 (starts March 12, 2026)*

## Database: "Agent Memory"
*Canonical source of truth for all agent memory beyond current session*

### Core Properties

| Property | Type | Description | Options |
|----------|------|-------------|---------|
| **Content** | Title | The memory/fact itself | — |
| **Type** | Select | Category of memory | decision, fact, preference, rule, project-state, entity, insight |
| **Scope** | Select | Boundary of relevance | Global, Project, Agent, Client |
| **Project** | Relation | Link to Projects DB | → Projects database |
| **Source** | Rich Text | Origin context | Conversation ID, research session, external input |
| **CreatedAt** | Date | When captured | Auto-populated |
| **LastVerified** | Date | When last confirmed accurate | Manual/script update |
| **ExpiresAt** | Date | TTL for staleness detection | Auto-flagging |
| **Priority** | Select | Importance level | Critical, Important, Reference |
| **Agent** | Select | Creating agent | Kitt, Anton, Ogilvy, Tatiana, Gerri, Julia, Jessica, Thibault |
| **Status** | Select | Memory lifecycle | Active, Superseded, Archived, Contradicted |

### Additional Properties

| Property | Type | Description |
|----------|------|-------------|
| **Tags** | Multi-select | Semantic clustering | api-key, contact, process, metric, deadline, etc. |
| **RelatedMemories** | Relation | Cross-references | Self-relation for memory graphs |
| **Context** | Rich Text | Additional detail/background | When needed |
| **VerificationScript** | Text | How to verify this is still true | For auto-verification |

## Memory Types & Examples

### Type: decision
**Purpose:** Strategic and tactical decisions that affect future work
**Examples:**
- "All CE pages must use Larken + Inter + JetBrains Mono fonts"
- "Sub-agent briefs max 5 lines: What + Constraints + Autonomy + Output + Done-when"
- "Creative pipeline: Kitt → Gerri → team + Anton → Gerri → Kitt → Assaf"

### Type: fact
**Purpose:** Verifiable information about systems, accounts, capabilities
**Examples:**
- "Gemini API key: AIzaSyDXqYZInk83iVV4mD29pSuHQKbgkiI1x9Q (in ~/.bashrc as GEMINI_API_KEY)"
- "Guild ID: 1467974388581273603"
- "Screenshots: Use Playwright (/usr/bin/playwright), NOT ScreenshotOne"

### Type: preference
**Purpose:** Assaf's working preferences and communication style
**Examples:**
- "Assaf prefers solutions over questions - bring recommendations, not options"
- "Don't interrupt or speak over him — core trigger"
- "Morning person (natural early riser), caffeine-dependent"

### Type: rule
**Purpose:** Operational rules and constraints
**Examples:**
- "NEVER write to openclaw.json or /root/.openclaw/ outside workspace"
- "All new Discord channels private by default"
- "Session >50k → alert | >100k → STOP"

### Type: project-state
**Purpose:** Current state of specific projects/initiatives
**Examples:**
- "HUD brand page: waiting on Assaf for image picks + human cost layer"
- "PHAT CEO deck: Thibault rebuilding with liquid gold direction"
- "Strategic Board Advisory: validation phase, Dan Shipper + Felipe emails ready"

### Type: entity
**Purpose:** People, companies, and relationship context
**Examples:**
- "Dan Shipper (Every.com) - ideal Strategic Board Advisory validation contact"
- "Yaniv Izardel (yaniv@isac-law.com) - eToro external counsel"
- "Felipe Arosemena - strong co-founder relationships, intro source"

### Type: insight
**Purpose:** Strategic insights and patterns discovered
**Examples:**
- "25% of skills had matching work done WITHOUT loading the skill - execution gap"
- "Token leak caused by 90 heartbeat sessions running on Opus 24/7"
- "Multi-channel revenue arbitrage: same content, different pricing models"

## Sync Protocol Design

### Write Path (Memory Creation)
**Triggers:**
- After significant decisions in conversations
- Completion of major tasks/projects
- Discovery of important facts or insights
- Changes to processes or preferences
- New entity relationships

**Script:** `scripts/notion-memory-write.py`
**Usage:** `python3 scripts/notion-memory-write.py --type decision --content "All CE pages MUST use styleguide" --scope Global --priority Critical`

### Read Path (Memory Retrieval)  
**Triggers:**
- Session boot (Priority: Critical memories)
- Before project work (Project-scoped memories)
- On-demand queries (memory_search replacement)

**Script:** `scripts/notion-memory-read.py`
**Usage:** `python3 scripts/notion-memory-read.py --project HUD --type fact,decision`

### MEMORY.md Generation
**Purpose:** Hot cache of most critical facts for auto-loading
**Source:** Agent Memory DB where Priority = Critical AND Status = Active
**Regeneration:** Daily via cron, after significant memory writes
**Script:** `scripts/generate-memory-md.py`

## Migration Strategy

### Phase 1: Database Setup (March 12-14)
1. Create "Agent Memory" database in Notion with schema above
2. Migrate current MEMORY.md entries as seed data
3. Test API read/write scripts

### Phase 2: Manual Population (March 15-19)  
1. Extract key decisions from recent daily logs (last 30 days)
2. Populate entity relationships from contact references
3. Add critical facts from docs/reference.md and credentials-registry.md

### Phase 3: Bi-directional Sync (March 20-26)
1. Implement write path: auto-capture decisions and facts
2. Implement read path: query on boot and on-demand
3. Auto-generate MEMORY.md from Critical priority entries
4. Test sync reliability and performance

### Phase 4: Full Integration (March 27+)
1. Replace memory_search with Notion queries
2. Retire flat-file dependency for semantic memory
3. Monitor sync performance and data quality
4. Establish maintenance routines

## Success Metrics

### Memory Quality
- **Completeness:** Key decisions/facts captured within 24h
- **Accuracy:** LastVerified dates current, no contradictions
- **Discoverability:** Can find relevant memories in <30s
- **Currency:** Stale memories flagged and updated/archived

### System Performance  
- **Load time:** Session boot <5s including critical memory load
- **Sync reliability:** 99%+ success rate on read/write operations  
- **Search speed:** Query results in <2s
- **Storage efficiency:** No duplicate or contradictory memories

### Agent Effectiveness
- **Context continuity:** Agents reference previous decisions correctly
- **Reduced repetition:** Don't re-ask questions answered in memory
- **Better delegation:** Sub-agents have access to relevant context
- **Improved handovers:** Knowledge persists across sessions/agents

---

**File:** `/root/.openclaw/workspace/brain-maintenance-notion-schema.md`
**Created:** March 6, 2026 — 5:40 PM UTC  
**Purpose:** Prep work for Brain Maintenance Move 2 (Structured Notion Sync)
**Next:** Wait for March 12 to begin implementation phase
**Part of:** Brain Maintenance architecture improvement initiative