Engram - Rust Implementation

A distributed memory system for AI agents, implemented in Rust with extensible architecture and BDD testing.

Features

Core Architecture

• Extensible Entity System: Trait-based entity architecture supporting dynamic model loading
• Git-based Storage: Content-addressable storage with multi-agent synchronization
• Modular CLI: Command-line interface with subcommands for all operations
• BDD Testing: Gherkin-style behavior-driven development testing
• Configuration System: Extensible configuration with validation
• Plugin Support: Dynamic plugin loading for custom extensions

Entity Types

• Tasks: Work items with status tracking, priority, and hierarchy
• Context: Background information with relevance scoring and source tracking
• Reasoning: Decision chains with confidence levels and evidence tracking
• Knowledge: Information storage with usage metrics and categorization
• Sessions: Agent sessions with SPACE framework and DORA metrics
• Compliance: Requirements tracking with violations and remediation
• Rules: System rules with execution history and conditions
• Standards: Team standards with versioning and relationships
• ADRs: Architectural Decision Records with alternatives and outcomes
• Workflows: State machines with transitions and permission schemes
• Relationships: Entity relationships with graph operations and path finding
• Commit Validation: Pre-commit hook system with task relationship requirements

Relationship Management

The relationship system provides powerful graph-based operations for modeling connections between entities:

Relationship Types

• DependsOn: Entity dependencies and prerequisites
• Contains: Hierarchical containment relationships
• References: Cross-references and citations
• Fulfills: Implementation and completion relationships
• Implements: Technical implementation relationships
• Supersedes: Version and replacement relationships
• AssociatedWith: General associations
• Influences: Impact and influence relationships
• Custom: User-defined relationship types

Relationship Features

• Bidirectional/Unidirectional: Configurable relationship directions
• Weighted Connections: Relationship strength (Weak, Medium, Strong, Critical)
• Graph Traversal: BFS, DFS, and Dijkstra pathfinding algorithms
• Relationship Constraints: Validation rules and cardinality limits
• Analytics: Connection statistics and graph metrics

Storage Features

• Content-addressable: SHA-256 hashing for integrity verification
• Multi-agent: Collaboration with conflict resolution strategies
• Git Integration: Full Git history, branching, and merging
• Performance: Efficient querying and indexing

CLI Commands

# Setup
engram setup workspace
engram setup agent --name alice --type coder

# Task Management
engram task create --title "Implement auth" --priority high
engram task list --agent alice
engram task update <id> --status done

# Context Management
engram context create --title "API docs" --source "documentation"
engram context list

# Reasoning Chains
engram reasoning create --title "Authentication approach" --task-id <id>

# Knowledge Management
engram knowledge create --title "OAuth2 flows" --type pattern

# Session Management
engram session start --agent alice --auto-detect
engram session status --id <session-id> --metrics

# Compliance & Standards
engram compliance create --title "Security requirements" --category security
engram standard create --title "Coding standards" --category coding

# ADRs
engram adr create --title "Database choice" --number 001

# Workflows
engram workflow create --title "Development pipeline"

### Skills Integration

Engram ships with specialized skills for common workflows:

