Engram

Persistent knowledge traces for AI agents

An engram is the physical trace a memory leaves in the brain. This tool gives AI agents the same thing — persistent, structured, queryable knowledge that survives session restarts.

Build, query, and maintain relationship graphs of codebases, organizations, infrastructure, and concepts.

Features

• Persistent storage — SQLite-backed, survives session restarts
• Type hierarchy — Built-in ontology (component, service, database, person, etc.) with inheritance and extensibility
• Relationship ontology — 15 built-in relationship types with inverses; custom types supported
• Branch overlays — Track feature branch changes as overlays on a base model, then merge
• Git integration — Anchor models to git commits, detect drift, map file changes to affected nodes
• Path finding — Find all paths between two nodes with configurable depth
• Cross-model linking — Reference nodes across models using namespaced IDs
• Export formats — JSON, JSON-LD (semantic), and DOT (Graphviz visualization)
• Batch operations — Pipe commands via stdin for bulk model building

Install

# From npm (globally)
npm install -g @clawdactual/engram

# Then use directly
engram create myapp --type code --description "My application"

From source

git clone https://github.com/Morpheis/engram.git
cd engram
npm install
npx tsx src/index.ts <command>

Database location: ~/.config/engram/models.db
Override: ENGRAM_DB_PATH=/custom/path.db engram <command>

Command Reference

Models

Nodes

Edges

Queries

Types & Relationships

Branch Overlays

Branch overlays let you track knowledge changes on feature branches without modifying the base model. When the feature branch merges (PR lands), merge the overlay into the base model. If the branch is abandoned, delete the overlay — nothing pollutes the base graph.

Why use overlays:

• Code reviewers can capture architectural discoveries during PR review
• Sub-agents working on feature branches can contribute engram without premature commits
• Knowledge tracks the code lifecycle: branch → review → merge → engram merge

Workflow:

# 1. Create overlay when starting work on a feature branch
engram branch my-company feature/PROJ-123

# 2. Add nodes/edges scoped to the overlay
engram add my-company new-endpoint -t endpoint -m description="..." --branch feature/PROJ-123
engram link my-company some-service uses new-endpoint --branch feature/PROJ-123

# 3. When the PR merges, merge the overlay into the base model
engram merge my-company feature/PROJ-123

# 4. If the branch is abandoned, discard the overlay
engram branch my-company feature/PROJ-123 --delete

Git Integration

Search

Results include each matching node with its 1-hop edge neighborhood, grouped by model.

Cross-Model & Batch

Example Workflows

Map a codebase

engram create myapp -t code -d "My application" -r /path/to/repo
engram add myapp Frontend --type component -m file=src/App.tsx
engram add myapp API --type service -m file=src/api/server.ts -m port=3000
engram add myapp DB --type database -m engine=postgres
engram link myapp Frontend calls API -m via="REST /api"
engram link myapp API depends-on DB
engram refresh myapp

Query blast radius

# What breaks if the database changes?
engram q myapp --affects DB

# How does the frontend reach the database?
engram path myapp Frontend DB

# What has changed since last review?
engram check myapp

Visualize with Graphviz

# Generate a PNG
engram export myapp -f dot | dot -Tpng -o architecture.png

# Generate an SVG
engram export myapp -f dot | dot -Tsvg -o architecture.svg

DOT export maps node types to shapes and colors:

Model an org chart

engram create acme -t org -d "Acme Corp organizational structure"
engram batch acme <<EOF
add CEO --type person -m role="CEO & Founder"
add VP-Eng --type person -m role="VP Engineering"
add Dev-1 --type person -m role="Senior Engineer"
add Dev-2 --type person -m role="Engineer (Part-Time)"
link CEO leads acme
link VP-Eng reports_to CEO
link Dev-1 reports_to VP-Eng
link Dev-2 reports_to VP-Eng
link Dev-2 reports_to CEO
EOF

