--- name: acfm-memory description: Autonomous memory system for persistent learning across sessions. Automatically saves architectural decisions, bugfixes, patterns, and insights. Use to recall context from previous work and build institutional knowledge. --- # AC Framework Memory System ## Overview The AC Framework Memory System provides **autonomous persistent memory** for AI agents. It automatically detects and saves valuable knowledge during development, then recalls relevant context when needed. **Key Capabilities:** - **Automatic saving**: Detects and stores important decisions, patterns, and solutions - **Full-text search**: Find relevant memories instantly - **Context recall**: Get relevant knowledge before starting tasks - **Pattern analysis**: Detect recurring themes and errors - **Timeline view**: See chronological context around any memory ## When to Use This Skill ### Before Starting Work - **Recall relevant context**: `acfm memory recall ""` - **Check for similar changes**: `acfm memory search ""` - **Review patterns**: `acfm memory patterns` ### During Work (Automatic) The agent automatically saves memories when: - Completing architectural proposals - Fixing bugs (especially after multiple attempts) - Refactoring code successfully - Optimizing performance - Discovering important patterns ### After Work - **Review learnings**: `acfm memory stats` - **Export for sharing**: `acfm memory export team-memory.json` - **Find gaps**: `acfm memory patterns --min-frequency 1` ## Memory Types | Type | Description | Auto-Trigger | |------|-------------|--------------| | `architectural_decision` | Major design decisions | After proposal/design | | `bugfix_pattern` | Solutions to bugs | After fixing error | | `refactor_technique` | Successful refactoring patterns | After refactor | | `performance_insight` | Optimization learnings | After performance work | | `security_fix` | Security vulnerability fixes | After security patch | | `api_pattern` | API design patterns | After API work | | `convention` | Project conventions | After establishing pattern | | `workaround` | Temporary solutions | After implementing hack | | `context_boundary` | System limitations | After defining boundaries | ## Commands ### Core Commands #### Initialize Memory System ```bash acfm memory init ``` Creates the SQLite database at `~/.acfm/memory.db`. #### Save Memory (Manual) ```bash acfm memory save "Descripción de la decisión o patrón" \ --type architectural_decision \ --importance high \ --tags "react,performance" ``` #### Recall Context ```bash # For specific task acfm memory recall "implementing authentication" # For current project (general context) acfm memory recall ``` #### Search Memories ```bash # Basic search acfm memory search "JWT" # Filtered search acfm memory search "database" --type architectural_decision --importance high ``` ### Advanced Commands #### Timeline View ```bash acfm memory timeline ``` Shows what happened before and after a specific memory. #### Connections ```bash acfm memory connections --depth 2 ``` Shows related memories as a graph. #### Pattern Detection ```bash acfm memory patterns acfm memory patterns --type bugfix_pattern ``` Finds recurring topics and frequent error types. #### Predictive Recall ```bash acfm memory anticipate "caching strategy" ``` Predicts which memories will be relevant for a future task. #### Statistics ```bash acfm memory stats acfm memory stats --project /path/to/project ``` #### Export/Import ```bash # Export for sharing acfm memory export team-memory.json # Import shared knowledge acfm memory import team-memory.json ``` ## Auto-Save Behavior ### What Triggers Auto-Save The agent evaluates content using a confidence score (0-1): **High confidence triggers (auto-save):** - Contains decision keywords: "decidimos", "optamos", "mejor usar" - Describes solution to problem - Contains architectural guidance - Has error + solution pair - Takes >10 minutes to resolve **Low confidence (skip):** - Very short content (<50 chars) - Contains specific IDs/UUIDs - Temporary TODOs - Obvious/common knowledge ### Confidence Scoring ``` Base: 0.5 + Decision keywords: +0.25 + Contains solution: +0.20 + Bug fix: +0.15 + Architecture: +0.20 + Optimization: +0.15 + Security: +0.25 - Too short: -0.20 - Specific IDs: -0.15 - TODO/FIXME: -0.20 Threshold for auto-save: 0.60 ``` ### Notification When auto-saving, the agent will display: ``` 💾 Memory saved: [Brief description of what was learned] Type: bugfix_pattern | Confidence: 85% ``` ## Privacy Content between `` tags is automatically redacted: ```markdown Decidimos usar AWS para hosting. Usaremos la cuenta producción-env-123 para el deployment. ``` Saved as: ``` Decidimos usar AWS para hosting. [REDACTED PRIVATE CONTENT] ``` ## Integration with Spec Workflow ### Before Creating Artifacts When you request `acfm spec instructions`, the system automatically: 1. Queries memories related to the change topic 2. Includes relevant memories in the response 3. Displays them as context for the agent Example output: ```json { "instruction": "...", "relevantMemories": [ { "id": 42, "type": "architectural_decision", "content": "Previous auth system used JWT...", "importance": "high" } ] } ``` ### During Apply Phase When implementing tasks, the system recalls: - Patterns from similar previous tasks - Bugfixes related to current work - Performance insights for optimization tasks ## Best Practices ### For Agents 1. **Always recall before starting**: Check `acfm memory recall` for relevant context 2. **Let auto-save work**: Don't manually save everything - trust the confidence scoring 3. **Use topic keys**: When manually saving, use consistent topic keys for deduplication 4. **Mark importance**: Critical decisions should be marked `critical` or `high` 5. **Add tags**: Tags improve searchability ### For Users 1. **Initialize once**: Run `acfm memory init` per machine 2. **Review periodically**: Check `acfm memory stats` to see what's been learned 3. **Export regularly**: Share knowledge with team via `acfm memory export` 4. **Prune old data**: Use `acfm memory prune` to archive obsolete memories 5. **Use private tags**: Mark sensitive content with `` tags ## Examples ### Example 1: Bug Fix **Agent fixes an authentication bug:** ``` 💾 Memory saved: JWT refresh token fails when expired during request Type: bugfix_pattern | Confidence: 87% Solution: Implement token refresh interceptor ``` **Later, similar task:** ```bash $ acfm memory recall "authentication token" → [Memory #42] JWT refresh token fails when expired... ``` ### Example 2: Architectural Decision **Agent completes proposal:** ``` 💾 Memory saved: Microservices architecture chosen for scalability Type: architectural_decision | Confidence: 92% Tags: ["architecture", "microservices", "scalability"] ``` **Weeks later, new service:** ```bash $ acfm memory search "microservices" --type architectural_decision → [Memory #15] Microservices architecture chosen for scalability ``` ### Example 3: Pattern Detection ```bash $ acfm memory patterns --type bugfix_pattern Detected patterns: - null-check-react (3×) - Null checks in React components - async-race-condition (2×) - Race conditions in async code - cors-preflight (2×) - CORS preflight issues Recommendation: Consider adding ESLint rules for null checks ``` ## Troubleshooting ### Memory not saving - Check initialization: `acfm memory init` - Content may be below confidence threshold - May contain too many specific IDs ### Search not finding results - Try broader keywords - Use `acfm memory recall` without query for general context - Check if memories exist: `acfm memory stats` ### Database locked - Close other instances of `acfm` - SQLite is single-writer; wait a moment and retry ## Related Skills - `acfm-spec-workflow` - Foundation for spec-driven development - `context-synthesizer` - For managing context in long conversations - `systematic-debugging` - For complex problem resolution ## CLI Reference See `acfm memory --help` for all commands and options. --- **Remember**: The memory system learns from every interaction. The more you use it, the more valuable it becomes.