القائمة
Knowledge accumulation and retrieval patterns for file-based agent memory
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | memory-protocol |
| version | 2.0.0 |
| author | jwilger |
| repository | jwilger/claude-code-plugins |
| description | Knowledge accumulation and retrieval patterns for file-based agent memory |
| tags | ["memory","file-based","learning","context","grep"] |
| portability | high |
| dependencies | [] |
| allowed-tools | Bash(grep *), Bash(find *), Bash(ls *), Bash(cat *), Bash(mkdir *) |
Version: 2.0.0 Portability: High
Memory is stored in ~/.claude/projects/<project-path>/memory/ and persists across sessions. Claude Code's auto memory feature manages this directory automatically.
Defines patterns for systematic knowledge accumulation and retrieval in agent workflows, enabling agents to learn from past experiences and avoid repeating work.
Purpose: Build institutional knowledge over time, recall solutions to previously-solved problems, and avoid context loss between sessions.
Scope:
The Principle: Before starting any task or debugging any problem, search accumulated knowledge for relevant past experiences.
Why this matters: The most wasteful work is work you've already done. Searching memory first prevents repeating solutions, rediscovering conventions, and re-debugging known issues.
How to apply:
Example:
# Bad workflow
User: "Fix the login bug"
Agent: Immediately starts debugging from scratch
(Wastes 30 minutes rediscovering root cause)
# Good workflow
User: "Fix the login bug"
Agent: Search memory: "login bug authentication error"
Found: "Login fails when session expires - solution: refresh token"
Apply known solution
(Fixes in 2 minutes)
Search triggers:
The Principle: After solving non-obvious problems, learning conventions, or making decisions, immediately store that knowledge.
Why this matters: Knowledge not captured is knowledge lost. Future you (or other agents) will encounter the same problems and waste time if solutions aren't stored.
What to remember:
What NOT to remember:
How to apply:
# After solving a problem
Agent: Discovered that API requires OAuth2 token in X-Custom-Auth header (not standard Authorization header)
Action: Store memory: "API authentication quirk: Use X-Custom-Auth header for OAuth2 tokens"
# After learning convention
Agent: Noticed all test files use suffix _test.py (not test_*.py)
Action: Store memory: "Project convention: Test files named <module>_test.py"
# After architectural decision
Agent: Chose event sourcing over CRUD for audit requirements
Action: Store memory: "Architecture: Using event sourcing. Rationale: Audit log requirement needs full history"
The Principle: Memories should be connected to related memories, forming a knowledge graph rather than isolated facts.
Why this matters: Connected knowledge is more discoverable and provides richer context. Finding one memory can lead to discovering related knowledge.
How to apply:
Example (Conceptual):
Memory 1: "Authentication uses JWT tokens"
└─ Related to: Memory 2 "JWT secret stored in environment variable JWT_SECRET"
└─ Related to: Memory 3 "Environment variables loaded from .env file"
Query: "How does authentication work?"
Result: Finds all 3 related memories (complete picture)
The Principle: Treat knowledge accumulation and retrieval as a primary responsibility, not an optional nice-to-have.
Why this matters: Agents without memory repeat mistakes, waste time, and don't improve. Memory is what enables learning and compound productivity gains.
How to apply:
Workflow integration:
Task start → Recall relevant knowledge
↓
Work on task
↓
Encounter problem → Recall solutions
↓
Solve problem → Remember solution
↓
Task complete → Remember insights
Rationale: Systematic knowledge management compounds over time. Initial overhead is small compared to long-term productivity gains.
Scenario: Starting work on a new feature.
Approach:
Step 1: Query for related work
Task: "Add email notification when order ships"
Search: "email notification" OR "order shipping" OR "email sending"
Results:
- Memory 1: "Email service uses SendGrid, API key in SENDGRID_API_KEY"
- Memory 2: "Email templates in templates/email/"
- Memory 3: "Order model has shipment_date field"
Step 2: Use knowledge to inform work
Benefits:
Scenario: Encountering an error during development.
Approach:
Step 1: Search for error
Error: "ssl.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED]"
Search: "CERTIFICATE_VERIFY_FAILED"
Result:
- Memory: "macOS SSL error: Install certificates.command after Python install"
Step 2: Apply known solution
/Applications/Python 3.x/Install Certificates.command
Step 3: If NOT found, debug and remember
(After solving novel error)
Store: "SSL error on macOS: Python doesn't use system certificates by default. Run Install Certificates.command in Python installation directory to fix."
Benefits:
Scenario: Working in an unfamiliar codebase.
Approach:
While working, notice patterns:
Observation 1: All API routes start with /api/v1/
Observation 2: Test files named <module>_test.py
Observation 3: Database models in src/models/
Observation 4: Validation uses Pydantic models
Store each convention:
Store: "Project convention: API routes prefixed with /api/v1/"
Store: "Project convention: Test files named <module>_test.py"
Store: "Architecture: Database models in src/models/, ORMs with SQLAlchemy"
Store: "Architecture: Input validation using Pydantic models"
Next time in this codebase:
Search: "API route convention"
Found: "API routes prefixed with /api/v1/"
Action: Follow established pattern automatically
Benefits:
Scenario: Making a significant architectural choice.
Approach:
During decision:
Decision: Use event sourcing for order history
Rationale:
- Requirement: Full audit trail of all order changes
- Requirement: Ability to replay state at any point in time
- Alternatives considered: CRUD with changelog table (insufficient)
Store decision:
Store: "Architecture: Order system uses event sourcing. Rationale: Audit requirements need full history and state replay capability. Alternative CRUD+changelog rejected (can't replay state)."
Benefits:
Works well with:
Prerequisites:
Problem: "This looks straightforward, I'll just start"
Solution: Search anyway. "Simple" problems often have non-obvious solutions already discovered.
Problem: Storing verbose explanations, full code snippets, essays
Solution: Store concise summaries with keywords. Details can be found in code/docs.
Example:
❌ Bad: "When I was working on the authentication system, I discovered that the JWT library we're using (jsonwebtoken version 8.5.1) requires the secret to be passed as a Buffer object, not a string, and if you pass a string it will throw a cryptic error message that says 'secret must be a Buffer' which took me 2 hours to figure out because the documentation is unclear..."
✓ Good: "JWT library requires secret as Buffer, not string. Use Buffer.from(secret) to convert."
Problem: Solve problem, move on, forget to store solution
Solution: Add "remember" step to workflow checkpoints:
Problem: Storing same fact multiple times with slight variations
Solution: Search before storing. If similar memory exists, update it instead of creating duplicate.
Tool: Markdown files in auto memory directory
Recall pattern:
# Search for authentication patterns
MEMORY_PATH="$HOME/.claude/projects/<project-path>/memory"
grep -r -i "jwt token" "$MEMORY_PATH" --include="*.md"
# Read relevant files
cat "$MEMORY_PATH/architecture/jwt-authentication.md"
Remember pattern:
# Create new memory file
cat > "$MEMORY_PATH/architecture/jwt-token-refresh.md" << 'EOF'
# JWT Token Refresh Pattern
**Date:** 2026-02-04
**Category:** architecture
**Project:** MyApp
## Problem / Context
JWT tokens expire after 1 hour, causing mid-session auth failures that disrupt user experience.
## Solution / Discovery
Implement proactive token refresh every 15 minutes to prevent expiration during active sessions.
## Details
```javascript
// In App.tsx
useEffect(() => {
const refreshInterval = setInterval(refreshToken, 15 * 60 * 1000);
return () => clearInterval(refreshInterval);
}, []);
### Example 2: Legacy Memento MCP Implementation (Deprecated)
**Note:** The sdlc plugin v6.0.0+ no longer uses Memento MCP. This example is kept for reference only.
**Tool:** Memento MCP server (knowledge graph) - **NO LONGER SUPPORTED**
**Recall pattern:**
```bash
# Search for error fix
grep -r "CERTIFICATE_VERIFY_FAILED" .memories/
# Output: .memories/python-ssl.md
# Solution: Install certificates.command
Remember pattern:
# Store new discovery
cat >> .memories/python-ssl.md << 'EOF'
## SSL Certificate Error (macOS)
**Problem:** `ssl.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED]`
**Solution:** Python on macOS doesn't use system certificates.
Run: `/Applications/Python 3.x/Install Certificates.command`
**Date:** 2026-02-04
**Context:** Encountered when using requests library
EOF
Tool: PostgreSQL or SQLite with full-text search
Schema:
CREATE TABLE memories (
id SERIAL PRIMARY KEY,
title TEXT NOT NULL,
content TEXT NOT NULL,
tags TEXT[],
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
CREATE INDEX idx_memories_content ON memories USING GIN(to_tsvector('english', content));
Recall pattern:
-- Search for authentication memories
SELECT title, content
FROM memories
WHERE to_tsvector('english', content) @@ plainto_tsquery('english', 'authentication jwt token')
ORDER BY ts_rank(to_tsvector('english', content), plainto_tsquery('english', 'authentication jwt token')) DESC
LIMIT 5;
Remember pattern:
-- Store new memory
INSERT INTO memories (title, content, tags)
VALUES (
'JWT Token Refresh Pattern',
'Refresh tokens proactively every 15 minutes to avoid mid-session auth failures. Implemented in App.tsx with setInterval.',
ARRAY['authentication', 'jwt', 'solution']
);
Scenario: Agent working through TDD cycle.
Task Start:
Task: "Write failing test for user registration"
Recall:
- Search: "user registration test patterns"
- Found: "Registration tests should verify email uniqueness"
- Found: "Use factory pattern for test users (UserFactory.build)"
Apply:
- Write test using UserFactory
- Include email uniqueness assertion
After RED Phase:
Remember:
- "Project convention: Test factories in tests/factories.py"
- "Domain rule: User emails must be unique (enforced by database constraint)"
After Encountering Error:
Error: "IntegrityError: duplicate key value violates unique constraint"
Recall:
- Search: "IntegrityError duplicate key"
- Found: "This means trying to create duplicate unique value"
Solution: Discovered test wasn't cleaning up between runs
Remember:
- "Test cleanup: Use pytest fixtures with 'autouse=True' to reset database"
Use this checklist to verify you're following the memory protocol:
Source Documentation:
Related Skills:
External Resources:
Extraction Source: sdlc/commands/remember.md and sdlc/commands/recall.md Extraction Date: 2026-02-04 Last Updated: 2026-02-04 (v2.0.0 - migrated to file-based) Compatibility: High portability (pattern is universal, file-based implementation is simple and portable) License: MIT
For users upgrading from Memento MCP:
Advantages of file-based:
Limitations of file-based:
Multi-agent orchestration patterns for delegation, coordination, and conflict resolution
Event Modeling facilitation methodology for event-sourced system design
Local task management using the dot CLI with file-based markdown storage, parent-child hierarchies, and blocking dependencies. Use when managing tasks, creating stories or epics, tracking work items, breaking down features, writing acceptance criteria, or querying task status. Triggers on: "create a task", "add a story", "break down this feature", "what's ready to work on", "show task status", "dot add", "dot ls", "dot ready", "dot tree", or any reference to the dot CLI or .dots/ directory.
Red-green-domain TDD cycle with strict phase boundaries and domain modeling review
Brad Frost's Atomic Design methodology for building UI component hierarchies
Systematic 4-phase debugging methodology for finding and fixing root causes