Engram — Knowledge Graphs for AI Agents

Engram

A persistent knowledge graph for AI agents. Store nodes (components, services, people, concepts) and edges (calls, depends_on, owns) in a local SQLite database. Survives sessions. Query dependencies, find paths, check freshness against git, export for visualization.

Installation

npm install -g @clawdactual/engram

This installs the engram CLI globally. Verify with:

engram --help

How to Run

engram 

Database: ~/.config/engram/models.db (override: ENGRAM_DB_PATH=/path/to/db)

Global flag: --json on any command outputs structured JSON.

Session awareness: Add a line to your workspace bootstrap file (e.g., AGENTS.md) so future sessions know the knowledge graph exists and should maintain it. See the README's "Agent Setup" section.

Quick Reference

Models (containers for graphs)

engram create  [-t code|org|concept|infra] [-d "description"] [-r /repo/path]
engram list
engram delete 
engram export  [-f jsonld|json|dot] [-o file]
engram import 

Nodes

engram add   [--type ] [-m key=value ...]
engram rm  
engram update   [--label new] [--type new] [-m key=value ...]
engram verify             # mark as recently verified
engram nodes  [-t type]

Edges

engram link     [-m key=value ...]
engram unlink    
engram edges  [--from node] [--to node] [--rel type]

Queries

engram q                  # neighbors (depth 1)
engram q   --depth 3     # expand neighborhood
engram q  --affects      # what breaks if this changes? (reverse traversal)
engram q  --depends-on   # what does this need? (forward traversal)
engram q  -t service           # all nodes of type (includes subtypes)
engram q  --stale --days 14    # nodes not verified in 14+ days
engram q  --orphans            # nodes with no edges
engram path    [--max-depth N]  # all paths between two nodes

Search (cross-model)

engram search                  # search ALL models (labels, types, metadata)
engram search  --model myapp   # search within one model
engram search  --limit 10      # max results (default 5)
engram search  --exclude zink-family --exclude test  # skip models
engram search  --json          # JSON output for recall/automation

Results show each matching node + its 1-hop edges, grouped by model.

Types & Relationships

engram type list                      # show type hierarchy tree
engram type add  [--parent p] [--domain code|org|infra|concept]
engram type rm 
engram rel list                       # show all relationship types with inverses
engram rel add  [--inverse inv]
engram rel rm 

Branch Overlays (feature branch knowledge tracking)

Use overlays when working on feature branches, reviewing PRs, or doing any work that hasn't merged yet. Overlays keep the base model clean while capturing architectural discoveries. Merge the overlay when the PR/branch merges; delete it if the branch is abandoned.

engram branch               # create overlay
engram branch  --list                    # list overlays
engram merge                # fold into parent
engram branch   --delete    # discard
Add nodes/edges to an overlay (use --branch flag)
engram add   -t  -m key=value --branch 
engram link     --branch 

Key rule: When working on a feature branch, always use --branch . Only write directly to the base model for merged/stable knowledge.

Git Integration (code models only)

engram check        # compare anchor vs HEAD, show affected nodes
engram refresh      # update anchor to HEAD, mark all verified
engram diff         # detailed file-by-file diff with affected subgraph
engram stale        # show stale nodes and edges

Cross-Model

engram xlink     

Batch

echo "add mymodel NodeA --type service
add mymodel NodeB --type database
link mymodel NodeA depends-on NodeB" | engram batch mymodel

Scaffold (auto-generate engram from repo)

Generate a starting-point engram from a repository's file structure. Outputs batch import commands for top-level modules, API routes, services, workflows, clients, and commands.

