@easylabs/engram

Engram

By Easy Labs

Persistent agent memory, mycelium-powered knowledge graph, safety hooks, code intelligence, provenance tracking, and video/audio ingestion. 10 MCP tools for Claude Code and compatible agents.

Inspired by LACP by @0xNyk — the original local agent context protocol that showed agents could have persistent memory.

Overview

Engram brings persistent agent memory into your development workflow. It gives your agents session memory that survives across conversations, a knowledge graph backed by Obsidian, safety hooks that block dangerous operations before they execute, and a hash-chained provenance trail for every session.

The plugin implements a 5-layer memory system: per-project session memory with daily structure, an Obsidian-backed knowledge graph with QMD semantic search, an ingestion pipeline for external content (including video and audio via insanely-fast-whisper), AST-level code intelligence, and cryptographic provenance receipts. These layers work together so that every agent session starts with institutional context and ends with auditable evidence of what happened.

Engram is for teams and individuals who run agents on real codebases and need guardrails (blocking npm publish, git reset --hard, secrets access), persistent memory (facts that carry between sessions), and a clear audit trail. It is local-first by default -- all data stays on your machine.

Key capabilities:

• Execution hooks (session context injection, pretool guard, quality gate, write validation)
• Risk-based policy routing with three tiers (safe / review / critical) and cost ceilings
• Per-project session memory with daily folder structure and per-agent session files
• Session auto-capture hook (fires automatically on /new and /reset)
• Obsidian-backed knowledge graph with QMD semantic search
• Video and audio ingestion via ffmpeg + insanely-fast-whisper transcription
• Vault doctor: scan orphans, fix frontmatter, add tags, rename hash files
• Vault migration tool for restructuring existing vaults into Engram-compatible layout
• 8-step curator maintenance cycle (inbox processing, consolidation, wikilinks, staleness, conflicts, schema, index, health)
• Code intelligence via AST analysis, call graphs, and impact analysis
• Cryptographic provenance tracking (SHA-256 hash-chained receipts)
• Multi-agent memory sharing with role-based access
• Configurable safety profiles from autonomous to full-audit
• 10 MCP tools for memory query, fact promotion, ingestion, guard status, vault management, graph indexing, brain resolution, memory KPIs, vault optimization, and session saving
• 30 CLI tools for managing memory, guard rules, ingestion, vault health, and more
• Node.js interactive wizard with arrow-key navigation (powered by @clack/prompts)

Quick Start

Prerequisites

Requirement	Version	Notes
OpenClaw	>= 0.23.0	Core runtime
Node.js	>= 22	CLI and wizard
Python	>= 3.9	Hook handlers and lib modules
Bash	>= 4.0	CLI tools are bash/python scripts
QMD	required	Semantic search and memory backend — installed by wizard
Obsidian	(optional)	Knowledge graph vault (Layer 2)
ffmpeg	(optional)	Video/audio ingestion (Layer 3)
insanely-fast-whisper	(optional)	GPU-accelerated audio transcription

Install

Global install (recommended):

npm install -g @easylabs/engram

One-shot (no install):

npx @easylabs/engram

From the repo:

git clone https://github.com/itseasyco/engram
cd engram
bash INSTALL.sh

First-time Setup

Run the setup wizard:

engram wizard

The wizard uses a Node.js interactive UI (powered by @clack/prompts) with arrow-key navigation. It walks you through:

• Obsidian vault -- auto-detects vaults on your system, or type/browse to a path
• Context engine -- choose lossless-claw (native LCM integration) or file-based (default)
• Safety profile -- pick from 7 profiles (see Safety Profiles)
• Operating mode -- standalone, connected, or curator
• Guard configuration -- block levels, rule toggling, allowlists
• Dependencies -- GitNexus, lossless-claw, obsidian-headless checks

The wizard outputs config to a temp file that INSTALL.sh consumes to complete installation. If Node.js is unavailable, it falls back to legacy bash prompts.

After install, verify:

engram doctor

Uninstall

engram uninstall

This removes the plugin extension directory, managed hooks, and gateway config entries. Vault data and LACP memory files are preserved. Pass --yes to skip confirmation.

MCP Tools (10 tools)

Engram exposes 10 tools via the Model Context Protocol that agents can call directly during sessions.

Tool	Description
engram_memory_query	Query session memory and LACP facts with semantic search (uses QMD when available)
engram_promote_fact	Promote a session observation to persistent scored fact
engram_ingest	Ingest transcripts, URLs, PDFs, files, video, and audio into the knowledge graph
engram_guard_status	Check guard rule status, recent blocks, and allowlist entries
engram_vault_status	Report on Obsidian vault health, note counts, and index freshness
engram_graph_index	Trigger knowledge graph re-indexing with optional QMD semantic search
engram_brain_resolve	Resolve a query against contradictions/supersessions in knowledge notes
engram_memory_kpi	Return memory system KPIs: fact count, schema coverage, staleness, contradictions
engram_vault_optimize	Apply memory-centric graph physics defaults (link distance, repel, node sizing, color groups)
engram_save_session	Save session memory to daily folder structure with per-agent session files