```bash
# Use skills from ./engram/skills/
cat ./engram/skills/meta/use-engram-memory.md      # Core memory skill
cat ./engram/skills/meta/delegate-to-agents.md     # Agent delegation
cat ./engram/skills/workflow/plan-feature.md       # Feature planning
cat ./engram/skills/compliance/check-compliance.md # Compliance checking

Prompts Library

Engram includes a comprehensive prompt library for agent orchestration:

# Agent prompts (170+)
ls ./engram/prompts/agents/

# Pipeline templates (100+)
ls ./engram/prompts/ai/pipelines/

# Compliance prompts (250+)
ls ./engram/prompts/compliance_and_certification/prompts/audit_checkpoints/

Engram-Adapted Prompts

Core agents and pipelines are adapted for engram integration:

• 01-the-one.yaml - Orchestrator with engram task creation
• 03-the-architect.yaml - Architecture with engram context storage
• 05-the-deconstructor.yaml - Task breakdown with engram subtasks
• 01-greenfield-feature-launch.yaml - Engram workflow orchestration

All adapted prompts include:

• task_id parameter for engram tracking
• engram reasoning create for progress storage
• engram context create for result storage
• engram relationship create for entity linking
• JSON response with engram entity IDs

Using Skills and Prompts

# Check available skills
ls ./engram/skills/

# Use a skill
cat ./engram/skills/meta/use-engram-memory.md

# Use an adapted agent prompt
cat ./engram/prompts/agents/01-the-one.yaml

# Use a pipeline template
cat ./engram/prompts/ai/pipelines/01-greenfield-feature-launch.yaml

Documentation

• Using Engram - Core workflow protocol
• Prompt Engineering Guide - Prompt construction patterns

Relationship Management

engram relationship create --source-id task1 --source-type task --target-id task2 --target-type task --relationship-type depends-on --agent alice
engram relationship list --agent alice
engram relationship get `<relationship-id>`
engram relationship find-path --source-id task1 --target-id task3 --algorithm dijkstra
engram relationship connected --entity-id task1 --relationship-type depends-on
engram relationship stats --agent alice
engram relationship delete `<relationship-id>`

Commit Validation and Hooks

engram validation commit --message "feat: implement user authentication [TASK-123]"
engram validation commit --message "test commit" --dry-run
engram validation hook install
engram validation hook uninstall
engram validation hook status
engram validation check

Synchronization

engram sync --agents "alice,bob" --strategy intelligent_merge

Perkeep Backup and Restore

engram perkeep backup --description "Full backup"
engram perkeep backup --entity-type task --include-relationships
engram perkeep list --detailed
engram perkeep restore --blobref "sha256-..."
engram perkeep health
engram perkeep config --server "http://localhost:3179"

Perkeep Integration

Engram supports backing up and restoring entities using Perkeep, a personal data store for content-addressable storage.

Configuration

Set environment variables to configure Perkeep:

export PERKEEP_SERVER="http://localhost:3179"  # Default: http://localhost:3179
export PERKEEP_AUTH_TOKEN="your-token"         # Optional: for authenticated servers

Backup Commands

# Backup all entity types
engram perkeep backup

# Backup specific entity type
engram perkeep backup --entity-type task

# Backup with description
engram perkeep backup --description "Weekly backup"

# Include relationships in backup (default: true)
engram perkeep backup --include-relationships

Restore Commands

# Restore from most recent backup
engram perkeep restore

# Restore from specific backup blobref
engram perkeep restore --blobref "sha256-abc123..."

# Dry run (preview what would be restored)
engram perkeep restore --dry-run

# Restore with agent override
engram perkeep restore --agent default

Management Commands

# List available backups
engram perkeep list
engram perkeep list --detailed

# Check server health
engram perkeep health

# Configure settings
engram perkeep config --server "http://localhost:3179"

How It Works

1. Content-Addressable Storage: Entities are serialized to JSON and uploaded as blobs to Perkeep
2. Backup Metadata: A schema object tracks all entity blobrefs, timestamps, and counts
3. Entity Types: task, context, reasoning, knowledge, session, and relationship entities
4. Restore Process: Fetches backup metadata, retrieves all entity blobs, and stores them

Development

Building

cargo build --release

Testing

# Run BDD tests
cargo test --test bdd

# Run unit tests
cargo test

# Run with specific feature
cargo test --features plugins

Examples

See the examples/ directory for usage examples:

cargo run --example basic_usage

Configuration

Engram supports YAML/TOML configuration with the following structure:

app:
  log_level: info
  default_agent: default
  git:
    author_name: Your Name
    author_email: your.email@example.com

workspace:
  agents:
    coder:
      type: implementation
      description: "Handles code changes"

storage:
  storage_type: git
  base_path: .engram
  sync_strategy: intelligent_merge

features:
  plugins: true
  analytics: true
  experimental: false

Architecture

Extensible Models

The Rust implementation uses trait-based architecture for extensibility:

#![allow(unused)]
fn main() {
pub trait Entity: Serialize + for<'de> Deserialize<'de> + Send + Sync {
    fn entity_type() -> &'static str;
    fn id(&self) -> &str;
    fn validate(&self) -> Result<(), String>;
    // ... other methods
}
}

Plugin System

Custom entity types can be added dynamically:

#![allow(unused)]
fn main() {
// Register new entity type
registry.register::<CustomEntity>();

// Create from generic representation
let entity = registry.create(generic_entity)?;
}

Commit Validation and Pre-commit Hooks

The validation system enforces disciplined development practices by ensuring all commits follow established patterns and reference proper tasks with required relationships.

Key Features:

• Task Reference Validation: Commits must reference existing tasks in multiple formats
• Relationship Requirements: Tasks must have reasoning and context relationships
• File Scope Validation: Changed files must match planned task scope
• Exemption Support: Configurable exemptions for chore, docs, fixup commits
• Performance Optimized: Caching and parallel validation support

Supported Task ID Formats:

• [TASK-123] - Brackets format
• [task:auth-impl-001] - Colon format
• Refs: #456 - Reference format

Validation Rules:

# Validate a commit
engram validation commit --message "feat: implement authentication [TASK-123]"

# Check hook status
engram validation hook status

# Install validation hook
engram validation hook install

Configuration:

Configuration via .engram/validation.yaml:

enabled: true
require_task_reference: true
require_reasoning_relationship: true
require_context_relationship: true
task_id_patterns:
  - pattern: '\[([A-Z]+-\d+)\]'
    name: "Brackets format"
    example: "[TASK-123]"
exemptions:
  - message_pattern: '^(chore|docs):'
    skip_specific: ["require_task_reference"]
performance:
  cache_ttl_seconds: 300
  enable_parallel_validation: true

Plugin System

Storage Layer

The storage layer supports multiple backends through the Storage trait:

#![allow(unused)]
fn main() {
pub trait Storage: Send + Sync {
    fn store(&mut self, entity: &dyn Entity) -> Result<(), EngramError>;
    fn get(&self, id: &str, entity_type: &str) -> Result<Option<Box<dyn Entity>>, EngramError>;
    // ... other methods
}
}

BDD Testing

Behavior-driven development testing with Gherkin syntax:

Feature: Task Management
  Scenario: Create a new task
    Given I have a workspace
    And I am logged in as agent "test-agent"
    When I create a new task "Implement login feature"
    Then the task should be created successfully

Performance

• Memory Efficient: Content-addressable storage prevents duplication
• Fast Queries: Indexed storage with agent-based filtering
• Scalable: Git handles large repositories efficiently
• Concurrent Safe: Thread-safe storage operations

Enterprise Features

• Multi-tenant: Isolated workspaces with shared memory
• Audit Trails: Complete Git history for compliance
• Conflict Resolution: Multiple strategies for team collaboration
• Analytics: SPACE framework and DORA metrics
• Security: Content integrity verification with SHA-256

Migration from Go

The Rust implementation is designed as a drop-in replacement for the Go version:

1. Same CLI commands and arguments
2. Compatible data formats (JSON/YAML)
3. Same Git storage structure
4. Enhanced performance and features

Contributing

The Rust implementation welcomes contributions for:

• New entity types
• Storage backends
• CLI commands
• BDD test scenarios
• Plugin examples

License

AGPL-3.0-or-later OR Commercial - dual-licensed for open source and commercial use

Getting Started with Engram

Stop re-explaining your codebase to every new AI session.

Engram gives your AI agents persistent memory — a knowledge graph that lives in your git repo. Plans, decisions, and context survive across sessions. A new agent queries engram and picks up where the last one left off.

Git tracks what changed. Engram tracks why.

Install

# Linux / macOS (one line)
curl -fsSL https://github.com/vincents-ai/engram/releases/latest/download/install.sh | bash

# Or: cargo install engram
# Or: nix run github:vincents-ai/engram -- --help

engram --version   # verify

See the README for all platforms including Windows and manual installs.

Set Up (2 minutes)

cd your-project

# 1. Initialize engram in your repo
engram setup workspace

# 2. Create your profile
engram setup agent --name "Your Name" --agent-type operator

# 3. Install the commit hook (requires task UUID in every commit)
engram validate hook install

Done. Now use it.

The Workflow: Plan → Execute → Remember

Plan

engram task create --title "Add user authentication" --priority high

Execute & Document

# Save reference material
engram context create --title "OAuth2 Spec" --source "https://oauth.net/2/"

# Link it to the task
engram relationship create \
  --source-id <TASK_ID> --source-type task \
  --target-id <CONTEXT_ID> --target-type context \
  --relationship-type references

# Record a decision
engram reasoning create \
  --title "Chose JWT over sessions" \
  --task-id <TASK_ID> \
  --content "Stateless, scales horizontally, no server-side session store."

Remember

# Ask a question across everything you've stored
engram ask query "why did we choose JWT for auth?"

# What should I work on next?
engram next

For AI Agents

If you use Claude Code, OpenCode, Goose, or similar tools:

# Install core skills (14 — teaches your agent the engram loop)
engram skills setup

# Install all skills (44 — planning, architecture, review, debugging, TDD, compliance)
engram setup skills

Your agent now knows to search engram before acting, store decisions after making them, and link everything. When a new session starts, it runs:

engram ask query "full-fidelity handoff"

…and gets the full project state.

Next Steps

• User Guide — Complete walkthrough for human operators
• Using Engram (for Agents) — Agent integration details
• CLI Reference — All commands and flags
• Theory Building — Capture mental models per Naur (1985)

Engram User Guide

Every new AI session starts from zero. Engram gives your agents — and you — persistent memory.

This guide is for human operators: developers, tech leads, and architects who want to stop losing context between sessions, between agents, and between sprints.

What is Engram?

Git tracks what changed. Engram tracks why it changed (the reasoning), how you planned it (the tasks), and what you learned along the way (the context). It’s a structured knowledge graph that lives inside your git repo — in .git/refs/engram/, not in your working tree. No extra files to commit, no wiki to maintain, no tool to context-switch to.

The result: when you (or an AI agent) ask “where were we on auth?”, engram returns the task, the decision log, the reference material, the open subtasks, and who worked on it last. No onboarding required.

Getting Started

Follow these steps to initialize Engram in your project.

1. Initialize Workspace

Run this in the root of your git repository. It creates the necessary internal structures in .git/.

engram setup workspace

2. Create Your Identity (Agent Profile)

Tell Engram who you are. This creates a “human” agent profile so your actions are attributed correctly.

engram setup agent --name "Your Name" --agent-type operator

• --name: Your display name.
• --agent-type: Use operator for humans. (Other types like coder or reviewer are for AI agents).

3. Install Validation Hook (Recommended)

The pre-commit hook ensures you never commit code without linking it to a task. This keeps your history clean and traceable.

# Check if hook is already installed
engram validate hook status

# Install the hook
engram validate hook install

Once installed, if you try git commit -m "fix bug" without a task ID, the commit will be rejected. You’ll need to use: git commit -m "fix bug [TASK-123]".

Core Concepts

1. Tasks

Tasks are the units of work. Unlike a simple todo list, Engram tasks are hierarchical and stateful.

• Use for: Planning features, tracking bugs, organizing research.
• Example: “Implement OAuth2 Login” (Parent) -> “Design DB Schema” (Child).

2. Context

Context represents the raw materials of your knowledge work. It’s where you dump information so you (and your AI agents) don’t have to hold it in your head.

• Use for: Storing documentation URLs, code snippets, error logs, meeting notes.
• Example: “Stripe API Docs - Payment Intents”, “Error Log from Production Crash”.

3. Reasoning

This is Engram’s superpower. A Reasoning entity captures the decision-making process.

• Use for: Explaining why you chose a library, why you refactored a class, or why you closed a bug as “wontfix”.
• Example: “Chose PostgreSQL over Mongo because we need relational integrity for transactions.”

4. Relationships

Entities don’t live in isolation. You link them together to create a knowledge graph.

• Common links:
  • Task depends_on Task
  • Task references Context
  • Reasoning justifies Task

Day-to-Day Workflow

Step 1: Start Your Day (Session)

Tell Engram you’re starting work. This helps track metrics and context switches.

engram session start --name human

Step 2: Plan Your Work

Before you code, define what “done” looks like.

# Create a task
engram task create --title "Fix login timeout bug" --priority high

# Create a subtask for investigation
engram task create --title "Reproduce timeout locally" --parent-id [TASK-ID]

Step 3: Capture Context

Found a relevant StackOverflow answer? Don’t just bookmark it—save it.

engram context create --title "JWT Expiration Solution" --source "https://stackoverflow.com/..."
engram relationship create --source-id [TASK-ID] --target-id [CONTEXT-ID] --relationship-type references

Step 4: Log Decisions

You decided to increase the timeout to 30 minutes. Record why.

engram reasoning create --title "Increased session timeout" --description "User feedback indicates 15m is too short for complex forms." --task-id [TASK-ID]

Step 5: Query History

Need to remember why you did something last month?

# Search for reasoning related to "timeout"
engram reasoning list --task-id [TASK-ID]

Working with AI Agents

Engram shines when you work with AI. Because your context and plans are structured, an AI agent can read your Engram workspace and immediately understand the project state.

To hand off work to an agent:

1. Be Explicit in Titles: Use “Implement…” or “Refactor…” verbs.
2. Add Context Links: Explicitly link relevant Context entities to the Task. The agent will read these first.
3. Define Acceptance Criteria: Put this in the task description.

Example Agent Handoff:

“I created task [TASK-123] ‘Refactor Auth Middleware’. I’ve linked the [Context-456] ‘New Security Standards’ doc. Please pick this up.”

Theory Building

Based on Peter Naur’s “Programming as Theory Building” (1985), capture the mental model behind your code.

# Create a theory about a domain
engram theory create "User Authentication" --agent your-agent

# Add conceptual model (concepts + definitions)
engram theory update --id <ID> --concept "User: A person who authenticates to the system"
engram theory update --id <ID> --concept "Session: A period of authenticated access"

# Add system mappings (how concepts map to code)
engram theory update --id <ID> --mapping "User: src/entities/user.rs (struct User)"
engram theory update --id <ID> --mapping "Session: src/entities/session.rs (struct Session)"

# Add design rationale (why decisions were made)
engram theory update --id <ID> --rationale "JWT Tokens: Stateless auth to avoid session storage"

# Add invariants (must-be-true statements)
engram theory update --id <ID> --invariant "User email must be unique"

State Reflection

When code behavior conflicts with your theory, use reflection to detect and resolve the dissonance.

# Create a reflection when you encounter unexpected behavior
engram reflect create \
  --theory <THEORY_ID> \
  --observed "Test failed: expected User but got None" \
  --trigger-type test_failure

# Record specific dissonance points
engram reflect record-dissonance \
  --id <REFLECTION_ID> \
  --description "Theory claims User always exists, but code allows null"

# Propose theory updates
engram reflect propose-update \
  --id <REFLECTION_ID> \
  --update "Make User optional in Session, update invariant"

# Check if mutation required (dissonance >= 0.7)
engram reflect requires-mutation --id <REFLECTION_ID>
# Exit 0 = theory must be updated before code fixes

The 0.7 threshold enforces Naur’s insight: bugs often indicate flawed mental models, not just typos.

Tips & Tricks

• Automatic Storage: Engram saves data instantly to your git repo’s database (.git/objects). You do not need to git add or commit Engram data manually; it’s handled automatically via git refs.
• Share with Team: Since Engram uses standard git refs, you can push/pull them to share context with your team (requires configuring your git fetch/push refspecs).
• Hook Usage: With the hook installed, use engram task list --status in_progress to find your active task ID before committing.
• Keep it Granular: It’s better to have 5 small tasks than 1 giant one. It makes reasoning easier to attach.
• Be Specific with AI: When creating tasks for AI agents, include explicit file paths, expected outcomes, and success criteria. This prevents the “tool calling loop” issue where agents over-investigate instead of acting. See Known Issues for details.

Architecture Overview

System Design

Engram is a distributed memory system that stores entity data in Git refs.

Core Components

┌─────────────────────────────────────────┐
│              CLI Layer                  │
│  (src/cli/*.rs)                        │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│            Entity Layer                 │
│  (src/entities/*.rs)                   │
│  - Task, Context, Reasoning, Knowledge  │
│  - Theory, StateReflection              │
│  - Session, Workflow, WorkflowInstance  │
│  - ADR, Compliance, Standard, Rule      │
│  - Lesson, Persona, DocFragment         │
│  - EscalationRequest, ExecutionResult   │
│  - AgentSandbox, ProgressiveGateConfig  │
│  - BottleneckReport, DoraMetricsReport  │
│  - TaskDurationReport, StaleTaskReport  │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│           Storage Layer                │
│  (src/storage/*.rs)                    │
│  - GitRefsStorage (primary)            │
│  - MemoryOnlyStorage (testing)         │
└─────────────────────────────────────────┘

Modules

Storage Backends

Entity Flow

1. User creates entity via CLI
2. Entity is validated
3. Converted to GenericEntity
4. Stored in storage backend
5. Can be retrieved, listed, updated, deleted

Tasks

Tasks are the fundamental unit of work in Engram. They are hierarchical and stateful.

CLI Usage

# Create a task
engram task create --title "Implement OAuth2 Login" --priority high

# Create subtask
engram task create --title "Design DB Schema" --parent-id <PARENT_TASK_ID>

# Update status
engram task update --id <TASK_ID> --status in_progress

# List tasks
engram task list
engram task list --status pending

Attributes

• title: Short description
• description: Detailed requirements
• priority: high, medium, low
• status: pending, in_progress, completed, blocked
• parent_id: For hierarchical tasks

Context

Context represents the raw materials for your work—documentation, code snippets, URLs, notes.

CLI Usage

# Create context
engram context create --title "Stripe API Docs" --source "https://stripe.com/docs/api"

# Create with content
engram context create --title "Error Log" --content "$(cat error.log)"

# List context
engram context list

Use Cases

• Documentation URLs
• Code snippets
• Error logs
• Meeting notes
• External resources

Reasoning

Reasoning captures the decision-making process—the “why” behind your choices.

CLI Usage

# Record a decision
engram reasoning create \
  --title "Chose JWT for stateless auth" \
  --description "Session storage adds overhead. JWT allows stateless verification." \
  --task-id <TASK_ID>

# Add structured steps, optionally with IBIS metadata
engram reasoning add-step <REASONING_ID> \
  --content "JWT keeps API nodes stateless" \
  --ibis-type idea
engram reasoning add-step <REASONING_ID> \
  --content "Token revocation needs explicit design" \
  --ibis-type con \
  --ibis-polarity con

# Conclude and inspect
engram reasoning conclude <REASONING_ID> --conclusion "Use JWT with short TTL and refresh rotation"
engram reasoning list
engram reasoning list --task-id <TASK_ID>
engram reasoning show <REASONING_ID>
engram reasoning history <REASONING_ID>
engram reasoning export <REASONING_ID> --output reasoning.json

# Search by IBIS metadata or keyword
engram reasoning search --ibis-type question
engram reasoning search --polarity pro --keyword jwt

IBIS Support

Reasoning steps can carry Issue-Based Information System metadata:

The entity model also supports ibis_mode and captured positions; positions are flattened into normal reasoning steps for compatibility with existing consumers.

Provenance and Event History

Reasoning chains maintain event history for important lifecycle changes. Events include automatic storage activity and agent attribution, so later agents can inspect who changed a chain and why.

Why It Matters

• Context preservation: Future developers understand why decisions were made
• Agent onboarding: AI agents can understand project history
• Audit trail: Complete record of decision rationale
• Argument mapping: IBIS metadata separates questions, candidate ideas, supporting arguments, objections, references, and notes

Knowledge

Knowledge represents reusable patterns and learnings that transcend individual tasks.

CLI Usage

# Create knowledge
engram knowledge create \
  --title "PostgreSQL Connection Pooling" \
  --content "Use r2d2 pool for PostgreSQL connections. Max 10 connections per worker." \
  --type pattern

# Knowledge types: fact, pattern, rule, concept, procedure, heuristic

# List knowledge
engram knowledge list
engram knowledge list --type pattern

# Inspect/update/delete
engram knowledge show <KNOWLEDGE_ID>
engram knowledge update <KNOWLEDGE_ID> --content "Updated guidance"
engram knowledge delete <KNOWLEDGE_ID>

Types

Decay, Usage, and Citations

Knowledge entities track freshness and usefulness metadata:

Refresh decay metadata with:

engram health refresh-decay --lambda 0.01

A lower decay weight indicates older or less recently used knowledge. Agents should prefer high-confidence, highly cited, recently used items when multiple knowledge entries conflict.

Relationships

Relationships link entities together to create a knowledge graph.

CLI Usage

# Create relationship
engram relationship create \
  --source-id <TASK_ID> \
  --target-id <CONTEXT_ID> \
  --type references

# Common types:
# - references: Task uses context
# - implements: Task fulfills requirement
# - depends_on: Task requires another task
# - justifies: Reasoning supports a decision
# - related: General connection

# List relationships
engram relationship list --source-id <ID>
engram relationship list --target-id <ID>

Why Relationships Matter

• Context graph: See all context relevant to a task
• Impact analysis: Understand how changes affect other work
• Traceability: Link decisions to requirements

Theory Building

Based on Peter Naur’s “Programming as Theory Building” (1985)

Overview

A program is not just its source text; it is the living theory built in the mind of the developer. Without this theory, code becomes incomprehensible—even if every statement is understood.

Engram captures this by allowing agents to build formal Theory entities that represent their mental model of a system domain.

What is a Theory?

A Theory consists of:

CLI Usage

Create a Theory

# Basic creation
./target/release/engram theory create "Workflow Engine"

# With agent and task
./target/release/engram theory create "Authentication" -a "the-architect" -t "task-123"

# From JSON
./target/release/engram theory create --json --json-file theory.json

Add Concepts

./target/release/engram theory update --id <ID> --concept "User: A person who interacts with the system"
./target/release/engram theory update --id <ID> --concept "Session: A context for a user's interaction"

Add System Mappings

./target/release/engram theory update --id <ID> --mapping "User: src/entities/user.rs:42 (struct User)"
./target/release/engram theory update --id <ID> --mapping "Session: src/entities/session.rs:28 (struct Session)"

Add Design Rationale

./target/release/engram theory update --id <ID> --rationale "JWT Tokens: Stateless auth avoids session storage overhead"

Add Invariants

./target/release/engram theory update --id <ID> --invariant "User email must be unique"
./target/release/engram theory update --id <ID> --invariant "Session expires after 24 hours"

List and Show

# List all theories
./target/release/engram theory list

# Filter by agent
./target/release/engram theory list -a "the-architect"

# Show details with metrics
./target/release/engram theory show --id <ID> --show-metrics

Agent Persona

Use the The Theorist agent to automatically extract theories from code:

# Use with your AI agent
prompts/agents/168-the-theorist.yaml

See Pipeline: Theory Building for the full workflow.

Integration with State Reflection

Theory entities work with State Reflection to detect when your mental model conflicts with reality.

When dissonance is detected (score ≥ 0.7), the theory must be updated before code fixes are attempted.

State Reflection

Cognitive Dissonance Detection for AI Agents

Overview

When an agent’s theory conflicts with observed reality, this is “cognitive dissonance.” State Reflection captures this gap and enforces that the theory is updated before code is modified.

Key principle: Bugs often indicate a flawed mental model, not just a typo. Fix the theory first, then fix the code.

The Dissonance Threshold

CLI Usage

Create a Reflection

./target/release/engram reflect create \
  --theory <THEORY_ID> \
  --observed "Test failed: expected User, got None" \
  --trigger-type test_failure \
  --agent "the-architect"

Record Dissonance

./target/release/engram reflect record-dissonance \
  --id <REFLECTION_ID> \
  --description "Theory claims User is always created before Session, but code allows Session without User"

Propose Theory Update

./target/release/engram reflect propose-update \
  --id <REFLECTION_ID> \
  --update "Add invariant: Session.user_id is optional; remove requirement that User must exist"

Check if Mutation Required

./target/release/engram reflect requires-mutation --id <REFLECTION_ID>
# Exit code 0 = mutation required (dissonance >= 0.7)
# Exit code 1 = mutation not required

Resolve Reflection

# After updating the theory
./target/release/engram reflect resolve \
  --id <REFLECTION_ID> \
  --new-theory-id <UPDATED_THEORY_ID>

Session Integration

Sessions can be bound to theories, and will enter Reflecting state when dissonance is detected:

# Bind theory to session
./target/release/engram session bind-theory <SESSION_ID> --theory <THEORY_ID>

# Session automatically enters Reflecting state when reflection is triggered
./target/release/engram session trigger-reflection <SESSION_ID>

Integration with Theory Building

State Reflection is the validation mechanism for Theory Building:

1. Agent builds a theory about a domain
2. Agent encounters test failure or unexpected behavior
3. Agent creates a StateReflection to analyze the dissonance
4. If dissonance ≥ 0.7, agent must update the theory
5. Only after theory is updated can code fixes be attempted

This enforces Naur’s insight: the bug is often in the mental model, not the code.

Example Workflows

This section provides complete end-to-end examples of how to use Engram’s features together.

Example 1: Basic Development Workflow

A human developer working on a feature.

# 1. Start a session
SESSION_ID=$(engram session start --agent developer --json | jq -r '.id')
echo "Started session: $SESSION_ID"

# 2. Create a task
TASK_ID=$(engram task create \
  --title "Implement user login endpoint" \
  --priority high \
  --json | jq -r '.id')
echo "Created task: $TASK_ID"

# 3. Add context (research)
CONTEXT_ID=$(engram context create \
  --title "OAuth2 Password Grant Flow" \
  --source "https://oauth.net/2/grant-types/password/" \
  --json | jq -r '.id')
echo "Created context: $CONTEXT_ID"

# 4. Link context to task
engram relationship create \
  --source-id $TASK_ID \
  --target-id $CONTEXT_ID \
  --type references

# 5. Implement and make a decision
REASONING_ID=$(engram reasoning create \
  --title "Use bcrypt for password hashing" \
  --description "bcrypt has built-in salting and adjustable cost factor. Scrypt or Argon2 would also work but bcrypt is more widely supported." \
  --task-id $TASK_ID \
  --json | jq -r '.id')
echo "Recorded reasoning: $REASONING_ID"

# 6. Complete the task
engram task update --id $TASK_ID --status completed

Example 2: Theory Building for Codebase

An AI agent extracting mental models from a new codebase.

# 1. Start session as theorist agent
SESSION_ID=$(engram session start --agent the-theorist --json | jq -r '.id')

# 2. Create theories for major domains
THEORY_ID=$(engram theory create "Authentication System" --agent the-theorist --json | jq -r '.id')

# 3. Add conceptual model
engram theory update --id $THEORY_ID \
  --concept "User: An entity that can authenticate to the system with credentials"
engram theory update --id $THEORY_ID \
  --concept "Credential: Proof of identity (password, API key, OAuth token)"
engram theory update --id $THEORY_ID \
  --concept "Session: An authenticated context with a timeout"

# 4. Add system mappings
engram theory update --id $THEORY_ID \
  --mapping "User: src/entities/user.rs:42 (struct User)"
engram theory update --id $THEORY_ID \
  --mapping "Credential: src/entities/credential.rs:15 (enum CredentialType)"
engram theory update --id $THEORY_ID \
  --mapping "Session: src/entities/session.rs:28 (struct Session)"

# 5. Add design rationale
engram theory update --id $THEORY_ID \
  --rationale "Password hashing: Use bcrypt with cost factor 12 - balances security vs performance"
engram theory update --id $THEORY_ID \
  --rationale "Token expiry: 24 hours for access, 7 days for refresh - standard security practice"

# 6. Add invariants
engram theory update --id $THEORY_ID \
  --invariant "User.password_hash must never be NULL for users with PASSWORD credential type"
engram theory update --id $THEORY_ID \
  --invariant "Session.expires_at must be in the future for active sessions"
engram theory update --id $THEORY_ID \
  --invariant "A User may have multiple Credentials but at most one verified email"

# 7. Bind theory to session for future work
engram session bind-theory $SESSION_ID --theory $THEORY_ID

# 8. View the theory
engram theory show --id $THEORY_ID --show-metrics

Example 3: State Reflection Workflow

When code behavior conflicts with theory, use reflection.

# Assume we have a theory about authentication
THEORY_ID="abc123"

# 1. Agent encounters test failure
# Test claims: "User without password should not be able to login"
# Code behavior: Users without password CAN authenticate with empty string

# 2. Create a reflection
REFLECTION_ID=$(engram reflect create \
  --theory $THEORY_ID \
  --observed "Test failed: test_login_without_password() - expected auth failure but succeeded" \
  --trigger-type test_failure \
  --agent the-architect \
  --json | jq -r '.id')

# 3. Record the dissonance
engram reflect record-dissonance \
  --id $REFLECTION_ID \
  --description "Theory invariant states 'User.password_hash must never be NULL' but code allows empty string which passes validation"

# 4. Propose theory updates
engram reflect propose-update \
  --id $REFLECTION_ID \
  --update "Either: (1) Enforce password_hash NOT NULL at DB level, OR (2) Update invariant to 'Empty password_hash rejects authentication'"

# 5. Check if mutation required
engram reflect requires-mutation --id $REFLECTION_ID
# If exit code 0, theory mutation is REQUIRED

# 6. After fixing (either update code or theory), resolve
engram reflect resolve --id $REFLECTION_ID --new-theory-id $UPDATED_THEORY_ID

Example 4: Full AI Agent Workflow

Complete workflow from task creation to theory building to code implementation.

#!/bin/bash
# Full AI Agent Workflow Example

set -e

AGENT="assistant-001"
echo "=== Starting AI Agent Workflow ==="

# PHASE 1: Task Analysis
echo "Phase 1: Analyzing task requirements..."

TASK_ID=$(engram task create \
  --title "Add password reset feature" \
  --description "Implement password reset via email with time-limited tokens" \
  --priority high \
  --agent $AGENT \
  --json | jq -r '.id')

# PHASE 2: Research & Context
echo "Phase 2: Capturing research context..."

CONTEXT_IDS=()

# Store relevant docs
DOC_ID=$(engram context create \
  --title "JWT RFC 7519" \
  --source "https://datatracker.ietf.org/doc/html/rfc7519" \
  --agent $AGENT \
  --json | jq -r '.id')
CONTEXT_IDS+=($DOC_ID)

DOC_ID=$(engram context create \
  --title "Email Security Best Practices" \
  --source "https://example.com/email-security" \
  --agent $AGENT \
  --json | jq -r '.id')
CONTEXT_IDS+=($DOC_ID)

# Link contexts to task
for ctx_id in "${CONTEXT_IDS[@]}"; do
  engram relationship create \
    --source-id $TASK_ID \
    --target-id $ctx_id \
    --type references
done

# PHASE 3: Theory Building
echo "Phase 3: Building mental model..."

# Check if theory exists for relevant domain
THEORY_ID=$(engram theory list --agent $AGENT --json | jq -r '.[] | select(.domain_name == "Authentication") | .id' 2>/dev/null || echo "")

if [ -z "$THEORY_ID" ]; then
  THEORY_ID=$(engram theory create "Authentication" --agent $AGENT --json | jq -r '.id')
  
  engram theory update --id $THEORY_ID \
    --concept "User: Entity with authentication credentials"
  engram theory update --id $THEORY_ID \
    --concept "PasswordResetToken: Time-limited token for password reset"
  engram theory update --id $THEORY_ID \
    --concept "EmailNotification: Outbound email with reset link"
  engram theory update --id $THEORY_ID \
    --invariant "PasswordResetToken expires after 1 hour"
  engram theory update --id $THEORY_ID \
    --invariant "PasswordResetToken can only be used once"
fi

# Bind theory to session
SESSION_ID=$(engram session start --agent $AGENT --json | jq -r '.id')
engram session bind-theory $SESSION_ID --theory $THEORY_ID

# PHASE 4: Implementation
echo "Phase 4: Implementing feature..."

# Create subtasks
SUBTASK_1=$(engram task create \
  --title "Create PasswordResetToken entity" \
  --parent-id $TASK_ID \
  --agent $AGENT \
  --json | jq -r '.id')

SUBTASK_2=$(engram task create \
  --title "Implement token generation and validation" \
  --parent-id $TASK_ID \
  --agent $AGENT \
  --json | jq -r '.id')

SUBTASK_3=$(engram task create \
  --title "Add reset email template and sending" \
  --parent-id $TASK_ID \
  --agent $AGENT \
  --json | jq -r '.id')

# Record design decisions
engram reasoning create \
  --title "Use cryptographically secure random tokens" \
  --description "Tokens must be 32 bytes, URL-safe base64 encoded. Cannot use UUID as it's predictable." \
  --task-id $SUBTASK_2 \
  --agent $AGENT

engram reasoning create \
  --title "Store tokens as hash, not plain text" \
  --description "Prevents token leakage if database is compromised. Use same hashing as passwords." \
  --task-id $SUBTASK_2 \
  --agent $AGENT

# Update theory with new invariant discovered during implementation
engram theory update --id $THEORY_ID \
  --invariant "PasswordResetToken must be hashed before storage"

# PHASE 5: Verification
echo "Phase 5: Verifying implementation..."

# Run tests - if they fail, use reflection
TEST_RESULT=$(cargo test password_reset 2>&1 || true)

if echo "$TEST_RESULT" | grep -q "FAILED"; then
  echo "Tests failed - creating state reflection..."
  
  REFLECTION_ID=$(engram reflect create \
    --theory $THEORY_ID \
    --observed "$TEST_RESULT" \
    --trigger-type test_failure \
    --agent $AGENT \
    --json | jq -r '.id')
  
  engram reflect record-dissonance \
    --id $REFLECTION_ID \
    --description "Theory claims tokens expire in 1 hour but test expects 30 minutes"
  
  # Check if major theory update needed
  if engram reflect requires-mutation --id $REFLECTION_ID; then
    echo "Theory must be updated before fixing code"
    # Update theory...
  fi
fi

# PHASE 6: Complete
echo "Phase 6: Completing task..."

engram task update --id $SUBTASK_1 --status completed
engram task update --id $SUBTASK_2 --status completed
engram task update --id $SUBTASK_3 --status completed
engram task update --id $TASK_ID --status completed

echo "=== Workflow Complete ==="
echo "Task: $TASK_ID"
echo "Theory: $THEORY_ID"
echo "Session: $SESSION_ID"

Example 5: Multi-Agent Collaboration

Multiple agents working on the same codebase.

# Agent 1: The Architect - defines the theory
ARCHITECT_SESSION=$(engram session start --agent the-architect --json | jq -r '.id')

THEORY_ID=$(engram theory create "Payment Processing" --agent the-architect --json | jq -r '.id')

engram theory update --id $THEORY_ID \
  --concept "Payment: Money transfer request with amount, currency, status"
engram theory update --id $THEORY_ID \
  --invariant "Payment.amount must be positive"
engram theory update --id $THEORY_ID \
  --invariant "Payment.status must transition: pending -> processing -> completed|failed"

# Agent 2: The Developer - implements and may find dissonance
DEV_SESSION=$(engram session start --agent developer-001 --json | jq -r '.id')

# Developer binds to existing theory
engram session bind-theory $DEV_SESSION --theory $THEORY_ID

# Developer finds issue during implementation
REFLECTION_ID=$(engram reflect create \
  --theory $THEORY_ID \
  --observed "Business requirement: refunds must be possible within 30 days" \
  --trigger-type manual_observation \
  --agent developer-001 \
  --json | jq -r '.id')

engram reflect propose-update \
  --id $REFLECTION_ID \
  --update "Add invariant: Payment can only be refunded within 30 days of completion"

# Architect reviews and resolves
engram reflect resolve --id $REFLECTION_ID --new-theory-id $THEORY_ID

# Now both agents work with updated theory

These examples demonstrate how all Engram features integrate: Tasks, Context, Reasoning, Knowledge, Theory, StateReflection, Sessions, and Relationships.

Workflows

Workflows define state machines for processes, enabling complex multi-step operations.

CLI Usage

Workflow Definitions

# Create workflow
engram workflow create --title "Code Review" --description "Code review process"

# Add states
engram workflow add-state <ID> --name pending --description "Pending review" --state-type start
engram workflow add-state <ID> --name review --description "Under review" --state-type in_progress
engram workflow add-state <ID> --name approved --description "Approved" --state-type done --is-final
engram workflow add-state <ID> --name rejected --description "Rejected" --state-type done --is-final

# Add transitions
engram workflow add-transition <ID> --name "start_review" --from-state <FROM> --to-state <TO>
engram workflow add-transition <ID> --name "approve" --from-state <FROM> --to-state <TO> --transition-type automatic

# Activate workflow
engram workflow activate <ID>

Workflow Instances

# Start a workflow instance
engram workflow start <WORKFLOW_ID> --agent "the-architect"
engram workflow start <WORKFLOW_ID> --agent "the-architect" --entity-id <ID> --entity-type task
engram workflow start <WORKFLOW_ID> --agent "the-architect" --variables "key1=val1,key2=val2"
engram workflow start <WORKFLOW_ID> --agent "the-architect" --context-file context.json

# Execute a transition
engram workflow transition <INSTANCE_ID> --transition "approve" --agent "the-architect"

# Get instance status
engram workflow status <INSTANCE_ID>

# List instances
engram workflow instances
engram workflow instances --workflow-id <ID> --agent "the-architect" --running-only

# Cancel an instance
engram workflow cancel <INSTANCE_ID> --agent "the-architect" --reason "No longer needed"

Actions and Queries

# Execute an action
engram workflow execute-action --action-type external_command --command "make test"

# Query available actions, guards, and transitions
engram workflow query-actions <WORKFLOW_ID>
engram workflow query-actions <WORKFLOW_ID> --state-id <STATE_ID>

Use Cases

• Code review processes
• Incident response stages
• Deployment pipelines
• Task approval flows

Sessions

Sessions track work periods and can bind to theories for context-aware execution.

CLI Usage

# Start session
engram session start --name "the-architect"

# Show session status (with optional metrics)
engram session status --id <SESSION_ID>
engram session status --id <SESSION_ID> --metrics

# End session (with optional summary generation)
engram session end --id <SESSION_ID>
engram session end --id <SESSION_ID> --generate-summary

# List sessions
engram session list
engram session list --agent "the-architect" --since 7d --limit 20

# Detect zombie sessions (started but never ended)
engram session zombies
engram session zombies --max-age-hours 48 --check-git

# Summarize recent sessions
engram session summaries
engram session summaries --agent "the-architect" --since 2024-01-01

Session States

Theory Binding

When a session is bound to a theory:

• Theory invariants are injected into the session metadata
• Agents receive the theory context during execution
• Reflection state blocks code execution until theory is updated

Sync

Engram sync coordinates memory state across agents, branches, and configured remotes. It is designed for distributed agent work where each agent may maintain local state and later reconcile with shared refs.

CLI Usage

# Synchronize local agent state
engram sync sync --agents alice,bob --strategy latest_wins
engram sync sync --agents alice,bob --strategy intelligent_merge --dry-run

# Configure and inspect remotes
engram sync add-remote origin https://example.com/org/repo.git --branch main
engram sync list-remotes
engram sync status --remote origin
engram sync status --remote origin --json

# Pull, push, or do both in safe order
engram sync pull --remote origin --branch main
engram sync push --remote origin --branch main
engram sync both --remote origin --branch main

# Branch helpers
engram sync create-branch feature/my-agent --agent alice
engram sync switch-branch feature/my-agent
engram sync list-branches --all
engram sync delete-branch feature/my-agent --force

# Import existing git remotes into engram sync config
engram sync import-git-remotes

# Resolve reported remote conflicts
engram sync resolve --remote origin --strategy latest_wins

Conflict Strategies

Remote Status

engram sync status --remote <name> reports local/remote divergence, pending pushes, pending pulls, and conflicts. Use --json for automation.

Recommended Flow

1. engram sync pull --remote origin
2. Resolve conflicts if reported.
3. Run local validation.
4. engram sync push --remote origin

engram sync both --remote origin performs the pull-then-push sequence for routine use.

Schema

Engram can generate JSON Schema documents for built-in entity types and publish those schemas into the git-ref-backed store.

CLI Usage

# Generate a schema to stdout
engram schema generate --entity task
engram schema generate --entity reasoning

# Write a schema to a file
engram schema generate --entity workflow --output workflow.schema.json

# Publish all built-in schemas as engram refs
engram schema publish

# Backward-compatible workflow-only generator
engram schema workflow --output workflow.schema.json

Supported Entities

schema generate accepts short names such as task and full schema IDs such as engram-task.

Publish Behavior

engram schema publish serializes every built-in schema wrapper and stores it as a generic schema entity owned by the engram agent. Published schemas include:

• id
• namespace_pattern
• title
• crate version
• JSON Schema payload
• optional UI hints field

Use published schemas when external tools need to discover engram entity structure from the repository itself.

Health

Health commands inspect repository quality, collaboration risk, and engram graph consistency.

CLI Usage

# Run all health checks and compute an overall score
engram health audit
engram health audit --store

# Repository history signals
engram health churn --top 20
engram health bus-factor
engram health bug-clusters --top 20
engram health velocity
engram health firefighting
engram health commit-size
engram health test-signal

# Entity graph checks
engram health score
engram health orphans
engram health consistency

# Refresh knowledge decay weights and citation counts
engram health refresh-decay --lambda 0.01

Checks

Stored Audits

engram health audit --store records the audit result as an engram context entity so future agents can use it during planning and handoff.

Doc

The doc command manages documentation fragments stored in engram and can assemble them into mdBook-compatible source files.

CLI Usage

# Build mdBook source from stored documentation fragments
engram doc build --output docs

# Discover topics and chunks
engram doc topics list
engram doc chunk list <topic>

# Write a chunk
engram doc write tasks task-overview --title "Task Overview" --order 10 --stdin
engram doc write tasks task-overview --title "Task Overview" --file overview.md

# Inspect documentation state
engram doc status
engram doc refs
engram doc fetch

Built-in Topics

• adrs
• decisions
• tasks
• knowledge
• theories
• workflows
• sessions
• reasoning
• standards
• overview

Staleness

Doc fragments can reference source entity IDs. When those entities change, the fragment can be marked stale and regenerated/reviewed.

mdBook Deployment

The GitHub Pages workflow runs mdbook build. Every file referenced in docs/SUMMARY.md must exist under docs/, and book.toml must use keys supported by the mdBook version installed in CI.

Analytics

Analytics commands compute delivery and task-flow metrics from engram entities and repository history.

CLI Usage

# DORA metrics over a time window
engram analytics dora --window-days 30

# Task duration report
engram analytics report

# Slowest tasks and bottlenecks
engram analytics bottleneck --top 10

Reports

Metrics

• Deployment frequency — how often changes are delivered.
• Lead time for changes — elapsed time from change/task start to delivery.
• Change failure rate — share of changes associated with failure signals.
• Mean time to recovery — time to recover from incidents or regressions.
• Task duration and bottlenecks — elapsed task time and slow-flow areas.

Analytics output is intended for both human review and agent planning: agents can use bottleneck and DORA signals to prioritize remediation work.

Personas & Lessons

Personas describe reusable agent roles. Lessons capture reusable experience, prevention rules, and patterns learned during work.

Persona CLI Usage

# Create a persona
engram persona create \
  --slug rust-expert \
  --title "Rust Expert" \
  --instructions "Review Rust code for correctness and maintainability" \
  --domain rust

# List and inspect personas
engram persona list
engram persona list --domain rust
engram persona show --id rust-expert

# Update or remove personas
engram persona update --id rust-expert --add-tag async
engram persona delete --id rust-expert

Lesson CLI Usage

# Create and list lessons
engram lesson create --title "Validate slug input" --domain rust --category code
engram lesson list
engram lesson show --id <LESSON_ID>

# Promote lessons into standards or rules when applicable
engram lesson update --id <LESSON_ID> --severity high

Usage

Use personas to select the right operating mode for an agent, then record lessons when work reveals durable knowledge that should guide future sessions.

Locus TUI

Locus is Engram’s terminal UI for browsing and navigating project memory without leaving the terminal.

What It Shows

Locus provides views over common engram entities, including:

• Tasks
• Context
• Reasoning
• ADRs
• Knowledge
• Relationships
• Sessions
• Theories
• Sync status

Usage

# Start the TUI
locus

# Or, when installed as an engram binary target, run the locus executable from the build output
cargo run --bin locus

Navigation

Use the keyboard-driven interface to switch views, inspect details, and refresh current state. Locus reads the same git-backed engram storage as the CLI, so CLI changes and TUI views stay aligned.

Using Engram

Role Definition

You are an autonomous agent using Engram as your exclusive source of truth for task management, context discovery, and workflow execution. You NEVER rely on prompt injection or external context - all task information, relationships, and state must be retrieved from the Engram CLI. Store enough detail in Engram that a later model or agent can recover and continue if the current model fails, times out, or loses context.

Source of Truth

Strict Engram Reliance: All context, task descriptions, relationships, and state must come from Engram CLI commands. Do not assume information from prompts or external sources.

Skills Integration

Engram provides specialized skills for common workflows. Use these skills to ensure consistent, engram-integrated execution.

Available Skills

./skills/
├── meta/
│   ├── use-engram-memory.md      # Core memory integration skill
│   ├── delegate-to-agents.md     # Delegation using engram-adapted agents
│   └── audit-trail.md            # Complete audit documentation
├── workflow/
│   └── plan-feature.md           # Feature planning with engram tasks
└── compliance/
    └── check-compliance.md       # Compliance checking with engram storage

Using Skills

When starting any work, check if a relevant skill exists:

# Check available skills
ls ./skills/

# Use a skill by reading its documentation
cat ./skills/meta/use-engram-memory.md

Prompt Templates

Engram provides engram-adapted agent prompts that integrate with the memory system.

Agent Prompts

./prompts/agents/
├── 01-the-one.yaml              # Orchestrator (adapted)
├── 03-the-architect.yaml        # Architecture design (adapted)
├── 05-the-deconstructor.yaml    # Task breakdown (adapted)
├── _template-engram-adapted.yaml # Template for adapting agents
└── [160+ specialized agents]

Pipeline Templates

./prompts/ai/pipelines/
├── 01-greenfield-feature-launch.yaml  # Feature development pipeline (adapted)
├── _template-engram-adapted.yaml       # Template for adapting pipelines
└── [100+ specialized pipelines]

Compliance Prompts

./prompts/compliance_and_certification/
└── prompts/audit_checkpoints/
    ├── igaming/           # Gaming compliance (GLI, MGA, UKGC)
    ├── saas_it/           # SOC2, ISO27001, PCI DSS
    ├── data_protection/   # GDPR, CCPA, PIPEDA
    ├── eu_regulations/    # DSA, DMA, AI Act, NIS2, DORA
    ├── gaming_certification/  # RNG, RTP, Fairness
    ├── software_development/  # OWASP, SDL, ISO 12207
    ├── german_compliance/     # GoBD, DSGVO, BSI
    ├── medical_device/        # IEC 62304
    ├── cross_compliance/      # Multi-framework integration
    └── cybersecurity_policies/ # NIST CSF, RMF, ISO 27002

Workflow Protocol

1. Task Initialization

# Update status to in_progress
engram task update {{TASK_ID}} --status inprogress

# Discover all related context
engram relationship connected --entity-id {{TASK_ID}}

# Read task description
engram task show {{TASK_ID}}

2. Context Discovery

# Find all references (context, docs, designs)
engram relationship connected --entity-id {{TASK_ID}} --relationship-type references

# Find reasoning (decisions, trade-offs)
engram relationship connected --entity-id {{TASK_ID}} --relationship-type documents

# Find subtasks (if task has children)
engram relationship connected --entity-id {{TASK_ID}} --relationship-type contains

# Get specific entity details
engram context show [CONTEXT_ID]
engram reasoning show [REASONING_ID]

3. Execution Phase

# Locate files via relationships
engram relationship connected --entity-id {{TASK_ID}} | grep -E "context|reasoning"

# Perform work (coding, writing, etc.)

# Store progress as reasoning
engram reasoning create \
  --title "[Work] Progress: [What was done]" \
  --task-id {{TASK_ID}} \
  --content "[Details of work completed, files touched, commands run, partial findings, blockers, and next step for recovery]"

# Store final result as context
engram context create \
  --title "[Result] [Work Description]" \
  --content "[Output, findings, or artifact summary]"

# Link result to task
engram relationship create \
  --source-id {{TASK_ID}} \
  --target-id [RESULT_CONTEXT_ID] \
  --produces

# Commit with task reference
git commit -m "type: description [{{TASK_ID}}]"

4. Completion

# Validate workflow compliance
engram validate check

# Update task status
engram task update {{TASK_ID}} --status done --outcome "[Summary of work]"

# Output summary
echo "Task {{TASK_ID}} completed. Entities created: [CONTEXT_ID], [REASONING_ID]"

Optimization Principles

• Context-First: Always gather complete context via Engram before starting execution
• Relationship Navigation: Use relationship traversal as the primary discovery mechanism
• Entity Linking: Link all created artifacts back to tasks for future discoverability
• Progress Tracking: Store progress as reasoning entities, not just in conversation
• Recovery Checkpoints: Before risky or long-running work, store current state, assumptions, files touched, commands run, blockers, and next steps for a later model
• Skills Usage: Check for relevant skills before starting work

Error Handling

• If a task ID is invalid: Stop and report the error
• If required relationships are missing: Create them or request clarification
• If context is incomplete: Use relationship traversal to find more information
• Never proceed without full Engram-validated context

Integration with External Prompts

When using external prompts (from ./prompts/), always adapt them:

1. Add task_id parameter to all prompts
2. Include engram commands in the prompt body
3. Update response schema to return engram entity IDs
4. Link outputs to the parent task via relationships

Example adaptation pattern:

# Original parameter
parameters:
  properties:
    context:
      type: string
      description: "The context"

# Adapted parameter
parameters:
  properties:
    task_id:
      type: string
      description: "The engram task ID for this work"
    context:
      type: string
      description: "The context"
  required:
    - task_id
    - context

Engram Prompt Engineering Guide

This guide explains how to construct effective prompts for agents using the Engram CLI. The goal is to create deterministic, context-rich workflows where agents rely exclusively on Engram as their source of truth.

Philosophy

• Single Source of Truth: Agents should look up task context via engram task show and engram relationship, not rely on prompt injection.
• Atomic Operations: Workflows should be broken down into discrete steps tracked by Engram tasks.
• Evidence-Based Validation: Every step must be verifiable via engram validate with provide evidence-based validation for all final claims instead of unsubstantiated assertions.
• Skills First: Check for existing skills before creating new prompts.
• Recovery-Ready Memory: Prompts should require agents to store enough detail in Engram for a later model or agent to resume if the current model fails, times out, or loses context.

Available Prompts

Engram provides pre-built engram-adapted prompts for common workflows.

Agent Prompts (170+)

Location: ./engram/prompts/agents/

Pipeline Templates (100+)

Location: ./engram/prompts/ai/pipelines/

Compliance Prompts (250+)

Location: ./engram/prompts/compliance_and_certification/prompts/audit_checkpoints/

Evidence-Based Validation Requirements

CRITICAL: All prompts must enforce evidence-based validation for all final claims instead of unsubstantiated assertions.

Required Evidence Types

Every assertion or claim must be supported by at least one of:

1. Code Evidence

   • Specific function names, file paths, and line numbers
   • Actual code snippets demonstrating the claim
   • Test results showing behavior

2. Execution Evidence

   • Command outputs with timestamps
   • Log files or error messages
   • Performance metrics or benchmarks

3. Documentation Evidence

   • Citations from official documentation
   • Links to specifications or standards
   • References to established patterns or frameworks

4. Measurement Evidence

   • Quantifiable metrics (e.g., “reduced from 500ms to 120ms”)
   • Test coverage percentages
   • Before/after comparisons

Evidence Format Requirements

## Claim: [Your assertion]

### Evidence:
- **Code Reference**: `src/file.rs:123` - Function `process_data()` shows...
- **Test Results**: `cargo test` output showing 100% pass rate
- **Execution Log**: `[2024-01-26 10:15:32] Successfully processed 1,247 records`
- **Documentation**: https://docs.rust-lang.org/std/result/enum.Result.html

Invalid Examples

❌ “The code is more efficient” ❌ “This improves security” ❌ “The refactoring is better”

Valid Examples

✅ “Reduced processing time from 500ms to 120ms (60% improvement) as measured by hyperfine benchmarks” ✅ “Fixed buffer overflow vulnerability in src/parser.rs:45 by adding bounds check, verified by cargo-audit scan” ✅ “Increased test coverage from 72% to 95% in src/utils/ module, confirmed by cargo tarpaulin report”

Standard Prompt Template

Use this template to instruct agents. Replace {{TASK_ID}} with the actual UUID.

You are an autonomous agent using Engram for state management.
**Task ID**: `{{TASK_ID}}`

### Protocol

1. **Initialize**:
   ```bash
   engram task update {{TASK_ID}} --status inprogress
   engram relationship connected --entity-id {{TASK_ID}} to find related context/reasoning.

