m3tam3re/AGENTS
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1bc81fb38c20154f0dd77f7da9b9d95439d8d873
AGENTS/.sisyphus/plans/memory-system.md

898 lines
37 KiB
Markdown
Raw Normal View History

docs(memory): update skills for opencode-memory plugin, deprecate mem0
2026-02-14 08:22:59 +01:00
# 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
Reference in New Issue Copy Permalink