f0f075461e
- Move session_memory.py, ensure-symlinks.sh into skills/cognitive-memory/scripts/ - Copy systemd units into skills/cognitive-memory/systemd/ with README - Move PROJECT_PLAN.json, migrate.py into skills/cognitive-memory/dev/ - Add mtime-based embeddings cache to client.py (6x faster semantic recall) - Default recall to semantic+keyword merge (was keyword-only) - Update settings.json SessionEnd hook path, MCP allow entry - Update SKILL.md, feature.json, mcp_server.py docs for new defaults Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
461 lines
22 KiB
JSON
461 lines
22 KiB
JSON
{
|
|
"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
|
|
}
|
|
}
|
|
} |