How the Memory System Works

Engram implements a continuous memory lifecycle across agent sessions. Understanding this cycle is key to getting the most out of the plugin.

The Five Layers

Layer 1: Session Memory     ~/.openclaw/projects/<slug>/memory/
Layer 2: Knowledge Graph    ~/obsidian/vault/ (Obsidian + QMD)
Layer 3: Ingestion Pipeline engram ingest (transcripts, URLs, PDFs, video, audio)
Layer 4: Code Intelligence  engram brain code (AST, call graphs, impact)
Layer 5: Provenance         ~/.openclaw/provenance/ (hash-chained receipts)

The Memory Lifecycle

  Agent works on a task
       |
       v
  Session memory accumulates (Layer 1)
  Per-project data in ~/.openclaw/projects/<slug>/memory/
       |
       v
  Facts get promoted to persistent memory (engram_promote_fact)
  Scored, categorized, deduplicated
       |
       v
  Knowledge gets indexed in vault/graph (Layer 2)
  Organized into projects / engineering / knowledge / inbox
       |
       v
  Session saved to daily structure (engram_save_session or auto-capture hook)
  vault/memory/YYYY-MM-DD/<agent-id>-<session>.md
       |
       v
  Next session starts
  session-start hook fires (Layer 1 + 2)
  Injects top relevant facts + git context into the agent's system message
       |
       v
  Agent has institutional memory from previous sessions

1. Session Memory

Every project gets its own memory directory at ~/.openclaw/projects/<slug>/memory/. The session-start hook reads the current git context (branch, recent commits, modified files) and injects it as a system message when a new session begins. Execution results -- cost, gate decisions, exit codes, learnings -- are appended via engram memory append.

2. Session Auto-Capture Hook

Engram includes a managed hook (engram-session-capture) that fires automatically when you issue /new or /reset in OpenClaw. It:

• Reads the session transcript (last N messages)
• Extracts key decisions, tasks completed/pending, and notable facts
• Writes a per-agent session file to vault/memory/YYYY-MM-DD/
• Updates the daily index with wikilinks

No agent action needed -- capture happens as a side effect of ending a session.

3. Daily Session Memory Structure

Session memory is organized into a daily folder structure for easy browsing and automatic indexing:

vault/memory/
  2026-03-24/
    agent-a1b2c3-session-001.md
    agent-a1b2c3-session-002.md
    agent-d4e5f6-session-001.md
    _daily-index.md              # Auto-generated summary of all sessions that day
  2026-03-23/
    agent-a1b2c3-session-001.md
    _daily-index.md

Each session file contains the agent ID, project slug, start/end timestamps, key facts discovered, commands run, and a session summary. The _daily-index.md is auto-generated and links to all session files for that day.

4. Persistent Facts

Persistent facts are extracted from session data and stored via engram memory context. Facts have scores, categories, and timestamps. The engram_promote_fact tool handles promotion from raw session summaries to scored, persistent facts. Deduplication prevents redundant facts from accumulating. Confidence calibration tunes promotion thresholds over time.

5. Knowledge Graph

The Obsidian vault is organized into the Engram taxonomy:

vault/
  home/           # Master index, vault overview
  memory/         # Daily session memory (YYYY-MM-DD folders)
  projects/       # Per-repo/per-project knowledge
  engineering/    # Architecture, decisions, active work
  knowledge/      # Concepts, learnings, agent knowledge
  inbox/          # Incoming notes awaiting curator processing
    queue-agent/    # Agent-submitted facts
    queue-cicd/     # CI/CD events
    queue-human/    # Human-submitted (email, voice notes, research)
    queue-session/  # Auto-captured session memories (connected mode)
    review-stale/   # Curator-flagged for review
  reference/      # External docs, API references
  people/         # Team members, contacts
  health/         # Personal/team health tracking
  strategy/       # Business strategy, planning
  archive/        # Archived/deprecated content
  _metadata/      # Vault config, taxonomy

engram brain graph initializes and indexes the vault. engram vault manages vault status, backups, and optimization. QMD provides semantic search across the vault when available.

6. Vault Doctor

The vault doctor scans every note in your vault and fixes what it can:

• Find orphans (notes with zero backlinks)
• Add/fix YAML frontmatter (title, category, tags, dates, status)
• Auto-detect tags from content (#PRD, #research, #architecture, #meeting, etc.)
• Rename hash-named files to prose-style titles
• Detect category and suggest/execute moves to correct folders
• Run wikilink weaver to connect orphans

engram brain heal
engram brain heal --dry-run    # Preview changes without writing

7. Vault Migration

For existing vaults that need restructuring into the Engram-compatible layout, the vault migration tool scans your vault, proposes a clean structure, and migrates files with wikilink preservation:

# Preview migration plan
python3 plugin/lib/vault_migrate.py /path/to/vault --dry-run

# Execute migration
python3 plugin/lib/vault_migrate.py /path/to/vault

8. Lossless Context Integration

When contextEngine is set to lossless-claw, the plugin integrates with the LCM (Lossless Context Manager) backend. LCM's DAG compaction works alongside Engram's fact injection: LCM compresses conversational context while Engram injects curated facts at session start. The two systems are complementary -- LCM handles within-session context efficiency, while Engram handles cross-session knowledge persistence.

Configure the integration in your plugin config:

{
  "contextEngine": "lossless-claw",
  "lcmQueryBatchSize": 50,
  "promotionThreshold": 70,
  "autoDiscoveryInterval": "6h"
}

Safety Profiles

Seven profiles control which hooks fire and how they behave.

Profile	Hooks Enabled	Block Behavior	Use Case
autonomous	session-start, pretool-guard, stop-quality-gate, write-validate	All hooks warn but never block; agent keeps working	Daily driver, autonomous agents, unattended operation
balanced	session-start, stop-quality-gate	No guard or write validation	General development, moderate-risk tasks (default)
context-only	session-start	No safety gates at all	Lightest touch, just inject git context
guard-rail	pretool-guard, stop-quality-gate	Blocks dangerous commands, catches incomplete work	Safety without context injection overhead
minimal-stop	stop-quality-gate	Only detects premature agent stops	Low-risk development and testing
hardened-exec	session-start, pretool-guard, stop-quality-gate, write-validate	All hooks block; violations require explicit approval	Production deploys, high-stakes work
full-audit	session-start, pretool-guard, stop-quality-gate, write-validate	All hooks block; verbose logging; full provenance	Compliance, audit trails, debugging hook behavior

Set the profile during install or change it later in ~/.openclaw/extensions/engram/config/.engram.env.

Guard System

The pretool-guard hook intercepts tool calls before execution and checks them against a configurable set of rules.

How It Works

• The agent attempts to run a command (e.g., npm publish)
• pretool-guard.py loads guard-rules.json (mtime-cached for performance)
• The command is checked against allowlists first (global + repo-specific) -- if matched, it passes
• Then checked against all enabled rules via regex patterns
• For a matched rule, the block level is resolved: repo override > rule-specific > global default
• Action is taken based on block level:
  • block -- command is rejected (exit 1)
  • warn -- warning is logged, command proceeds (exit 0)
  • log -- silently logged, command proceeds (exit 0)
• Every match is written to guard-blocks.jsonl for audit

Built-in Rules (16 rules)

The guard ships with rules for common dangerous patterns:

Rule ID	Pattern	Category
npm-publish	npm/yarn/pnpm/cargo publish	destructive
curl-pipe-interpreter	curl | python, wget | node, etc.	destructive
chmod-777	chmod 777 (overly permissive)	destructive
git-reset-hard	git reset --hard	destructive
git-clean-force	git clean -f	destructive
docker-privileged	docker run --privileged	destructive
fork-bomb	Fork bomb pattern	destructive
scp-rsync-root	scp/rsync to /root	destructive
data-exfiltration	curl --data @.env, @.ssh, etc.	destructive
env-files	.env file access	protected-path
config-toml	config.toml access	protected-path
secrets-directory	secrets/ directory access	protected-path
claude-settings	.claude/settings.json	protected-path
authorized-keys	authorized_keys	protected-path
pem-key-files	.pem, .key files	protected-path
gnupg-directory	.gnupg/ directory	protected-path

Global Defaults vs Per-Repo Overrides

Global defaults are in guard-rules.json under defaults. Per-repo overrides let you relax or tighten rules for specific repositories:

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

Using engram guard

# List all rules with their status
engram guard rules

# View recent blocks from the log
engram guard blocks
engram guard blocks --tail 20

# Enable or disable a rule
engram guard toggle npm-publish

# Set block level for a specific rule
engram guard level git-reset-hard warn

# Add a command to the global allowlist
engram guard allow "git reset --hard HEAD~1" --reason "Common dev workflow"

# Add a repo-specific allowlist entry
engram guard allow "docker run --privileged" --repo /path/to/ci-repo --reason "CI builds"

# Remove a command from all allowlists
engram guard deny "git reset --hard HEAD~1"

# Interactive configuration
engram guard config

# Configure overrides for a specific repo
engram guard config --repo /path/to/my-repo

# Set global default block level
engram guard defaults --level warn

# Reset to factory defaults
engram guard reset

Automation & Ingestion

Engram supports multiple patterns for getting external data into the knowledge graph, including text, documents, and video/audio media.

1. Webhook to Agent to Ingest

A webhook receives meeting data and feeds transcripts to the agent for processing:

# Webhook handler receives a transcript file, then:
engram ingest transcript ~/obsidian/vault /tmp/meeting-2026-03-21.txt \
  --speaker "Alice" --date "2026-03-21"

The transcript is converted into a structured Obsidian note with metadata and placed in the inbox/queue-generated/ directory.

2. Video and Audio Ingestion

Engram can ingest video and audio files by extracting audio via ffmpeg and transcribing with Whisper. Supported formats include mp4, mov, mkv, wav, mp3, m4a, flac, ogg, and more.

# Ingest a single video file
engram ingest video ~/obsidian/vault ./meeting-recording.mp4 \
  --speaker "Team Standup" --date "2026-03-23"

# Ingest a single audio file
engram ingest audio ~/obsidian/vault ./voice-memo.mp3 \
  --title "Architecture Discussion"

# Batch-process an entire directory of video files
engram ingest video-batch ~/obsidian/vault ./recordings/ \
  --date-from-filename --parallel 4

# Customize whisper model for better accuracy
engram ingest video ~/obsidian/vault ./presentation.mov \
  --whisper-model large --language en

The pipeline: ffmpeg extracts audio -> insanely-fast-whisper transcribes to text -> transcript is structured into an Obsidian note with timestamps, speaker labels, and metadata.

3. Cron-based Sweep

Set up a cron job to ingest files dropped into a directory:

# In crontab (runs every 6 hours):
0 */6 * * * for f in ~/inbox/*.txt; do engram ingest file ~/obsidian/vault "$f"; done

4. Manual Ingestion

Use engram ingest directly for one-off ingestion:

# Ingest a transcript
engram ingest transcript ~/obsidian/vault ./call-notes.txt --speaker "Bob" --date "2026-03-20"

# Ingest a URL
engram ingest url ~/obsidian/vault "https://example.com/article" --title "Architecture Overview"

# Ingest a PDF
engram ingest pdf ~/obsidian/vault ./whitepaper.pdf --title "System Design"

# Ingest any file
engram ingest file ~/obsidian/vault ./meeting-notes.md --title "Sprint Retro"

# Re-index the vault (optionally with QMD semantic indexing)
engram ingest index ~/obsidian/vault --qmd

5. Curator Maintenance Cycle

The curator engine runs an 8-step maintenance cycle on your vault:

• Process inbox (route queue-agent, queue-human, queue-cicd, queue-session)
• Run mycelium consolidation (spreading activation, memory decay, path reinforcement)
• Weave wikilinks (connect related notes)
• Staleness scan (flag outdated content)
• Conflict resolution (detect contradictions)
• Schema enforcement (validate frontmatter)
• Index update (rebuild graph index)
• Health report (summary of vault state)

engram brain expand --curator-cycle

CLI Reference

The engram command is the main entry point with the following subcommands:

Top-level Commands

Command	Description
engram wizard	Interactive setup wizard (Node.js UI with arrow-key navigation)
engram wizard --section <name>	Run a specific wizard section: vault, engine, profile, mode, guard, dependencies, all
engram status	Memory and context health dashboard (mode, mutations, vault, tools)
engram doctor	Health check across plugin, hooks, modules, guard config, and tests
engram connect	Join a shared vault (shortcut for engram-connect join)
engram disconnect	Leave the shared vault
engram uninstall	Remove Engram (preserves vault data); pass --yes to skip confirmation
engram -v / engram --version	Print version

Guard Commands

Command	Description
engram guard rules	List all guard rules with their status
engram guard blocks	View recent blocks from the audit log
engram guard toggle <rule-id>	Enable or disable a specific rule
engram guard level <rule-id> <level>	Set block level (block/warn/log) for a rule
engram guard allow "<cmd>"	Add a command to the global allowlist
engram guard deny "<cmd>"	Remove a command from all allowlists
engram guard config	Interactive guard configuration
engram guard defaults --level <level>	Set global default block level
engram guard reset	Reset to factory defaults

Memory Commands

Command	Description
engram memory query <topic>	Search memory for facts matching a topic
engram memory promote	Promote session facts to persistent memory
engram memory status	Show memory system status
engram memory kpi	Memory quality KPIs

Brain Commands

Command	Description
engram brain expand	Re-summarize, deduplicate, and compress memory layers
engram brain expand --curator-cycle	Run full 8-step curator maintenance cycle
engram brain expand --consolidate	Run mycelium consolidation pass
engram brain resolve	Resolve contradictions/supersessions in knowledge notes
engram brain kpi	Vault quality metrics (aliases engram-memory-kpi)
engram brain optimize	Apply memory-centric graph physics defaults to vault
engram brain code	AST analysis, symbol lookup, call graphs, impact analysis
engram brain graph	Initialize, index, and query the knowledge graph
engram brain ingest	Ingest transcripts, URLs, PDFs, video, audio, files
engram brain doctor	Brain-specific diagnostics
engram brain heal	Vault doctor: scan orphans, fix frontmatter, add tags, rename hash files

Vault Commands

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 vault from backup

Ingestion & Watch

Command	Description
engram ingest <type> <vault> <source>	Ingest content (file, transcript, url, pdf, video, video-batch)
engram watch setup	Configure file watcher for auto-ingestion
engram watch run	Run file watcher
engram watch status	Check watcher status

Connector Commands

Command	Description
engram connector list	List available connectors
engram connector add	Add a connector
engram connector remove	Remove a connector
engram connector test	Test a connector

Additional CLI Tools (plugin/bin)

All 30 CLI tools use the engram-* prefix:

Tool	Description
engram-agent-id	Persistent agent identity per (hostname, project) pair
engram-brain-code	AST analysis, symbol lookup, call graphs
engram-brain-doctor	Brain diagnostics
engram-brain-expand	Memory expansion, consolidation, curator cycle
engram-brain-graph	Knowledge graph init, index, query
engram-brain-ingest	Content ingestion pipeline
engram-brain-resolve	Contradiction/supersession resolution
engram-brain-stack	Brain stack inspection
engram-calibrate	Confidence calibration for promotion thresholds
engram-connect	Connected mode: join/leave shared vaults
engram-connector	External integration management
engram-context	Fact injection and query
engram-dedup	Semantic deduplication for promoted facts
engram-gated-run	Policy enforcement wrapper (cost ceilings, approval)
engram-guard	Guard rule management
engram-ingest-watch	File watcher for auto-ingestion
engram-memory-append	Append execution results to session memory
engram-memory-init	Scaffold per-project session memory structure
engram-memory-kpi	Memory quality KPIs
engram-memory-status	Memory system status
engram-obsidian	Vault management (status, audit, backup, restore)
engram-obsidian-optimize	Vault graph physics optimization
engram-policies	View and manage multi-agent sharing policies
engram-promote	Fact promotion to persistent memory
engram-provenance	SHA-256 hash-chained session receipts
engram-repo-research-sync	Mirror repo docs into the knowledge graph
engram-route	Risk-based policy routing for tasks
engram-share	Multi-agent memory sharing
engram-validate	Schema/format validation
engram-verify	Task verification (heuristic, test, LLM, hybrid modes)

Coming Soon

The following features exist in the codebase but are not fully wired or tested end-to-end. Use at your own risk.

Pretool Guard Blocking (Partial)

The before_tool_call hook is registered in index.ts and shells out to pretool-guard.py, but the OpenClaw gateway's before_tool_call lifecycle event may not be fully supported in all runtimes yet. The guard code works; delivery depends on the gateway version.

Connected Mode

The engram-connect CLI exists for joining and leaving shared vaults (engram connect --token inv_abc123). The underlying sync_daemon.py, invites.py, and heartbeat.py modules are implemented but have not been tested end-to-end against live multi-user scenarios.

Curator Mode

The curator engine (plugin/lib/curator.py) implements the full 8-step maintenance cycle and can be triggered via engram brain expand --curator-cycle. The code is functional but has not been battle-tested in production vaults at scale.

Obsidian-headless Shared Vault Sync

The wizard checks for obsidian-headless (ob CLI) and the status command reports its presence, but headless vault sync for multi-machine setups is not yet fully integrated.

Connectors: GitHub, Slack, Email

Connector modules exist at plugin/lib/connectors/ for GitHub (github.py), Slack (slack.py), Email (email.py), filesystem (filesystem.py), webhooks (webhook.py), and cron-based fetching (cron_fetch.py). These have not been tested against real external services. A community connector packaging system (community.py, registry.py, trust.py) is scaffolded but not production-ready.

Customizing the Install Wizard

What the Wizard Configures

The engram wizard command sets up:

• Plugin directory at ~/.openclaw/extensions/engram/
• Gateway registration in ~/.openclaw/openclaw.json
• package.json with required fields (type: "module", openclaw.extensions)
• index.ts entry point (hook registration shim)
• SDK symlink in node_modules/
• All configuration files under config/
• Safety profile selection
• Obsidian vault path (auto-detected or user-specified)

Advanced Options

During the wizard you can configure:

• Guard level: Set the global default block level (block/warn/log)
• Rule toggling: Enable or disable individual guard rules
• Operating mode: Standalone, connected, or curator
• Policy tier: Default risk tier for unmatched tasks (safe/review/critical)
• Code graph: Enable or disable AST analysis and call graphs
• Provenance: Enable or disable hash-chained cryptographic receipts
• Context engine: Choose between file-based and lossless-claw backends
• Cost ceilings: Per-tier spending limits in USD

Re-running the Wizard

To change settings after install:

# Re-run the full wizard
engram wizard

# Run a specific section
engram wizard --section guard
engram wizard --section profile
engram wizard --section vault

# Or validate and fix specific issues
engram doctor

# Or configure guard rules interactively
engram guard config

Plugin SDK Compatibility

Current SDK Version

The plugin targets OpenClaw >= 0.23.0 and uses a type-only import from the SDK:

import type { OpenClawPluginApi } from "openclaw/plugin-sdk";

This import is type-only (import type), so it works with the current SDK even though the module may not have a runtime export. The installer creates a symlink at $PLUGIN_PATH/node_modules/openclaw pointing to the detected SDK location.

Hook Registration

Hooks are registered via api.on() lifecycle listeners in index.ts:

api.on("session_start", async (event, ctx) => { ... });
api.on("before_tool_call", async (event, ctx) => { ... });
api.on("agent_end", async (event, ctx) => { ... });
api.on("before_message_write", async (event, ctx) => { ... });

Each listener shells out to a Python handler via execFileSync("python3", [scriptPath], { input: eventJson }). The Python handlers read JSON from stdin and write JSON to stdout.

Migration Note

The current SDK exposes openclaw/plugin-sdk. A future SDK release may move to openclaw/plugin-sdk/core. The index.ts entry point will need to be updated when that transition happens. Watch the OpenClaw changelog for migration guidance.

Configuration Reference

Plugin Config

Location: ~/.openclaw/extensions/engram/config/.engram.env

Environment-style config for the plugin. Set during install by the wizard.

Guard Rules

Location: ~/.openclaw/extensions/engram/config/guard-rules.json

Controls all 16 guard rules, block levels, allowlists, and per-repo overrides. See Guard System for the full schema.

Gateway Registration

Location: ~/.openclaw/openclaw.json

The plugin must be registered here with "source": "path":

{
  "plugins": {
    "installs": {
      "engram": {
        "source": "path",
        "path": "~/.openclaw/extensions/engram"
      }
    }
  }
}

Plugin Manifest

Location: openclaw.plugin.json (in the plugin directory)

Declares plugin metadata, hooks, profiles, config schema, capabilities, and CLI binaries. The kind field must be "provider" and the name field must be present.

Profile Definitions

Location: hooks/profiles/<profile-name>.json

Each profile JSON declares which hooks are enabled, their configuration (sensitivity, block level, TTL), and usage notes. Available profiles:

• autonomous.json
• balanced.json
• context-only.json
• guard-rail.json
• minimal-stop.json
• hardened-exec.json
• full-audit.json

Config Schema Properties

Property	Type	Default	Description
enabled	boolean	true	Enable/disable the plugin
profile	string	"balanced"	Safety profile: minimal-stop, balanced, hardened-exec, etc.
obsidianVault	string	~/obsidian/vault	Path to Obsidian knowledge vault
knowledgeRoot	string	~/.openclaw/data/knowledge	Directory for knowledge graph data
automationRoot	string	~/.openclaw/data/automation	Directory for automation data
localFirst	boolean	true	All data stays on-device, no external sync
codeGraphEnabled	boolean	false	Enable AST analysis, call graphs, impact analysis
provenanceEnabled	boolean	true	Enable hash-chained cryptographic receipts
policyTier	string	"review"	Default risk tier: safe, review, critical
costCeilingSafeUsd	number	1.0	Cost ceiling for safe-tier tasks (USD)
costCeilingReviewUsd	number	10.0	Cost ceiling for review-tier tasks (USD)
costCeilingCriticalUsd	number	100.0	Cost ceiling for critical-tier tasks (USD)
approvalCacheTtlMinutes	integer	30	TTL for cached approvals
contextEngine	string/null	null	"lossless-claw" for LCM integration, null for file-based
lcmQueryBatchSize	number	50	Batch size for LCM queries
promotionThreshold	number	70	Minimum score for auto-promotion (0-100)
autoDiscoveryInterval	string	"6h"	Auto-discovery interval (requires LCM backend)

Troubleshooting

"plugin not found"

The gateway cannot discover the plugin. Check that:

• package.json exists in the plugin directory with "openclaw": { "extensions": ["./index.ts"] }
• The gateway config (~/.openclaw/openclaw.json) has the plugin entry under plugins.installs

"missing register/activate export"

The index.ts file is either missing or has the wrong export format. It must export a default object with a register(api) method:

export default {
  name: "Engram",
  register(api: OpenClawPluginApi) { ... }
};

"source: Invalid input"

In the gateway config, the plugin source must be "path", not "local". The gateway only accepts npm, archive, or path.

SDK not found

The index.ts imports openclaw/plugin-sdk which must be resolvable. The installer should create a symlink:

~/.openclaw/extensions/engram/node_modules/openclaw -> <sdk_path>

If the symlink is missing, find the SDK location and create it manually:

# Check other installed plugins
ls ~/.openclaw/extensions/*/node_modules/openclaw

# Or check global install
ls "$(dirname "$(which openclaw)")/../lib/node_modules/openclaw"

# Create the symlink
ln -s <detected_path> ~/.openclaw/extensions/engram/node_modules/openclaw

Hooks not showing in openclaw hooks list

This is expected behavior. Engram registers hooks as lifecycle listeners via api.on(), which do not appear in openclaw hooks list. The hooks still fire correctly on their respective events. You can verify by checking the logs or running engram doctor.

Run the full validator

# Check everything with verbose output
engram doctor

# Re-run the wizard to fix configuration
engram wizard

Contributing

Repo Structure

engram/
  package.json               # @easylabs/engram, v2.2.0
  openclaw.plugin.json       # Plugin manifest (hooks, profiles, config schema, bins)
  plugin.json                # Plugin metadata
  INSTALL.sh                 # Install script (consumed by wizard output)
  bin/
    engram                   # Main CLI entry point (bash router)
    wizard.mjs               # Node.js interactive wizard (@clack/prompts)
  plugin/
    index.ts                 # Gateway entry point (hook + tool registration)
    bin/                     # 30 CLI tools (engram-*)
    config/                  # Guard rules, example configs
    hooks/
      handlers/              # Python hook scripts
        session-start.py     # Git context + memory injection
        pretool-guard.py     # Dangerous pattern blocking
        stop-quality-gate.py # Incomplete work detection
        write-validate.py    # Schema/format validation
      managed/
        engram-session-capture/  # Auto-capture hook (/new, /reset)
      profiles/              # 7 safety profile JSONs
      tests/                 # Hook unit tests (pytest)
    lib/                     # Python modules
      mycelium.py            # Spreading activation, FSRS memory model, flow scores
      curator.py             # 8-step curator maintenance cycle
      vault_doctor.py        # Orphan scan, frontmatter fix, tag detection, rename
      vault_migrate.py       # Vault structure migration with wikilink preservation
      consolidation.py       # Memory consolidation
      session_writer.py      # Daily session file writer
      wikilink_weaver.py     # Auto-link related notes
      staleness.py           # Stale content detection
      schema_enforcer.py     # Frontmatter schema validation
      conflict_resolver.py   # Contradiction detection
      inbox_processor.py     # Inbox queue routing
      index_generator.py     # Graph index builder
      health_reporter.py     # Vault health reporting
      mode.py                # Operating mode (standalone/connected/curator)
      heartbeat.py           # Connected mode heartbeat
      sync_daemon.py         # Vault sync daemon
      knowledge_gaps.py      # Gap detection
      review_queue.py        # Review queue management
      connectors/            # GitHub, Slack, Email, filesystem, webhook, cron connectors
      tests/                 # Lib unit tests
    memory/
      tests/                 # Memory layer tests
    policy/                  # Risk policy routing
    v2-lcm/                  # LCM bidirectional integration
      tests/                 # LCM integration tests
  docs/                      # Additional documentation
  releases/                  # Distribution ZIPs

Adding a New Profile

• Create a JSON file in plugin/hooks/profiles/<name>.json
• Follow the schema from an existing profile (e.g., balanced.json)
• Declare hooks_enabled, hooks_disabled, and per-hook configuration
• If the profile should be selectable in the manifest, add it to openclaw.plugin.json under profiles

Adding a New Guard Rule

• Edit plugin/config/guard-rules.json
• Add a rule object to the rules array:

  {
    "id": "my-new-rule",
    "pattern": "\\bsome-dangerous-command\\b",
    "flags": "IGNORECASE",
    "label": "Human-readable label",
    "message": "Why this is blocked.",
    "block_level": "block",
    "enabled": true,
    "category": "destructive"
  }
  

• Add tests in plugin/hooks/tests/test_pretool_guard.py

Adding a New CLI Tool

• Create the script in plugin/bin/engram-<name> (bash or python)
• Make it executable (chmod +x)
• Register it in openclaw.plugin.json under the bin map
• Add corresponding tests

Running Tests

# All hook tests
cd plugin && python -m pytest hooks/tests/ -v

# All memory tests
cd plugin && python -m pytest memory/tests/ -v

# All LCM tests
cd plugin && python -m pytest v2-lcm/tests/ -v

# Everything
cd plugin && python -m pytest -v

# Specific test file
cd plugin && python -m pytest hooks/tests/test_pretool_guard.py -v

Alternative: Using Hooks with Claude Code

While Engram is designed for the OpenClaw gateway, two of the four hooks can also be wired directly into Claude Code via its native hooks system in ~/.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
      }
    ]
  }
}

