Engram

Persistent memory, safety hooks, and code intelligence for AI agents.

By Easy Labs | Inspired by LACP by @0xNyk

What Is Engram?

Engram gives AI agents memory that persists between sessions, guardrails that block dangerous operations, and a knowledge graph that grows over time. Every session starts with institutional context and ends with an auditable provenance trail.

10 MCP tools for in-session use. ~20 CLI commands for management. Works with Claude Code, OpenClaw, and compatible agent runtimes.

Core Capabilities

Area	What It Does
Memory	Per-project session memory, fact promotion, daily capture, semantic search via QMD
Safety	16 guard rules, 7 safety profiles, risk-based policy routing, cost ceilings
Knowledge	Obsidian-backed graph, wikilinks, curator maintenance, vault doctor
Ingestion	Transcripts, URLs, PDFs, video/audio (ffmpeg + Whisper)
Code Intelligence	Dead code detection, blast radius, hotspots, architecture analysis via GitNexus
Provenance	SHA-256 hash-chained receipts for every session
Maintenance	Workspace cleanup, bloat detection, stray file analysis

Quick Start

# Install
npm install -g @easylabs/engram

# Setup
engram wizard       # Interactive setup
engram doctor       # Verify installation

# Uninstall (preserves vault data)
engram uninstall

Alternative install methods

# One-shot (no install)
npx @easylabs/engram

# From source
git clone https://github.com/itseasyco/engram
cd engram && bash INSTALL.sh

Prerequisites

Requirement	Version	Notes
Node.js	>= 22	CLI and wizard
Python	>= 3.9	Hooks and lib modules
QMD	required	Semantic search — installed by wizard
Obsidian	optional	Knowledge graph vault
ffmpeg	optional	Video/audio ingestion
GitNexus	optional	Code intelligence

How Memory Works

Engram implements a 5-layer memory system. Each layer builds on the previous one.

                      ┌─────────────────────────┐
                      │   Layer 5: Provenance    │  SHA-256 hash chains
                      ├─────────────────────────┤
                      │  Layer 4: Code Intel     │  AST, call graphs, impact
                      ├─────────────────────────┤
                      │  Layer 3: Ingestion      │  Video, audio, PDFs, URLs
                      ├─────────────────────────┤
                      │  Layer 2: Knowledge      │  Obsidian vault + QMD
                      ├─────────────────────────┤
                      │  Layer 1: Session Memory │  Per-project, daily files
                      └─────────────────────────┘

The Lifecycle

Agent works → Session memory accumulates (Layer 1)
                    ↓
           Facts get promoted (scored, categorized, deduplicated)
                    ↓
           Knowledge indexed in vault/graph (Layer 2)
                    ↓
           Session saved to daily structure
                    ↓
           Next session starts → session-start hook injects
           top facts + git context → Agent has institutional memory

Session Auto-Capture

A managed hook fires on /new and /reset in OpenClaw. It reads the transcript, extracts decisions and facts, writes a per-agent session file, and updates the daily index.

CLI Reference

System

Command	Description
`engram wizard`	Interactive setup (arrow-key UI)
`engram wizard --section <name>`	Run specific section: vault, engine, profile, mode, guard, dependencies
`engram status`	System overview
`engram doctor`	Full diagnostics across all 5 layers
`engram uninstall [--yes]`	Remove Engram (preserves vault data)

Memory

Command	Description
`engram memory query <topic>`	Search memory for facts
`engram memory promote`	Promote session facts to persistent memory
`engram memory status`	Memory system dashboard

Guard

Command	Description
`engram guard rules`	List all rules with status
`engram guard blocks`	Recent blocks from audit log
`engram guard toggle <id>`	Enable/disable a rule
`engram guard level <id> <level>`	Set block level (block/warn/log)
`engram guard allow "<cmd>"`	Add to allowlist
`engram guard deny "<cmd>"`	Remove from allowlist
`engram guard config`	Interactive configuration
`engram guard defaults --level <level>`	Set global default
`engram guard reset`	Factory defaults