2. Execute:

   • Read the task description: engram task show {{TASK_ID}}
   • Access linked contexts: engram context show [CONTEXT_ID]
   • Store progress: engram reasoning create --title "[Progress]" --task-id {{TASK_ID}} --content "[Details]"
   • Store recovery checkpoints before risky or long-running work so a later model can continue after failure: include files touched, commands run, partial findings, blockers, and the next step.

3. Validate:

   • Run engram validate check
   • Run tests/linters as required by the task
   • Evidence-Based Validation: Provide evidence-based validation for all final claims instead of unsubstantiated assertions. Every assertion must be supported by:
     • Concrete evidence from code, tests, logs, or documentation
     • Verifiable measurements or test results
     • Specific examples or citations
     • Quantifiable metrics where applicable

4. Complete:

   • Store result: engram context create --title "[Result]" --content "[Output]"
   • Link result: engram relationship create --source-id {{TASK_ID}} --target-id [RESULT_ID] --produces
   • Update status: engram task update {{TASK_ID}} --status done

## Engram-Adapted Prompt Pattern

All engram-adapted prompts follow this pattern:

### 1. Parameters Include task_id

```yaml
parameters:
  properties:
    task_id:
      type: string
      description: "The engram task ID for this work"
    context:
      type: string
      description: "Additional context"
  required:
    - task_id
    - context

2. Engram Commands in Prompt Body

YOUR WORK:

STEP 1: Retrieve task
```bash
engram task show {{task_id}}

