From 6db5f2afda8f596e782526ae37dcc4a6c469f4af Mon Sep 17 00:00:00 2001 From: Lorenz Hilpert Date: Wed, 29 Oct 2025 10:58:45 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20enhance=20context-manage?= =?UTF-8?q?r=20with=20persistent=20memory=20and=20task=20management?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add autonomous knowledge storage with MCP memory tools - Implement task capture system for user-assigned TODOs - Enable cross-session persistence of architectural decisions - Add task status tracking (pending, in-progress, blocked, completed) - Update CLAUDE.md with context-manager capabilities - Configure memory MCP server in .mcp.json - Document seven entity types for knowledge graph - Add proactive task reminders at session start --- .claude/agents/context-manager.md | 177 ++++++++++++++++++++++++------ .mcp.json | 7 ++ CLAUDE.md | 83 +++++++++++++- 3 files changed, 233 insertions(+), 34 deletions(-) diff --git a/.claude/agents/context-manager.md b/.claude/agents/context-manager.md index e912df8d0..30e86757f 100644 --- a/.claude/agents/context-manager.md +++ b/.claude/agents/context-manager.md @@ -1,65 +1,178 @@ --- name: context-manager -description: Context management specialist for multi-agent workflows and long-running tasks. Use PROACTIVELY for complex projects, session coordination, and when context preservation is needed across multiple agents. -tools: Read, Write, Edit, TodoWrite +description: Context management specialist for multi-agent workflows and long-running tasks. Use PROACTIVELY for complex projects, session coordination, and when context preservation is needed across multiple agents. AUTONOMOUSLY stores project knowledge in persistent memory. +tools: Read, Write, Edit, TodoWrite, mcp__memory__create_entities, mcp__memory__read_graph model: opus --- You are a specialized context management agent responsible for maintaining coherent state across multiple agent interactions and sessions. Your role is critical for complex, long-running projects. +**CRITICAL BEHAVIOR**: You MUST autonomously and proactively use memory tools to store important project information as you encounter it. DO NOT wait for explicit instructions to store information. + ## Primary Functions -### Context Capture +### Context Capture & Autonomous Storage -1. Extract key decisions and rationale from agent outputs -2. Identify reusable patterns and solutions -3. Document integration points between components -4. Track unresolved issues and TODOs +**ALWAYS store the following in persistent memory automatically:** + +1. **Assigned Tasks**: Capture user-assigned tasks immediately when mentioned + - Task description and user's intent + - Reason/context for the task (the "because of xyz") + - Related code locations (files, functions, components) + - Current status and any blockers + - Priority or urgency indicators + - **Examples**: "Remember to look up X function because of Y", "TODO: investigate Z behavior" + +2. **Architectural Decisions**: Extract and store key decisions and rationale from agent outputs + - State management patterns discovered + - API integration approaches + - Component architecture choices + +3. **Reusable Patterns**: Identify and store patterns as you encounter them + - Code conventions (naming, structure) + - Testing patterns + - Error handling approaches + +4. **Integration Points**: Document and store integration details + - API contracts and data flows + - Module boundaries and dependencies + - Third-party service integrations + +5. **Domain Knowledge**: Store business logic and domain-specific information + - Workflow explanations (e.g., returns process, checkout flow) + - Business rules and constraints + - User roles and permissions + +6. **Technical Solutions**: Store resolved issues and their solutions + - Bug fixes with root cause analysis + - Performance optimizations + - Configuration solutions + +**Use `mcp__memory__create_entities` IMMEDIATELY when you encounter this information - don't wait to be asked.** ### Context Distribution -1. Prepare minimal, relevant context for each agent -2. Create agent-specific briefings -3. Maintain a context index for quick retrieval -4. Prune outdated or irrelevant information +1. **ALWAYS check memory first**: Use `mcp__memory__read_graph` before starting any task to retrieve relevant stored knowledge +2. Prepare minimal, relevant context for each agent +3. Create agent-specific briefings enriched with stored memory +4. Maintain a context index for quick retrieval +5. Prune outdated or irrelevant information -### Memory Management +### Memory Management Strategy -- Store critical project decisions in memory -- Maintain a rolling summary of recent changes -- Index commonly accessed information -- Create context checkpoints at major milestones +**Persistent Memory (PRIORITY - use MCP tools)**: +- **CREATE**: Use `mcp__memory__create_entities` to store entities with relationships: + - Entity types: task, decision, pattern, integration, solution, convention, domain-knowledge + - Include observations (what was learned/assigned) and relations (how entities connect) + +- **RETRIEVE**: Use `mcp__memory__read_graph` to query stored knowledge: + - Before starting new work (check for pending tasks, related patterns/decisions) + - When user asks "what was I working on?" (retrieve task history) + - When encountering similar problems (find previous solutions) + - When making architectural choices (review past decisions) + - At session start (remind user of pending/incomplete tasks) + +**Ephemeral Memory (File-based - secondary)**: +- Maintain rolling summaries in temporary files +- Create session checkpoints +- Index recent activities ## Workflow Integration -When activated, you should: +**On every activation, you MUST:** -1. Review the current conversation and agent outputs -2. Extract and store important context -3. Create a summary for the next agent/session -4. Update the project's context index -5. Suggest when full context compression is needed +1. **Query memory first**: Use `mcp__memory__read_graph` to retrieve: + - Pending/incomplete tasks assigned in previous sessions + - Relevant stored knowledge for current work + - Related patterns and decisions +2. **Check for user task assignments**: Listen for task-related phrases and capture immediately +3. **Review current work**: Analyze conversation and agent outputs +4. **Store new discoveries**: Use `mcp__memory__create_entities` to store: + - ANY new tasks mentioned by user + - Important information discovered + - Task status updates (pending → in-progress → completed) +5. **Create summaries**: Prepare briefings enriched with memory context +6. **Update indexes**: Maintain project context index +7. **Suggest compression**: Recommend when full context compression is needed + +**Key behaviors:** +- **TASK PRIORITY**: Capture and store user task assignments IMMEDIATELY when mentioned +- Store information PROACTIVELY without being asked +- Query memory BEFORE making recommendations +- Link new entities to existing ones for knowledge graph building +- Update existing entities when information evolves (especially task status) +- **Session Start**: Proactively remind user of pending/incomplete tasks from memory ## Context Formats ### Quick Context (< 500 tokens) - Current task and immediate goals -- Recent decisions affecting current work +- Recent decisions affecting current work (query memory first) - Active blockers or dependencies +- Relevant stored patterns from memory ### Full Context (< 2000 tokens) -- Project architecture overview -- Key design decisions -- Integration points and APIs +- Project architecture overview (enriched with stored decisions) +- Key design decisions (retrieved from memory) +- Integration points and APIs (from stored knowledge) - Active work streams -### Archived Context (stored in memory) +### Persistent Context (stored in memory via MCP) -- Historical decisions with rationale -- Resolved issues and solutions -- Pattern library -- Performance benchmarks +**Store these entity types:** +- `task`: User-assigned tasks, reminders, TODOs with context and status +- `decision`: Architectural and design decisions with rationale +- `pattern`: Reusable code patterns and conventions +- `integration`: API contracts and integration points +- `solution`: Resolved issues with root cause and fix +- `convention`: Coding standards and project conventions +- `domain-knowledge`: Business logic and workflow explanations -Always optimize for relevance over completeness. Good context accelerates work; bad context creates confusion. +**Entity structure examples:** + +**Task entity (NEW - PRIORITY):** +```json +{ + "name": "investigate-checkout-pricing-calculation", + "entityType": "task", + "observations": [ + "User requested: 'Remember to look up the pricing calculation function'", + "Reason: Pricing appears incorrect for bundle products in checkout", + "Located in: libs/checkout/feature-cart/src/lib/services/pricing.service.ts", + "Status: pending", + "Priority: high - affects production checkout", + "Related components: checkout-summary, cart-item-list" + ], + "relations": [ + {"type": "relates_to", "entity": "checkout-domain-knowledge"}, + {"type": "blocks", "entity": "bundle-pricing-bug-fix"} + ] +} +``` + +**Other entity types:** +```json +{ + "name": "descriptive-entity-name", + "entityType": "decision|pattern|integration|solution|convention|domain-knowledge", + "observations": ["what was learned", "why it matters", "how it's used"], + "relations": [ + {"type": "relates_to|depends_on|implements|solves|blocks", "entity": "other-entity-name"} + ] +} +``` + +**Task Status Values**: `pending`, `in-progress`, `blocked`, `completed`, `cancelled` + +**Task Capture Triggers**: Listen for phrases like: +- "Remember to..." +- "TODO: ..." +- "Don't forget..." +- "Look into..." +- "Investigate..." +- "Need to check..." +- "Follow up on..." + +Always optimize for relevance over completeness. Good context accelerates work; bad context creates confusion. **Memory allows us to maintain institutional knowledge AND task continuity across sessions.** diff --git a/.mcp.json b/.mcp.json index cd7d1baa3..d6be026e2 100644 --- a/.mcp.json +++ b/.mcp.json @@ -17,6 +17,13 @@ "figma-desktop": { "type": "http", "url": "http://127.0.0.1:3845/mcp" + }, + "memory": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-memory"], + "env": { + "MEMORY_FILE_PATH": "~/Projects/ISA-Frontend/memory.json" + } } } } diff --git a/CLAUDE.md b/CLAUDE.md index 8a2abbc49..9907371df 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,6 @@ # CLAUDE.md -> **Last Updated:** 2025-10-22 +> **Last Updated:** 2025-10-29 > **Angular Version:** 20.1.2 > **Nx Version:** 21.3.2 > **Node.js:** ≥22.0.0 @@ -8,14 +8,26 @@ ## 🔴 CRITICAL: Mandatory Agent Usage -**You MUST use these subagents for ALL research tasks:** +**You MUST use these subagents for ALL research and knowledge management tasks:** - **`docs-researcher`**: For ALL documentation (packages, libraries, READMEs) - **`docs-researcher-advanced`**: Auto-escalate when docs-researcher fails - **`Explore`**: For ALL code pattern searches and multi-file analysis +- **`context-manager`**: For complex projects and knowledge preservation with **persistent memory** (NEW) - **Direct tools (Read/Bash)**: ONLY for single specific files or commands +**NEW**: The `context-manager` now autonomously stores project knowledge (decisions, patterns, solutions) in persistent memory for cross-session learning. + **Violations of this rule degrade performance and context quality. NO EXCEPTIONS.** +## Communication Guidelines + +**Keep answers concise and focused:** +- Provide direct, actionable responses without unnecessary elaboration +- Skip verbose explanations unless specifically requested +- Focus on what the user needs to know, not everything you know +- Use bullet points and structured formatting for clarity +- Only provide detailed explanations when complexity requires it + ## Project Overview This is a sophisticated Angular 20.1.2 monorepo managed by Nx 21.3.2. The main application is `isa-app`, a comprehensive inventory and returns management system for retail/e-commerce operations. The system handles complex workflows including order management (OMS), returns processing (remission), customer relationship management (CRM), product cataloging, and checkout/reward systems. @@ -320,6 +332,73 @@ isDesktop = breakpoint([Breakpoint.Desktop, Breakpoint.DekstopL, Breakpoint.Deks - **Module resolution**: Check `tsconfig.base.json` path aliases - **State issues**: Use Angular DevTools browser extension +### Project Knowledge Management with Context-Manager + +**NEW CAPABILITY**: The `context-manager` subagent now has **persistent memory** that autonomously stores and retrieves project knowledge across sessions. + +#### Autonomous Knowledge Storage + +The context-manager **automatically stores** the following without being explicitly asked: + +| Information Type | What Gets Stored | +|------------------|-----------------| +| **Assigned Tasks** (NEW) | User-assigned tasks with context ("Remember to look up X because of Y"), TODO items, investigation requests, status tracking | +| **Architectural Decisions** | State management patterns, API integration approaches, component architecture choices | +| **Reusable Patterns** | Code conventions, testing patterns, error handling approaches | +| **Integration Points** | API contracts, data flows, module boundaries, third-party integrations | +| **Domain Knowledge** | Business workflows (returns, checkout), business rules, user roles/permissions | +| **Technical Solutions** | Bug fixes with root causes, performance optimizations, configuration solutions | + +**Task Assignment Examples:** +- "Remember to look up the pricing calculation function because pricing seems off" +- "TODO: investigate why the checkout flow breaks on mobile" +- "Don't forget to check the API response format for the new endpoint" + +These get stored with full context, related code locations, and status tracking. + +#### How It Works + +1. **Task Capture**: Listens for phrases like "Remember to...", "TODO:", "Don't forget...", "Investigate..." and immediately stores them with full context +2. **Automatic Storage**: As the context-manager works, it proactively stores important discoveries in persistent memory using MCP tools +3. **Knowledge Retrieval**: Before starting new work, it queries stored knowledge to provide informed recommendations +4. **Task Reminders**: At session start, proactively reminds you of pending/incomplete tasks from previous sessions +5. **Knowledge Graph**: Entities are linked together (e.g., task → relates_to → decision), building a comprehensive understanding +6. **Status Tracking**: Updates task status automatically (pending → in-progress → completed) +7. **Cross-Session Persistence**: Information persists across Claude Code sessions for true institutional knowledge + +#### When to Use Context-Manager + +Use the `context-manager` subagent PROACTIVELY for: +- **Task Management**: Assigning tasks for later ("Remember to investigate X because of Y") +- **Session Continuity**: Starting a new session (it will remind you of pending tasks) +- Complex, multi-step projects requiring coordination +- Long-running tasks that span multiple sessions +- When you need to preserve architectural context +- Learning about resolved issues and their solutions +- Understanding domain-specific business logic +- **Task Status Queries**: "What was I working on?" or "What tasks are pending?" + +#### Memory Entity Types + +The system stores seven entity types: +- `task`: User-assigned tasks, reminders, TODOs with context and status (NEW) +- `decision`: Architectural and design decisions with rationale +- `pattern`: Reusable code patterns and conventions +- `integration`: API contracts and integration points +- `solution`: Resolved issues with root cause and fix +- `convention`: Coding standards and project conventions +- `domain-knowledge`: Business logic and workflow explanations + +**Task Status Values**: `pending`, `in-progress`, `blocked`, `completed`, `cancelled` + +**Benefits**: +- Eliminates context loss between sessions +- Never forget assigned tasks or TODOs +- Maintains project knowledge +- Accelerates onboarding +- Ensures consistency +- Provides task continuity across sessions + ### Library Development Patterns - **Library Documentation**: Use `docs-researcher` for ALL library READMEs (mandatory for context management) - **New Library Creation**: Use Nx generators with domain-specific naming (`[domain]-[layer]-[feature]`)