@vuau/agent-memory 0.1.0

package/docs/RESEARCH.md

@@ -0,0 +1,216 @@
+# Research: AI Memory Solutions — Tools Tried & Why File-Based Won
+
+## The Problem
+
+AI assistants (OpenCode, Copilot, Cursor, Windsurf) lose context between sessions. They need:
+- ✅ Local-first (no API keys)
+- ✅ Cross-IDE (OpenCode, VS Code, Windsurf, Antigravity)
+- ✅ Cross-platform (Host + VM, Windows 11 + Linux)
+- ✅ Persistent memory for decisions
+- ✅ Low token overhead
+- ✅ Reliable retrieval
+
+## Tools Evaluated
+
+| Tool | Auto-capture | VM compatible | Blocker | Status |
+|------|--------------|---------------|---------|--------|
+| **qmd** | ❌ (search only) | ❌ | better-sqlite3 needs Visual Studio Build Tools; HuggingFace blocked | ❌ Failed |
+| **memsearch** | ✅ (daemon hooks) | ❌ | milvus-lite has no Windows wheels; HuggingFace blocked | ❌ Failed |
+| **mem0** | ✅ (hooks) | ❌ | Requires OpenAI API key or HuggingFace models | ❌ Failed |
+| **memories.sh** | ✅ (MCP) | ✅ | Auto-generates 10+ IDE config files (bloats repo) | ⚠️ Rejected |
+| **codemem** | ❌ | ❌ | Flaky (unreliable save/recall) | ⚠️ Rejected |
+| **OpenCode plugin** | ✅ (lifecycle hooks) | ✅ | None | ✅ **Viable** |
+| **GitHub Copilot native** | Partial (skills) | ✅ | No lifecycle hooks; no direct session integration | ⚠️ Limited |
+| **File-based + rules** | Manual (via rules) | ✅ | None | ✅ **CHOSEN** |
+
+---
+
+## Why Each Failed
+
+### qmd
+**Blocker**: `better-sqlite3` native module requires Visual Studio Build Tools to compile on Windows. HuggingFace is also blocked in many environments.
+**Impact**: Cannot run on VM Windows 11 → breaks cross-platform requirement.
+
+### memsearch
+**Blockers**:
+1. `milvus-lite` has no pre-built wheels for Windows → must compile from source
+2. HuggingFace models blocked in isolated environments
+3. **Context Blindness**: Auto-capture can't link user command ("remember this info") to 10-line analysis from previous turn → writes "No context provided" error
+4. **Context Bloat**: Falls back to `memory_transcript`, pulling 19 old tool calls into context = **47,389 tokens (24% of context budget)**
+
+**Impact**: Unreliable on Windows + VM. Token cost makes it unusable for real work.
+
+### mem0
+**Blocker**: Requires OpenAI API key or HuggingFace (both violate "local-first, no API key" requirement).
+**Impact**: Not viable for local-first requirement.
+
+### memories.sh
+**Reevaluation**:
+- ✅ CLI tool (good)
+- ✅ Local-first (good)
+- ✅ MCP support (cross-IDE capable)
+- ✅ Clear memory fragmentation (Session, Semantic, Episodic, Procedural)
+- ❌ **Auto-generates 10+ config files per IDE** (`.memories.sh` configs for Zsh, Bash, Fish, Zed, Helix, Neovim, etc.)
+- ❌ Conflicts with "lightweight, centralized control" goal
+
+**Decision**: Violates architecture principle of keeping configuration minimal and in one place. Repository becomes cluttered.
+
+### codemem
+**Issue**: Flaky (sometimes saves, sometimes doesn't). No consistent retrieval.
+**Impact**: Cannot be relied upon for critical decisions.
+
+---
+
+## Why File-Based Won
+
+### 1. **No Environmental Blockers**
+- Plain text files work everywhere (Host, VM, Windows 11, Linux)
+- No native modules, no HuggingFace, no build tools required
+- ✅ Cross-platform by default
+
+### 2. **Handles Context Blindness**
+- **Problem with auto-capture**: System can't reliably link user intent ("remember this") to prior technical analysis
+- **Solution**: Agents write memory **when they understand context**
+  - Agent just finished exploring codebase → writes 1-line decision
+  - User approved decision → agent appends to MEMORY.md
+  - Agent reads MEMORY.md before implementing → follows pointer to spec file
+- Result: Context is always linked because agent is in session when writing
+
+### 3. **Solves Context Bloat**
+- Auto-capture tools fail gracefully → pull raw transcripts (~47k tokens)
+- File-based stores curated 1-liners (~200 tokens)
+- **66x cheaper per session**
+
+### 4. **IDE Portability**
+| IDE | Integration | Works Now |
+|-----|-------------|-----------|
+| OpenCode | Plugin hooks | ✅ Yes |
+| GitHub Copilot | Reads `.github/copilot-instructions.md` | ✅ Yes |
+| Cursor | Reads `.cursorrules` | ✅ Yes |
+| Windsurf | Reads `.windsurfrules` | ✅ Yes |
+| VS Code | Reads markdown in workspace | ✅ Yes |
+
+No custom driver needed per IDE. Markdown is portable.
+
+### 5. **Sharing & Sync**
+- Lives in git repo → automatically shared via Git/Rsync/Dropbox
+- Developers see decision history in commits
+- Can be backed up, versioned, audited
+- No external database to sync across machines
+
+### 6. **Transparent & Auditable**
+- Human-readable: can review MEMORY.md directly
+- No "locked in SQLite/Vector DB" problem
+- No export/import needed
+- Git history shows who decided what and when
+
+---
+
+## Architecture: 4-Layer Design
+
+### Why 4 Layers?
+
+**Problem**: Automatic memory systems fail when:
+1. They can't link user intent to prior context (blindness)
+2. They generate massive output when fallback fails (bloat)
+3. They aren't portable across environments
+
+**Solution**: Explicit layers that separate concerns:
+
+```
+Layer 1: Router (AGENTS.md, ~100 lines)
+├─ Critical rules + pointers only
+└─ Every IDE reads this first
+
+Layer 2: Memory (MEMORY.md, ~150 lines)
+├─ Curated 1-line decisions
+├─ Category headers with spec pointers
+└─ Agent reads before implementing
+
+Layer 3: Tasks (TASKS.md)
+├─ Current work, in-progress, next steps
+└─ Enables session continuity
+
+Layer 4: Specs (spec/*.md, on-demand)
+├─ Detailed patterns, examples
+├─ Referenced by Layer 2
+└─ Agent loads only when needed
+```
+
+**Progressive Disclosure**: Agents read ~200 tokens initially, follow pointers on-demand. Same token cost regardless of project size.
+
+---
+
+## Token Cost Comparison
+
+### Session 1: Find Storybook Rules (memsearch)
+```
+memory_search query:           100 tokens
+memory_get fails              (file lock)
+↓ fallback to memory_transcript
+memory_transcript (19 calls): 47,389 tokens
+TOTAL:                        47,489 tokens
+```
+
+### Session 2: Find Storybook Rules (file-based)
+```
+Read MEMORY.md:                 200 tokens
+Follow pointer → spec file:     500 tokens
+TOTAL:                          700 tokens
+```
+
+**Ratio**: 66x cheaper with file-based approach.
+
+---
+
+## Why "Manual" (Agent Rules) > "Automatic"
+
+### Automatic Capture (memsearch, qmd, mem0)
+- ❌ Context Blindness: Can't link decision to prior context
+- ❌ Context Bloat: Fallback pulls massive raw data
+- ❌ Platform Bloat: Needs dependencies (sqlite, milvus, HF)
+- ✅ Zero manual effort
+
+### Agent Rules (File-based)
+- ✅ Context aware: Agent writes when they understand
+- ✅ Curated: Only important decisions survive
+- ✅ Portable: Works everywhere (no dependencies)
+- ❌ Needs agent discipline (mitigated by plugin reminders)
+
+**Verdict**: Quality + Portability > Automation for teams of 1-10.
+
+---
+
+## Cross-IDE Reality Check
+
+### ✅ What Works Now
+- OpenCode: Plugin hooks + session lifecycle
+- Copilot: Reads `.github/copilot-instructions.md` natively
+- Cursor: Reads `.cursorrules`
+- Windsurf: Reads `.windsurfrules`
+- VS Code: Reads markdown files
+
+### ⚠️ Limitations
+- Copilot doesn't have lifecycle hooks (can't auto-remind to update tasks)
+- Cursor/Windsurf limited to reading rules, not injecting context
+- **Solution**: VSCode extension (Phase 3) to provide unified sidebar
+
+---
+
+## Conclusion
+
+**For teams 1-10 working on focused projects:**
+
+File-based memory + agent rules beats every alternative because it:
+1. Works on VM Windows 11 (no build tools, no native modules)
+2. Doesn't bloat token budget (700 vs 47k tokens)
+3. Works with all IDEs without custom drivers
+4. Shares naturally via git (Host ↔ VM ↔ Team)
+5. Is transparent and auditable
+
+**Automated memory capture fails** because:
+- Context Blindness: Can't reliably link user intent to prior analysis
+- Context Bloat: Fallback to raw transcripts costs 47k+ tokens
+- Platform bloat: Requires dependencies that don't compile on Windows/VM
+
+**The right trade-off**: Sacrifice full automation for reliability, portability, and cost.

