engram

Memory layer for AI coding agents. Stores context, extracts patterns, generates skills.

# Generate a skill from your Claude Code sessions
npx @4meta5/engram generate-skill --workspace . --output ./skills

What It Does

• Remembers context: Stores decisions, patterns, and gotchas from coding sessions
• Extracts patterns: Finds which files change together, common commands, error fixes
• Generates skills: Creates markdown skills from session history for Claude Code
• Searches semantically: Hybrid BM25 + vector search with RRF fusion

Packages

| Package | Path | npm | |---------|------|-----| | @4meta5/engram | . | | | @4meta5/semantic-memory | packages/semantic-memory | | | @4meta5/skill-generator | packages/skill-generator | |

Architecture

graph TD
    CLI["@4meta5/engram CLI"] --> SM["@4meta5/semantic-memory"]
    CLI --> SG["@4meta5/skill-generator"]
    SG --> Parsers["Session Parsers"]
    SG --> Extractors["Pattern Extractors"]
    SG --> Generators["Skill Generators"]
    SM --> SQLite["SQLite + FTS5"]
    Parsers --> CC["Claude Code"]
    Parsers --> OC["OpenClaw"]

Quick Start

CLI

# Install globally
npm install -g @4meta5/engram

# Generate a skill from Claude Code history
engram generate-skill --workspace /path/to/project --output ./skills

# Search memories
engram search "authentication flow"

# Add a memory manually
engram add "Use JWT for API auth, refresh tokens stored in httpOnly cookies"

# List recent sessions
engram sessions --days 7

Library

import { createMemoryStore, generateProjectSkill } from '@4meta5/engram';

// Memory storage
const store = createMemoryStore({ dbPath: './memory.db' });
await store.add('JWT tokens for auth', { topics: ['auth'] });
const results = store.searchBM25('authentication');

// Skill generation
const result = await generateProjectSkill('.', './skills', { days: 30 });
console.log(`Generated: ${result.skillPath}`);

CLI Reference

Core Commands (Stable)

| Command | Description | |---------|-------------| | search | Search memories | | add | Add a memory | | stats | Show memory statistics | | ingest-git | Ingest recent git log summaries into memory | | ingest-claude | Import Claude Code sessions | | sessions | List session history (Claude Code by default) | | generate-skill | Generate skill from session history |

Experimental Commands

| Command | Description | |---------|-------------| | summarize | Extract learnings with LLM (requires Claude Code OAuth) | | evaluate-skill | Check if sessions warrant skill generation | | mcp | Start MCP server over stdio | | ingest-openclaw | Import OpenClaw sessions |

Authentication (summarize only)

Both CLI and MCP use Claude Code OAuth credentials:

• macOS Keychain (Claude Code-credentials service)
• ~/.claude/.credentials.json (fallback)

If credentials are expired, they are refreshed automatically. If no credentials are found, open Claude Code and sign in.

OpenClaw Support

OpenClaw sessions are off by default. Use --openclaw flag to include:

engram generate-skill --workspace . --openclaw
engram summarize --workspace . --openclaw
engram sessions --source all  # or --source openclaw

Run engram <command> --help for options.

Memory Maintenance

Keep memory current with lightweight, decoupled workflows.

Ingest recent git activity

# Ingest recent commits from the current repo
engram ingest-git --days 30

Ingest multiple repos (helper script)

# From this repo
./scripts/ingest-git-all.sh /path/to/repo1 /path/to/repo2

Daily/Weekly Routine (Low Friction)

Drop this into your project README or team docs to make Engram stick:

### Engram Routine

**Daily (end of session):**
- `engram ingest-git --days 7`
- `engram add "one non-obvious learning" -t gotcha,decision,pattern`

**Before starting a task:**
- `engram search "your keywords"`

**Monthly (per project):**
- `engram generate-skill --workspace . --days 30 --output ./generated-skills`

For automation, use a scheduler (e.g. Heartbeat) to run ingest-git across repos weekly.

MCP Server (Experimental)

Expose Engram as a minimal MCP server over stdio.

engram mcp --workspace .

Available tools:

• engram.search — BM25 memory search
• engram.add — add a memory
• engram.stats — memory stats
• engram.ingestGit — ingest recent git log summary
• engram.summarize — summarize recent sessions (requires Claude Code OAuth)

engram.summarize inputs:

• days (number, default 30)
• minConfidence (number, default 0.5)
• includeOpenClaw (boolean, default false)
• openclawAgent (string, optional)

Optional error wrapper (for clients that prefer tool errors in result):

engram mcp --workspace . --wrap-errors

Without --wrap-errors, tool failures return { error, message } in the tool result.

Smoke test:

node ./scripts/mcp-smoke.js

Example MCP client config (stdio):

{
  "command": "node",
  "args": ["/absolute/path/to/engram/dist/cli.js", "mcp", "--workspace", "/path/to/project"]
}

Plan + rationale: docs/MCP_PLAN.md

Features

Semantic Memory (@4meta5/semantic-memory)

• BM25 full-text search with SQLite FTS5
• Optional vector search with embedding providers
• RRF fusion for hybrid ranking
• Pluggable storage backends

Skill Generator (@4meta5/skill-generator)

• Parses Claude Code and OpenClaw session formats
• Extracts file co-edits, tool sequences, error patterns
• Quality gates filter noise from learnings
• Trigger detection for automatic skill generation

Development

# Clone and install
git clone https://github.com/bobamatcha/engram.git
cd engram
npm install

# Build all packages
npm run build

# Run tests
npm test

# Run CLI in development
npm run cli -- generate-skill --help

Integration

This project powers the skill generation in 4meta5/skills-cli. Install skills-cli to manage Claude Code skills across projects.

License

MIT

Credits

Built by Patch, an AI, with Amar.