Works with Claude Code today:

• session-start (session_initialization) — injects git context and LACP memory
• stop-quality-gate (agent_stop) — catches premature stops and rationalization patterns

Requires OpenClaw (not available in Claude Code):

• pretool-guard (pre_tool_use) — intercepts tool calls before execution
• write-validate (file_write) — validates file writes before they happen

Multi-Agent Setup

The setup wizard scans your openclaw.json for configured agents and lets you choose which ones get Engram memory tools.

engram wizard

During setup, the wizard will:

• Detect all agents in your OpenClaw config
• Let you select which agents should use Engram
• Append Engram tool documentation to each agent's TOOLS.md
• Initialize the knowledge graph, agent identity, and provenance chain
• Wire up integrations (lossless-claw, GitNexus, QMD, MCP servers) based on your choices

Each selected agent gets a TOOLS.md section that teaches it when and how to use the memory tools — query before investigating, promote facts as they're discovered, ingest external references, save session state.

To add Engram to additional agents later:

engram wizard --section agents

Dependencies

The wizard detects and installs dependencies automatically. Core dependencies are required. Optional integrations are offered during setup:

Required (installed automatically):

Dependency	What it enables
QMD	Semantic search, memory backend, context injection — the core of the memory system
poppler (pdftotext)	PDF text extraction for ingestion