# Preview what would be generated (no changes)
engram-scaffold ~/path/to/repo model-name --dry-run
Generate batch file, then import (scaffold.sh lives in the engram repo's tools/ directory)
./tools/scaffold.sh ~/path/to/repo model-name
engram batch  < /tmp/engram-scaffold-*.txt

The scaffold is a skeleton — enrich nodes with descriptions and add cross-service relationship edges after import. Supports Node.js/TypeScript repos (Medusa, NestJS, CLI), monorepos.

Built-in Types (extensible)

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

Type queries include subtypes: engram q model -t service finds services AND microservices.

Built-in Relationships (extensible)

| Relationship | Inverse | |---|---| | calls | called_by | | depends_on | depended_on_by | | contains | contained_in | | owns | owned_by | | uses | used_by | | extends | extended_by | | implements | implemented_by | | configures | configured_by | | produces | produced_by | | consumes | consumed_by | | proxies_to | proxied_by | | manages | managed_by | | tests | tested_by | | belongs_to | has_member | | renders | rendered_by |

Best Practices for Building Models

First Install: Seed Your Environment

On first use, scan your workspace and create models for:

A fresh session should be able to query the graph and understand your operational context immediately. This is a one-time investment that compounds every session.

The Hybrid Approach (Recommended)

After testing both "review everything first, then batch" and "enter as you go", the optimal workflow is:

1. Explore first (5-10 min) — Scan the codebase or domain. Read key files, understand major components. Don't enter anything yet.

2. Batch the skeleton — Create all major nodes and their primary relationships in one batch command. This captures the obvious architecture quickly.

   engram batch myapp <

3. Add discoveries incrementally — During coding, when you discover non-obvious relationships (e.g., "this function silently depends on NODE_ENV being set"), add them immediately:

   engram add myapp isPubSubDisabled --type function -m "note=returns false in production regardless of DISABLE_AUTH"
   engram link myapp fleet-rest calls isPubSubDisabled
   

4. Review after sessions — Quick pass: "Did I discover anything worth keeping?" Batch any accumulated additions.

What to Model (and What Not To)

DO model:

engram link Ken reports_to Tom
engram link Ken reports_to Deepak

engram add Brandon --type person -m role="Hardware Manager (Part-Time)"

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   # anchor to current git HEAD

engram q myapp --affects API       # everything upstream of API
engram path myapp Frontend DB      # all paths from Frontend to DB
engram check myapp                 # what git changes affect which nodes

engram branch myapp feature/new-cache
engram add myapp Redis --type database
engram link myapp API uses Redis
... later ...
engram merge myapp feature/new-cache   # fold changes into base model

engram export myapp -f jsonld -o myapp.jsonld    # export with semantic context
engram import myapp.jsonld                        # another agent imports it

engram export myapp -f dot | dot -Tpng -o graph.png   # requires graphviz installed
engram export myapp -f dot -o myapp.dot                # save DOT file

engram stale myapp --days 7        # what hasn't been verified this week?
engram verify myapp API            # mark a node as freshly verified
engram refresh myapp               # mark everything verified (after review)

# 1. See what changed since last review
engram check myapp
Output: lists changed files → affected nodes → affected edges
2. For cosmetic/rename changes (no structural change): just refresh
engram refresh myapp
3. For structural changes (new files, new dependencies, removed modules):
   a. Check what's new/deleted
engram diff myapp
   b. Add nodes for new files
engram add myapp NewService --type service -m file=src/new-service.ts
engram link myapp API calls NewService
   c. Remove nodes for deleted files
engram rm myapp OldService
   d. Update metadata if file paths changed
engram update myapp SomeModule -m file=src/new-path/module.ts
   e. Refresh to anchor at new HEAD
engram refresh myapp

# 1. See what files changed (the source of truth)
cd /path/to/repo && git diff HEAD~N --stat        # or git diff main..branch --stat
2. For each changed file, review what actually changed
git diff HEAD~N -- src/changed-file.ts
3. List current engram nodes for this model
engram nodes mymodel
4. Cross-reference: for each changed file, find its engram node(s)
   Check if the node's metadata/note is still accurate
   Check if edges are still correct (added/removed imports, calls, etc.)
5. Update stale nodes with verified information from the diff
engram update mymodel  -m 'note=Updated description from actual code'
6. Check for stale edges (did you remove a dependency? add a new call?)
engram edges mymodel --from 
engram edges mymodel --to 
Remove edges that no longer exist, add new ones
7. Add nodes for new exports/modules introduced in the changes
engram add mymodel NewThing -t function -m file=src/file.ts 'note=...'
8. Refresh the git anchor
engram refresh mymodel