STEP 2: Get related context

engram relationship connected --entity-id {{task_id}} --references

STEP 3: Store progress

engram reasoning create --title "[Work] Progress" --task-id {{task_id}} --content "[What you did]"

STEP 4: Complete

engram context create --title "[Result]" --content "[Output]"
engram relationship create --source-id {{task_id}} --target-id [RESULT_ID] --produces
engram task update {{task_id}} --status done --outcome "[Summary]"

### 3. Response Includes Entity IDs

```yaml
response:
  format: json
  schema:
    type: object
    properties:
      task_id:
        type: string
        description: "The task ID (echoed for confirmation)"
      status:
        type: string
        enum: ["completed", "in_progress"]
        description: "Status of work"
      result_context_id:
        type: string
        description: "The engram context ID for the result"
    required:
      - task_id
      - status
      - result_context_id

Workflow Examples

1. Research & Planning

For tasks requiring investigation before implementation.

**Phase**: Research
**Goal**: Analyze requirements and create a plan.

1. Initialize:
   ```bash
   engram task update {{TASK_ID}} --status inprogress

2. Gather Info:

   engram relationship connected --entity-id {{TASK_ID}} --references
   engram context list | grep -i [keyword]
   

3. Document Plan:

   engram reasoning create \
     --title "Research: [Topic] - Findings" \
     --task-id {{TASK_ID}} \
     --content "[Research findings]"
   
   engram context create \
     --title "Plan: [Feature] Implementation" \
     --content "[Implementation approach]"
   
   engram relationship create \
     --source-id {{TASK_ID}} \
     --target-id [PLAN_CONTEXT_ID] \
     --references
   