Optional (offered during setup):

Dependency	What it enables
ffmpeg	Video/audio processing for media ingestion
insanely-fast-whisper	GPU-accelerated audio transcription
GitNexus	Multi-language AST, call graphs, complexity analysis
lossless-claw	Native LCM SQLite context engine (alternative to file-based)
obsidian-headless (ob)	Multi-machine vault sync for connected/curator modes

Video / Audio Transcription

Engram can ingest video and audio files by extracting audio with ffmpeg and transcribing with insanely-fast-whisper. The wizard offers to install it during setup, or you can install it manually:

# Install pipx if you don't have it
brew install pipx    # macOS
# or: pip install pipx

# Install insanely-fast-whisper (isolated, no dependency conflicts)
pipx install insanely-fast-whisper==0.0.15 --force --pip-args="--ignore-requires-python"

# Or run without installing
pipx run insanely-fast-whisper --file-name recording.mp4

Hardware & transcription speed:

Transcription time depends heavily on your hardware. A 1-hour recording might take 30 seconds on a high-end GPU or 20+ minutes on CPU. Here's what to expect:

Setup	~Time for 1 hour of audio	Notes
NVIDIA A100 / 4090	~1 min	Best performance. Flash Attention 2 supported.
NVIDIA T4 / 3060	~3-5 min	Use --batch-size 12 if you hit OOM.
Mac (Apple Silicon)	~5-10 min	Engram auto-sets --device-id mps --batch-size 4. Uses ~12GB GPU memory.
CPU only	~20-40 min	Use openai-whisper instead (pip install openai-whisper). Works everywhere, just slower.