Vault

Command	Description
`engram vault status`	Vault health and statistics
`engram vault audit`	Full audit (broken links, orphans)
`engram vault backup`	Backup vault
`engram vault restore`	Restore from backup
`engram vault optimize`	Apply memory-centric graph physics
`engram vault kpi`	Quality KPIs (fact count, staleness, contradictions)
`engram vault heal [--dry-run]`	Scan orphans, fix frontmatter, rename hash files
`engram vault migrate <path> [--dry-run]`	Structure migration with wikilink preservation

Brain

Command	Description
`engram brain expand`	Re-summarize, deduplicate, compress
`engram brain expand --consolidate`	Mycelium consolidation pass
`engram brain expand --curator-cycle`	Full 8-step curator maintenance
`engram brain resolve`	Resolve contradictions in knowledge notes
`engram brain code`	AST analysis, symbol lookup, call graphs
`engram brain graph`	Initialize, index, and query the knowledge graph

Code

Command	Description
`engram code report [--repo <name>]`	Full code health report (strengths, improvements, issues)
`engram code dead-code [--repo <name>]`	Find exported functions with no callers
`engram code hotspots [--repo <name>]`	Find files with too many functions
`engram code blast-radius [--repo <name>]`	Find functions with the most callers
`engram code orphans [--repo <name>]`	Find source files nothing imports
`engram code architecture [--repo <name>]`	Architecture cluster analysis

All code commands support --output <path> to save the report to a file and --all to run across all indexed repos.

Ingest

Command	Description
`engram ingest transcript <source>`	Ingest a text transcript
`engram ingest url <source>`	Ingest a web page
`engram ingest pdf <source>`	Ingest a PDF document
`engram ingest file <source>`	Ingest a markdown/text file
`engram ingest video <source>`	Ingest video (ffmpeg + Whisper)
`engram ingest video-batch <dir>`	Batch-process a directory of videos
`engram ingest audio <source>`	Ingest audio (ffmpeg + Whisper)

Agent

Command	Description
`engram agent create`	Scaffold a new agent workspace from templates

Maintenance

Command	Description
`engram tune-up [--dry-run]`	Workspace cleanup: bloat, stray files, old logs
`engram tune-up --agent <name>`	Clean a specific agent workspace
`engram repo init`	Generate repositories.json from GitNexus registry

MCP Tools

10 tools exposed via the Model Context Protocol for in-session use by agents.

Tool	What It Does
`engram_memory_query`	Query session memory and facts with semantic search
`engram_promote_fact`	Promote an observation to persistent scored fact
`engram_ingest`	Ingest transcripts, URLs, PDFs, files, video, audio
`engram_guard_status`	Check guard rules, recent blocks, allowlists
`engram_vault_status`	Vault health, note counts, index freshness
`engram_graph_index`	Trigger knowledge graph re-indexing
`engram_brain_resolve`	Resolve contradictions in knowledge notes
`engram_memory_kpi`	Memory KPIs: fact count, schema coverage, staleness
`engram_vault_optimize`	Apply graph physics defaults (link distance, repel, colors)
`engram_save_session`	Save session to daily folder with per-agent files

Safety Profiles

Seven profiles control which hooks fire and how.

Profile	What's Enabled	Use Case
autonomous	All hooks — warn only, never block	Unattended operation, daily driver
balanced	session-start, quality-gate	General development (default)
context-only	session-start only	Lightest touch — just inject context
guard-rail	pretool-guard, quality-gate	Safety without context overhead
minimal-stop	quality-gate only	Low-risk development
hardened-exec	All hooks — all block	Production deploys, high-stakes work
full-audit	All hooks — block + verbose logging	Compliance, audit trails

Set during install or change in ~/.openclaw/extensions/engram/config/.engram.env.

Guard System

The pretool-guard intercepts commands before execution and checks them against configurable rules.

How It Works