package/docs/RESEARCH.vi.md

@@ -0,0 +1,216 @@
+# Nghiên cứu: Giải pháp AI Memory — Các Tool Đã Thử & Tại Sao File-Based Thắng
+
+## Bài toán
+
+AI assistants (OpenCode, Copilot, Cursor, Windsurf) mất context giữa sessions. Chúng cần:
+- ✅ Local-first (không API key)
+- ✅ Cross-IDE (OpenCode, VS Code, Windsurf, Antigravity)
+- ✅ Cross-platform (Host + VM, Windows 11 + Linux)
+- ✅ Persistent memory cho decisions
+- ✅ Token overhead thấp
+- ✅ Retrieval đáng tin cậy
+
+## Các Tool Đánh giá
+
+| Tool | Auto-capture | VM compatible | Blocker | Trạng thái |
+|------|--------------|---------------|---------|-----------|
+| **qmd** | ❌ (search only) | ❌ | better-sqlite3 cần Visual Studio Build Tools; HuggingFace blocked | ❌ Failed |
+| **memsearch** | ✅ (daemon) | ❌ | milvus-lite không có Windows wheels; HuggingFace blocked | ❌ Failed |
+| **mem0** | ✅ (hooks) | ❌ | Cần OpenAI API key hoặc HuggingFace models | ❌ Failed |
+| **memories.sh** | ✅ (MCP) | ✅ | Auto-generate 10+ IDE config files (bloat repo) | ⚠️ Rejected |
+| **codemem** | ❌ | ❌ | Flaky (unreliable save/recall) | ⚠️ Rejected |
+| **OpenCode plugin** | ✅ (lifecycle hooks) | ✅ | None | ✅ **Viable** |
+| **GitHub Copilot native** | Partial (skills) | ✅ | Không có lifecycle hooks | ⚠️ Limited |
+| **File-based + rules** | Manual (via rules) | ✅ | None | ✅ **CHOSEN** |
+
+---
+
+## Tại Sao Mỗi Cái Failed
+
+### qmd
+**Blocker**: `better-sqlite3` native module cần Visual Studio Build Tools để compile trên Windows. HuggingFace cũng bị blocked.
+**Impact**: Không chạy được trên VM Windows 11 → phá vỡ cross-platform requirement.
+
+### memsearch
+**Blockers**:
+1. `milvus-lite` không có pre-built wheels cho Windows → phải compile từ source
+2. HuggingFace bị blocked trong isolated environments
+3. **Context Blindness**: Auto-capture không thể liên kết lệnh user ("remember this info") với 10-line analysis từ turn trước → ghi "No context provided" error
+4. **Context Bloat**: Fallback sang `memory_transcript`, kéo 19 old tool calls vào context = **47,389 tokens (24% of context budget)**
+
+**Impact**: Unreliable trên Windows + VM. Token cost làm nó unusable.
+
+### mem0
+**Blocker**: Cần OpenAI API key hoặc HuggingFace (cả hai violate "local-first, no API key").
+**Impact**: Không phù hợp với local-first requirement.
+
+### memories.sh
+**Đánh giá lại**:
+- ✅ CLI tool (tốt)
+- ✅ Local-first (tốt)
+- ✅ MCP support (cross-IDE capable)
+- ✅ Clear memory fragmentation (Session, Semantic, Episodic, Procedural)
+- ❌ **Auto-generate 10+ config files per IDE** (`.memories.sh` cho Zsh, Bash, Fish, Zed, Helix, Neovim, etc.)
+- ❌ Conflict với "lightweight, centralized control" goal
+
+**Decision**: Violate architecture principle của keeping configuration minimal. Repo bị clutter.
+
+### codemem
+**Issue**: Flaky (thỉnh thoảng save được, thỉnh thoảng không). Retrieval không consistent.
+**Impact**: Không thể rely on cho critical decisions.
+
+---
+
+## Tại Sao File-Based Thắng
+
+### 1. **Không Environmental Blockers**
+- Plain text files hoạt động everywhere (Host, VM, Windows 11, Linux)
+- Không native modules, không HuggingFace, không build tools
+- ✅ Cross-platform by default
+
+### 2. **Xử lý Context Blindness**
+- **Vấn đề với auto-capture**: System không thể reliably link user intent ("remember this") tới prior technical analysis
+- **Solution**: Agents ghi memory **khi họ hiểu context**
+  - Agent vừa explore xong codebase → ghi 1-line decision
+  - User approved decision → agent append vào MEMORY.md
+  - Agent read MEMORY.md trước implement → follow pointer tới spec file
+- Result: Context always linked vì agent đang trong session khi ghi
+
+### 3. **Giải quyết Context Bloat**
+- Auto-capture tools fail gracefully → pull raw transcripts (~47k tokens)
+- File-based store curated 1-liners (~200 tokens)
+- **66x cheaper per session**
+
+### 4. **IDE Portability**
+| IDE | Integration | Works Now |
+|-----|-------------|-----------|
+| OpenCode | Plugin hooks | ✅ Yes |
+| GitHub Copilot | Reads `.github/copilot-instructions.md` | ✅ Yes |
+| Cursor | Reads `.cursorrules` | ✅ Yes |
+| Windsurf | Reads `.windsurfrules` | ✅ Yes |
+| VS Code | Reads markdown | ✅ Yes |
+
+Không cần custom driver per IDE. Markdown portable.
+
+### 5. **Sharing & Sync**
+- Live trong git repo → auto-shared via Git/Rsync/Dropbox
+- Developers thấy decision history trong commits
+- Có thể backup, version, audit
+- Không external database để sync qua machines
+
+### 6. **Transparent & Auditable**
+- Human-readable: có thể review MEMORY.md trực tiếp
+- Không "locked in SQLite/Vector DB" problem
+- Không cần export/import
+- Git history show ai decided what và khi nào
+
+---
+
+## Kiến trúc: Thiết kế 4 Lớp
+
+### Tại Sao 4 Lớp?
+
+**Vấn đề**: Automatic memory systems fail khi:
+1. Không thể link user intent tới prior context (blindness)
+2. Generate massive output khi fallback fails (bloat)
+3. Không portable qua environments
+
+**Solution**: Explicit layers tách concerns:
+
+```
+Lớp 1: Router (AGENTS.md, ~100 dòng)
+├─ Critical rules + pointers only
+└─ Mọi IDE đọc first
+
+Lớp 2: Memory (MEMORY.md, ~150 dòng)
+├─ Curated 1-line decisions
+├─ Category headers với spec pointers
+└─ Agent đọc trước implement
+
+Lớp 3: Tasks (TASKS.md)
+├─ Current work, in-progress, next steps
+└─ Enable session continuity
+
+Lớp 4: Specs (spec/*.md, on-demand)
+├─ Detailed patterns, examples
+├─ Referenced bởi Lớp 2
+└─ Agent load chỉ khi cần
+```
+
+**Progressive Disclosure**: Agents đọc ~200 tokens initially, follow pointers on-demand. Same token cost regardless of project size.
+
+---
+
+## So sánh Token Cost
+
+### Session 1: Tìm Storybook Rules (memsearch)
+```
+memory_search query:           100 tokens
+memory_get fails              (file lock)
+↓ fallback to memory_transcript
+memory_transcript (19 calls): 47,389 tokens
+TOTAL:                        47,489 tokens
+```
+
+### Session 2: Tìm Storybook Rules (file-based)
+```
+Read MEMORY.md:                 200 tokens
+Follow pointer → spec file:     500 tokens
+TOTAL:                          700 tokens
+```
+
+**Ratio**: 66x cheaper với file-based approach.
+
+---
+
+## Tại Sao "Manual" (Agent Rules) > "Automatic"
+
+### Automatic Capture (memsearch, qmd, mem0)
+- ❌ Context Blindness: Không thể link decision tới prior context
+- ❌ Context Bloat: Fallback kéo massive raw data
+- ❌ Platform Bloat: Cần dependencies (sqlite, milvus, HF)
+- ✅ Zero manual effort
+
+### Agent Rules (File-based)
+- ✅ Context aware: Agent ghi khi họ hiểu
+- ✅ Curated: Chỉ important decisions sống sót
+- ✅ Portable: Hoạt động everywhere (no dependencies)
+- ❌ Cần agent discipline (mitigated bởi plugin reminders)
+
+**Verdict**: Quality + Portability > Automation cho teams 1-10.
+
+---
+
+## Cross-IDE Reality Check
+
+### ✅ Gì hoạt động ngay
+- OpenCode: Plugin hooks + session lifecycle
+- Copilot: Read `.github/copilot-instructions.md` natively
+- Cursor: Read `.cursorrules`
+- Windsurf: Read `.windsurfrules`
+- VS Code: Read markdown files
+
+### ⚠️ Limitations
+- Copilot không có lifecycle hooks (cannot auto-remind update tasks)
+- Cursor/Windsurf limited tới read rules, không inject context
+- **Solution**: VSCode extension (Phase 3) để provide unified sidebar
+
+---
+
+## Kết luận
+
+**Cho teams 1-10 làm việc trên focused projects:**
+
+File-based memory + agent rules thắng mọi alternative vì nó:
+1. Hoạt động trên VM Windows 11 (no build tools, no native modules)
+2. Không bloat token budget (700 vs 47k tokens)
+3. Hoạt động với all IDEs mà không cần custom drivers
+4. Share naturally via git (Host ↔ VM ↔ Team)
+5. Transparent và auditable
+
+**Automated memory capture fails** vì:
+- Context Blindness: Không thể reliably link user intent tới prior analysis
+- Context Bloat: Fallback sang raw transcripts cost 47k+ tokens
+- Platform bloat: Cần dependencies không compile trên Windows/VM
+
+**Trade-off đúng**: Hy sinh full automation cho reliability, portability, và cost.