Usage with Engram:

# Ingest a video (extracts audio, transcribes, creates vault note)
engram ingest video /Volumes/Vault ~/recordings/meeting.mp4 --title "Q1 Planning" --speaker "Andrew"

# With a specific model (tiny/base/small/medium/large)
engram ingest video /Volumes/Vault ~/recordings/call.mp3 --model large

Engram tries transcription tools in this order: installed insanely-fast-whisper > pipx run insanely-fast-whisper > openai-whisper CLI. If none are available, it tells you how to install.

Current Limitations

Hooks — waiting on OpenClaw lifecycle methods:

• The pretool-guard and write-validate hooks depend on pre_tool_use and file_write lifecycle events not yet exposed by the OpenClaw gateway. These hooks are fully implemented and tested, but will only activate once OpenClaw introduces these trigger points. Currently only session_initialization (session-start) and agent_stop (stop-quality-gate) are wired.

Code intelligence:

• Built-in AST parsing covers Python only. If GitNexus is not installed, JS/TS/Go/Rust files are counted but not parsed. The wizard offers to install GitNexus during setup. To add additional repos after setup, run gitnexus analyze <repo-path> or instruct your agent to initialize the repo with engram-brain-code analyze <repo-path>.

Ingestion:

• Video/audio ingestion is functional but requires external tools (see below).

Shared vault (connected/curator modes):

• Requires obsidian-headless (ob) which is an experimental dependency. The wizard offers to install it if you select connected or curator mode.

Execution lifecycle:

• The 12-state lifecycle (SUBMITTED through COMPLETED) is designed but not tracked at runtime. The gated-run system covers the core approval/execution flow but does not emit state transitions.

License

MIT