4. Complete:

   engram task update {{TASK_ID}} --status done --outcome "Research complete, plan created"
   

2. Using Engram-Adapted Agent

For delegating work to specialized agents.

**Agent**: [Agent Name from ./engram/prompts/agents/]
**Task ID**: {{TASK_ID}}

1. The agent should retrieve its task:
   ```bash
   engram task show {{TASK_ID}}

2. The agent should get context:

   engram relationship connected --entity-id {{TASK_ID}} --references
   

3. The agent should store progress:

   engram reasoning create --title "[Agent] Progress" --task-id {{TASK_ID}} --content "[What was done]"
   

4. The agent should complete:

   engram context create --title "[Agent] Result" --content "[Output]"
   engram relationship create --source-id {{TASK_ID}} --target-id [RESULT_ID] --produces
   engram task update {{TASK_ID}} --status done --outcome "[Summary]"
   

Example agents:

• Architecture: Use ./engram/prompts/agents/03-the-architect.yaml
• Task Breakdown: Use ./engram/prompts/agents/05-the-deconstructor.yaml
• Testing: Use ./engram/prompts/agents/15-the-tester.yaml
• Documentation: Use ./engram/prompts/agents/41-the-technical-writer.yaml

3. Using Pipeline

For multi-stage workflows.

**Pipeline**: Feature Development
**Template**: ./engram/prompts/ai/pipelines/01-greenfield-feature-launch.yaml

1. Creates engram workflow with stages: strategy → architecture → breakdown
2. Calls engram-adapted agents for each stage
3. Stores all outputs in engram entities
4. Returns workflow ID and created entity IDs

Parameters:
- feature_idea: "Description of feature"
- parent_task_id: "{{TASK_ID}}"

4. Compliance Checking

For verifying work against compliance frameworks.

**Compliance Check**: [Framework]
**Prompts**: ./engram/prompts/compliance_and_certification/prompts/audit_checkpoints/[framework]/

1. Get context:
   ```bash
   engram context list | grep [compliance-area]

