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

37 KiB
Raw Blame History

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

  • All 11 files created/updated as specified
  • 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
  • ./scripts/test-skill.sh --validate passes for new/updated skills
  • 80-memory/ folder exists in CODEX vault with 5 subfolders
  • 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

  • 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: 
      ---
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

  • 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

  • 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: 
        "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

  • 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: 
      ---
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

  • 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

  • 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

  • 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

  • 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

  • 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

# 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

  • All "Must Have" present (dual-layer, auto-capture, auto-recall, categories, health checks, error handling)
  • All "Must NOT Have" absent (no citation system, no deletion, no dashboards, no unit tests)
  • CODEX commits pushed (vault structure + docs)
  • AGENTS commits pushed (skills + prompts + profile)
  • User reminded to add Obsidian MCP to Nix config and run home-manager switch
  • User reminded to spin up Mem0 server before using memory features
Reference in New Issue View Git Blame Copy Permalink