Agent attempts a command (e.g., npm publish)
Command checked against allowlists first (global + repo-specific)
If no allowlist match, checked against enabled rules via regex
Block level resolved: repo override > rule-specific > global default
Action taken: block (reject), warn (log + proceed), or log (silent)
Every match written to guard-blocks.jsonl for audit

Built-in Rules (16)

Category	Rules
Destructive	npm/yarn/pnpm/cargo publish, curl pipe to interpreter, chmod 777, git reset --hard, git clean -f, docker --privileged, fork bombs, scp/rsync to /root, data exfiltration
Protected Paths	.env files, config.toml, secrets/, .claude/settings.json, authorized_keys, .pem/.key files, .gnupg/

Per-Repo Overrides

{
  "repo_overrides": {
    "/path/to/my-repo": {
      "block_level": "warn",
      "rules_override": { "npm-publish": { "enabled": false } },
      "command_allowlist": [
        { "pattern": "docker run --privileged", "reason": "CI builds" }
      ]
    }
  }
}

Video & Audio Ingestion

Engram ingests media files via ffmpeg + insanely-fast-whisper.

engram ingest video ./meeting.mp4 --speaker "Team Standup" --date "2026-03-23"
engram ingest audio ./voice-memo.mp3 --title "Architecture Discussion"
engram ingest video-batch ./recordings/ --date-from-filename --parallel 4

Hardware	~Time for 1h Audio	Notes
NVIDIA A100 / 4090	~1 min	Best performance
NVIDIA T4 / 3060	~3-5 min	`--batch-size 12` if OOM
Apple Silicon	~5-10 min	Auto-sets `--device-id mps`
CPU only	~20-40 min	Use `openai-whisper` instead

Whisper installation

pipx install insanely-fast-whisper==0.0.15 --force --pip-args="--ignore-requires-python"

Knowledge Graph Structure

The Obsidian vault follows the Engram taxonomy:

vault/
  home/           Master index
  memory/         Daily session memory (YYYY-MM-DD/)
  projects/       Per-repo knowledge
  engineering/    Architecture, decisions, active work
  knowledge/      Concepts, learnings
  inbox/          Incoming notes awaiting processing
  reference/      External docs, API references
  people/         Team members, contacts
  archive/        Deprecated content
  _metadata/      Vault config, taxonomy

Curator Maintenance Cycle

The curator runs 8 steps: inbox processing, mycelium consolidation, wikilink weaving, staleness scan, conflict resolution, schema enforcement, index update, and health report.

engram brain expand --curator-cycle

Using with Claude Code

Two hooks can be wired directly into Claude Code via ~/.claude/settings.json:

{
  "hooks": {
    "session_initialization": [{
      "command": "python3 ~/.openclaw/extensions/engram/plugin/hooks/handlers/session-start.py",
      "timeout": 10000
    }],
    "agent_stop": [{
      "command": "python3 ~/.openclaw/extensions/engram/plugin/hooks/handlers/stop-quality-gate.py",
      "timeout": 5000
    }]
  }
}

Hook	Platform	Status
`session-start`	Claude Code + OpenClaw	Injects git context + memory
`stop-quality-gate`	Claude Code + OpenClaw	Catches premature stops
`pretool-guard`	OpenClaw only	Intercepts tool calls
`write-validate`	OpenClaw only	Validates file writes

Configuration

File	Purpose
`~/.openclaw/extensions/engram/config/.engram.env`	Plugin config (set by wizard)
`~/.openclaw/extensions/engram/config/guard-rules.json`	Guard rules, allowlists, overrides

Key Properties

Property	Default	Description
`profile`	`balanced`	Safety profile
`obsidianVault`	`~/obsidian/vault`	Path to knowledge vault
`codeGraphEnabled`	`false`	AST analysis, call graphs
`provenanceEnabled`	`true`	Hash-chained receipts
`contextEngine`	`null`	`lossless-claw` for LCM integration
`promotionThreshold`	`70`	Minimum score for auto-promotion (0-100)