package/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @vuau/agent-memory
+ *
+ * Structured AI memory for codebases.
+ * OpenCode plugin entry point.
+ */
+
+export { MemoryLifecyclePlugin as AgentMemoryPlugin } from "./src/opencode/plugin.ts"
+
+// Re-export core for programmatic use
+export * from "./src/core/index.ts"

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@vuau/agent-memory",
+  "version": "0.1.0",
+  "description": "Structured AI memory for codebases — OpenCode plugin + scaffolding CLI",
+  "type": "module",
+  "main": "index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "bin": {
+    "agent-memory": "./bin/cli.ts"
+  },
+  "files": [
+    "index.ts",
+    "src/",
+    "templates/",
+    "bin/",
+    "docs/",
+    "README.md"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "agent-memory",
+    "ai-memory",
+    "agents",
+    "copilot",
+    "cursor",
+    "windsurf"
+  ],
+  "author": "Au Pham <phamvuau@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vuau/agent-memory"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opencode-ai/plugin": {
+      "optional": true
+    }
+  }
+}

package/src/core/doctor.ts

@@ -0,0 +1,86 @@
+/**
+ * Doctor — validate .agents/ structure integrity.
+ */
+
+import { existsSync, readFileSync } from "fs"
+import { join } from "path"
+import {
+  AGENTS_DIR,
+  SPEC_DIR,
+  MEMORY_FILE,
+  TASKS_FILE,
+  AGENTS_MD,
+  COPILOT_INSTRUCTIONS,
+  type DoctorResult,
+  type DoctorIssue,
+} from "./types.ts"
+
+export function doctor(projectDir: string): DoctorResult {
+  const issues: DoctorIssue[] = []
+
+  // Check required files
+  const required = [
+    { file: AGENTS_MD, desc: "Root router file" },
+    { file: MEMORY_FILE, desc: "Long-term memory" },
+    { file: TASKS_FILE, desc: "Working memory" },
+  ]
+
+  for (const { file, desc } of required) {
+    const filePath = join(projectDir, file)
+    if (!existsSync(filePath)) {
+      issues.push({ level: "error", file, message: `Missing ${desc}` })
+    }
+  }
+
+  // Check directories
+  for (const dir of [AGENTS_DIR, SPEC_DIR]) {
+    if (!existsSync(join(projectDir, dir))) {
+      issues.push({ level: "error", file: dir, message: "Directory missing" })
+    }
+  }
+
+  // Check optional files
+  const copilotPath = join(projectDir, COPILOT_INSTRUCTIONS)
+  if (!existsSync(copilotPath)) {
+    issues.push({
+      level: "warning",
+      file: COPILOT_INSTRUCTIONS,
+      message: "Copilot instructions missing — VSCode/GitHub Copilot won't have context",
+    })
+  }
+
+  // Validate AGENTS.md has documentation map
+  const agentsPath = join(projectDir, AGENTS_MD)
+  if (existsSync(agentsPath)) {
+    const content = readFileSync(agentsPath, "utf-8")
+    if (!content.includes(".agents/")) {
+      issues.push({
+        level: "warning",
+        file: AGENTS_MD,
+        message: "No references to .agents/ — agents may not find memory files",
+      })
+    }
+    if (content.split("\n").length > 150) {
+      issues.push({
+        level: "warning",
+        file: AGENTS_MD,
+        message: "Over 150 lines — consider keeping it concise as a router",
+      })
+    }
+  }
+
+  // Validate MEMORY.md line count
+  const memoryPath = join(projectDir, MEMORY_FILE)
+  if (existsSync(memoryPath)) {
+    const lines = readFileSync(memoryPath, "utf-8").split("\n").length
+    if (lines > 150) {
+      issues.push({
+        level: "warning",
+        file: MEMORY_FILE,
+        message: `${lines} lines — consider compressing or archiving old entries`,
+      })
+    }
+  }
+
+  return { ok: issues.filter((i) => i.level === "error").length === 0, issues }
+}