2. Run compliance check:

   # Use relevant compliance prompts from:
   # ./engram/prompts/compliance_and_certification/prompts/audit_checkpoints/
   

3. Store results:

   engram compliance create \
     --title "Compliance: [Feature] - [Framework]" \
     --category [security/privacy/quality] \
     --requirements "✅ [Requirement 1]\n✅ [Requirement 2]"
   
   engram context create \
     --title "Audit: [Feature] - [Framework]" \
     --content "[Audit findings]"
   
   engram relationship create \
     --source-id {{TASK_ID}} \
     --target-id [AUDIT_CONTEXT_ID] \
     --fulfills
   

5. Documentation

For writing docs.

**Phase**: Documentation
**Goal**: Update documentation to match code/specs.

1. Initialize:
   ```bash
   engram task update {{TASK_ID}} --status inprogress

2. Get source:

   engram relationship connected --entity-id {{TASK_ID}} --references
   

3. Write:

   • Update markdown files
   • Reference engram entities in docs

4. Store:

   engram context create \
     --title "Documentation: [File/Feature]" \
     --content "[Summary of docs updated]"
   
   engram relationship create \
     --source-id {{TASK_ID}} \
     --target-id [DOC_CONTEXT_ID] \
     --produces
   

5. Commit:

   git commit -m "docs: update [file] [{{TASK_ID}}]"
   

6. Complete:

   engram task update {{TASK_ID}} --status done --outcome "Documentation complete"
   

Best Practices

• No Hallucinations: If a UUID isn’t found, stop and error out. Don’t invent IDs.
• Link Everything: If you create a new artifact (file, module), create a corresponding Engram entity and link it to the task.
• Status Hygiene: Always move tasks to inprogress before starting and done only after validation.
• Evidence-Based Validation: Provide evidence-based validation for all final claims instead of unsubstantiated assertions. Every claim must be backed by:
  • Verifiable evidence (code, tests, logs, documentation)
  • Specific examples and citations
  • Quantifiable metrics and measurements
  • Test results or execution outputs
• Skills First: Check ./engram/skills/ for existing skills before creating new prompts.
• Use Adapted Prompts: Prefer engram-adapted prompts from ./engram/prompts/ over generic prompts.
• Store Progress: Don’t just complete tasks - store intermediate progress as reasoning entities.
• Checkpoint for Model Failure: Store recovery-grade details throughout the session so a different model can resume without relying on the current conversation.

Prompt Locations Quick Reference

CLI Reference

This reference reflects the current top-level engram CLI command surface. Run engram <command> --help for full flag detail and current defaults.

Setup and Onboarding

engram setup workspace
engram setup agent --name <NAME> --type <TYPE>
engram setup skills
engram setup prompts

engram guide onboarding
engram guide getting-started
engram guide examples

engram info
engram next

Core Memory Entities

# Tasks
engram task create --title <TEXT> [--priority high|medium|low|critical]
engram task list [--status <STATUS>] [--agent <NAME>]
engram task show <ID>
engram task update <ID> --status <STATUS>
engram task archive <ID>
engram task archive-bulk [--status done]
engram task resolve <ID>
engram task create-batch --file <JSON_FILE>

# Context
engram context create --title <TEXT> [--source <URL>] [--content <TEXT>]
engram context list [--agent <NAME>]
engram context show <ID>
engram context update <ID> [--title <TEXT>] [--content <TEXT>]
engram context delete <ID>

# Reasoning
engram reasoning create --title <TEXT> [--description <TEXT>] [--task-id <ID>]
engram reasoning add-step <ID> --content <TEXT>
engram reasoning conclude <ID> --conclusion <TEXT>
engram reasoning list [--task-id <ID>]
engram reasoning show <ID>
engram reasoning history <ID>
engram reasoning export <ID> --output <FILE>
engram reasoning search [--ibis-type question|idea|pro|con|reference|note] [--polarity pro|con]
engram reasoning log <ID> --event-type <TYPE> --content <TEXT>
engram reasoning delete <ID>

# Knowledge
engram knowledge create --title <TEXT> [--content <TEXT>] [--type fact|pattern|rule|concept|procedure|heuristic]
engram knowledge list [--type <TYPE>] [--agent <NAME>]
engram knowledge show <ID>
engram knowledge update <ID> [--title <TEXT>] [--content <TEXT>]
engram knowledge delete <ID>

# Relationships
engram relationship create --source-id <ID> --target-id <ID> --type <TYPE>
engram relationship list [--source-id <ID>] [--target-id <ID>]
engram relationship get <ID>
engram relationship delete <ID>
engram relationship find-path --from <ID> --to <ID>
engram relationship connected --entity-id <ID> [--max-depth <N>]
engram relationship stats

Process, Governance, and Decisions

# ADRs
engram adr create --title <TEXT> --context <TEXT>
engram adr list
engram adr get <ID>
engram adr update <ID>
engram adr accept <ID>
engram adr add-alternative <ID>
engram adr add-stakeholder <ID>
engram adr delete <ID>

# Workflows
engram workflow create --title <TEXT> [--description <TEXT>]
engram workflow add-state <WORKFLOW_ID> --name <NAME>
engram workflow add-transition <WORKFLOW_ID> --from-state <FROM> --to-state <TO>
engram workflow activate <WORKFLOW_ID>
engram workflow start <WORKFLOW_ID> [--entity-id <ID>] [--agent <NAME>]
engram workflow transition <INSTANCE_ID> --transition <NAME>
engram workflow status <INSTANCE_ID>
engram workflow instances [--workflow-id <ID>] [--running-only]
engram workflow cancel <INSTANCE_ID>
engram workflow execute-action --action-type <TYPE>
engram workflow query-actions <WORKFLOW_ID>

# Rules, standards, compliance
engram rule create|get|update|delete|list|execute
engram standard create|get|update|delete|list|add-requirement
engram compliance create|list|show|update|delete

Sessions, Theories, and Reflection

engram session start --name <NAME> [--auto-detect]
engram session status --id <SESSION_ID> [--metrics]
engram session end --id <SESSION_ID> [--generate-summary]
engram session list [--agent <NAME>] [--since <DATE_OR_DURATION>]
engram session zombies [--max-age-hours <N>] [--check-git]
engram session summaries [--agent <NAME>]

engram theory create <DOMAIN> [--agent <NAME>] [--task <ID>]
engram theory list [--agent <NAME>] [--domain <DOMAIN>]
engram theory show --id <ID> [--show-metrics]
engram theory update --id <ID>
engram theory apply-reflection --id <ID> --reflection <ID>
engram theory history --id <ID>
engram theory decay [--max-weight <F64>]
engram theory delete --id <ID>

engram reflect create --theory <ID> --observed <TEXT> --trigger-type <TYPE>
engram reflect list [--agent <NAME>] [--severity <LEVEL>]
engram reflect show --id <ID>
engram reflect record-dissonance --id <ID> --description <TEXT>
engram reflect propose-update --id <ID> --update <TEXT>
engram reflect resolve --id <ID> [--new-theory-id <ID>]
engram reflect requires-mutation --id <ID>
engram reflect delete --id <ID>

Git, Sync, Validation, and Migration

# gix-backed git porcelain: no production shell-outs
engram git status
engram git log
engram git checkpoint --message <TEXT>
engram git verify-history

# Multi-agent and remote sync
engram sync sync --agents alice,bob --strategy latest_wins
engram sync add-remote origin <URL> --branch main
engram sync list-remotes
engram sync status --remote origin [--json]
engram sync pull --remote origin [--branch main]
engram sync push --remote origin [--branch main]
engram sync both --remote origin [--branch main]
engram sync resolve --remote origin --strategy <STRATEGY>
engram sync import-git-remotes

# Validation hooks and checks
engram validate hook install
engram validate hook status
engram validate commit --message "feat: title [<TASK_UUID>]"
engram validate check

# Storage migration/repair
engram migration
engram migrate triple-nesting

Documentation, Schemas, Skills, and Prompts

engram doc build --output docs
engram doc topics list
engram doc chunk list <TOPIC>
engram doc write <TOPIC> <CHUNK_ID> --title <TEXT> --stdin
engram doc status
engram doc refs
engram doc fetch

engram schema generate --entity task --output task.schema.json
engram schema generate --entity reasoning
engram schema publish
engram schema workflow --output workflow.schema.json

engram skills setup
engram skills list
engram skills show <NAME>

engram prompts list [--category <NAME>]
engram prompts show <NAME>
engram prompts validate

Security, Backup, Analytics, and Evolution

engram sandbox create|list|get|update|delete|validate|stats|check|reset
engram escalation create|list|get|review|cancel|cleanup|approve|deny|stats

engram perkeep backup|restore|list|health|config

engram analytics dora --window-days 30
engram analytics report
engram analytics bottleneck --top 10

engram health audit [--store]
engram health churn --top 20
engram health bus-factor
engram health bug-clusters --top 20
engram health velocity
engram health firefighting
engram health commit-size
engram health test-signal
engram health score
engram health orphans
engram health consistency
engram health refresh-decay --lambda 0.01

engram evo ingest|evaluate|optimize|replay|loop|report

Experimental Commands

engram convert
engram test

convert is present in the command surface and marked experimental/not yet implemented by the CLI help.

Entity Schema

ADR

AgentSandbox

BottleneckReport

Compliance

Context

DocFragment

DoraMetricsReport

EscalationRequest

ExecutionResult

Knowledge

Lesson

Persona

ProgressiveGateConfig

Reasoning

ReasoningStep

IbisPosition

Relationship

Rule

Session

Standard

StateReflection

StaleTaskReport

Task

TaskDurationReport

Theory

Workflow

WorkflowInstance

API Reference

Rust API

For Rust API documentation, see the source code in src/.

Core Traits

#![allow(unused)]
fn main() {
pub trait Entity {
    fn entity_type() -> &'static str;
    fn id(&self) -> &str;
    fn agent(&self) -> &str;
    fn timestamp(&self) -> DateTime<Utc>;
    fn validate_entity(&self) -> Result<()>;
    fn to_generic(&self) -> GenericEntity;
    fn from_generic(entity: GenericEntity) -> Result<Self>;
}
}

Storage Trait

#![allow(unused)]
fn main() {
pub trait Storage {
    fn store(&mut self, entity: &GenericEntity) -> Result<()>;
    fn get(&self, id: &str, entity_type: &str) -> Result<Option<GenericEntity>>;
    fn list_ids(&self, entity_type: &str) -> Result<Vec<String>>;
    fn delete(&mut self, id: &str, entity_type: &str) -> Result<()>;
}
}

Validation Reference

Engram validation protects task traceability and repository quality gates.

Commit Message Validation

Commits must reference a valid engram task UUID:

<type>: <title> [<ENGRAM_TASK_UUID>]

Example:

fix: resolve sync conflict handling [171af123-9b96-48b1-b071-deba76492dac]

CLI Usage

# Install git hooks
engram validate hook install

# Run validation checks
engram validate check

# Inspect validation configuration and results
engram validation list
engram validation run

Quality Gates

Validation can enforce:

• Commit/task linkage
• Required reasoning relationships
• Repository consistency
• Configured rule and quality-gate checks

See also Validation.

Setup & Configuration

Building

# Clone and build
cargo build --release

# Run tests
cargo test

# Run with debug
cargo run -- --help

Configuration

Engram stores data in .git/refs/engram/. No additional config required.

Git Integration

Install the validation hook to enforce task linking:

engram validate hook install

This prevents commits without task IDs.

Contributing

Adding New Entities

1. Define entity in src/entities/
2. Implement Entity trait
3. Add CLI commands in src/cli/
4. Register storage handler
5. Add tests

Adding New CLI Commands

1. Create file in src/cli/
2. Define command enum with clap::Subcommand
3. Implement handler functions
4. Register in src/main.rs

Running Tests

# Run all tests
cargo test

# Run specific module
cargo test --lib entities

# Run with output
cargo test -- --nocapture

Engram Validation Configuration

Validation Rules Configuration

The validation system supports flexible configuration through YAML files or CLI options.

Configuration File

Create a .engram/validation.yaml file in your project root:

enabled: true
require_task_reference: true
require_reasoning_relationship: true
require_context_relationship: true
require_file_scope_match: true

task_id_patterns:
  - pattern: '\[([A-Z]+-\d+)\]'
    name: "Brackets format"
    example: "[TASK-123]"
  - pattern: '\[task:([a-z0-9-]+)\]'
    name: "Colon format"
    example: "[task:auth-impl-001]"
  - pattern: 'Refs:\s*#(\d+)'
    name: "Refs format"
    example: "Refs: #456"

exemptions:
  - message_pattern: '^(chore|docs):'
    skip_validation: false
    skip_specific:
      - "require_task_reference"
  - message_pattern: '^fixup!'
    skip_validation: true
  - message_pattern: '^amend!'
    skip_validation: true

performance:
  cache_ttl_seconds: 300
  max_cache_entries: 1000
  enable_parallel_validation: true
  validation_timeout_seconds: 30

Environment Variables

You can override configuration with environment variables:

• ENGRAM_VALIDATION_ENABLED - Enable/disable validation
• ENGRAM_VALIDATION_STRICT - Enable strict mode (no exemptions)
• ENGRAM_VALIDATION_CACHE_TTL - Cache TTL in seconds
• ENGRAM_VALIDATION_TIMEOUT - Validation timeout in seconds

CLI Commands

# Validate a commit message
engram validate commit --message "feat: implement authentication [TASK-123]"

# Validate with dry run (doesn't require git repo)
engram validate commit --message "test commit" --dry-run

# Install pre-commit hook
engram validate hook install

# Check hook status
engram validate hook status

# Uninstall hook
engram validate hook uninstall

Configuration Priority

1. Environment variables (highest priority)
2. Project configuration file (.engram/validation.yaml)
3. User configuration file (~/.engram/validation.yaml)
4. Default configuration

Performance Tuning

For optimal performance:

1. Cache Configuration: Tune cache settings in validation.yaml

   performance:
     enable_parallel_validation: true
     max_cache_entries: 5000  # For large repositories
     cache_ttl_seconds: 600   # 10 minutes
   

Advanced Configuration

Custom Task ID Patterns

Add your own task ID patterns:

task_id_patterns:
  - pattern: 'PROJECT-(\d+)'
    name: "Project format"
    example: "PROJECT-123"
  - pattern: 'jira/([A-Z]+-\d+)'
    name: "JIRA format"
    example: "jira/PROJ-123"

Custom Exemptions

Create exemptions for specific commit types:

exemptions:
  - message_pattern: '^(hotfix|emergency):'
    skip_validation: false
    skip_specific:
      - "require_reasoning_relationship"
      - "require_context_relationship"
  - message_pattern: '^WIP:'
    skip_validation: true
    reason: "Work in progress commits"

Integration with CI/CD

GitHub Actions

- name: Validate Commit
  run: |
     engram validate commit --message "${{ github.event.head_commit.message }}"

GitLab CI

validate-commit:
  stage: validate
  script:
    - engram validate commit --message "$CI_COMMIT_MESSAGE"

Troubleshooting

Common Issues

1. Hook not found

   # Check if engram is in PATH
   which engram
   
   # Install hook manually
   engram validate hook install
   

2. Validation timeout

   performance:
     validation_timeout_seconds: 60  # Increase timeout
   

3. False positives

   # Add custom exemptions
   exemptions:
     - message_pattern: '^merge:'
       skip_validation: true
   

Best Practices

1. Consistent Format: Use one task ID format across your team
2. Regular Updates: Keep cache TTL reasonable for your commit frequency
3. Appropriate Exemptions: Use exemptions for automated commits, not to bypass quality
4. Performance Monitoring: Use cache stats to monitor effectiveness

Migration Guide

When upgrading validation configuration:

1. Backup: Copy your .engram/validation.yaml file

2. Update: Modify configuration file

3. Validate: Test new configuration

   engram validate check
   

4. Deploy: Roll out to team with documentation