Team Sync via Git

Engrams is designed for collaboration. Instead of committing a binary SQLite database to Git, you export your project memory to version-controlled Markdown files. Teammates pull the changes and import them back into their local database.

How Team Sync Works

The workflow is transparent and integrates directly with your standard Git cycle:

  1. Develop & Log: You and your AI log decisions, patterns, or progress in your local SQLite database (engrams/context.db).
  2. Export: Before committing, run engrams export to dump the database state to human-readable Markdown files under engrams_export/.
  3. Commit: Commit the engrams_export/ directory to Git. Teammates can review changes (ADRs, patterns) in standard pull requests.
  4. Import: Teammates pull the branch and run engrams import to merge the updated Markdown files back into their local SQLite database.

Directory Structure

When you run engrams export, it generates the following layout under engrams_export/: 

your-project/
├── engrams_export/
│   ├── active_context.md    # Active context document
│   ├── product_context.md   # Product context document
│   ├── decisions/
│   │   ├── 1.md             # Decision ID 1
│   │   └── 2.md             # Decision ID 2
│   ├── patterns/
│   │   ├── cli-args.md      # Pattern by name
│   │   └── ...
│   ├── progress/            # Logged progress items
│   ├── custom/              # Custom key-value config
│   └── links.json           # Relationships between items
└── engrams/
    └── context.db           # SQLite DB (local cache, DO NOT COMMIT)

Recommended .gitignore

You must ignore the local SQLite database folder to prevent binary conflicts in Git. Add the following to your .gitignore: 

# Ignore the local Engrams SQLite database cache
engrams/

# Do NOT ignore engrams_export/
# engrams_export/

Setting Up Team Sync

1. Initialize the Workspace

Run the initialization command in your project root:

engrams init

This creates the local database schema at engrams/context.db.

2. Perform Initial Export

Export the default database (even if empty) to create the export folder structure:

engrams export

3. Commit the Export Folder

Add and commit the generated folder:

git add engrams_export/
git commit -m "chore: initialize engrams sync folder"
git push

4. Teammate Setup

When teammates pull the repository, they simply install the CLI and run:

engrams init
engrams import

This populates their local SQLite database with all the shared decisions, patterns, and context.

Summary of CLI Sync Commands

  • engrams export [--path <DIR>] — Dump the database to Markdown files (defaults to ./engrams_export).
  • engrams import [--path <DIR>] — Reconstruct/update the SQLite database from the Markdown folder.