package/src/core/index.ts

@@ -0,0 +1,5 @@
+export { scaffold, type ScaffoldResult } from "./scaffold.ts"
+export { appendMemory, readMemory, type MemoryEntry } from "./memory.ts"
+export { readTasks, writeTasks, type TaskItem, type TaskStatus } from "./tasks.ts"
+export { doctor } from "./doctor.ts"
+export * from "./types.ts"

package/src/core/memory.ts

@@ -0,0 +1,86 @@
+/**
+ * Memory — read/append operations for MEMORY.md
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "fs"
+import { join } from "path"
+import { MEMORY_FILE } from "./types.ts"
+
+export interface MemoryEntry {
+  date: string
+  content: string
+  category?: string
+}
+
+/**
+ * Append a 1-line entry to MEMORY.md under a category.
+ * Creates category header if it doesn't exist.
+ */
+export function appendMemory(
+  projectDir: string,
+  entry: MemoryEntry
+): void {
+  const filePath = join(projectDir, MEMORY_FILE)
+  if (!existsSync(filePath)) {
+    throw new Error(`${MEMORY_FILE} not found. Run 'agent-memory init' first.`)
+  }
+
+  const content = readFileSync(filePath, "utf-8")
+  const category = entry.category || "Decisions"
+  const line = `- ${entry.date}: ${entry.content}`
+
+  // Find category header
+  const categoryHeader = `## ${category}`
+  const headerIndex = content.indexOf(categoryHeader)
+
+  let updated: string
+  if (headerIndex === -1) {
+    // Append new category at end
+    updated = content.trimEnd() + `\n\n${categoryHeader}\n${line}\n`
+  } else {
+    // Find next ## header or end of file
+    const afterHeader = headerIndex + categoryHeader.length
+    const nextHeaderIndex = content.indexOf("\n## ", afterHeader)
+    const insertAt = nextHeaderIndex === -1 ? content.length : nextHeaderIndex
+
+    // Find last non-empty line in category
+    const categoryContent = content.slice(afterHeader, insertAt)
+    const lastLineEnd = afterHeader + categoryContent.trimEnd().length
+
+    updated =
+      content.slice(0, lastLineEnd) +
+      "\n" + line +
+      content.slice(lastLineEnd)
+  }
+
+  writeFileSync(filePath, updated)
+}
+
+/**
+ * Read all entries from MEMORY.md, parsed by category.
+ */
+export function readMemory(
+  projectDir: string
+): Record<string, string[]> {
+  const filePath = join(projectDir, MEMORY_FILE)
+  if (!existsSync(filePath)) return {}
+
+  const content = readFileSync(filePath, "utf-8")
+  const categories: Record<string, string[]> = {}
+  let currentCategory = "_uncategorized"
+
+  for (const line of content.split("\n")) {
+    const headerMatch = line.match(/^## (.+)/)
+    if (headerMatch) {
+      currentCategory = headerMatch[1]
+      categories[currentCategory] = categories[currentCategory] || []
+      continue
+    }
+    if (line.startsWith("- ") && currentCategory) {
+      categories[currentCategory] = categories[currentCategory] || []
+      categories[currentCategory].push(line.slice(2))
+    }
+  }
+
+  return categories
+}