{
  "meta": {
    "version": "1.0.0",
    "created": "2026-02-13",
    "lastUpdated": "2026-02-13",
    "planType": "feature",
    "project": "cognitive-memory",
    "description": "Remaining phases for the cognitive-memory skill. Phase 1 (core system + migration) is complete. This plan covers Phase 1 polish, Phase 2 (reflection + procedural + search), and Phase 3 (identity + economy + multi-agent).",
    "totalEstimatedHours": 52,
    "totalTasks": 18,
    "completedTasks": 10,
    "note": "SKILL.md, SCHEMA.md, CLAUDE.md, and feature.json updated to v2.0.0 with all Phase 2 features"
  },
  "categories": {
    "critical": "Must fix - blocking daily usage",
    "high": "Phase 1 polish - improves existing system significantly",
    "medium": "Phase 2 - reflection, procedural memory, semantic search",
    "low": "Phase 3 - identity, token economy, multi-agent",
    "feature": "Nice-to-have enhancements"
  },
  "tasks": [
    {
      "id": "HIGH-001",
      "name": "Add one-line summaries to CORE.md entries",
      "description": "CORE.md currently lists memory titles and tags but no summary. Each entry should include a brief one-line summary extracted from the memory content (first sentence or explicit summary field). This makes CORE.md useful at a glance without opening individual files.",
      "category": "high",
      "priority": 1,
      "completed": true,
      "tested": true,
      "dependencies": [],
      "files": [
        {
          "path": "~/.claude/skills/cognitive-memory/client.py",
          "lines": [
            539,
            580
          ],
          "issue": "core() method builds entries from index only, doesn't read file content for summaries"
        }
      ],
      "suggestedFix": "In core(), read the first sentence of each memory body (or a 'summary' frontmatter field if present) and append it after the link. Format: '- [title](path) - one-line summary'",
      "estimatedHours": 1,
      "notes": "Budget is ~3K tokens. With summaries, may need to reduce entries per section from 15 to 10."
    },
    {
      "id": "HIGH-002",
      "name": "Add scheduled decay recalculation",
      "description": "Decay scores only update when 'decay' command is run manually. Should auto-recalculate during recall/search operations if scores are stale (>24h since last calculation). Currently 56 memories are archived and 187 dormant - accessing one should refresh its score automatically.",
      "category": "high",
      "priority": 2,
      "completed": true,
      "tested": true,
      "dependencies": [],
      "files": [
        {
          "path": "~/.claude/skills/cognitive-memory/client.py",
          "lines": [
            283,
            350
          ],
          "issue": "recall() and search() read decay scores from state but never recalculate them"
        }
      ],
      "suggestedFix": "Add a _maybe_refresh_decay() check at the start of recall/search. If _state.json 'updated' is >24h old, run decay(). Also, when get() updates access_count, recalculate that memory's individual decay score immediately.",
      "estimatedHours": 2,
      "notes": "Be careful not to make recall() slow. Full decay recalc over 313 memories should be fast (<100ms) since it's just math, no file I/O."
    },
    {
      "id": "HIGH-003",
      "name": "Add 'merge' command to consolidate duplicate/related memories",
      "description": "With 313 memories, there are inevitably duplicates and near-duplicates (e.g., multiple PostgreSQL migration fixes). A 'merge' command should combine two memories into one, preserving the best content from each, merging tags, and keeping all relations.",
      "category": "high",
      "priority": 3,
      "completed": true,
      "tested": true,
      "dependencies": [],
      "files": [
        {
          "path": "~/.claude/skills/cognitive-memory/client.py",
          "issue": "No merge functionality exists"
        }
      ],
      "suggestedFix": "Add merge(keep_id, absorb_id) method: read both memories, combine content (keep_id content + separator + absorb_id content), merge tags (union), take max importance, redirect all absorb_id relations to keep_id, delete absorb_id file. Add 'merge' CLI subcommand.",
      "estimatedHours": 3,
      "notes": "Should also update any other memories that reference absorb_id in their relations to point to keep_id instead."
    },
    {
      "id": "HIGH-004",
      "name": "Improve recall content search performance",
      "description": "Currently recall() falls back to reading individual markdown files for body content search when title/tag matching fails. With 313+ files this is slow. Should use _index.json with a content preview field, or build a simple inverted index.",
      "category": "high",
      "priority": 4,
      "completed": true,
      "tested": true,
      "dependencies": [],
      "files": [
        {
          "path": "~/.claude/skills/cognitive-memory/client.py",
          "lines": [
            310,
            325
          ],
          "issue": "recall() reads individual files for content matching - O(n) file I/O"
        }
      ],
      "suggestedFix": "Option A: Add 'content_preview' (first 200 chars) to _index.json entries during reindex. Option B: Build a simple inverted word index in _index.json mapping common terms to memory IDs. Option A is simpler and sufficient for 300-500 memories.",
      "estimatedHours": 2,
      "notes": "Option B becomes necessary if memory count grows past ~1000. For now, Option A is the right call."
    },
    {
      "id": "MED-001",
      "name": "Reflection cycle - automated consolidation sessions",
      "description": "Structured process where the agent reviews recent memories, identifies patterns across them, consolidates duplicates, and generates insight memories. Triggered manually ('reflect') or automatically after N new memories since last reflection.",
      "category": "medium",
      "priority": 5,
      "completed": true,
      "tested": true,
      "dependencies": [
        "HIGH-003"
      ],
      "files": [
        {
          "path": "~/.claude/skills/cognitive-memory/client.py",
          "issue": "No reflection functionality exists"
        }
      ],
      "suggestedFix": "Add reflect() method and 'reflect' CLI command. Steps: (1) Load memories created since last reflection, (2) Group by tags/project, (3) Identify clusters of related memories, (4) For each cluster, generate a consolidated 'insight' memory (new type) summarizing the pattern, (5) Create BUILDS_ON relations from insight to source memories, (6) Log reflection as episode entry, (7) Store last_reflection timestamp in _state.json.",
      "estimatedHours": 6,
      "notes": "The actual insight generation requires Claude to analyze the cluster - this command should output the cluster data and prompt the agent to create the insight, not try to auto-generate it. Phase 2 core feature."
    },
    {
      "id": "MED-002",
      "name": "Procedural memory store - learned workflow patterns",
      "description": "New memory type 'procedure' that encodes multi-step workflows the agent has learned. Stored in graph/procedures/ with special frontmatter fields: steps (ordered list), preconditions, postconditions, success_rate. Procedures are higher-weight in decay (1.4) since they encode reusable operational knowledge.",
      "category": "medium",
      "priority": 6,
      "completed": true,
      "tested": true,
      "dependencies": [],
      "files": [
        {
          "path": "~/.claude/skills/cognitive-memory/client.py",
          "issue": "No procedure type or special handling exists"
        }
      ],
      "suggestedFix": "Add 'procedure' to VALID_TYPES and TYPE_DIRS (graph/procedures/). Add TYPE_WEIGHTS['procedure'] = 1.4. Extend frontmatter to support 'steps' field (ordered list of strings). Add 'procedure' CLI subcommand that prompts for step-by-step input. Update CORE.md generation to include a 'Key Procedures' section.",
      "estimatedHours": 4,
      "notes": "Procedures should be extractable from episode logs - if the same sequence of actions appears in multiple episodes, suggest creating a procedure."
    },
    {
      "id": "MED-003",
      "name": "Embedding-based semantic search via local model",
      "description": "Use a local embedding model (e.g., all-MiniLM-L6-v2 via sentence-transformers, or Ollama embeddings) to enable semantic search that finds conceptually similar memories even without keyword overlap. Store embeddings in a separate _embeddings.json file.",
      "category": "medium",
      "priority": 7,
      "completed": true,
      "tested": true,
      "dependencies": [
        "HIGH-004"
      ],
      "files": [
        {
          "path": "~/.claude/skills/cognitive-memory/client.py",
          "issue": "Search is keyword-only, no semantic understanding"
        }
      ],
      "suggestedFix": "Create embeddings.py module. On 'embed' command: (1) Load all memories, (2) Generate embeddings for title + first 200 chars of content, (3) Store in _embeddings.json (gitignored). On recall: compute query embedding, cosine similarity against all stored embeddings, merge scores with keyword search. Use Ollama API if available (check localhost:11434), fall back to keyword-only.",
      "estimatedHours": 6,
      "notes": "Keep this optional - keyword search must remain the default. Ollama is already running on the homelab. Embedding model choice: nomic-embed-text or all-minilm via Ollama. _embeddings.json should be gitignored and regeneratable."
    },
    {
      "id": "MED-004",
      "name": "Auto-episode logging from git commits",
      "description": "Automatically create episode entries when memories are stored after git commits. Detect when the context is a post-commit storage trigger and auto-populate episode fields from commit metadata (branch, files changed, commit message).",
      "category": "medium",
      "priority": 8,
      "completed": true,
      "tested": true,
      "dependencies": [],
      "files": [
        {
          "path": "~/.claude/skills/cognitive-memory/client.py",
          "lines": [
            590
          ],
          "issue": "store() doesn't auto-log episodes"
        }
      ],
      "suggestedFix": "Add optional --episode flag to store command. When set, automatically append an episode entry after storing the memory. Include the memory file path as the memory_link. This avoids requiring two separate CLI calls.",
      "estimatedHours": 1,
      "notes": "Simple quality-of-life improvement. Most stores should also log an episode."
    },
    {
      "id": "MED-005",
      "name": "REFLECTION.md - periodic reflection summary",
      "description": "Similar to CORE.md but focused on patterns and insights discovered during reflection cycles. Auto-generated file that tracks: recurring themes, cross-project patterns, most accessed memories, and memories that were consolidated.",
      "category": "medium",
      "priority": 9,
      "completed": true,
      "tested": true,
      "dependencies": [
        "MED-001"
      ],
      "files": [
        {
          "path": "~/.claude/memory/REFLECTION.md",
          "issue": "File does not exist"
        }
      ],
      "suggestedFix": "Generate during reflect() command. Structure: '## Themes' (tag co-occurrence analysis), '## Cross-Project Patterns' (memories that share tags across different projects), '## Most Accessed' (top 10 by access_count), '## Consolidated' (memories merged in this reflection). Store at ~/.claude/memory/REFLECTION.md alongside CORE.md.",
      "estimatedHours": 3,
      "notes": "Depends on reflection cycle being implemented first."
    },
    {
      "id": "MED-006",
      "name": "Tag co-occurrence analysis and suggestions",
      "description": "Analyze tag patterns across memories to suggest related memories during store and identify under-tagged memories. Build a tag co-occurrence matrix that reveals hidden connections (e.g., 'redis' frequently co-occurs with 'timeout' and 'production').",
      "category": "medium",
      "priority": 10,
      "completed": true,
      "tested": true,
      "dependencies": [],
      "files": [
        {
          "path": "~/.claude/skills/cognitive-memory/client.py",
          "issue": "No tag analysis exists"
        }
      ],
      "suggestedFix": "Add 'tags' CLI command with subcommands: 'tags list' (all tags with counts), 'tags related <tag>' (co-occurring tags), 'tags suggest <memory_id>' (suggest additional tags based on content and co-occurrence). Build co-occurrence matrix from _index.json during reindex.",
      "estimatedHours": 3,
      "notes": "Useful for maintaining tag hygiene and discovering patterns."
    },
    {
      "id": "LOW-001",
      "name": "IDENTITY.md - agent identity and preferences tracking",
      "description": "Auto-maintained markdown file that tracks the agent's learned identity: user preferences, communication style, project familiarity, skill proficiencies, and interaction patterns. Updated during reflection cycles based on accumulated memories.",
      "category": "low",
      "priority": 11,
      "completed": false,
      "tested": false,
      "dependencies": [
        "MED-001"
      ],
      "files": [
        {
          "path": "~/.claude/memory/IDENTITY.md",
          "issue": "File does not exist"
        }
      ],
      "suggestedFix": "Generate during reflection cycle. Sections: '## User Profile' (Cal's preferences from memories), '## Project Familiarity' (projects ranked by memory count and recency), '## Interaction Patterns' (common workflows, preferred tools), '## Learned Preferences' (extracted from decision memories). Load alongside CORE.md at session start.",
      "estimatedHours": 4,
      "notes": "Phase 3. Should be lightweight and focused on actionable context, not personality. Maximum ~1K tokens to avoid bloating system prompt."
    },
    {
      "id": "LOW-002",
      "name": "Token economy - budget system for reflections",
      "description": "Assign token costs to reflection operations and maintain a budget that replenishes over time. Prevents excessive reflection runs and encourages efficient memory management. Budget tracked in _state.json.",
      "category": "low",
      "priority": 12,
      "completed": false,
      "tested": false,
      "dependencies": [
        "MED-001"
      ],
      "files": [
        {
          "path": "~/.claude/skills/cognitive-memory/client.py",
          "issue": "No budget tracking exists"
        }
      ],
      "suggestedFix": "Add 'budget' section to _state.json: {tokens_remaining, tokens_max, last_refill, refill_rate}. Reflection costs: full reflect = 100 tokens, merge = 10, core regen = 5. Budget refills at 50 tokens/day. When budget is exhausted, reflection operations are blocked with a warning. 'budget' CLI command shows current balance.",
      "estimatedHours": 3,
      "notes": "Phase 3. Mainly useful if autonomous reflection is implemented (cron-triggered). For manual reflection, this may be unnecessary."
    },
    {
      "id": "LOW-003",
      "name": "Multi-agent pending queue - gated writes for team workflows",
      "description": "When multiple Claude Code agents work in a team, memory writes should go through a pending queue that the lead agent reviews before committing. Prevents conflicting or low-quality memories from parallel agents.",
      "category": "low",
      "priority": 13,
      "completed": false,
      "tested": false,
      "dependencies": [],
      "files": [
        {
          "path": "~/.claude/memory/",
          "issue": "No pending queue mechanism exists"
        }
      ],
      "suggestedFix": "Add ~/.claude/memory/_pending/ directory (gitignored). When store() detects team context (environment variable or flag), write to _pending/ instead of graph/. Add 'pending' CLI command: 'pending list', 'pending approve <id>', 'pending reject <id>', 'pending approve-all'. Approved memories move to graph/ with normal git commit. Rejected ones are deleted.",
      "estimatedHours": 5,
      "notes": "Phase 3. Only needed if multi-agent workflows become common. For now, single-agent usage doesn't need this."
    },
    {
      "id": "LOW-004",
      "name": "Memory visualization - graph export for external tools",
      "description": "Export the memory graph as JSON or DOT format for visualization in tools like Obsidian, Gephi, or a custom web viewer. Show memories as nodes, relations as edges, with size/color based on decay score and type.",
      "category": "low",
      "priority": 14,
      "completed": false,
      "tested": false,
      "dependencies": [],
      "files": [
        {
          "path": "~/.claude/skills/cognitive-memory/client.py",
          "issue": "No export functionality exists"
        }
      ],
      "suggestedFix": "Add 'export' CLI command with --format flag (json, dot, obsidian). JSON: full graph with nodes and edges. DOT: Graphviz format. Obsidian: Generate [[wikilinks]] in memory files for Obsidian graph view. Output to stdout or --output file.",
      "estimatedHours": 3,
      "notes": "Phase 3 nice-to-have. The Obsidian export is most interesting since Cal could browse memories in Obsidian's graph view."
    },
    {
      "id": "FEAT-001",
      "name": "Cron-based auto-maintenance",
      "description": "Set up a cron job or systemd timer that runs periodic maintenance: decay recalculation, CORE.md regeneration, and stale memory detection. Runs daily or weekly without requiring an active Claude session.",
      "category": "feature",
      "priority": 15,
      "completed": false,
      "tested": false,
      "dependencies": [
        "HIGH-002"
      ],
      "files": [
        {
          "path": "~/.claude/skills/cognitive-memory/client.py",
          "issue": "No maintenance command exists"
        }
      ],
      "suggestedFix": "Add 'maintain' CLI command that runs: decay(), core(), and reports stale/archived memory counts. Create systemd user timer or cron entry: '0 4 * * * python3 ~/.claude/skills/cognitive-memory/client.py maintain'. Add --quiet flag for cron usage.",
      "estimatedHours": 2,
      "notes": "Simple automation. Should also push to git after maintenance."
    },
    {
      "id": "FEAT-002",
      "name": "Memory import from external sources",
      "description": "Import memories from other formats: NoteDiscovery notes, markdown files, JSON dumps. Useful for bootstrapping memories from existing knowledge bases or migrating from other systems.",
      "category": "feature",
      "priority": 16,
      "completed": false,
      "tested": false,
      "dependencies": [],
      "files": [
        {
          "path": "~/.claude/skills/cognitive-memory/client.py",
          "issue": "No import functionality beyond migrate.py"
        }
      ],
      "suggestedFix": "Add 'import' CLI command with --format flag (markdown, json, notediscovery). Markdown: parse frontmatter or use filename as title. JSON: expect {title, content, type, tags} objects. NoteDiscovery: use NoteDiscovery client to fetch and convert notes.",
      "estimatedHours": 3,
      "notes": "Lower priority but useful for knowledge consolidation."
    },
    {
      "id": "FEAT-003",
      "name": "Memory health report",
      "description": "Generate a health report showing: memories with no tags, memories with no relations, duplicate titles, stale memories that should be archived or revived, tag distribution imbalance, and orphaned relations.",
      "category": "feature",
      "priority": 17,
      "completed": false,
      "tested": false,
      "dependencies": [],
      "files": [
        {
          "path": "~/.claude/skills/cognitive-memory/client.py",
          "issue": "stats() only shows counts, no qualitative analysis"
        }
      ],
      "suggestedFix": "Add 'health' CLI command. Checks: (1) untagged memories, (2) memories with 0 relations, (3) duplicate/near-duplicate titles (Levenshtein or token overlap), (4) memories below archive threshold, (5) tag distribution (warn if >50% of memories share same tag), (6) broken relation targets. Output as markdown report.",
      "estimatedHours": 3,
      "notes": "Good complement to reflection cycle. Run before reflect() to identify consolidation targets."
    },
    {
      "id": "DOCS-001",
      "name": "Update NoteDiscovery with cognitive-memory reference docs",
      "description": "Create reference documentation in NoteDiscovery at reference/skills/cognitive-memory covering the full skill documentation, CLI reference, schema, and migration notes.",
      "category": "feature",
      "priority": 18,
      "completed": false,
      "tested": false,
      "dependencies": [],
      "files": [],
      "suggestedFix": "Use NoteDiscovery client to create/update a note at reference/skills/cognitive-memory with SKILL.md content adapted for the wiki format. Include links to the git repo.",
      "estimatedHours": 1,
      "notes": "Keeps NoteDiscovery in sync with skill documentation, matching the pattern used for MemoryGraph docs."
    }
  ],
  "quickWins": [
    {
      "taskId": "MED-004",
      "estimatedMinutes": 45,
      "impact": "Eliminates the need for two separate CLI calls (store + episode) on every memory save"
    },
    {
      "taskId": "HIGH-001",
      "estimatedMinutes": 60,
      "impact": "Makes CORE.md immediately useful at a glance without opening individual files"
    },
    {
      "taskId": "DOCS-001",
      "estimatedMinutes": 30,
      "impact": "Keeps wiki docs in sync with new skill"
    }
  ],
  "productionBlockers": [],
  "weeklyRoadmap": {
    "week1": {
      "theme": "Phase 1 Polish",
      "tasks": [
        "HIGH-001",
        "HIGH-002",
        "HIGH-004",
        "MED-004"
      ],
      "estimatedHours": 6
    },
    "week2": {
      "theme": "Merge & Health",
      "tasks": [
        "HIGH-003",
        "FEAT-003",
        "MED-006"
      ],
      "estimatedHours": 9
    },
    "week3": {
      "theme": "Phase 2 Core - Reflection",
      "tasks": [
        "MED-001",
        "MED-005"
      ],
      "estimatedHours": 9
    },
    "week4": {
      "theme": "Phase 2 - Procedural & Maintenance",
      "tasks": [
        "MED-002",
        "FEAT-001",
        "DOCS-001"
      ],
      "estimatedHours": 7
    },
    "week5": {
      "theme": "Phase 2 - Semantic Search",
      "tasks": [
        "MED-003"
      ],
      "estimatedHours": 6
    },
    "week6_plus": {
      "theme": "Phase 3 - Identity, Economy, Multi-Agent",
      "tasks": [
        "LOW-001",
        "LOW-002",
        "LOW-003",
        "LOW-004",
        "FEAT-002"
      ],
      "estimatedHours": 18
    }
  }
}