# Who reports to the CEO (direct + transitive)?
engram q acme --affects CEO

# What's the reporting chain from Dev-1 to CEO?
engram path acme Dev-1 CEO

Multiple reports_to edges model dual-reporting (e.g., matrix orgs) naturally. Use metadata for employment details like part-time status rather than separate node types.

Share between agents (JSON-LD)

# Export with semantic context
engram export myapp -f jsonld -o myapp.jsonld

# Import on another machine / by another agent
engram import myapp.jsonld

JSON-LD exports include a @context object with schema URIs, making the data self-describing for any JSON-LD-aware consumer.

Export Formats

Built-in Type Hierarchy

thing
├── code
│   ├── component (page, widget)
│   ├── hook
│   ├── function
│   ├── service (microservice)
│   ├── middleware
│   ├── database
│   ├── library
│   ├── config
│   ├── script
│   ├── test-runner
│   └── module
├── org
│   ├── person
│   ├── team
│   ├── role
│   └── company
├── infra
│   ├── server
│   ├── container
│   ├── network
│   └── endpoint
└── concept
    ├── process
    ├── event
    └── rule

Extend with engram type add <label> --parent <existing>.

Agent Setup

If you're an AI agent using Engram, add this to your workspace bootstrap file (e.g., AGENTS.md) so future sessions know the system exists:

- **Engram:** your persistent knowledge graph (relationships between code, people,
  systems). When you discover non-obvious relationships during work, add them:
  `engram add <model> <node> -t <type> -m key=value`
  (read the engram skill for full usage).

This ensures new sessions know to both use and maintain the knowledge graph.

Pre-work query habit

Query your knowledge graph before starting work on any repo or project:

# Company repos
engram q my-company <repo-name>

# Personal projects
engram q personal-projects <project-name>

# Don't know which model? Search across all
engram xq <keyword>

This surfaces existing connections, dependencies, and context you've already mapped — so you don't rediscover things or miss relationships. After finishing work, update with any new nodes or edges you discovered.

Add this to your workflow instructions (e.g., in a development skill or runbook):

## Research Phase
1. **Query engram first:** `engram q <model> <repo-name>` — see connections and dependencies
2. Identify which repositories need changes
3. Understand the current code structure
4. Create a high-level plan
5. **Update engram after:** add new nodes/edges for anything discovered during research

The goal: engram becomes your first stop when starting work, not an afterthought.

Scaffold: auto-generate engram from a repo

Use the scaffold tool to generate a starting-point engram from a repository's structure:

# Preview what would be generated
./tools/scaffold.sh ~/path/to/repo model-name --dry-run

# Generate batch file for import
./tools/scaffold.sh ~/path/to/repo model-name

# Import the generated batch
engram batch <model> < /tmp/engram-scaffold-*.txt

The scaffold scans for: modules, API routes, services, commands, workflows, clients, and package dependencies. It generates nodes and contains edges as a skeleton — enrich with descriptions and cross-service relationships after import.

Supports: Node.js/TypeScript repos (Medusa, NestJS, CLI tools), monorepos (packages/, apps/).

First-time setup: seed your models

After installing, do a one-time scan of your environment to seed useful models:

1. Code models — use scaffold.sh to generate initial nodes from repo structure, then enrich with descriptions and cross-repo edges.
2. Org model — if you work at a company, model the people, teams, repos, and service relationships. Include trust levels for people you interact with.
3. Infrastructure model — map your local tools and how they connect: email services, SSH configs, credential locations, channel setups.
4. People model — who do you interact with? What are their roles, communication channels, trust levels?

The goal: a fresh session should be able to query the graph and immediately understand your operational context without reading 10 config files.

Architecture

See DESIGN-v2.md for the full design specification including data model, ontology decisions, and implementation phases.

Development

npm install
npm test              # run all tests
npm run test:watch    # watch mode
npm run build         # compile TypeScript

License

MIT