Dependencies

Dependency	Required	What It Enables
QMD	Yes	Semantic search, memory backend
poppler (pdftotext)	Yes	PDF text extraction
ffmpeg	No	Video/audio processing
insanely-fast-whisper	No	GPU-accelerated transcription
GitNexus	No	Code intelligence (AST, call graphs)
lossless-claw	No	LCM SQLite context engine
obsidian-headless (ob)	No	Multi-machine vault sync

Troubleshooting

"plugin not found"

Check that package.json exists in the plugin directory with "openclaw": { "extensions": ["./index.ts"] } and the gateway config has the entry under plugins.installs.

"missing register/activate export"

The index.ts must export a default object with a register(api) method.

SDK not found

The installer creates a symlink at ~/.openclaw/extensions/engram/node_modules/openclaw. If missing:

ls ~/.openclaw/extensions/*/node_modules/openclaw
ln -s <detected_path> ~/.openclaw/extensions/engram/node_modules/openclaw

Hooks not showing in `openclaw hooks list`

Expected behavior. Engram registers hooks as lifecycle listeners via api.on(), not as standalone hooks. Run engram doctor to verify.

General fix: engram doctor to diagnose, engram wizard to reconfigure.

Coming Soon

Connected mode — engram connect / engram disconnect for shared vaults
Connectors — GitHub, Slack, Email, filesystem, webhooks, cron fetching
File watcher — engram watch for auto-ingestion of new files
Obsidian-headless sync — Multi-machine vault sync via ob CLI

Contributing

Repo Structure

engram/
  package.json                 @easylabs/engram
  openclaw.plugin.json         Plugin manifest
  INSTALL.sh                   Install script
  bin/
    engram                     Main CLI router (bash)
    wizard.mjs                 Interactive wizard (@clack/prompts)
  plugin/
    index.ts                   Gateway entry point (hook + tool registration)
    bin/                       CLI tools (engram-*)
    config/                    Guard rules, example configs
    hooks/
      handlers/                Python hook scripts
      managed/                 Auto-capture hook
      profiles/                7 safety profile JSONs
    lib/                       Python modules
      mycelium.py              Spreading activation, FSRS memory model
      curator.py               8-step curator maintenance cycle
      vault_doctor.py          Orphan scan, frontmatter fix
      vault_migrate.py         Vault structure migration
      connectors/              GitHub, Slack, Email, filesystem, webhook, cron
    templates/
      agent-template/          Agent workspace scaffolding

Running Tests

cd plugin && python -m pytest -v               # All tests
cd plugin && python -m pytest hooks/tests/ -v   # Hook tests
cd plugin && python -m pytest lib/tests/ -v     # Lib tests

License

MIT

Name		Name	Last commit message	Last commit date
.claude/skills/gitnexus		.claude/skills/gitnexus
.github		.github
bin		bin
plugin		plugin
.gitignore		.gitignore
.npmignore		.npmignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
INSTALL.sh		INSTALL.sh
LICENSE		LICENSE
README.md		README.md
SETUP.md		SETUP.md
openclaw.plugin.json		openclaw.plugin.json
package.json		package.json
plugin.json		plugin.json
pnpm-lock.yaml		pnpm-lock.yaml

Latest commit

History

Folders and files

Repository files navigation

Engram

What Is Engram?

Core Capabilities

Quick Start

Prerequisites

How Memory Works

The Lifecycle

Session Auto-Capture

CLI Reference

System

Memory

Guard

Vault

Brain

Code

Ingest

Agent

Maintenance

MCP Tools

Safety Profiles

Guard System

How It Works

Built-in Rules (16)

Per-Repo Overrides

Video & Audio Ingestion

Knowledge Graph Structure

Curator Maintenance Cycle

Using with Claude Code

Configuration

Key Properties

Dependencies

Troubleshooting

Coming Soon

Contributing

Repo Structure

Running Tests

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages