commit 4236420b70171f1f6f09ffc545c77d6f6474fbe4 Author: Zhongwei Li Date: Sun Nov 30 08:29:41 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..ccdaef6 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,21 @@ +{ + "name": "memory-store", + "description": "Gives Claude persistent memory across sessions. Fully autonomous memory tracking - works immediately after install with zero configuration. Records corrections, patterns, and decisions automatically. Optional intelligence layer for proactive pattern following.", + "version": "1.2.3", + "author": { + "name": "Autotelic Team", + "email": "developers@autotelic.inc" + }, + "skills": [ + "./skills" + ], + "agents": [ + "./agents" + ], + "commands": [ + "./commands" + ], + "hooks": [ + "./hooks" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..c8591f1 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# memory-store + +Gives Claude persistent memory across sessions. Fully autonomous memory tracking - works immediately after install with zero configuration. Records corrections, patterns, and decisions automatically. Optional intelligence layer for proactive pattern following. diff --git a/agents/memory-tracker.md b/agents/memory-tracker.md new file mode 100644 index 0000000..dd18d67 --- /dev/null +++ b/agents/memory-tracker.md @@ -0,0 +1,307 @@ +--- +description: Specialized agent for deep project analysis and development context management +capabilities: + - project-analysis + - git-history-analysis + - team-workflow-documentation + - cross-repo-context + - branching-strategy-analysis +--- + +# Memory Tracker Agent + +A specialized agent that performs deep analysis of projects, tracks development patterns, and maintains comprehensive context in the memory store. + +## When Claude Should Invoke This Agent + +Invoke this agent when tasks require: + +1. **Deep Project Analysis** + - Analyzing entire project structure + - Understanding complex relationships + - Mapping business logic flows + - Identifying architectural patterns + +2. **Git History Analysis** + - Examining commit patterns over time + - Understanding branching strategies + - Tracking feature development lifecycle + - Identifying contributors and ownership + +3. **Cross-Repository Context** + - Analyzing related repositories + - Understanding microservice relationships + - Mapping dependencies + - Tracking shared patterns + +4. **Team Workflow Documentation** + - Documenting development processes + - Capturing team conventions + - Analyzing code review patterns + - Understanding deployment strategies + +5. **Pattern Evolution Tracking** + - How patterns changed over time + - Why refactorings were done + - Evolution of architectural decisions + - Learning from past mistakes + +## Agent Expertise + +### Core Competencies + +**Project Structure Analysis** +- File organization patterns +- Module dependencies +- Code architecture mapping +- Key component identification + +**Git & Version Control** +- Commit message analysis +- Branch naming conventions +- Merge strategies +- Release patterns + +**Development Patterns** +- Coding conventions +- Testing strategies +- Error handling approaches +- API design patterns + +**Business Logic Documentation** +- Core workflows +- Business rules +- Domain models +- Integration points + +**Team Collaboration** +- Code review patterns +- Communication channels +- Decision-making processes +- Knowledge sharing methods + +## How This Agent Works + +### Analysis Process + +1. **Discovery Phase** + - Scan project structure + - Identify key files and directories + - Map dependencies + - Locate documentation (CLAUDE.md, README, etc.) + +2. **Git Analysis Phase** + - Analyze commit history (last 3-6 months) + - Identify active contributors + - Map feature branches + - Track release patterns + +3. **Pattern Recognition Phase** + - Extract coding patterns + - Identify conventions + - Detect inconsistencies + - Map business logic + +4. **Documentation Phase** + - Sync CLAUDE.md files + - Parse anchor comments + - Extract inline documentation + - Map knowledge locations + +5. **Storage Phase** + - Store findings in memory store + - Create searchable context + - Link related concepts + - Enable future retrieval + +## Example Invocations + +### Deep Project Analysis + +``` +User: "Can you analyze this entire project and document the architecture?" + +Claude: I'll invoke the Memory Tracker agent to perform a comprehensive analysis. + +Memory Tracker Agent: +1. Scanning project structure... + - Found 450+ files across 12 main directories + - Identified React frontend + Node.js backend + - Detected microservices architecture + +2. Analyzing git history... + - 1,200+ commits over 6 months + - 5 active contributors + - Feature branch workflow with PR reviews + - Weekly release cycle + +3. Extracting patterns... + - Service layer pattern consistently used + - Jest + React Testing Library for tests + - Conventional commit messages + - TypeScript strict mode enabled + +4. Documenting business logic... + - Core workflows: Auth, Products, Orders, Payments + - Payment integration with Stripe + - Email notifications via SendGrid + - Background jobs with Bull queue + +5. Storing in memory... + ✓ 50+ patterns documented + ✓ 12 key decisions recorded + ✓ 8 business workflows mapped + ✓ Team conventions captured + +Analysis complete. Generated comprehensive project overview. +``` + +### Branching Strategy Analysis + +``` +User: "How does our team handle branching and releases?" + +Memory Tracker Agent: +Analyzing git branching strategy... + +Branch Patterns Found: +- main: Production branch (protected) +- develop: Integration branch +- feature/*: Feature development (15 active) +- bugfix/*: Bug fixes (3 active) +- hotfix/*: Emergency fixes (1 in last month) + +Merge Strategy: +- Squash merges to main +- Regular merges for feature branches +- PR required with ≥1 approval +- CI/CD runs on all PRs + +Release Pattern: +- Weekly releases (Fridays) +- Semantic versioning (v2.3.1) +- Release tags with notes +- Automated deployment to staging → production + +Conventions: +- Branch naming: type/ticket-number-description +- Commit format: Conventional commits +- PR titles: Match ticket numbers +- Reviews: Code owners required + +Stored in memory for team reference. +``` + +### Cross-Repository Context + +``` +User: "We have multiple microservices. Can you analyze how they relate?" + +Memory Tracker Agent: +Analyzing multi-repository context... + +Repositories Found: +1. api-gateway (Node.js) +2. auth-service (Node.js) +3. product-service (Python) +4. order-service (Node.js) +5. notification-service (Go) + +Relationships Mapped: +- API Gateway → All services (REST APIs) +- Auth Service → All services (JWT validation) +- Order Service → Product Service (inventory check) +- Order Service → Notification Service (order updates) + +Shared Patterns: +- Docker containers for all services +- Kubernetes deployment +- gRPC for service-to-service +- REST for external APIs +- Common logging format (JSON) +- Shared monitoring (Prometheus) + +Data Flow: +Order Creation: + Client → API Gateway → Auth Service (validate) + → Order Service → Product Service (check stock) + → Payment Service (charge) + → Notification Service (email) + +Stored cross-repo context in memory store. +``` + +## Integration with Memory Store + +### What Gets Stored + +**Project Structure** +```json +{ + "type": "project-structure", + "directories": ["src/", "tests/", "docs/"], + "key_files": ["package.json", "tsconfig.json"], + "architecture": "microservices", + "tech_stack": ["Node.js", "React", "PostgreSQL"] +} +``` + +**Development Patterns** +```json +{ + "type": "pattern", + "name": "service-layer-pattern", + "location": "src/services/", + "usage": "All business logic in service layer", + "example": "src/services/auth.ts" +} +``` + +**Team Conventions** +```json +{ + "type": "convention", + "category": "commits", + "rule": "Conventional commits required", + "enforcement": "CI check", + "examples": ["feat:", "fix:", "docs:"] +} +``` + +**Business Logic** +```json +{ + "type": "business-logic", + "workflow": "order-processing", + "steps": ["validate", "charge", "fulfill", "notify"], + "owner": "order-service", + "documentation": "CLAUDE.md#order-flow" +} +``` + +## Agent Tools & Capabilities + +This agent has access to: +- File system (read, analyze) +- Git commands (log, branch, diff) +- Memory MCP tools (record, recall, overview) +- Documentation parsers (Markdown, JSDoc) +- Code analysis tools (AST parsing) + +## Success Criteria + +The Memory Tracker Agent is successful when: +- New team members can quickly understand the project +- Architectural patterns are well-documented +- Team conventions are clearly defined +- Business logic is mapped and accessible +- Git history provides meaningful insights +- Cross-team knowledge sharing improves +- Development patterns are consistent + +## Related Components + +- `/memory-overview` command - Generates reports from agent's findings +- Memory Context Retrieval Skill - Uses agent's stored context +- Session hooks - Continuous tracking complements agent's deep analysis +- CLAUDE.md sync - Agent maintains anchor comment relationships diff --git a/commands/memory-overview.md b/commands/memory-overview.md new file mode 100644 index 0000000..d22dcb4 --- /dev/null +++ b/commands/memory-overview.md @@ -0,0 +1,199 @@ +--- +description: Generate comprehensive project overview from memory store +--- + +# Memory Overview + +Generates a comprehensive overview of the project by analyzing the memory store, git history, CLAUDE.md files, and development patterns. Provides a holistic view of project architecture, business logic, and team conventions. + +## What this command generates + +1. **Project architecture**: High-level structure and key components +2. **Business logic overview**: Core business rules and workflows +3. **Development patterns**: Established coding conventions and patterns +4. **Technology stack**: Languages, frameworks, and tools used +5. **Team conventions**: Coding standards, commit patterns, branching strategy +6. **Key decisions**: Important architectural and technical decisions +7. **Active areas**: Currently active development areas +8. **Knowledge gaps**: Areas with less documentation or context + +## Usage + +``` +/memory-overview +``` + +## Options + +``` +/memory-overview --format=markdown +/memory-overview --format=json +/memory-overview --save-to=PROJECT_OVERVIEW.md +/memory-overview --detailed +``` + +## Example Output + +``` +User: /memory-overview + +Claude: Project Overview - E-Commerce Platform +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +Generated from 247 memories, 150+ commits, 5 CLAUDE.md files + +## Architecture Overview + +### Frontend (React + TypeScript) +- Component structure: Atomic design pattern +- State management: Redux Toolkit +- Routing: React Router v6 +- Styling: Tailwind CSS + CSS Modules + +Key directories: +- src/components/ - Reusable UI components +- src/pages/ - Page-level components +- src/store/ - Redux state management +- src/api/ - API client layer + +### Backend (Node.js + Express) +- Architecture: RESTful API with service layer pattern +- Database: PostgreSQL with Prisma ORM +- Authentication: OAuth2 + JWT tokens +- File structure: Feature-based modules + +Key directories: +- src/api/ - API routes and controllers +- src/services/ - Business logic layer +- src/models/ - Database models +- src/middleware/ - Express middleware + +## Business Logic + +### Core Workflows +1. **User Authentication** (src/api/auth.ts) + - OAuth2 flow with Google/GitHub + - JWT token-based sessions + - Automatic token refresh + - Documented: CLAUDE.md + +2. **Product Catalog** (src/services/products.ts) + - Dynamic pricing rules + - Inventory management + - Category hierarchy + - Search with Elasticsearch + +3. **Order Processing** (src/services/orders.ts) + - Multi-step checkout flow + - Payment integration (Stripe) + - Order fulfillment pipeline + - Email notifications + +## Development Patterns + +### Coding Conventions +- TypeScript strict mode enabled +- ESLint + Prettier for code formatting +- Functional components with hooks +- Error handling: Standardized error codes +- Testing: Jest + React Testing Library + +### Commit Patterns +- Conventional commits (feat:, fix:, docs:, etc.) +- Branch naming: feature/, bugfix/, hotfix/ +- PR requirements: Tests + review +- Squash merges to main + +### Key Decisions + +1. **Why PostgreSQL over MongoDB?** (3 months ago) + - Decision: Use PostgreSQL for ACID compliance + - Reasoning: Complex relationships, transactions needed + - Team consensus in session mem-2024-10-15-xyz + +2. **OAuth2 Authentication** (2 months ago) + - Decision: Implement OAuth2 instead of basic auth + - Reasoning: Better security, SSO support, industry standard + - Implementation: src/api/auth.ts + +3. **Service Layer Pattern** (1 month ago) + - Decision: Separate business logic from API routes + - Reasoning: Better testability, code organization + - Pattern: src/services/* + +## Active Development Areas + +Current sprint focus: +- 🔥 Payment integration (Stripe) +- 🔥 Admin dashboard redesign +- 📝 API documentation (OpenAPI) +- 🧪 E2E test coverage improvement + +Recent commits (last 7 days): +- 15 commits on payment features +- 8 commits on admin UI +- 5 commits on testing + +## Team Conventions + +### CLAUDE.md Anchor Comments +- - Authentication patterns +- - API security guidelines +- - Database schema decisions +- - Error handling conventions +- - Testing best practices + +### Code Review Guidelines +- Minimum 1 approval required +- Tests must pass +- No console.logs in production code +- Update CLAUDE.md for new patterns + +## Knowledge Gaps + +Areas needing more documentation: +⚠️ Payment webhook handling +⚠️ Database backup strategy +⚠️ Deployment pipeline +⚠️ Performance monitoring setup + +## Statistics + +- Total files: 450+ +- Lines of code: ~85,000 +- Test coverage: 78% +- Team size: 5 developers +- Project age: 6 months +- Last major refactor: 2 weeks ago + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +This overview is continuously updated as development progresses. +Last updated: 5 minutes ago +Next sync: Automatic on session end +``` + +## Use Cases + +### For New Team Members +``` +/memory-overview --save-to=ONBOARDING.md +``` +Creates a comprehensive onboarding document. + +### For Documentation +``` +/memory-overview --format=markdown > PROJECT_OVERVIEW.md +``` +Generates markdown documentation. + +### For Stakeholder Updates +``` +/memory-overview --format=json | jq '.active_areas' +``` +Extracts specific sections for reports. + +## Related Commands + +- `/memory-sync` - Sync current state to memory +- `/memory-status` - View tracking status +- `/memory-context` - Retrieve specific context diff --git a/commands/memory-recall.md b/commands/memory-recall.md new file mode 100644 index 0000000..a11b980 --- /dev/null +++ b/commands/memory-recall.md @@ -0,0 +1,157 @@ +--- +description: Retrieve relevant context from memory store for current work +--- + +# Memory Recall + +Retrieves relevant development context, patterns, and team knowledge from the memory store based on your query or current task. + +## What this command does + +1. **Searches memory store**: Finds relevant past work and decisions +2. **Shows similar implementations**: Displays patterns used in similar contexts +3. **Retrieves team knowledge**: Surfaces insights from other team members +4. **Suggests best practices**: Recommends patterns based on project history +5. **Warns about deviations**: Alerts if current approach differs from established patterns + +## Usage + +``` +/memory-recall [query] +``` + +## Examples + +### Query Authentication Patterns +``` +/memory-recall authentication flow +``` + +**Returns:** +- OAuth2 implementation pattern (src/api/auth.ts:45) +- Past decisions about auth approach +- Token refresh strategy +- Error handling conventions +- Related team decisions + +### Find Database Decisions +``` +/memory-recall why did we choose PostgreSQL +``` + +**Returns:** +- Decision reasoning (ACID compliance) +- Rejected alternatives (MongoDB, etc.) +- When decided (Nov 13, 2025) +- Stakeholders (Security Team) +- Related constraints + +### Retrieve Error Handling Patterns +``` +/memory-recall error handling in API +``` + +**Returns:** +- Established error patterns +- Standardized error codes +- Logging conventions +- Team practices +- Example implementations + +### Get Team Expertise +``` +/memory-recall who knows about frontend +``` + +**Returns:** +- Ownership map (Bob: 90% frontend commits) +- Expertise areas +- Recent work +- Best person to ask + +## Example Output + +``` +/memory-recall authentication patterns + +📋 Retrieved Context from Memory Store +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Authentication Implementation (3 relevant memories) + +1. OAuth2 Flow Pattern (2 weeks ago) + - Location: src/api/auth.ts:45 + - Decision: OAuth2 password flow for all auth + - Reasoning: PCI compliance requirement + - Context: in CLAUDE.md + +2. Token Refresh Strategy (1 week ago) + - Pattern: Automatic refresh before expiration + - Implementation: src/utils/tokenManager.ts:78 + - Edge cases: Network failures, concurrent requests + +3. Error Handling (3 days ago) + - Pattern: Standardized auth error codes + - Location: src/types/errors.ts:23 + - Used by: All authentication endpoints + +Related Patterns: + - Session management: src/api/sessions.ts + - User permissions: src/middleware/permissions.ts + - API security: See CLAUDE.md + +Suggested Actions: + 1. Follow OAuth2 pattern in src/api/auth.ts + 2. Use standardized error codes + 3. Update documentation with any new patterns +``` + +## When to Use + +- ✅ Starting new feature (check similar work) +- ✅ Making decisions (review past choices) +- ✅ Code reviews (understand context) +- ✅ Bug fixing (see similar issues) +- ✅ Onboarding (learn project patterns) + +## Automatic vs Manual + +**Automatic Recall** (happens during conversation): +- Claude retrieves context automatically +- No command needed +- Happens every 5-10 messages +- Triggered by keywords + +**Manual Recall** (this command): +- Explicit context retrieval +- Specific queries +- Detailed results +- On-demand information + +## Advanced Usage + +### Filter by Time +``` +/memory-recall --since="1 week" database changes +``` + +### Filter by Author +``` +/memory-recall --author=alice backend patterns +``` + +### Include Commits +``` +/memory-recall --with-commits authentication +``` + +## Related Commands + +- `/memory-record "info"` - Store new memories +- `/memory-overview` - Full project overview +- `/memory-status` - Current session stats +- `/memory-ownership [person]` - Team expertise map + +## Note + +Most context retrieval happens **automatically** during conversations. Use `/memory-recall` when you want specific, detailed information on demand. diff --git a/commands/memory-status.md b/commands/memory-status.md new file mode 100644 index 0000000..165a9b9 --- /dev/null +++ b/commands/memory-status.md @@ -0,0 +1,72 @@ +--- +description: View current memory tracking status and statistics +--- + +# Memory Status + +Displays the current session tracking status, showing what files have been modified, commits analyzed, and context stored during this session. + +## What this command shows + +1. **Session information**: Current session ID, duration, and start time +2. **Files tracked**: List of files modified in this session +3. **Commits analyzed**: Recent commits that have been processed +4. **Context stored**: Number of memories recorded +5. **Memory store statistics**: Total memories, last sync time + +## Usage + +``` +/memory-status +``` + +## Options + +``` +/memory-status --detailed +/memory-status --json +``` + +## Example Output + +``` +User: /memory-status + +Claude: Memory Tracking Status +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Session Information: + Session ID: mem-2025-01-15-abc123 + Duration: 2h 45m + Started: 2025-01-15 09:30:00 + +Files Tracked (8): + ✓ src/api/auth.ts - Modified 15 minutes ago + ✓ src/components/Login.tsx - Modified 20 minutes ago + ✓ tests/auth.test.ts - Created 30 minutes ago + ✓ CLAUDE.md - Updated anchor comments + ... (4 more files) + +Commits Analyzed (3): + ✓ feat: add OAuth2 authentication flow + ✓ test: add auth integration tests + ✓ docs: update CLAUDE.md with auth patterns + +Context Stored: + - 12 development decisions recorded + - 5 pattern implementations tracked + - 3 business logic rules captured + +Memory Store: + Total memories: 247 + Last sync: 5 minutes ago + Status: ✓ Connected + +Next automatic sync: in 10 minutes +``` + +## Related Commands + +- `/memory-sync` - Manually sync to memory +- `/memory-context` - Retrieve relevant context +- `/memory-overview` - Generate project overview diff --git a/hooks/hooks.json b/hooks/hooks.json new file mode 100644 index 0000000..74e1894 --- /dev/null +++ b/hooks/hooks.json @@ -0,0 +1,73 @@ +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/session-start.sh" + } + ] + } + ], + "SessionEnd": [ + { + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/session-end.sh" + } + ] + } + ], + "PreToolUse": [ + { + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/track-changes.sh" + }, + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/analyze-anchors.sh" + } + ], + "matcher": "Write|Edit" + }, + { + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate-commit.sh" + } + ], + "matcher": "Bash" + } + ], + "PreCompact": [ + { + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/save-context.sh" + } + ] + } + ], + "Notification": [ + { + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/feedback-capture.sh" + }, + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/auto-feedback.sh" + } + ], + "matcher": "error|failed|incorrect|wrong|mistake|deprecated|warning" + } + ] + } +} diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..15b2f3a --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,81 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:julep-ai/memory-store-plugin:", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "eed537f8c704ef8449a57e3a55d2fab8daf1a083", + "treeHash": "35c53466a8a7b78deec457110f8afa4e1258655ab9a83f8027c24170c225b6bc", + "generatedAt": "2025-11-28T10:19:20.990341Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "memory-store", + "description": "Gives Claude persistent memory across sessions. Fully autonomous memory tracking - works immediately after install with zero configuration. Records corrections, patterns, and decisions automatically. Optional intelligence layer for proactive pattern following.", + "version": "1.2.3" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "cfa661c587b1b99ec38b74385106def512194222fb9eba663e6e1c16331058b4" + }, + { + "path": "agents/memory-tracker.md", + "sha256": "ddf09c793a87d70ba9f5da3aeaedd2cb698b1d3c92c97544d7e9e8e62a823a1d" + }, + { + "path": "hooks/hooks.json", + "sha256": "381ddf48df7d6749eeabb814842e171816be278e4d8778b3c5f87226c5f6c742" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "64cc1940181b57e8d2d98ea22f8a4da25d3d4b6452f2810a5ca00746d49cf818" + }, + { + "path": "commands/memory-overview.md", + "sha256": "4672cba909beb5817ee78ffa1c6e9f3471bb127ac0cb9261b21b57e029d7caa2" + }, + { + "path": "commands/memory-status.md", + "sha256": "118cf7f23e3a157e2ad763a12e8ad5765e831a43fd6c02baf06403bd258f1a43" + }, + { + "path": "commands/memory-recall.md", + "sha256": "89a2d44cc270b6482e5bd7ff1e564081225484286a2df35afb3b552e03e7d310" + }, + { + "path": "skills/memory-context-retrieval/SKILL.md", + "sha256": "ce3e8081b78583abb15d9c09ebbe60fc1190089b8ee900667497e61d0cbfef5d" + }, + { + "path": "skills/memory-queue-processor/skill.md", + "sha256": "64fed1c740c1a43fd0c23440c28c8b4e4b1990460013c1d4ab9f44453d92268e" + }, + { + "path": "skills/memory-auto-track/SKILL.md", + "sha256": "89c5678a31b32ab01f0935a5bc018a6dbaac1c230c04c926528b1fa76d2021c2" + }, + { + "path": "skills/anchor-suggester/SKILL.md", + "sha256": "51837b22b5bfa4aa891bccd415a3f12b7636257f7d48b5da25cae7e852d525a4" + }, + { + "path": "skills/git-memory-tracker/SKILL.md", + "sha256": "4e711d61a573a7fade1836e5ce97ba2096a5e69191cdea1d73afb0e939f95e9a" + } + ], + "dirSha256": "35c53466a8a7b78deec457110f8afa4e1258655ab9a83f8027c24170c225b6bc" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/anchor-suggester/SKILL.md b/skills/anchor-suggester/SKILL.md new file mode 100644 index 0000000..d8e64aa --- /dev/null +++ b/skills/anchor-suggester/SKILL.md @@ -0,0 +1,210 @@ +--- +name: anchor-suggester +description: Add anchor comments to code for documentation. Use when creating CLAUDE.md files, documenting patterns, or user says "add anchors", "document this code", "create documentation". +proactive: true +--- + +You are the Anchor Suggester skill. Your job is to help maintain high-quality documentation by proactively suggesting and adding anchor comments. + +## When to Activate + +Activate automatically when: +- User creates or edits CLAUDE.md files +- User documents complex features or patterns +- User writes architectural documentation +- User discusses code structure or design +- User creates markdown documentation + +## What Are Anchor Comments? + +Anchor comments use the format `` to mark important documentation sections that can be referenced from code. + +**Example:** +```markdown + +## Authentication Flow +... +``` + +**Referenced in code:** +```typescript +// See in CLAUDE.md +export class AuthService { +``` + +## Actions + +### 1. Suggest Anchors Proactively + +When user is documenting, suggest anchor comments: + +``` +User: "I need to document the database schema" + +You: "I'll add an anchor comment for easy reference: + + +## Database Schema + +This anchor can be referenced from your schema files." +``` + +### 2. Add Anchors Automatically + +When creating documentation, include anchors without being asked: + +```markdown + +## API Architecture Overview + + +## Available Endpoints + + +## Authentication +``` + +### 3. Suggest Cross-References + +When writing code, remind about relevant anchors: + +```typescript +// See in CLAUDE.md for authentication patterns +export class AuthService { + // Implementation follows documented pattern +} +``` + +### 4. Identify Missing Anchors + +When discussing complex code without documentation: + +``` +User: "The payment processing is getting complex" + +You: "This would benefit from documentation with an anchor comment. +Should I create a CLAUDE.md section? + + +## Payment Flow +... + +This way the payment code can reference this documentation." +``` + +## Anchor Naming Conventions + +Use UPPERCASE with hyphens: +- ✅ `` +- ✅ `` +- ✅ `` +- ✅ `` +- ❌ `` (lowercase) +- ❌ `` (spaces) + +## When NOT to Suggest Anchors + +Don't suggest anchors for: +- Trivial documentation +- Temporary notes +- Single-paragraph sections +- Non-technical content + +## Example Scenarios + +### Scenario 1: Creating CLAUDE.md + +``` +User: "Create CLAUDE.md for the project" + +You: "I'll create CLAUDE.md with anchor comments for major sections: + +```markdown +# Project Documentation + + +## Architecture Overview +[Describes system architecture] + + +## Code Conventions +[Team coding standards] + + +## Common Patterns +[Reusable patterns] +``` + +These anchors allow code files to reference specific sections." +``` + +### Scenario 2: Complex Feature Documentation + +``` +User: "Document the caching strategy" + +You: "I'll document this with an anchor for future reference: + +```markdown + +## Caching Strategy + +We use Redis for session caching with a 1-hour TTL... +``` + +In your cache implementation: +```typescript +// See in CLAUDE.md +export class CacheService { +``` +``` + +### Scenario 3: Undocumented Complex Code + +``` +User: "The authentication code is hard to follow" + +You: "Let's document it with an anchor comment. I'll create: + +```markdown + +## Authentication Implementation Details + +Step-by-step explanation of the auth flow... +``` + +Then update your auth.ts: +```typescript +// See in CLAUDE.md for detailed explanation +``` + +This creates a living reference between code and docs." +``` + +## Benefits of Anchor Comments + +Explain to users why anchors are valuable: +- ✅ **Cross-referencing**: Code can point to specific doc sections +- ✅ **Navigation**: Easy to find documentation on specific topics +- ✅ **Team knowledge**: New members can follow references +- ✅ **Maintenance**: Clear connection between code and docs +- ✅ **Tracking**: Plugin tracks anchor usage and adoption + +## Integration with Memory Store + +The plugin automatically tracks: +- When anchors are added +- Which anchors are referenced most +- Orphaned anchors (no references) +- Documentation coverage + +This skill helps INCREASE anchor adoption by proactively suggesting them! + +## Remember + +- Always suggest anchors for complex features +- Add anchors automatically when creating docs +- Remind about cross-referencing in code +- Use consistent naming conventions +- Explain the benefit to users +- Make documentation maintenance easy diff --git a/skills/git-memory-tracker/SKILL.md b/skills/git-memory-tracker/SKILL.md new file mode 100644 index 0000000..a29d6e3 --- /dev/null +++ b/skills/git-memory-tracker/SKILL.md @@ -0,0 +1,361 @@ +--- +description: Track git commits and analyze development patterns. Use when user says "track this commit", "analyze commits", "what did I work on", or after git commit commands to store commit history in Memory Store. +proactive: true +--- + +# Git Memory Tracker Skill + +**⚡ PROACTIVE: Suggest tracking commits when you notice git activity or user mentions commits.** + +**Purpose**: Manually analyze git history and store commit patterns in Memory Store when hooks don't capture them automatically. + +## When to Use This Skill + +**Invoke this skill when:** + +1. **After creating commits** - To manually track commit history + - User says: "Track this commit" or "Analyze the last commit" + - After a merge or rebase operation + - When you want to store commit context for future reference + +2. **Analyzing git patterns** - To understand development flow + - User says: "What's our commit history?" or "Show me recent commits" + - User asks: "What patterns do we use for commits?" + - Before creating a PR to summarize changes + +3. **Tracking contributions** - To record who worked on what + - User asks: "Who worked on this feature?" + - User says: "Track ownership for these changes" + - Team wants to understand code ownership + +4. **After batch operations** - When multiple commits need analysis + - After cherry-picking commits + - After merging branches + - After rebasing or squashing commits + +**Don't use this skill for:** +- Single file changes (use automatic file tracking instead) +- Questions that don't involve git history +- General project questions (use memory-auto-track instead) + +## How This Skill Works + +This skill runs the `analyze-commits.sh` script which: +1. Analyzes the most recent commit(s) +2. Extracts commit metadata (message, author, files changed, type) +3. Detects patterns (conventional commits, breaking changes) +4. Stores commit information in Memory Store via `mcp__memory-store__record` + +## Usage Instructions + +### Step 1: Detect When Manual Tracking is Needed + +**Look for these patterns:** + +```markdown +User: "I just committed some changes, can you track them?" +User: "Analyze my last 5 commits" +User: "What did I work on today?" +User: "Track this PR's commits" +``` + +### Step 2: Run the analyze-commits.sh Script + +```bash +bash ${CLAUDE_PLUGIN_ROOT}/scripts/analyze-commits.sh +``` + +**Note**: The script automatically: +- Reads the most recent commit from git +- Extracts all relevant metadata +- Records it in Memory Store +- Increments the session commit counter + +### Step 3: Parse Results and Inform User + +The script outputs JSON with commit information. Parse it and tell the user what was tracked: + +```markdown +✓ Tracked commit abc1234: "feat: add OAuth2 authentication" + - Type: feature + - Files changed: 8 + - Breaking change: No + - Stored in Memory Store with high importance +``` + +## Advanced: Batch Commit Analysis + +For analyzing multiple commits (e.g., after a PR merge): + +### Step 1: Get Commit Range + +```bash +# Get last N commits +git log --oneline -n 5 + +# Get commits since main +git log main..HEAD --oneline + +# Get commits in PR +git log origin/main..feature-branch --oneline +``` + +### Step 2: Analyze Each Commit + +For each commit in the range: + +```bash +# Checkout specific commit +git show --stat + +# Extract info and record +mcp__memory-store__record { + "memory": " ()", + "background": "Commit on branch . Files: . Author: . Date: ", + "importance": "normal" +} +``` + +### Step 3: Create Summary + +After analyzing all commits, create a summary memory: + +```javascript +mcp__memory-store__record({ + "memory": "Feature branch merged: with commits", + "background": "Commits: . Total files changed: . Date range: to ", + "importance": "high" +}) +``` + +## Commit Pattern Detection + +The skill automatically detects these patterns: + +### Conventional Commits + +- `feat:` → Type: feature (importance: normal) +- `fix:` → Type: bugfix (importance: normal) +- `docs:` → Type: documentation (importance: low) +- `test:` → Type: test (importance: low) +- `refactor:` → Type: refactoring (importance: normal) +- `chore:` → Type: chore (importance: low) +- `style:` → Type: style (importance: low) + +### Breaking Changes + +If commit message contains `BREAKING CHANGE` or `BREAKING:`: +- Importance automatically upgraded to **high** +- Breaking change flag set to true +- ⚠️ warning added to commit summary + +### Important Files + +If commit affects these files: +- `package.json`, `tsconfig.json`, `.env` → Importance: normal +- `plugin.json`, `hooks.json` → Importance: high +- `CLAUDE.md`, `README.md` → Importance: normal +- Infrastructure (docker, kubernetes) → Importance: normal + +### Ticket References + +Automatically extracts ticket numbers from: +- Commit message: `feat: add auth (#123)` +- Branch name: `feature/AUTH-456` + +## Examples + +### Example 1: Single Commit Tracking + +**User says:** +``` +I just committed the new authentication feature, can you track it? +``` + +**Action:** +1. Run analyze-commits.sh +2. Parse output +3. Confirm to user + +**Response:** +```markdown +✓ Commit tracked successfully! + +**Commit**: feat: add OAuth2 authentication flow +- Hash: abc1234 +- Type: feature +- Files changed: 8 (+245/-12 lines) +- Ticket: AUTH-123 +- Importance: high (affects infrastructure) +- Stored in Memory Store ✓ + +This commit is now searchable in memory for future reference. +``` + +### Example 2: Analyzing Recent History + +**User says:** +``` +What did I work on in the last 5 commits? +``` + +**Action:** +1. Get last 5 commits with `git log --oneline -5` +2. For each commit, analyze and record +3. Create summary + +**Response:** +```markdown +Here's your recent work (last 5 commits): + +1. ✓ **fix: resolve auth token expiration bug** (bugfix) + - 3 files changed, 45 minutes ago + +2. ✓ **test: add auth integration tests** (test) + - 2 files changed, 2 hours ago + +3. ✓ **feat: add OAuth2 authentication flow** (feature) 🔴 BREAKING + - 8 files changed, 1 day ago + +4. ✓ **docs: update API documentation** (documentation) + - 1 file changed, 1 day ago + +5. ✓ **refactor: extract auth helpers** (refactoring) + - 4 files changed, 2 days ago + +**Summary**: 5 commits across 2 days, mostly focused on authentication. +All commits have been tracked in Memory Store. +``` + +### Example 3: PR Preparation + +**User says:** +``` +I'm about to create a PR, can you summarize my commits since main? +``` + +**Action:** +1. Get commit range: `git log main..HEAD --oneline` +2. Analyze all commits +3. Create PR summary with commit breakdown + +**Response:** +```markdown +**PR Summary: Add OAuth2 Authentication** + +**Commits**: 8 commits since main +- 3 features +- 2 bug fixes +- 2 tests +- 1 documentation update + +**Breaking Changes**: Yes (1 commit) +- feat: add OAuth2 authentication flow (requires migration) + +**Files Changed**: 15 files (+347/-89 lines) + +**Key Changes**: +1. OAuth2 flow implementation (auth.ts, oauth.ts) +2. Token management (token-manager.ts) +3. Integration tests (auth.test.ts) +4. API documentation updates + +All commits have been tracked in Memory Store for future reference. +Would you like me to draft a PR description? +``` + +## Session Counter Updates + +When using this skill, manually update the session counter: + +```bash +# Read current count +source .claude-session +COMMITS_COUNT=$((${MEMORY_COMMITS_COUNT:-0} + 1)) + +# Update session file +sed -i.bak "s/MEMORY_COMMITS_COUNT=.*/MEMORY_COMMITS_COUNT=${COMMITS_COUNT}/" .claude-session +rm -f .claude-session.bak +``` + +This ensures the session tracking remains accurate. + +## Error Handling + +### If analyze-commits.sh fails: + +```markdown +⚠️ Unable to analyze commit: + +Possible causes: +- Not in a git repository +- No commits to analyze +- MCP server connection issue + +Try: +1. Verify you're in a git repo: `git status` +2. Check recent commits: `git log -1` +3. Check MCP connection: `claude mcp list` +``` + +### If Memory Store is unavailable: + +```markdown +⚠️ Commit analyzed but not stored in Memory Store (server unavailable) + +**Commit**: +- Hash: +- Details: <...> + +The commit metadata is captured locally and will sync when the connection is restored. +``` + +## Integration with Other Skills + +This skill works alongside: + +1. **memory-auto-track**: For automatic memory retrieval when answering questions +2. **anchor-suggester**: For documenting patterns found in commits +3. **memory-context-retrieval**: For finding related past commits + +**Example workflow:** +1. User commits changes → Git Memory Tracker records them +2. User asks "How did we implement auth?" → Memory Auto-Track retrieves it +3. User creates CLAUDE.md → Anchor Suggester documents patterns +4. User asks about ownership → Memory Context Retrieval finds contributors + +## Best Practices + +1. **Track immediately after committing** - Don't wait until later +2. **Track PR merges** - Capture the full feature context +3. **Track breaking changes** - Always note these for future reference +4. **Batch analyze when needed** - For rebases or cherry-picks +5. **Update session counters** - Keep tracking accurate + +## Testing This Skill + +To verify it works: + +1. Make a test commit: + ```bash + echo "test" > test-file.md + git add test-file.md + git commit -m "test: verify git-memory-tracker skill" + ``` + +2. Ask Claude: "Track this commit" + +3. Verify it was stored: + ```bash + cat .claude-session # Should show MEMORY_COMMITS_COUNT incremented + ``` + +4. Test retrieval: + Ask Claude: "What did I just commit?" + Should retrieve from Memory Store and mention the test commit + +**Success criteria**: ✓ Commit tracked, counter incremented, retrievable from memory + +--- + +**💡 Pro Tip**: Use this skill proactively when working on features. Track commits as you go to build a rich history for future Claude sessions! diff --git a/skills/memory-auto-track/SKILL.md b/skills/memory-auto-track/SKILL.md new file mode 100644 index 0000000..6a71da6 --- /dev/null +++ b/skills/memory-auto-track/SKILL.md @@ -0,0 +1,294 @@ +--- +description: Automatically search memory and retrieve context when user asks questions about the project, past work, patterns, decisions, or implementations. Always invoke before answering "how did we", "what patterns", "who worked on". +proactive: true +--- + +# Memory Auto-Track Skill + +**⚡ IMPORTANT: This skill is ALWAYS ACTIVE. Use it automatically whenever the user asks questions.** + +## Purpose + +**Automatic memory search** integrated into conversation: +- **ALWAYS search memory** when user asks ANY question about the project +- **Check for established patterns** before suggesting implementations +- **Surface relevant past work** automatically +- **No manual /memory-recall needed** - you do it automatically + +**Note**: Storage is handled automatically by hooks. This skill makes retrieval AUTOMATIC. + +## When to Search Memory (Automatically!) + +**ALWAYS invoke mcp__memory-store__recall when:** + +1. **User asks ANY question about the project** + - "How did we implement X?" + - "What patterns do we use?" + - "Why did we choose Y?" + - **→ AUTOMATICALLY search memory BEFORE answering** + +2. **User asks you to implement something** + - "Create an API endpoint" + - "Add authentication" + - "Fix the bug in X" + - **→ AUTOMATICALLY search for similar past work** + +3. **User asks about team/ownership** + - "Who worked on X?" + - "What does the team use for Y?" + - **→ AUTOMATICALLY search memory** + +4. **User mentions uncertainty** + - "I'm not sure how we..." + - "What's our convention for..." + - **→ AUTOMATICALLY search memory** + +5. **You're about to suggest something** + - Before proposing an approach + - **→ AUTOMATICALLY search to check for existing patterns** + +**Cues for retrieval:** +- Project name +- File/directory names being worked on +- Technology stack keywords +- Feature names +- Problem domain terms + +## What to Do + +### For Storing Memories + +When storing (reactive to hooks): + +1. **Parse the context** to extract: + - The main memory text (concise summary) + - Background details (full context) + - Importance level (low, normal, high) + +2. **Invoke `mcp__memory__record`** tool with the extracted information + +3. **Confirm silently** - No need to tell the user unless there's an error + +### For Retrieving Context + +When retrieving (proactive for guidance): + +1. **Identify what you need to know**: + - What patterns exist for this type of work? + - How was similar functionality implemented? + - What decisions were made about this? + +2. **Create search cues** (3-7 relevant terms): + ```javascript + ["authentication", "API endpoint", "OAuth", "patterns"] + ``` + +3. **Invoke `mcp__memory__recall`** with: + - `cues`: Array of search terms + - `background`: Context about why you're searching + - `k`: Number of results (default 10) + +4. **Use the results** to: + - Follow established patterns + - Reference past decisions + - Ensure consistency with team conventions + - Provide better, context-aware responses + +5. **Mention to user** when using past context: + - "Based on our previous work with authentication..." + - "Following the API pattern we established in auth.ts..." + - "Consistent with the decision we made on 2024-11-01..." + +## Examples + +### Example 1: Storing - Session Start + +**Input additionalContext:** +``` +🚀 Development session starting in project mem-plugin on branch main. +Session ID: mem-20251113-ABC123. This session context should be stored +in memory using memory__record tool with importance: normal. +``` + +**Action:** +```javascript +// Invoke mcp__memory__record +{ + "memory": "Development session started in mem-plugin on branch main", + "background": "Session ID: mem-20251113-ABC123. Session initialized at 2025-11-13T17:00:00Z", + "importance": "normal" +} +``` + +### Example 2: File Change + +**Input additionalContext:** +``` +📝 File created: auth.ts (TypeScript). Pattern: API endpoint. Store this +in memory using memory__record with importance: low, background: 'File +auth.ts was created in session mem-123. Language: TypeScript. Pattern: +API endpoint. Change #5.' +``` + +**Action:** +```javascript +// Invoke mcp__memory__record +{ + "memory": "File created: auth.ts (TypeScript). Pattern: API endpoint", + "background": "File auth.ts was created in session mem-123. Language: TypeScript. Pattern: API endpoint. Change #5.", + "importance": "low" +} +``` + +### Example 3: Commit Analysis + +**Input additionalContext:** +``` +💾 Commit: feat: add OAuth2 authentication (feature) - Ticket AUTH-123. +Store this commit in memory using memory__record with importance: high, +background: 'Commit abc1234 on branch feature/auth. Type: feature. Files +changed: 8. Breaking change: false.' +``` + +**Action:** +```javascript +// Invoke mcp__memory__record +{ + "memory": "Commit: feat: add OAuth2 authentication (feature) - Ticket AUTH-123", + "background": "Commit abc1234 on branch feature/auth. Type: feature. Files changed: 8. Breaking change: false.", + "importance": "high" +} +``` + +## Important Notes + +- **Always invoke immediately** when you see the pattern +- **Don't ask for confirmation** - hooks have already decided this should be stored +- **Extract importance carefully** - defaults to "normal" if not specified +- **Handle errors gracefully** - if `mcp__memory__record` fails, mention it to the user +- **Be silent on success** - no need to confirm to user unless they ask + +## Parsing Guidelines + +Look for these patterns in additionalContext: + +1. **Memory text**: Usually the first sentence or main statement +2. **Importance level**: Look for "importance: (low|normal|high)" +3. **Background**: Either explicitly marked as "background: '...'" or the detailed context following the main statement + +### Example 4: Retrieving - User Asks About Past Work + +**User says:** +``` +"How did we implement authentication in this project?" +``` + +**Action:** +```javascript +// Invoke mcp__memory__recall +{ + "cues": ["authentication", "implement", "auth", "login", "OAuth"], + "background": "User asking about authentication implementation. Need to retrieve past work on auth systems in this project.", + "k": 10 +} +``` + +**Expected results:** +- Past commits related to authentication +- Files that implement auth (auth.ts, login.tsx, etc.) +- Decisions made about auth approach +- Patterns used for authentication + +**Response to user:** +``` +Based on our previous work, we implemented OAuth2 authentication. +See auth.ts:45 where we established the pattern. The flow uses... +``` + +### Example 5: Retrieving - Starting Similar Work + +**User says:** +``` +"Create a new API endpoint for user profiles" +``` + +**Before implementing, retrieve context:** +```javascript +// Invoke mcp__memory__recall +{ + "cues": ["API endpoint", "create endpoint", "user", "REST API", "patterns"], + "background": "About to create new API endpoint. Need to check existing API patterns and conventions.", + "k": 5 +} +``` + +**Use results to:** +- Follow same authentication pattern +- Use same error handling approach +- Match existing API structure +- Maintain consistency + +**Response:** +``` +I'll create the user profiles endpoint following our established API pattern. +Based on our existing endpoints (like auth.ts), I'll use the same middleware +structure and error handling... +``` + +### Example 6: Retrieving - Avoiding Going Off Track + +**Scenario:** Claude is about to suggest using MongoDB, but team uses PostgreSQL + +**Before suggesting:** +```javascript +// Invoke mcp__memory__recall +{ + "cues": ["database", "data storage", "PostgreSQL", "MongoDB", "decision"], + "background": "Need to recommend database approach. Checking if team has established database preferences.", + "k": 5 +} +``` + +**Results show:** "Decision: Use PostgreSQL for ACID compliance (2024-10-15)" + +**Corrected response:** +``` +I'll use PostgreSQL for this, consistent with our team's decision from +October 2024. This ensures ACID compliance and aligns with our existing +database infrastructure. +``` + +## Error Handling + +If `mcp__memory__record` fails: +1. **Don't silently fail** - inform the user +2. **Provide context** - tell them what you were trying to store +3. **Suggest solutions** - check MCP server connection, retry later + +Example error message: +``` +⚠️ Unable to store memory: "File created: auth.ts". +The memory store server may be unavailable. Your work is still tracked +locally and will sync when the connection is restored. +``` + +## Testing + +**For Storage:** +1. Make a file change +2. Hook fires → outputs additionalContext +3. This skill activates → invokes memory__record +4. Memory is stored + +**For Retrieval:** +1. Ask Claude about past work: "How did we implement X?" +2. Skill should invoke memory__recall automatically +3. Claude uses retrieved context in response +4. Mentions where pattern/decision came from + +**End-to-end test:** +1. Create file with specific pattern (e.g., API endpoint) +2. Verify stored via memory__record +3. Later ask: "How should I create an API endpoint?" +4. Claude retrieves the pattern and follows it +5. Consistency maintained! ✅ diff --git a/skills/memory-context-retrieval/SKILL.md b/skills/memory-context-retrieval/SKILL.md new file mode 100644 index 0000000..bb8fa71 --- /dev/null +++ b/skills/memory-context-retrieval/SKILL.md @@ -0,0 +1,183 @@ +--- +description: Retrieve development context and patterns from memory. Use when user asks "how did we build", "what's the pattern for", "who worked on", "show me previous", or when implementing similar features. +proactive: true +--- + +# Memory Context Retrieval Skill + +This skill enables Claude to automatically retrieve relevant development context, patterns, and team knowledge from the memory store without explicit user requests. + +## When to Invoke This Skill + +Claude should invoke this skill automatically when: + +1. **Starting new implementations** + - User asks to implement a feature + - Similar patterns might exist in memory + - Team has established conventions + +2. **Making architectural decisions** + - User proposes a technical approach + - Past decisions might be relevant + - Team consensus should be checked + +3. **Debugging or investigating code** + - User asks about existing code + - Context about why code was written exists + - Historical decisions provide insight + +4. **Refactoring or modifying code** + - Changes might affect established patterns + - Team conventions should be maintained + - Similar refactorings have been done before + +5. **Answering "why" questions** + - User asks why something was done a certain way + - Decision history is stored in memory + - Business logic reasoning is available + +## How to Use This Skill + +### Automatic Context Retrieval + +When Claude detects a task that might benefit from historical context: + +``` +1. Identify key concepts from user's request +2. Use memory_recall to search for relevant memories +3. Present relevant context to inform the response +4. Suggest patterns or warn about deviations +``` + +### Example Invocations + +**Scenario 1: New Feature Implementation** +``` +User: "I need to add a new API endpoint for user preferences" + +Claude (internally): +- Detects: New API endpoint needed +- Recalls: API endpoint patterns, authentication requirements +- Retrieves: Similar endpoint implementations, team conventions +- Applies: Suggests following established patterns + +Claude: "I'll help you create the user preferences endpoint. Based on our established +patterns (see src/api/auth.ts:45), I'll follow the same authentication and error +handling conventions we've used for other endpoints..." +``` + +**Scenario 2: Architectural Decision** +``` +User: "Should we use MongoDB or PostgreSQL for this new feature?" + +Claude (internally): +- Detects: Database choice decision +- Recalls: Previous database decisions +- Retrieves: Reasoning from 3 months ago +- Applies: Provides historical context + +Claude: "Looking at our memory store, the team decided to use PostgreSQL 3 months ago +(session mem-2024-10-15-xyz) for ACID compliance and complex relationships. Unless this +feature has significantly different requirements, I'd recommend staying consistent..." +``` + +**Scenario 3: Code Investigation** +``` +User: "Why is this authentication code structured this way?" + +Claude (internally): +- Detects: Question about existing code +- Recalls: Authentication implementation decisions +- Retrieves: Context from when code was written +- Applies: Explains reasoning + +Claude: "This authentication structure was implemented 2 weeks ago following the OAuth2 +pattern. The team chose this approach for better security and SSO support (documented +in CLAUDE.md anchor ). The specific structure handles edge cases +like token refresh and concurrent requests..." +``` + +## Integration with Memory Store + +### Tools Used + +This skill primarily uses these memory MCP tools: + +1. **memory_recall** - Retrieve relevant memories + ```typescript + memory_recall({ + cues: ["authentication", "api endpoint", "pattern"], + background: "User is implementing new API endpoint for user preferences", + k: 5 + }) + ``` + +2. **memory_overview** - Get project-wide context + ```typescript + memory_overview({ + mode: "standard" + }) + ``` + +### Context Categories + +The skill retrieves context from these categories: + +- **Implementation Patterns**: How similar features were built +- **Team Conventions**: Coding standards and practices +- **Decision History**: Why certain approaches were chosen +- **Business Logic**: Core workflows and rules +- **Error Patterns**: Common mistakes and their solutions +- **Architecture**: Overall system structure and patterns + +## Skill Behavior Guidelines + +### Do: +- ✓ Automatically recall context when relevant +- ✓ Present historical decisions naturally in responses +- ✓ Warn when user's approach deviates from patterns +- ✓ Suggest following established conventions +- ✓ Explain the reasoning behind past decisions +- ✓ Surface team knowledge proactively + +### Don't: +- ✗ Overwhelm user with too much historical context +- ✗ Blindly follow patterns without considering new requirements +- ✗ Retrieve context for trivial or unrelated tasks +- ✗ Block user's creativity with rigid pattern enforcement +- ✗ Ignore when patterns should evolve + +### Balance: +The skill should balance consistency with flexibility. Historical context informs but doesn't dictate. When user has good reasons to deviate, support the new approach while documenting it for future reference. + +## Performance Considerations + +- **Caching**: Recently retrieved memories are cached for session +- **Relevance**: Only retrieve highly relevant context (don't search everything) +- **Timing**: Retrieve context early in conversation, not repeatedly +- **Scope**: Limit context to what's immediately useful + +## Example Usage Pattern + +``` +User starts task → Skill activates → Retrieve context → Apply to response + ↓ + Store new patterns → Update memory → Enable future retrieval +``` + +## Related Components + +- `/memory-context` command - Manual context retrieval +- Session tracking hooks - Automatic context capture +- CLAUDE.md sync - Anchor comment integration +- Commit analysis - Git history context + +## Success Metrics + +This skill is successful when: +- Claude provides more contextually aware responses +- Team patterns are consistently followed +- New developers quickly learn established conventions +- Architectural decisions are well-informed +- Code reviews mention fewer pattern violations +- Team knowledge is effectively shared diff --git a/skills/memory-queue-processor/skill.md b/skills/memory-queue-processor/skill.md new file mode 100644 index 0000000..698d4ca --- /dev/null +++ b/skills/memory-queue-processor/skill.md @@ -0,0 +1,261 @@ +--- +description: Automatically process queued memory storage requests from hooks. Always checks .memory-queue.jsonl and processes items, reporting to user what was saved. +proactive: true +--- + +# Memory Queue Processor Skill + +**⚡ CRITICAL: This skill MUST check and process the queue on EVERY user message automatically, and report what was saved.** + +## Purpose + +**Fully autonomous memory processing with user feedback**: +- Hooks write to `.memory-queue.jsonl` file +- This skill checks the queue on EVERY interaction +- Processes all queued items automatically +- Reports to user what was saved +- Zero user intervention required + +## When to Activate + +**ALWAYS activate on EVERY user message:** +1. **Before responding** - Check queue first thing +2. **Process all items** - Invoke MCP tools automatically +3. **Report to user** - Tell them what was saved +4. **Clear queue** - Remove processed items +5. **Continue** - Respond to their question normally + +**No exceptions** - this happens automatically every single time. + +## How It Works + +### 1. Check for Queue File + +```bash +ls -la .memory-queue.jsonl +``` + +If file exists and is non-empty, process it. + +### 2. Read Queue Contents + +Each line is a JSON object: +```json +{"memory":"Session started...","background":"Project: mem-plugin...","importance":"normal","queued_at":"2025-11-21T15:00:00Z"} +``` + +### 3. Process Each Item + +For each line: +1. Parse JSON +2. Invoke `mcp__memory-store__record` with the parameters +3. Mark as processed (remove from queue or move to `.memory-queue-processed.jsonl`) + +### 4. Clean Up + +After processing: +- Clear the queue file or archive it +- Report how many items were processed (optional, only if > 5 items) + +## Implementation + +**HYBRID APPROACH**: Hooks provide foundational metadata, Claude adds conversational intelligence. + +**ALWAYS check the queue at the start of EVERY response:** + +```javascript +// 1. Check if queue exists +if (fileExists('.memory-queue.jsonl')) { + + // 2. Read all queued items + const queue = readFileLines('.memory-queue.jsonl') + .filter(line => line.trim()) + .map(line => JSON.parse(line)); + + // 3. ENRICH each item with conversational context before storing + for (const item of queue) { + // Hook provided: File: X, Action: created, Session: Y, Language: Z... + const foundationalContext = item.background; + + // Claude adds: What's being discussed? What problem is being solved? + const conversationalContext = analyzeCurrentContext({ + recentMessages: last5UserMessages, + currentTask: whatUserIsWorkingOn, + fileBeingModified: item.memory, + projectInfo: loadedFrom_claude_project_context + }); + + // Combine: Foundational (reliable) + Conversational (intelligent) + const enrichedBackground = `${foundationalContext}. Context: ${conversationalContext}`; + + await mcp__memory-store__record({ + memory: item.memory, + background: enrichedBackground, // ← Now includes BOTH + importance: item.importance + }); + } + + // 4. Clear queue + clearFile('.memory-queue.jsonl'); +} + +// 5. Continue with normal response +``` + +**Rules**: +- ✅ **ALWAYS CHECK** - Every single message, no exceptions +- ✅ **ENRICH CONTEXT** - Add conversation context to hook metadata +- ✅ **REPORT TO USER** - Tell user what was saved in Memory Store +- ✅ **FAIL GRACEFULLY** - If error, continue anyway +- ✅ **BE BRIEF** - Quick confirmation, don't interrupt workflow + +**Context Enrichment Strategy**: +1. **What user is working on**: "Fixing OAuth authentication", "Adding MCP validation", "Refactoring queue system" +2. **Why this change matters**: "This script validates MCP connection at session start to catch config issues early" +3. **How it relates to conversation**: "Part of implementing the hybrid context approach discussed with user" +4. **Project-specific details**: From `.claude-project-context` - architecture, purpose, components + +## Hybrid Context Examples + +### Example 1: File Change with Conversational Enrichment + +**Hook writes (foundational)**: +```json +{ + "memory": "File modified: scripts/session-start.sh (Shell)", + "background": "File: scripts/session-start.sh, Action: modified, Session: mem-xyz, Language: Shell, Pattern: , Change: #5, Project: mem-plugin, Version: 1.2.3, Component: script" +} +``` + +**Claude enriches (before storing)**: +- Sees conversation: User said "add MCP validation at session start" +- Understands context: This is part of fixing broken MCP detection +- Reads `.claude-project-context`: Understands mem-plugin architecture +- **Adds**: "Context: User implementing MCP connection validation at session start. This script now checks if memory-store MCP is configured using `claude mcp list` and displays status/setup command. Part of making the plugin more user-friendly by catching configuration issues early. Related to queue-based architecture where hooks need reliable MCP connection." + +**Final stored background**: +``` +File: scripts/session-start.sh, Action: modified, Session: mem-xyz, Language: Shell, Pattern: , Change: #5, Project: mem-plugin, Version: 1.2.3, Component: script. Context: User implementing MCP connection validation at session start. This script now checks if memory-store MCP is configured using `claude mcp list` and displays status/setup command. Part of making the plugin more user-friendly by catching configuration issues early. Related to queue-based architecture where hooks need reliable MCP connection. +``` + +### Example 2: Session Start with Intelligence + +**Hook writes (foundational)**: +```json +{ + "memory": "Session mem-20251121-ABC started in mem-plugin on branch main", + "background": "Session: mem-20251121-ABC, Started: 2025-11-21T15:00:00Z, Project: mem-plugin, Branch: main, Commit: 7005850, Files: 48, MCP: configured, Version: 1.2.3" +} +``` + +**Claude enriches**: +- Sees recent commits: "feat: add enriched background context", "feat: add MCP validation" +- Understands ongoing work: Improving context quality in memory storage +- **Adds**: "Context: Continuing work on hybrid context approach - hooks provide foundational metadata, Claude adds conversational intelligence. Recent work includes MCP validation and enriched background context. User wants reliable but intelligent memory storage." + +**Result**: Future sessions know what was being worked on and why! + +### Example 3: Original Approach + +**Scenario**: User starts new session, previous session queued 3 items + +**Action**: +1. Check `.memory-queue.jsonl` exists +2. Read 3 items +3. Invoke `mcp__memory-store__record` for each +4. Clear queue +5. Report: "💾 Saved 3 items to Memory Store (session start, 2 file changes)" + +### Example 2: File Changes + +**Scenario**: User edits 5 files rapidly, hooks queue each + +**Action**: +1. After user's next message, check queue +2. Find 5 items +3. Process all 5 +4. Report: "💾 Saved 5 file changes to Memory Store" + +### Example 3: Empty Queue + +**Scenario**: No queued items + +**Action**: +1. Check file (doesn't exist or empty) +2. Skip processing +3. Continue normally (no report needed) + +## Reporting Format + +**When items processed, always tell the user:** + +- **1-2 items**: "💾 Saved to Memory Store: [brief description]" +- **3-5 items**: "💾 Saved 4 items to Memory Store (session, 3 files)" +- **6+ items**: "💾 Saved 8 items to Memory Store" + +**Keep it brief** - just confirm what was saved, don't interrupt their workflow. + +## Integration with Hooks + +Hooks use `queue-memory.sh` instead of outputting signals: + +**Old approach (didn't work)**: +```bash +cat <