# Brain Maintenance: Memory Architecture & Notion Sync

## Status: ACTIVE — Move 1 in progress (March 2026)

## Background

Research conducted March 5, 2026 across web sources, academic papers, and industry blogs.
Key sources: arXiv survey "Memory in the Age of AI Agents" (2512.13564), @roeyazroel (Notion memory pattern), developers.dev, Mem0, CalmOps, Notion Custom Agents launch.

**Finding:** Our flat-file, human-auditable architecture is sound and validated by industry research. The consensus three-pillar model (Working/Episodic/Semantic memory) maps well to what we have. The gaps are in hygiene, sync, and semantic retrieval — not in the fundamental approach.

---

## Current Architecture Assessment

### What We Have (mapped to three-pillar model)

| Pillar | Industry Standard | Our Implementation | Grade |
|--------|------------------|-------------------|-------|
| **Working Memory** | Context window + active state | QMD current.json + auto-loaded files (AGENTS.md, SOUL.md, MEMORY.md, USER.md, HEARTBEAT.md) | **A** |
| **Episodic Memory** | Session history in Redis/DB | memory/YYYY-MM-DD.md daily logs + LEARNINGS.md | **B+** |
| **Semantic Memory** | Vector DB + knowledge graph | MEMORY.md (~30 lines) + memory_search (Gemini) + Notion (on-demand) | **C+** |

### Strengths
- **Human-auditable:** Every memory is a readable file. Assaf or any agent can inspect, edit, correct.
- **Security:** Immune to MINJA/AgentPoison/MemoryGraft attacks (no vector retrieval to poison).
- **Schema discipline:** QMD has structured JSON. MEMORY.md has enforced brevity.
- **Boot sequence:** Mandatory reads on session start (AGENTS.md boot protocol) ensures context continuity.

### Weaknesses
1. **No memory hygiene:** Zero TTL on daily logs. No dedup. No contradiction resolution. MEMORY.md grows until manually pruned.
2. **Notion sync is one-directional and manual:** We query Notion on-demand but don't write back systematically. Memory lives in two places and drifts.
3. **Semantic retrieval is weak:** memory_search is keyword/embedding over flat files. No relationships, no multi-hop reasoning.
4. **Daily logs accumulate without summarization:** 30+ days of daily logs = noise. No automatic compaction to monthly/weekly summaries.
5. **QMD accumulates cruft:** Completed tasks stay until manually compacted.

---

## The Plan: Three Moves

### Move 1: Memory Hygiene (This Week — March 5-12)
**Impact: HIGH | Effort: LOW**

#### 1a. Daily Log TTL & Auto-Summarization
- Daily logs older than 30 days → auto-summarized to `memory/monthly/YYYY-MM.md`
- Summary = key decisions, outcomes, learnings, unresolved items
- Raw daily logs archived to `memory/archive/YYYY-MM-DD.md` (kept but not searched by default)
- Script: `scripts/memory-compact-monthly.py`

#### 1b. MEMORY.md Dedup & Contradiction Gate
- Before any write to MEMORY.md: check for semantic duplicates
- If a new fact contradicts an existing one → replace, don't append
- Hard cap: 40 lines. If approaching, force a review.
- Script: `scripts/memory-dedup-check.py`

#### 1c. QMD Aggressive Compaction
- Auto-run `scripts/qmd-compact.py` on every heartbeat (not just session end)
- Completed tasks → daily log immediately, removed from QMD
- QMD should never exceed 50 lines of JSON

#### 1d. LEARNINGS.md Categorization
- Group rules by category (already partially done)
- Add date and source to each rule
- Remove any that are now encoded in SKILL.md files (deduplicate with skills)

### Move 2: Structured Notion Sync (March 12-26)
**Impact: HIGH | Effort: MEDIUM**

#### 2a. Design Notion Memory Schema
Create a dedicated Notion database: **"Agent Memory"**
Properties:
| Property | Type | Purpose |
|----------|------|---------|
| Content | Title | The memory/fact itself |
| Type | Select | decision / fact / preference / rule / project-state |
| Scope | Select | Global / Project / Agent |
| Project | Relation | Link to Projects DB |
| Source | Text | Where this came from (conversation, research, etc.) |
| CreatedAt | Date | When captured |
| LastVerified | Date | When last confirmed still true |
| ExpiresAt | Date | TTL — auto-flag stale entries |
| Priority | Select | Critical / Important / Reference |
| Agent | Select | Which agent created it (Kitt, Anton, etc.) |

#### 2b. Bi-Directional Sync Protocol
- **Write path:** After significant decisions/outcomes → create memory in Notion DB via API
- **Read path:** On boot / on-demand → query Notion for relevant memories (filtered by project, type, priority)
- **Sync script:** `scripts/notion-memory-sync.py`
- **MEMORY.md becomes a cache:** Top 20-30 critical facts, auto-generated from Notion DB (Priority = Critical)

