majiayu000 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:
summarizeextracts the meaninggeneratecaptures 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_KEYenvironment 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