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

Engram is a distributed memory system for AI agents and human operators. It acts as a “second brain” for your software projects.

Installation

# Clone the repository
git clone https://github.com/vincents-ai/engram.git
cd engram

# Build the binary
cargo build --release

# Add to PATH
export PATH="$PWD/target/release:$PATH"

Quick Setup

# Initialize workspace
./target/release/engram setup workspace

# Create your profile
./target/release/engram setup agent --name "Your Name" --agent-type operator

Core Workflow

The Engram workflow follows a simple cycle: Plan → Execute → Remember.

1. Plan

# Create a task
./target/release/engram task create --title "Add user authentication" --priority high

2. Execute & Document

# Store context
./target/release/engram context create --title "OAuth2 Spec" --source "https://oauth.net/2/"

# Link to task
./target/release/engram relationship create --source-id <TASK_ID> --target-id <CONTEXT_ID> --type references

3. Remember

# Record a decision
./target/release/engram reasoning create --title "Chose JWT for stateless auth" --task-id <TASK_ID>

Next Steps

• User Guide - Full workflow documentation
• Theory Building - Capture mental models
• CLI Reference - Command reference

Engram User Guide

Welcome to Engram! This guide is written for human operators—developers, product managers, and architects who want to use Engram to manage their software projects.

What is Engram?

Engram is a “second brain” for your code. While Git tracks what changed (the code), Engram tracks why it changed (the reasoning), how you planned it (the tasks), and what you learned along the way (the context).

It lives inside your repository but doesn’t clutter your files. Engram stores data directly in your .git database using custom references (refs/engram/). This means your project management is version-controlled without you ever having to git add a task file.

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 --agent 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] --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 --search "timeout"

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 inprogress 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, Relationship      │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│           Storage Layer                │
│  (src/storage/*.rs)                    │
│  - GitStorage                          │
│  - MemoryStorage                       │
└─────────────────────────────────────────┘

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>

# List reasoning
engram reasoning list
engram reasoning list --task-id <TASK_ID>

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

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

Types

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

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

# Add states
engram workflow add-state --name pending --workflow-id <ID>
engram workflow add-state --name review --workflow-id <ID>
engram workflow add-state --name approved --workflow-id <ID>
engram workflow add-state --name rejected --workflow-id <ID>

# Add transitions
engram workflow add-transition --from pending --to review --workflow-id <ID>
engram workflow add-transition --from review --to approved --workflow-id <ID>
engram workflow add-transition --from review --to rejected --workflow-id <ID>

# Update state
engram workflow transition --to review --id <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 --agent "the-architect"

# Bind theory to session
engram session bind-theory <SESSION_ID> --theory <THEORY_ID>

# Trigger reflection (when dissonance detected)
engram session trigger-reflection <SESSION_ID>

# Resolve reflection
engram session resolve-reflection <SESSION_ID>

# End session
engram session end <SESSION_ID>

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

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.

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]"

# 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
• 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.

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]"

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.

Prompt Locations Quick Reference

CLI Reference

Core Commands

Task

engram task create --title <TEXT> [--priority high|medium|low] [--parent-id <ID>]
engram task list [--status <STATUS>] [--agent <NAME>]
engram task show --id <ID>
engram task update --id <ID> --status <STATUS>
engram task delete --id <ID>

Context

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

Reasoning

engram reasoning create --title <TEXT> --description <TEXT> [--task-id <ID>]
engram reasoning list [--task-id <ID>]
engram reasoning show --id <ID>
engram reasoning delete --id <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 <ID>
engram knowledge update --id <ID> --field <FIELD> --value <VALUE>
engram knowledge delete --id <ID>

Theory

engram theory create <DOMAIN> [--agent <NAME>] [--task <ID>] [--json]
engram theory list [--agent <NAME>] [--domain <DOMAIN>] [--limit <N>]
engram theory show --id <ID> [--show-metrics]
engram theory update --id <ID> [--concept X:Y] [--mapping X:Y] [--rationale X:Y] [--invariant X]
engram theory delete --id <ID>

Reflection

engram reflect create --theory <ID> --observed <TEXT> --trigger-type <TYPE> [--agent <NAME>]
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>

Session

engram session start --agent <NAME>
engram session list
engram session show --id <ID>
engram session bind-theory --id <SESSION_ID> --theory <THEORY_ID>
engram session trigger-reflection --id <ID>
engram session resolve-reflection --id <ID>
engram session end --id <ID>

Workflow

engram workflow create --title <TEXT> [--description <TEXT>]
engram workflow add-state --name <NAME> --workflow-id <ID>
engram workflow add-transition --from <NAME> --to <NAME> --workflow-id <ID>
engram workflow transition --to <NAME> --id <ID>
engram workflow list
engram workflow show --id <ID>

Relationship

engram relationship create --source-id <ID> --target-id <ID> --type <TYPE>
engram relationship list [--source-id <ID>] [--target-id <ID>]
engram relationship delete --id <ID>

Setup Commands

engram setup workspace
engram setup agent --name <NAME> --type <TYPE>
engram validate hook install
engram validate hook status

Entity Schema

Task

Context

Reasoning

Knowledge

Theory

StateReflection

Session

Relationship

Workflow

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<()>;
}
}

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.

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 validation commit --message "feat: implement authentication [TASK-123]"

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

# Install pre-commit hook
engram validation hook install

# Check hook status
engram validation hook status

# Uninstall hook
engram validation 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 Warming: Pre-load common task IDs

   engram validation warm-cache TASK-123 TASK-456
   

2. Parallel Validation: Enable multi-threaded validation

   performance:
     enable_parallel_validation: true
   

3. Memory Management: Configure appropriate cache sizes

   performance:
     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 validation commit --message "${{ github.event.head_commit.message }}"

GitLab CI

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

Troubleshooting

Common Issues

1. Hook not found

   # Check if engram is in PATH
   which engram
   
   # Install hook manually
   engram validation 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: Export current configuration

   engram validation config export > validation-backup.yaml
   

2. Update: Modify configuration file

3. Validate: Test new configuration

   engram validation check
   

4. Deploy: Roll out to team with documentation

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