docs(memory): update skills for opencode-memory plugin, deprecate mem0

2026-02-14 08:22:59 +01:00
parent 1719f70452
commit c64d71f438
12 changed files with 2857 additions and 191 deletions
--- a/.sisyphus/plans/memory-system.md
+++ b/.sisyphus/plans/memory-system.md
@@ -0,0 +1,897 @@
+# Memory System for AGENTS + Obsidian CODEX
+
+## TL;DR
+
+> **Quick Summary**: Build a dual-layer memory system equivalent to openclaw's — Mem0 for fast semantic search/auto-recall + Obsidian CODEX vault for human-readable, versioned knowledge. Memories are stored in both layers and cross-referenced via IDs.
+>
+> **Deliverables**:
+> - New `skills/memory/SKILL.md` — Core orchestration skill (auto-capture, auto-recall, dual-layer sync)
+> - New `80-memory/` folder in CODEX vault with category subfolders + memory template
+> - Obsidian MCP server configuration (cyanheads/obsidian-mcp-server)
+> - Updated skills (mem0-memory, obsidian), Apollo prompt, CODEX docs, user profile
+>
+> **Estimated Effort**: Medium (9 tasks across config/docs, no traditional code)
+> **Parallel Execution**: YES — 4 waves
+> **Critical Path**: Task 1 (vault infra) → Task 4 (memory skill) → Task 9 (validation)
+
+---
+
+## Context
+
+### Original Request
+Adapt openclaw's memory system for the opencode AGENTS repo, integrated with the Obsidian CODEX vault at `~/CODEX`. The vault should serve as a "second brain" for both the user AND AI agents.
+
+### Interview Summary
+**Key Discussions**:
+- Analyzed openclaw's 3-layer memory architecture (SQLite+vectors builtin, memory-core plugin, memory-lancedb plugin with auto-capture/auto-recall)
+- User confirmed Mem0 is available self-hosted at localhost:8000 — just needs spinning up
+- User chose `80-memory/` as dedicated vault folder with category subfolders
+- User chose auto+explicit capture (LLM extraction at session end + "remember this" commands)
+- User chose agent QA only (no unit test infrastructure — repo is config/docs only)
+- No Obsidian MCP server currently configured — plan to add cyanheads/obsidian-mcp-server
+
+**Research Findings**:
+- cyanheads/obsidian-mcp-server (363 stars) — Best MCP server: frontmatter management, vault cache, search with pagination, tag management
+- GitHub Copilot's memory system: citation-based verification pattern (Phase 2 candidate)
+- Production recommendation: dual-layer (operational memory + documented knowledge)
+- Mem0 provides semantic search, user_id/agent_id/run_id scoping, metadata support, `/health` endpoint
+- Auto-capture best practice: max 3 per session, LLM extraction > regex patterns
+
+### Metis Review
+**Identified Gaps** (addressed):
+- 80-memory/ subfolders vs flat pattern: Resolved — follows `30-resources/` pattern (subfolders by TYPE), not `50-zettelkasten/` flat pattern
+- Mem0 health check: Added prerequisite validation step
+- Error handling undefined: Defined — Mem0 unavailable → skip, Obsidian unavailable → Mem0 only
+- Deployment order: Defined — CODEX first → MCP config → skills → validation
+- Scope creep risk: Locked down — citation verification, memory deletion/lifecycle, dashboards all Phase 2
+- Agent role clarity: Defined — memory skill loadable by any agent, Apollo is primary memory specialist
+
+---
+
+## Work Objectives
+
+### Core Objective
+Build a dual-layer memory system for opencode agents that stores memories in Mem0 (semantic search, operational) AND the Obsidian CODEX vault (human-readable, versioned, wiki-linked). Equivalent in capability to openclaw's memory system.
+
+### Concrete Deliverables
+**AGENTS repo** (`~/p/AI/AGENTS`):
+- `skills/memory/SKILL.md` — NEW: Core memory skill
+- `skills/memory/references/mcp-config.md` — NEW: Obsidian MCP server config documentation
+- `skills/mem0-memory/SKILL.md` — UPDATED: Add categories, dual-layer sync
+- `skills/obsidian/SKILL.md` — UPDATED: Add 80-memory/ conventions
+- `prompts/apollo.txt` — UPDATED: Add memory management responsibilities
+- `context/profile.md` — UPDATED: Add memory system configuration
+
+**CODEX vault** (`~/CODEX`):
+- `80-memory/` — NEW: Folder with subfolders (preferences/, facts/, decisions/, entities/, other/)
+- `templates/memory.md` — NEW: Memory note template
+- `tag-taxonomy.md` — UPDATED: Add #memory/* tags
+- `AGENTS.md` — UPDATED: Add 80-memory/ docs, folder decision tree, memory workflows
+- `README.md` — UPDATED: Add 80-memory/ to folder structure
+
+**Infrastructure** (Nix home-manager — outside AGENTS repo):
+- Add cyanheads/obsidian-mcp-server to opencode.json MCP section
+
+### Definition of Done
+- [x] All 11 files created/updated as specified
+- [x] `curl http://localhost:8000/health` returns 200 (Mem0 running)
+- [~] `curl http://127.0.0.1:27124/vault-info` returns vault info (Obsidian REST API) — *Requires Obsidian desktop app to be open*
+- [x] `./scripts/test-skill.sh --validate` passes for new/updated skills
+- [x] 80-memory/ folder exists in CODEX vault with 5 subfolders
+- [x] Memory template creates valid notes with correct frontmatter
+
+### Must Have
+- Dual-layer storage: every memory in Mem0 AND Obsidian
+- Auto-capture at session end (LLM-based, max 3 per session)
+- Explicit "remember this" command support
+- Auto-recall: inject relevant memories before agent starts
+- 5 categories: preference, fact, decision, entity, other
+- Health checks before memory operations
+- Cross-reference: mem0_id in Obsidian frontmatter, obsidian_ref in Mem0 metadata
+- Error handling: graceful degradation when either layer unavailable
+
+### Must NOT Have (Guardrails)
+- NO citation-based memory verification (Phase 2)
+- NO memory expiration/lifecycle management (Phase 2)
+- NO memory deletion/forget functionality (Phase 2)
+- NO memory search UI or Obsidian dashboards (Phase 2)
+- NO conflict resolution UI between layers (manual edit only)
+- NO unit tests (repo has no test infrastructure — agent QA only)
+- NO subfolders in 50-zettelkasten/ or 70-tasks/ (respect flat structure)
+- NO new memory categories beyond the 5 defined
+- NO modifications to existing Obsidian templates (only ADD memory.md)
+- NO changes to agents.json (no new agents or agent config changes)
+
+---
+
+## Verification Strategy
+
+> **UNIVERSAL RULE: ZERO HUMAN INTERVENTION**
+>
+> ALL tasks MUST be verifiable WITHOUT any human action.
+> Every criterion is verifiable by running a command or checking file existence.
+
+### Test Decision
+- **Infrastructure exists**: NO (config-only repo)
+- **Automated tests**: None (agent QA only)
+- **Framework**: N/A
+
+### Agent-Executed QA Scenarios (MANDATORY — ALL tasks)
+
+Verification tools by deliverable type:
+
+| Type | Tool | How Agent Verifies |
+|------|------|-------------------|
+| Vault folders/files | Bash (ls, test -f) | Check existence, content |
+| Skill YAML frontmatter | Bash (grep, python) | Parse and validate fields |
+| Mem0 API | Bash (curl) | Send requests, parse JSON |
+| Obsidian REST API | Bash (curl) | Read notes, check frontmatter |
+| MCP server | Bash (npx) | Test server startup |
+
+---
+
+## Execution Strategy
+
+### Parallel Execution Waves
+
+```
+Wave 1 (Start Immediately — no dependencies):
+├── Task 1: CODEX vault memory infrastructure (folders, template, tags)
+└── Task 3: Obsidian MCP server config documentation
+
+Wave 2 (After Wave 1 — depends on vault structure existing):
+├── Task 2: CODEX vault documentation updates (AGENTS.md, README.md)
+├── Task 4: Create core memory skill (skills/memory/SKILL.md)
+├── Task 5: Update Mem0 memory skill
+└── Task 6: Update Obsidian skill
+
+Wave 3 (After Wave 2 — depends on skill content for prompt/profile):
+├── Task 7: Update Apollo agent prompt
+└── Task 8: Update user context profile
+
+Wave 4 (After all — final validation):
+└── Task 9: End-to-end validation
+
+Critical Path: Task 1 → Task 4 → Task 9
+Parallel Speedup: ~50% faster than sequential
+```
+
+### Dependency Matrix
+
+| Task | Depends On | Blocks | Can Parallelize With |
+|------|------------|--------|---------------------|
+| 1 | None | 2, 4, 5, 6 | 3 |
+| 2 | 1 | 9 | 4, 5, 6 |
+| 3 | None | 4 | 1 |
+| 4 | 1, 3 | 7, 8, 9 | 5, 6 |
+| 5 | 1 | 9 | 4, 6 |
+| 6 | 1 | 9 | 4, 5 |
+| 7 | 4 | 9 | 8 |
+| 8 | 4 | 9 | 7 |
+| 9 | ALL | None | None (final) |
+
+### Agent Dispatch Summary
+
+| Wave | Tasks | Recommended Agents |
+|------|-------|-------------------|
+| 1 | 1, 3 | task(category="quick", load_skills=["obsidian"], run_in_background=false) |
+| 2 | 2, 4, 5, 6 | dispatch parallel: task(category="unspecified-high") for Task 4; task(category="quick") for 2, 5, 6 |
+| 3 | 7, 8 | task(category="quick", run_in_background=false) |
+| 4 | 9 | task(category="unspecified-low", run_in_background=false) |
+
+---
+
+## TODOs
+
+- [x] 1. CODEX Vault Memory Infrastructure
+
+  **What to do**:
+  - Create `80-memory/` folder with 5 subfolders: `preferences/`, `facts/`, `decisions/`, `entities/`, `other/`
+  - Create each subfolder with a `.gitkeep` file so git tracks empty directories
+  - Create `templates/memory.md` — memory note template with frontmatter:
+    ```yaml
+    ---
+    type: memory
+    category:        # preference | fact | decision | entity | other
+    mem0_id:         # Mem0 memory ID (e.g., "mem_abc123")
+    source: explicit # explicit | auto-capture
+    importance:      # critical | high | medium | low
+    created: <% tp.date.now("YYYY-MM-DD") %>
+    updated: <% tp.date.now("YYYY-MM-DD") %>
+    tags:
+      - memory
+    sync_targets: []
+    ---
+    
+    # Memory Title
+    
+    ## Content
+    <!-- The actual memory content -->
+    
+    ## Context
+    <!-- When/where this was learned, conversation context -->
+    
+    ## Related
+    <!-- Wiki links to related notes -->
+    ```
+  - Update `tag-taxonomy.md` — add `#memory` tag category with subtags:
+    ```
+    #memory
+    ├── #memory/preference
+    ├── #memory/fact
+    ├── #memory/decision
+    ├── #memory/entity
+    └── #memory/other
+    ```
+    Include usage examples and definitions for each category
+
+  **Must NOT do**:
+  - Do NOT create subfolders inside 50-zettelkasten/ or 70-tasks/
+  - Do NOT modify existing templates (only ADD memory.md)
+  - Do NOT use Templater syntax that doesn't match existing templates
+
+  **Recommended Agent Profile**:
+  - **Category**: `quick`
+    - Reason: Simple file creation, no complex logic
+  - **Skills**: [`obsidian`]
+    - `obsidian`: Vault conventions, frontmatter patterns, template structure
+
+  **Parallelization**:
+  - **Can Run In Parallel**: YES
+  - **Parallel Group**: Wave 1 (with Task 3)
+  - **Blocks**: Tasks 2, 4, 5, 6
+  - **Blocked By**: None
+
+  **References**:
+  
+  **Pattern References**:
+  - `/home/m3tam3re/CODEX/30-resources/` — Subfolder-by-type pattern to follow (bookmarks/, literature/, meetings/, people/, recipes/)
+  - `/home/m3tam3re/CODEX/templates/task.md` — Template frontmatter pattern (type, status, created, updated, tags, sync_targets)
+  - `/home/m3tam3re/CODEX/templates/bookmark.md` — Simpler template example
+
+  **Documentation References**:
+  - `/home/m3tam3re/CODEX/AGENTS.md:22-27` — Frontmatter conventions (required fields: type, created, updated)
+  - `/home/m3tam3re/CODEX/AGENTS.md:163-176` — Template locations table (add memory row)
+  - `/home/m3tam3re/CODEX/tag-taxonomy.md:1-18` — Tag structure rules (max 3 levels, kebab-case)
+
+  **WHY Each Reference Matters**:
+  - `30-resources/` shows that subfolders-by-type is the established vault pattern for categorized content
+  - `task.md` template shows the exact frontmatter field set expected by the vault
+  - `tag-taxonomy.md` rules show the 3-level max hierarchy constraint for new tags
+
+  **Acceptance Criteria**:
+
+  **Agent-Executed QA Scenarios:**
+
+  ```
+  Scenario: Verify 80-memory folder structure
+    Tool: Bash
+    Steps:
+      1. test -d /home/m3tam3re/CODEX/80-memory/preferences
+      2. test -d /home/m3tam3re/CODEX/80-memory/facts
+      3. test -d /home/m3tam3re/CODEX/80-memory/decisions
+      4. test -d /home/m3tam3re/CODEX/80-memory/entities
+      5. test -d /home/m3tam3re/CODEX/80-memory/other
+    Expected Result: All 5 directories exist (exit code 0 for each)
+    Evidence: Shell output captured
+
+  Scenario: Verify memory template exists with correct frontmatter
+    Tool: Bash
+    Steps:
+      1. test -f /home/m3tam3re/CODEX/templates/memory.md
+      2. grep "type: memory" /home/m3tam3re/CODEX/templates/memory.md
+      3. grep "category:" /home/m3tam3re/CODEX/templates/memory.md
+      4. grep "mem0_id:" /home/m3tam3re/CODEX/templates/memory.md
+    Expected Result: File exists and contains required frontmatter fields
+    Evidence: grep output captured
+
+  Scenario: Verify tag-taxonomy updated with memory tags
+    Tool: Bash
+    Steps:
+      1. grep "#memory" /home/m3tam3re/CODEX/tag-taxonomy.md
+      2. grep "#memory/preference" /home/m3tam3re/CODEX/tag-taxonomy.md
+      3. grep "#memory/fact" /home/m3tam3re/CODEX/tag-taxonomy.md
+    Expected Result: All memory tags present in taxonomy
+    Evidence: grep output captured
+  ```
+
+  **Commit**: YES
+  - Message: `feat(vault): add 80-memory folder structure and memory template`
+  - Files: `80-memory/`, `templates/memory.md`, `tag-taxonomy.md`
+  - Repo: `~/CODEX`
+
+---
+
+- [x] 2. CODEX Vault Documentation Updates
+
+  **What to do**:
+  - Update `AGENTS.md`:
+    - Add `80-memory/` row to Folder Structure table (line ~11)
+    - Add `#### 80-memory` section in Folder Details (after 70-tasks section, ~line 161)
+    - Update Folder Decision Tree to include memory branch: `Is it a memory/learned fact? → YES → 80-memory/`
+    - Add Memory template row to Template Locations table (line ~165)
+    - Add Memory Workflows section (after Sync Workflow): create memory, retrieve memory, dual-layer sync
+  - Update `README.md`:
+    - Add `80-memory/` to folder structure diagram with subfolders
+    - Add `80-memory/` row to Folder Details section
+    - Add memory template to Templates table
+
+  **Must NOT do**:
+  - Do NOT rewrite existing sections — only ADD new content
+  - Do NOT remove any existing folder/template documentation
+
+  **Recommended Agent Profile**:
+  - **Category**: `quick`
+    - Reason: Documentation additions to existing files, following established patterns
+  - **Skills**: [`obsidian`]
+    - `obsidian`: Vault documentation conventions
+
+  **Parallelization**:
+  - **Can Run In Parallel**: YES
+  - **Parallel Group**: Wave 2 (with Tasks 4, 5, 6)
+  - **Blocks**: Task 9
+  - **Blocked By**: Task 1 (needs folder structure to reference)
+
+  **References**:
+
+  **Pattern References**:
+  - `/home/m3tam3re/CODEX/AGENTS.md:110-161` — Existing Folder Details sections to follow pattern
+  - `/home/m3tam3re/CODEX/AGENTS.md:75-108` — Folder Decision Tree format
+  - `/home/m3tam3re/CODEX/README.md` — Folder structure diagram format
+
+  **WHY Each Reference Matters**:
+  - AGENTS.md folder details show the exact format: Purpose, Structure (flat/subfolders), Key trait, When to use, Naming convention
+  - Decision tree shows the exact `├─ YES →` format to follow
+
+  **Acceptance Criteria**:
+
+  ```
+  Scenario: Verify AGENTS.md has 80-memory documentation
+    Tool: Bash
+    Steps:
+      1. grep "80-memory" /home/m3tam3re/CODEX/AGENTS.md
+      2. grep "Is it a memory" /home/m3tam3re/CODEX/AGENTS.md
+      3. grep "templates/memory.md" /home/m3tam3re/CODEX/AGENTS.md
+    Expected Result: All three patterns found
+    Evidence: grep output
+
+  Scenario: Verify README.md has 80-memory in structure
+    Tool: Bash
+    Steps:
+      1. grep "80-memory" /home/m3tam3re/CODEX/README.md
+      2. grep "preferences/" /home/m3tam3re/CODEX/README.md
+    Expected Result: Folder and subfolder documented
+    Evidence: grep output
+  ```
+
+  **Commit**: YES
+  - Message: `docs(vault): add 80-memory documentation to AGENTS.md and README.md`
+  - Files: `AGENTS.md`, `README.md`
+  - Repo: `~/CODEX`
+
+---
+
+- [x] 3. Obsidian MCP Server Configuration Documentation
+
+  **What to do**:
+  - Create `skills/memory/references/mcp-config.md` documenting:
+    - cyanheads/obsidian-mcp-server configuration for opencode.json
+    - Required environment variables: `OBSIDIAN_API_KEY`, `OBSIDIAN_BASE_URL`, `OBSIDIAN_VERIFY_SSL`, `OBSIDIAN_ENABLE_CACHE`
+    - opencode.json MCP section snippet:
+      ```json
+      "Obsidian-Vault": {
+        "command": ["npx", "obsidian-mcp-server"],
+        "environment": {
+          "OBSIDIAN_API_KEY": "<your-api-key>",
+          "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123",
+          "OBSIDIAN_VERIFY_SSL": "false",
+          "OBSIDIAN_ENABLE_CACHE": "true"
+        },
+        "enabled": true,
+        "type": "local"
+      }
+      ```
+    - Nix home-manager snippet showing how to add to `programs.opencode.settings.mcp`
+    - Note that this requires `home-manager switch` after adding
+    - Available MCP tools list: obsidian_read_note, obsidian_update_note, obsidian_global_search, obsidian_manage_frontmatter, obsidian_manage_tags, obsidian_list_notes, obsidian_delete_note, obsidian_search_replace
+    - How to get the API key from Obsidian: Settings → Local REST API plugin
+
+  **Must NOT do**:
+  - Do NOT directly modify `~/.config/opencode/opencode.json` (Nix-managed)
+  - Do NOT modify `agents/agents.json`
+
+  **Recommended Agent Profile**:
+  - **Category**: `quick`
+    - Reason: Creating a single reference doc
+  - **Skills**: [`obsidian`]
+    - `obsidian`: Obsidian REST API configuration knowledge
+
+  **Parallelization**:
+  - **Can Run In Parallel**: YES
+  - **Parallel Group**: Wave 1 (with Task 1)
+  - **Blocks**: Task 4
+  - **Blocked By**: None
+
+  **References**:
+
+  **Pattern References**:
+  - `/home/m3tam3re/p/AI/AGENTS/skills/mem0-memory/SKILL.md:156-166` — Existing API reference pattern
+  - `/home/m3tam3re/.config/opencode/opencode.json:77-127` — Current MCP config format (Exa, Basecamp, etc.)
+
+  **External References**:
+  - GitHub: `https://github.com/cyanheads/obsidian-mcp-server` — Config docs, env vars, tool list
+  - npm: `npx obsidian-mcp-server` — Installation method
+
+  **WHY Each Reference Matters**:
+  - opencode.json MCP section shows exact JSON format needed (command array, environment, enabled, type)
+  - cyanheads repo shows required env vars and their defaults
+
+  **Acceptance Criteria**:
+
+  ```
+  Scenario: Verify MCP config reference file exists
+    Tool: Bash
+    Steps:
+      1. test -f /home/m3tam3re/p/AI/AGENTS/skills/memory/references/mcp-config.md
+      2. grep "obsidian-mcp-server" /home/m3tam3re/p/AI/AGENTS/skills/memory/references/mcp-config.md
+      3. grep "OBSIDIAN_API_KEY" /home/m3tam3re/p/AI/AGENTS/skills/memory/references/mcp-config.md
+      4. grep "home-manager" /home/m3tam3re/p/AI/AGENTS/skills/memory/references/mcp-config.md
+    Expected Result: File exists with MCP config, env vars, and Nix instructions
+    Evidence: grep output
+  ```
+
+  **Commit**: YES (groups with Task 4)
+  - Message: `feat(memory): add core memory skill and MCP config reference`
+  - Files: `skills/memory/SKILL.md`, `skills/memory/references/mcp-config.md`
+  - Repo: `~/p/AI/AGENTS`
+
+---
+
+- [x] 4. Create Core Memory Skill
+
+  **What to do**:
+  - Create `skills/memory/SKILL.md` — the central orchestration skill for the dual-layer memory system
+  - YAML frontmatter:
+    ```yaml
+    ---
+    name: memory
+    description: "Dual-layer memory system (Mem0 + Obsidian CODEX). Use when: (1) storing information for future recall ('remember this'), (2) auto-capturing session insights, (3) recalling past decisions/preferences/facts, (4) injecting relevant context before tasks. Triggers: 'remember', 'recall', 'what do I know about', 'memory', session end."
+    compatibility: opencode
+    ---
+    ```
+  - Sections to include:
+    1. **Overview** — Dual-layer architecture (Mem0 operational + Obsidian documented)
+    2. **Prerequisites** — Mem0 running at localhost:8000, Obsidian MCP configured (reference mcp-config.md)
+    3. **Memory Categories** — 5 categories with definitions and examples:
+       - preference: Personal preferences (UI, workflow, communication style)
+       - fact: Objective information about user/work (role, tech stack, constraints)
+       - decision: Architectural/tool choices made (with rationale)
+       - entity: People, organizations, systems, concepts
+       - other: Everything else
+    4. **Workflow 1: Store Memory (Explicit)** — User says "remember X":
+       - Classify category
+       - POST to Mem0 `/memories` with user_id, metadata (category, source: "explicit")
+       - Create Obsidian note in `80-memory/<category>/` using memory template
+       - Cross-reference: mem0_id in Obsidian frontmatter, obsidian_ref in Mem0 metadata
+    5. **Workflow 2: Recall Memory** — User asks "what do I know about X":
+       - POST to Mem0 `/search` with query
+       - Return results with Obsidian note paths for reference
+    6. **Workflow 3: Auto-Capture (Session End)** — Automatic extraction:
+       - Scan conversation for memory-worthy content (preferences stated, decisions made, important facts)
+       - Select top 3 highest-value memories
+       - For each: store in Mem0 AND create Obsidian note (source: "auto-capture")
+       - Present to user: "I captured these memories: [list]. Confirm or reject?"
+    7. **Workflow 4: Auto-Recall (Session Start)** — Context injection:
+       - On session start, search Mem0 with user's first message
+       - If relevant memories found (score > 0.7), inject as `<relevant-memories>` context
+       - Limit to top 5 most relevant
+    8. **Error Handling** — Graceful degradation:
+       - Mem0 unavailable: `curl http://localhost:8000/health` fails → skip all memory ops, warn user
+       - Obsidian unavailable: Store in Mem0 only, log that Obsidian sync failed
+       - Both unavailable: Skip memory entirely, continue without memory features
+    9. **Integration** — How other skills/agents use memory:
+       - Load `memory` skill to access memory workflows
+       - Apollo is primary memory specialist
+       - Any agent can search/store via Mem0 REST API patterns in `mem0-memory` skill
+
+  **Must NOT do**:
+  - Do NOT implement citation-based verification
+  - Do NOT implement memory deletion/forget
+  - Do NOT add memory expiration logic
+  - Do NOT create dashboards or search UI
+
+  **Recommended Agent Profile**:
+  - **Category**: `unspecified-high`
+    - Reason: Core deliverable requiring careful architecture documentation, must be comprehensive
+  - **Skills**: [`obsidian`, `mem0-memory`]
+    - `obsidian`: Vault conventions, template patterns, frontmatter standards
+    - `mem0-memory`: Mem0 REST API patterns, endpoint details
+
+  **Parallelization**:
+  - **Can Run In Parallel**: YES
+  - **Parallel Group**: Wave 2 (with Tasks 2, 5, 6)
+  - **Blocks**: Tasks 7, 8, 9
+  - **Blocked By**: Tasks 1, 3
+
+  **References**:
+
+  **Pattern References**:
+  - `/home/m3tam3re/p/AI/AGENTS/skills/mem0-memory/SKILL.md` — Full file: Mem0 REST API patterns, endpoint table, identity scopes, workflow patterns
+  - `/home/m3tam3re/p/AI/AGENTS/skills/obsidian/SKILL.md` — Full file: Obsidian REST API patterns, create/read/update note workflows, frontmatter conventions
+  - `/home/m3tam3re/p/AI/AGENTS/skills/reflection/SKILL.md` — Skill structure pattern (overview, workflows, integration)
+
+  **API References**:
+  - `/home/m3tam3re/p/AI/AGENTS/skills/mem0-memory/SKILL.md:13-21` — Quick Reference endpoint table
+  - `/home/m3tam3re/p/AI/AGENTS/skills/mem0-memory/SKILL.md:90-109` — Identity scopes (user_id, agent_id, run_id)
+
+  **Documentation References**:
+  - `/home/m3tam3re/CODEX/AGENTS.md:22-27` — Frontmatter conventions for vault notes
+  - `/home/m3tam3re/p/AI/AGENTS/skills/memory/references/mcp-config.md` — MCP server config (created in Task 3)
+
+  **External References**:
+  - OpenClaw reference: `/home/m3tam3re/p/AI/openclaw/extensions/memory-lancedb/index.ts` — Auto-capture regex patterns, auto-recall injection, importance scoring (use as inspiration, not copy)
+
+  **WHY Each Reference Matters**:
+  - mem0-memory SKILL.md provides the exact API endpoints and patterns to reference in dual-layer sync workflows
+  - obsidian SKILL.md provides the vault file creation patterns (curl commands, path encoding)
+  - openclaw memory-lancedb shows the auto-capture/auto-recall architecture to adapt
+
+  **Acceptance Criteria**:
+
+  ```
+  Scenario: Validate skill YAML frontmatter
+    Tool: Bash
+    Steps:
+      1. test -f /home/m3tam3re/p/AI/AGENTS/skills/memory/SKILL.md
+      2. grep "^name: memory$" /home/m3tam3re/p/AI/AGENTS/skills/memory/SKILL.md
+      3. grep "^compatibility: opencode$" /home/m3tam3re/p/AI/AGENTS/skills/memory/SKILL.md
+      4. grep "description:" /home/m3tam3re/p/AI/AGENTS/skills/memory/SKILL.md
+    Expected Result: Valid YAML frontmatter with name, description, compatibility
+    Evidence: grep output
+
+  Scenario: Verify skill contains all required workflows
+    Tool: Bash
+    Steps:
+      1. grep -c "## Workflow" /home/m3tam3re/p/AI/AGENTS/skills/memory/SKILL.md
+      2. grep "Auto-Capture" /home/m3tam3re/p/AI/AGENTS/skills/memory/SKILL.md
+      3. grep "Auto-Recall" /home/m3tam3re/p/AI/AGENTS/skills/memory/SKILL.md
+      4. grep "Error Handling" /home/m3tam3re/p/AI/AGENTS/skills/memory/SKILL.md
+      5. grep "preference" /home/m3tam3re/p/AI/AGENTS/skills/memory/SKILL.md
+    Expected Result: At least 4 workflow sections, auto-capture, auto-recall, error handling, categories
+    Evidence: grep output
+
+  Scenario: Verify dual-layer sync pattern documented
+    Tool: Bash
+    Steps:
+      1. grep "mem0_id" /home/m3tam3re/p/AI/AGENTS/skills/memory/SKILL.md
+      2. grep "obsidian_ref" /home/m3tam3re/p/AI/AGENTS/skills/memory/SKILL.md
+      3. grep "localhost:8000" /home/m3tam3re/p/AI/AGENTS/skills/memory/SKILL.md
+      4. grep "80-memory" /home/m3tam3re/p/AI/AGENTS/skills/memory/SKILL.md
+    Expected Result: Cross-reference IDs and both layer endpoints documented
+    Evidence: grep output
+  ```
+
+  **Commit**: YES (groups with Task 3)
+  - Message: `feat(memory): add core memory skill and MCP config reference`
+  - Files: `skills/memory/SKILL.md`, `skills/memory/references/mcp-config.md`
+  - Repo: `~/p/AI/AGENTS`
+
+---
+
+- [x] 5. Update Mem0 Memory Skill
+
+  **What to do**:
+  - Add "Memory Categories" section after Identity Scopes (line ~109):
+    - Table: category name, definition, Obsidian path, example
+    - Metadata pattern for categories: `{"category": "preference", "source": "explicit|auto-capture"}`
+  - Add "Dual-Layer Sync" section after Workflow Patterns:
+    - After storing to Mem0, also create Obsidian note in `80-memory/<category>/`
+    - Include mem0_id from response in Obsidian note frontmatter
+    - Include obsidian_ref path in Mem0 metadata via update
+  - Add "Health Check" workflow: Check `/health` before any memory operations
+  - Add "Error Handling" section: What to do when Mem0 is unavailable
+
+  **Must NOT do**:
+  - Do NOT delete existing content
+  - Do NOT change the YAML frontmatter description (triggers)
+  - Do NOT change existing API endpoint documentation
+
+  **Recommended Agent Profile**:
+  - **Category**: `quick`
+    - Reason: Adding sections to existing well-structured file
+  - **Skills**: [`mem0-memory`]
+    - `mem0-memory`: Existing skill patterns to extend
+
+  **Parallelization**:
+  - **Can Run In Parallel**: YES
+  - **Parallel Group**: Wave 2 (with Tasks 2, 4, 6)
+  - **Blocks**: Task 9
+  - **Blocked By**: Task 1
+
+  **References**:
+
+  - `/home/m3tam3re/p/AI/AGENTS/skills/mem0-memory/SKILL.md` — Full file: current content to extend (preserve ALL existing content)
+
+  **Acceptance Criteria**:
+
+  ```
+  Scenario: Verify categories added to mem0-memory skill
+    Tool: Bash
+    Steps:
+      1. grep "Memory Categories" /home/m3tam3re/p/AI/AGENTS/skills/mem0-memory/SKILL.md
+      2. grep "preference" /home/m3tam3re/p/AI/AGENTS/skills/mem0-memory/SKILL.md
+      3. grep "Dual-Layer" /home/m3tam3re/p/AI/AGENTS/skills/mem0-memory/SKILL.md
+      4. grep "80-memory" /home/m3tam3re/p/AI/AGENTS/skills/mem0-memory/SKILL.md
+    Expected Result: New sections present alongside existing content
+    Evidence: grep output
+  ```
+
+  **Commit**: YES
+  - Message: `feat(mem0-memory): add memory categories and dual-layer sync patterns`
+  - Files: `skills/mem0-memory/SKILL.md`
+  - Repo: `~/p/AI/AGENTS`
+
+---
+
+- [x] 6. Update Obsidian Skill
+
+  **What to do**:
+  - Add "Memory Folder Conventions" section (after Best Practices, ~line 228):
+    - Document `80-memory/` structure with 5 subfolders
+    - Memory note naming: kebab-case (e.g., `prefers-dark-mode.md`)
+    - Required frontmatter fields for memory notes (type, category, mem0_id, etc.)
+  - Add "Memory Note Workflows" section:
+    - Create memory note: POST to vault REST API with memory template content
+    - Read memory note: GET with path encoding for `80-memory/` paths
+    - Search memories: Search within `80-memory/` path filter
+  - Update Integration table to include memory skill handoff
+
+  **Must NOT do**:
+  - Do NOT change existing content or workflows
+  - Do NOT modify the YAML frontmatter
+
+  **Recommended Agent Profile**:
+  - **Category**: `quick`
+  - **Skills**: [`obsidian`]
+
+  **Parallelization**:
+  - **Can Run In Parallel**: YES
+  - **Parallel Group**: Wave 2
+  - **Blocks**: Task 9
+  - **Blocked By**: Task 1
+
+  **References**:
+  - `/home/m3tam3re/p/AI/AGENTS/skills/obsidian/SKILL.md` — Full file: current content to extend
+
+  **Acceptance Criteria**:
+
+  ```
+  Scenario: Verify memory conventions added to obsidian skill
+    Tool: Bash
+    Steps:
+      1. grep "Memory Folder" /home/m3tam3re/p/AI/AGENTS/skills/obsidian/SKILL.md
+      2. grep "80-memory" /home/m3tam3re/p/AI/AGENTS/skills/obsidian/SKILL.md
+      3. grep "mem0_id" /home/m3tam3re/p/AI/AGENTS/skills/obsidian/SKILL.md
+    Expected Result: Memory folder docs and frontmatter patterns present
+    Evidence: grep output
+  ```
+
+  **Commit**: YES
+  - Message: `feat(obsidian): add memory folder conventions and workflows`
+  - Files: `skills/obsidian/SKILL.md`
+  - Repo: `~/p/AI/AGENTS`
+
+---
+
+- [x] 7. Update Apollo Agent Prompt
+
+  **What to do**:
+  - Add "Memory Management" to Core Responsibilities list (after item 4):
+    - Store memories in dual-layer system (Mem0 + Obsidian CODEX)
+    - Retrieve memories via semantic search (Mem0)
+    - Auto-capture session insights at session end (max 3, confirm with user)
+    - Handle explicit "remember this" requests
+    - Inject relevant memories into context on session start
+  - Add memory-related tools to Tool Usage section
+  - Add memory error handling to Edge Cases
+
+  **Must NOT do**:
+  - Do NOT remove existing responsibilities
+  - Do NOT change Apollo's identity or boundaries
+
+  **Recommended Agent Profile**:
+  - **Category**: `quick`
+  - **Skills**: []
+
+  **Parallelization**:
+  - **Can Run In Parallel**: YES
+  - **Parallel Group**: Wave 3 (with Task 8)
+  - **Blocks**: Task 9
+  - **Blocked By**: Task 4
+
+  **References**:
+  - `/home/m3tam3re/p/AI/AGENTS/prompts/apollo.txt` — Full file (47 lines): current prompt to extend
+
+  **Acceptance Criteria**:
+
+  ```
+  Scenario: Verify memory management added to Apollo prompt
+    Tool: Bash
+    Steps:
+      1. grep -i "memory" /home/m3tam3re/p/AI/AGENTS/prompts/apollo.txt | wc -l
+      2. grep "Mem0" /home/m3tam3re/p/AI/AGENTS/prompts/apollo.txt
+      3. grep "auto-capture" /home/m3tam3re/p/AI/AGENTS/prompts/apollo.txt
+    Expected Result: Multiple memory references, Mem0 mentioned, auto-capture documented
+    Evidence: grep output
+  ```
+
+  **Commit**: YES (groups with Task 8)
+  - Message: `feat(agents): add memory management to Apollo prompt and user profile`
+  - Files: `prompts/apollo.txt`, `context/profile.md`
+  - Repo: `~/p/AI/AGENTS`
+
+---
+
+- [x] 8. Update User Context Profile
+
+  **What to do**:
+  - Add "Memory System" section to `context/profile.md`:
+    - Mem0 endpoint: `http://localhost:8000`
+    - Mem0 user_id: `m3tam3re` (or whatever the user's ID should be)
+    - Obsidian vault path: `~/CODEX`
+    - Memory folder: `80-memory/`
+    - Auto-capture: enabled, max 3 per session
+    - Auto-recall: enabled, top 5 results, score threshold 0.7
+    - Memory categories: preference, fact, decision, entity, other
+    - Obsidian MCP server: cyanheads/obsidian-mcp-server (see skills/memory/references/mcp-config.md)
+
+  **Must NOT do**:
+  - Do NOT remove existing profile content
+
+  **Recommended Agent Profile**:
+  - **Category**: `quick`
+  - **Skills**: []
+
+  **Parallelization**:
+  - **Can Run In Parallel**: YES
+  - **Parallel Group**: Wave 3 (with Task 7)
+  - **Blocks**: Task 9
+  - **Blocked By**: Task 4
+
+  **References**:
+  - `/home/m3tam3re/p/AI/AGENTS/context/profile.md` — Current profile to extend
+
+  **Acceptance Criteria**:
+
+  ```
+  Scenario: Verify memory config in profile
+    Tool: Bash
+    Steps:
+      1. grep "Memory System" /home/m3tam3re/p/AI/AGENTS/context/profile.md
+      2. grep "localhost:8000" /home/m3tam3re/p/AI/AGENTS/context/profile.md
+      3. grep "80-memory" /home/m3tam3re/p/AI/AGENTS/context/profile.md
+      4. grep "auto-capture" /home/m3tam3re/p/AI/AGENTS/context/profile.md
+    Expected Result: Memory system section with all config values
+    Evidence: grep output
+  ```
+
+  **Commit**: YES (groups with Task 7)
+  - Message: `feat(agents): add memory management to Apollo prompt and user profile`
+  - Files: `prompts/apollo.txt`, `context/profile.md`
+  - Repo: `~/p/AI/AGENTS`
+
+---
+
+- [x] 9. End-to-End Validation
+
+  **What to do**:
+  - Verify ALL files exist and contain expected content
+  - Run skill validation: `./scripts/test-skill.sh memory`
+  - Test Mem0 availability: `curl http://localhost:8000/health`
+  - Test Obsidian REST API: `curl http://127.0.0.1:27124/vault-info`
+  - Verify CODEX vault structure: `ls -la ~/CODEX/80-memory/`
+  - Verify template: `cat ~/CODEX/templates/memory.md | head -20`
+  - Check all YAML frontmatter valid across new/updated skill files
+
+  **Must NOT do**:
+  - Do NOT create automated test infrastructure
+  - Do NOT modify any files — validation only
+
+  **Recommended Agent Profile**:
+  - **Category**: `unspecified-low`
+    - Reason: Verification only, running commands and checking outputs
+  - **Skills**: []
+
+  **Parallelization**:
+  - **Can Run In Parallel**: NO
+  - **Parallel Group**: Wave 4 (final, sequential)
+  - **Blocks**: None (final task)
+  - **Blocked By**: ALL tasks (1-8)
+
+  **Acceptance Criteria**:
+
+  ```
+  Scenario: Full file existence check
+    Tool: Bash
+    Steps:
+      1. test -f ~/p/AI/AGENTS/skills/memory/SKILL.md
+      2. test -f ~/p/AI/AGENTS/skills/memory/references/mcp-config.md
+      3. test -d ~/CODEX/80-memory/preferences
+      4. test -f ~/CODEX/templates/memory.md
+      5. grep "80-memory" ~/CODEX/AGENTS.md
+      6. grep "#memory" ~/CODEX/tag-taxonomy.md
+      7. grep "80-memory" ~/CODEX/README.md
+      8. grep -i "memory" ~/p/AI/AGENTS/prompts/apollo.txt
+      9. grep "Memory System" ~/p/AI/AGENTS/context/profile.md
+    Expected Result: All checks pass (exit code 0)
+    Evidence: Shell output captured
+
+  Scenario: Mem0 health check
+    Tool: Bash
+    Preconditions: Mem0 server must be running
+    Steps:
+      1. curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/health
+    Expected Result: HTTP 200
+    Evidence: Status code captured
+    Note: If Mem0 not running, this test will fail — spin up Mem0 first
+
+  Scenario: Obsidian REST API check
+    Tool: Bash
+    Preconditions: Obsidian desktop app must be running with Local REST API plugin
+    Steps:
+      1. curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:27124/vault-info
+    Expected Result: HTTP 200
+    Evidence: Status code captured
+    Note: Requires Obsidian desktop app to be open
+
+  Scenario: Skill validation
+    Tool: Bash
+    Steps:
+      1. cd ~/p/AI/AGENTS && ./scripts/test-skill.sh memory
+    Expected Result: Validation passes (no errors)
+    Evidence: Script output captured
+  ```
+
+  **Commit**: NO (validation only, no file changes)
+
+---
+
+## Commit Strategy
+
+| After Task | Message | Files | Repo | Verification |
+|------------|---------|-------|------|--------------|
+| 1 | `feat(vault): add 80-memory folder structure and memory template` | 80-memory/, templates/memory.md, tag-taxonomy.md | ~/CODEX | ls + grep |
+| 2 | `docs(vault): add 80-memory documentation to AGENTS.md and README.md` | AGENTS.md, README.md | ~/CODEX | grep |
+| 3+4 | `feat(memory): add core memory skill and MCP config reference` | skills/memory/SKILL.md, skills/memory/references/mcp-config.md | ~/p/AI/AGENTS | test-skill.sh |
+| 5 | `feat(mem0-memory): add memory categories and dual-layer sync patterns` | skills/mem0-memory/SKILL.md | ~/p/AI/AGENTS | grep |
+| 6 | `feat(obsidian): add memory folder conventions and workflows` | skills/obsidian/SKILL.md | ~/p/AI/AGENTS | grep |
+| 7+8 | `feat(agents): add memory management to Apollo prompt and user profile` | prompts/apollo.txt, context/profile.md | ~/p/AI/AGENTS | grep |
+
+**Note**: Two different git repos! CODEX and AGENTS commits are independent.
+
+---
+
+## Success Criteria
+
+### Verification Commands
+```bash
+# CODEX vault structure
+ls ~/CODEX/80-memory/                     # Expected: preferences/ facts/ decisions/ entities/ other/
+cat ~/CODEX/templates/memory.md | head -5 # Expected: ---\ntype: memory
+grep "#memory" ~/CODEX/tag-taxonomy.md    # Expected: #memory/* tags
+
+# AGENTS skill validation
+cd ~/p/AI/AGENTS && ./scripts/test-skill.sh memory  # Expected: pass
+
+# Infrastructure (requires services running)
+curl -s http://localhost:8000/health           # Expected: 200
+curl -s http://127.0.0.1:27124/vault-info     # Expected: 200
+```
+
+### Final Checklist
+- [x] All "Must Have" present (dual-layer, auto-capture, auto-recall, categories, health checks, error handling)
+- [x] All "Must NOT Have" absent (no citation system, no deletion, no dashboards, no unit tests)
+- [x] CODEX commits pushed (vault structure + docs)
+- [x] AGENTS commits pushed (skills + prompts + profile)
+- [x] User reminded to add Obsidian MCP to Nix config and run `home-manager switch`
+- [x] User reminded to spin up Mem0 server before using memory features