Engram Summarize

Extract structured learnings from Claude Code and OpenClaw session history using LLM-based summarization.

When to Use

• After completing significant work on a project
• Before onboarding someone new to a codebase
• Periodically to capture accumulated knowledge
• When you want to distill decisions and patterns

What It Extracts

| Category | Description | Example | |----------|-------------|---------| | decision | Architectural and design choices | "Chose SQLite over PostgreSQL for local CLI" | | pattern | Code patterns and idioms | "Uses Result<T, E> for error handling" | | gotcha | Things that went wrong and fixes | "index.json must sync with posts/" | | convention | Project-specific norms | "Tests colocated with source files" | | context | Background knowledge | "This is a Rust 2021 edition project" |

Workflow

Step 1: Set up API key

export ANTHROPIC_API_KEY=your-key

Step 2: Summarize sessions

# Summarize last 30 days for current workspace
npx engram summarize --workspace . --days 30

# Save to file
npx engram summarize --workspace . -o learnings.json

# Higher confidence threshold
npx engram summarize --workspace . --min-confidence 0.7

Step 3: Review learnings

The output includes:

• Session count processed
• Learnings by category
• Top learnings ranked by confidence

Example output:

📊 Summary:
  Sessions: 12
  Learnings: 23

  By category:
    Decisions:   5
    Patterns:    8
    Gotchas:     4
    Conventions: 3
    Context:     3

📝 Top learnings:
  [gotcha] Blog index.json must be updated when posts are renamed
  [pattern] All exports go through index.ts barrel files
  [decision] Used vitest over jest for faster test execution

Step 4: Integrate with skill generation

Use summarized learnings to enhance generated skills:

# Generate skill with richer context
npx engram generate-skill --workspace . --days 30

CLI Options

| Option | Description | Default | |--------|-------------|---------| | -w, --workspace <path> | Workspace to filter sessions | . | | -d, --days <number> | Days of history to analyze | 30 | | --no-openclaw | Exclude OpenClaw sessions | include | | -a, --agent <id> | OpenClaw agent ID filter | all | | -c, --min-confidence <n> | Confidence threshold (0-1) | 0.5 | | -o, --output <path> | Save learnings to JSON file | stdout | | --json | Output as JSON | pretty print |

Integration with Other Skills

| Skill | When to Combine | |-------|-----------------| | engram-generate | Summarize before generating for richer skills | | engram-recall | Recall + summarize for full context | | describe-codebase | Add summarized learnings to codebase description |

Comparison: Generate vs Summarize

| Aspect | engram-generate | engram-summarize | |--------|-----------------|------------------| | Method | Pattern matching | LLM extraction | | Output | Structural patterns | Semantic learnings | | Cost | Free (local) | API tokens | | Depth | File co-edits, commands | Decisions, rationale |

Use both together for best results:

1. summarize extracts the meaning
2. generate captures the structure

Example Learnings

{
  "learnings": [
    {
      "category": "gotcha",
      "summary": "Blog index.json must be updated when posts are renamed",
      "detail": "The blog uses a static index.json. Renaming a post without updating causes 404 errors.",
      "files": ["index.json", "posts/*.md"],
      "confidence": 0.95
    },
    {
      "category": "decision", 
      "summary": "Chose TypeScript for type safety",
      "confidence": 0.85
    }
  ]
}

Important

• Requires ANTHROPIC_API_KEY environment variable
• Uses Claude Sonnet for extraction (cost-effective)
• Review learnings before sharing (may contain sensitive info)
• Higher confidence threshold reduces noise but may miss insights