b4san/acfm-memory

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 "<task description>"
• Check for similar changes: acfm memory search "<topic>"
• 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

acfm memory init

Creates the SQLite database at ~/.acfm/memory.db.

Save Memory (Manual)

acfm memory save "Descripción de la decisión o patrón" \
  --type architectural_decision \
  --importance high \
  --tags "react,performance"

Recall Context

# For specific task
acfm memory recall "implementing authentication"

# For current project (general context)
acfm memory recall

Search Memories

# Basic search
acfm memory search "JWT"

# Filtered search
acfm memory search "database" --type architectural_decision --importance high

Advanced Commands

Timeline View

acfm memory timeline <memory-id>

Shows what happened before and after a specific memory.

Connections

acfm memory connections <memory-id> --depth 2

Shows related memories as a graph.

Pattern Detection

acfm memory patterns
acfm memory patterns --type bugfix_pattern

Finds recurring topics and frequent error types.

Predictive Recall

acfm memory anticipate "caching strategy"

Predicts which memories will be relevant for a future task.

Statistics

acfm memory stats
acfm memory stats --project /path/to/project

Export/Import

# 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 <private> tags is automatically redacted:

Decidimos usar AWS para hosting. <private>Usaremos la cuenta
producción-env-123</private> 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:

{
  "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 <private> 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:

$ 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:

$ acfm memory search "microservices" --type architectural_decision
→ [Memory #15] Microservices architecture chosen for scalability

Example 3: Pattern Detection

$ 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.