#### 2c. Canonical Source of Truth
- Notion = semantic memory (long-term facts, decisions, relationships)
- QMD = working memory (active tasks, current session state)
- Daily logs = episodic memory (what happened today)
- MEMORY.md = hot cache (critical facts loaded every session)
- LEARNINGS.md = procedural memory (how to avoid mistakes)

### Move 3: Evaluate Notion Custom Agents (April 2026)
**Impact: POTENTIALLY HIGH | Effort: LOW (evaluation only)**

#### 3a. What to evaluate
- Can Notion Custom Agents monitor our Agent Memory DB and surface relevant context?
- Can they route project updates from Notion to Discord channels?
- Can they replace our manual sync scripts?
- Pricing: how many credits does a monitoring agent consume?

#### 3b. Pilot workflow
- One agent: "Project Status Updater" — monitors Projects DB, posts weekly summaries to Discord

#### 3c. Decision gate
- If Custom Agents can replace ≥2 of our scripts → adopt
- If they're too expensive or limited → continue with our scripts

---

## What We're NOT Doing (and why)

| Don't | Why |
|-------|-----|
| Vector DB (Pinecone/Weaviate) | Single-user system, Notion search + Gemini memory_search covers our needs |
| Knowledge Graph (Neo4j) | Overkill — use Notion relations between databases instead |
| Mem0/Zep/LangGraph | Multi-user SaaS tools, wrong abstraction for us |
| MemGPT-style architecture | Interesting pattern but our boot-sequence + QMD already handles this simpler |
| Fancy embeddings | memory_search with Gemini is good enough for our scale |

---

## Security Considerations

### Current Status: GOOD
- Flat files = human-auditable, no vector poisoning possible
- AGENTS.md boot sequence = deterministic context loading
- No external memory stores that could be corrupted

### Improvements to Add
- [ ] TTL on daily logs (Move 1a) — prevents memory rot
- [ ] Dedup gate on MEMORY.md (Move 1b) — prevents prompt pollution
- [ ] LastVerified date on Notion memories (Move 2a) — flags stale facts
- [ ] Agent attribution on memories (Move 2a) — audit trail for who wrote what

---

## Research Sources

1. **"Memory in the Age of AI Agents: A Survey"** — arXiv 2512.13564, Dec 2025 (1k+ stars). Definitive taxonomy.
2. **"Long-term memory for AI Agents using Notion Database"** — @roeyazroel, Medium, Jan 2026. Notion-as-memory pattern.
3. **"Architecting Persistent Memory for AI Agents"** — developers.dev, Mar 2026. Three-pillar model, enterprise patterns.
4. **"AI Agent Memory Systems: Context Management at Scale"** — CalmOps, Mar 2026. MemGPT patterns, implementation code.
5. **"AI Memory Security: Best Practices"** — Mem0 blog, Feb 2026. MINJA, AgentPoison, MemoryGraft attacks.
6. **"Building Persistent Memory with Go (Beads)"** — dasroot.net, Feb 2026. Benchmarks: Mem0 26% accuracy gain, Zep 18.5%.
7. **"Introducing Custom Agents"** — Notion blog, Feb 24 2026. Notion's native agent platform.
8. **Microsoft Azure: Memory Management for AI Agents** — techcommunity.microsoft.com, Apr 2025. Mem0 + Azure integration.
9. **"Demystifying AI Agent Memory"** — getmaxim.ai, Oct 2025. Schema design best practices.
10. **Redis: AI Agent Architecture in 2026** — redis.io blog. Production patterns.

---

## File Map

```
memory/
├── brain-maintenance/
│   ├── ARCHITECTURE.md          ← This file
│   └── IMPLEMENTATION-LOG.md    ← Progress tracking
├── qmd/
│   └── current.json             ← Working memory (active state)
├── monthly/                     ← NEW: Monthly summaries (Move 1a)
│   └── YYYY-MM.md
├── archive/                     ← NEW: Archived daily logs (Move 1a)
│   └── YYYY-MM-DD.md
├── YYYY-MM-DD.md                ← Episodic memory (daily logs)
scripts/
├── memory-compact-monthly.py    ← NEW: Monthly compaction (Move 1a)
├── memory-dedup-check.py        ← NEW: Dedup gate (Move 1b)
├── notion-memory-sync.py        ← NEW: Bi-directional sync (Move 2)
├── qmd-compact.py               ← EXISTS: Enhance for aggressive compaction
```

---

*Created: 2026-03-05 by Kitt*
*Last updated: 2026-03-05*
*Thread: #brain-maintenance → Research: AI Agent Memory & Notion Sync*