engram

A daily work journal with an immutable hashgraph backbone. Harvests your AI coding session history, summarizes it via Claude API, and commits each summary hash to a local Hedera Consensus Service (HCS) topic.

Run one command. Get a structured brief of what you worked on. Build a tamper-proof, cross-project work history that any AI agent can read.

How it works

engram digest
    |
    v
Read bookmark -> "what's new since last run?"
    |
    v
Harvest raw sessions from OpenCode (+ future tools)
    |
    v
Claude API: summarize into structured journal entry
    |
    v
Append to ~/.engram/journal/YYYY-MM-DD.md
    |
    v
Advance bookmark (no duplicates on next run)

Prerequisites

• Node.js 24.x
• pnpm
• One of:
  • A Claude Pro/Max subscription (free API usage via OAuth)
  • An Anthropic API key

Setup

# Clone and install
git clone git@github.com:adamcbrewer/engram.git
cd engram
pnpm install

# Initialize engram
pnpm dev init

Authentication

Choose one of two methods:

Option A: Claude Pro/Max subscription (recommended)

Uses your existing Anthropic subscription via OAuth — no API costs:

pnpm dev auth login

This opens a browser URL for Anthropic authorization. Paste the code back into the terminal. Tokens are stored in ~/.engram/auth.json (file permissions 600) and auto-refresh.

Option B: API key

cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

Check which method is active:

pnpm dev auth status

This creates ~/.engram/ with:

• config.json — harvester settings, summarizer model, etc.
• bookmark.json — created on first digest run
• journal/ — daily markdown files

Usage

Digest (main command)

Harvest new sessions, summarize, and append to today's journal:

pnpm dev digest

Preview what would be processed without writing anything:

pnpm dev digest --dry-run

Journal

Print today's journal:

pnpm dev journal

Print a specific day:

pnpm dev journal --date 2026-02-10

Status

Show bookmark state, last run, and detected harvesters:

pnpm dev status

Configuration

Edit ~/.engram/config.json to customize:

{
  "version": 1,
  "summarizer": {
    "model": "claude-sonnet-4-20250514",
    "apiKeyEnv": "ANTHROPIC_API_KEY"
  },
  "harvesters": {
    "opencode": {
      "enabled": true,
      "path": "~/.local/share/opencode/storage"
    },
    "claude-code": {
      "enabled": false,
      "path": "~/.claude/projects"
    }
  },
  "subagentMode": "flag"
}

Subagent handling

Controls how sub-sessions (e.g. OpenCode @explore) are processed:

• flag (default) — harvest as separate sessions with isSubagent: true
• inline — merge subagent messages into the parent session
• skip — ignore subagent sessions entirely

Authentication

Method	Setup	Cost
OAuth (Pro/Max)	engram auth login	Free (uses subscription)
API key	ANTHROPIC_API_KEY env var	Pay-per-use (~$0.01-0.05/digest)

OAuth is checked first. If no OAuth tokens are found, falls back to the API key env var.

Command	Description
pnpm dev auth login	Sign in with Claude Pro/Max
pnpm dev auth status	Show current auth method
pnpm dev auth logout	Remove stored OAuth tokens

Development

pnpm dev <command>       # run CLI via tsx (no build needed)
pnpm test                # run all tests
pnpm test -- --watch     # watch mode
pnpm run typecheck       # type check without emitting
pnpm run build           # compile to dist/
pnpm run format          # format with Prettier
pnpm run format:check    # check formatting (CI)

Project structure

bin/
  engram.ts              # CLI entry point
src/
  auth/                  # OAuth + API key authentication
  cli/                   # Commander command definitions
  harvesters/            # Pluggable harvester modules
  summarizer/            # Claude API summarization
  journal/               # Journal file writer
  hcs/                   # HCS client (Phase 2)
  lib/                   # Shared utilities
  types.ts               # Core interfaces

Data directory

~/.engram/
  config.json            # Settings
  auth.json              # OAuth tokens (permissions: 600)
  bookmark.json          # Dedup state (high-water marks per harvester)
  journal/
    YYYY-MM-DD.md        # Daily journal (append-only)
  rolling-context.md     # Agent-consumable work state (Phase 3)

Roadmap

• Phase 1 (current) — Core pipeline: OpenCode harvester, summarizer, journal writer
• Phase 2 — HCS integration: local Hedera node, hash chain, verification
• Phase 3 — Rolling context generation, cron automation
• Phase 4 — Polish, MCP server, npm publish

See docs/plan.md for detailed task tracking.

License

ISC