Git Sync

Share memories across machines and team members using compressed chunks

Engram’s Git Sync feature allows you to share memories through git repositories using compressed chunks with a manifest index. This design avoids merge conflicts, keeps files small, and works seamlessly for teams.

Quick Start

# Export new memories as a compressed chunk
# (automatically filters by current directory name as project)
engram sync

# Commit to git
git add .engram/ && git commit -m "sync engram memories"

# On another machine / clone: import new chunks
engram sync --import

# Check sync status
engram sync --status

Architecture

Directory Structure

.engram/
├── manifest.json          ← small index (git diffs this)
├── chunks/
│   ├── a3f8c1d2.jsonl.gz ← chunk by Alan (compressed, ~2KB)
│   ├── b7d2e4f1.jsonl.gz ← chunk by Juan
│   └── c9f1a2b3.jsonl.gz ← chunk by Alan (next day)
└── engram.db              ← gitignored (local working DB)

How It Works

1. Export creates a new chunk

   Each engram sync creates a new chunk — never modifies old ones.

   The chunk contains:

   • Sessions created after the last chunk
   • Observations created after the last chunk
   • Prompts created after the last chunk
2. Chunk is compressed and hashed

   • Chunk content is serialized to JSON
   • Compressed with gzip (typically ~2KB for 8 sessions + 10 observations)
   • SHA-256 hash is computed from content
   • First 8 characters of hash become the chunk ID
3. Manifest is updated

   The manifest.json file is updated with a new entry:

   {
     "version": 1,
     "chunks": [
       {
         "id": "a3f8c1d2",
         "created_by": "alan",
         "created_at": "2026-03-03T10:15:30Z",
         "sessions": 8,
         "memories": 10,
         "prompts": 5
       }
     ]
   }
   
4. Chunk is tracked locally

   The local DB stores a sync_chunks table with chunk IDs that have been imported or exported.

   This prevents re-importing the same data if sync --import runs multiple times.

Commands

Export Memories

engram sync

Exports new memories as a compressed chunk to .engram/chunks/.

Project Detection: By default, engram sync uses the current directory name as the project filter. Only memories from sessions matching that project are exported.

Example:

cd ~/projects/my-app
engram sync  # Exports only memories from project "my-app"

Export All Projects

engram sync --all

Exports ALL memories from every project, ignoring the directory-based filter.

Use case: Shared team knowledge base or documentation repo where you want to sync memories from multiple projects into one centralized location.

Override Project

engram sync --project other-name

Manually specify a project name instead of using the directory name.

Import Chunks

engram sync --import

Imports chunks listed in the manifest that haven’t been imported yet.

How it works:

1. Reads manifest.json
2. Gets list of chunks already imported from local DB (sync_chunks table)
3. For each chunk in the manifest not yet imported:
   • Reads and decompresses the chunk file
   • Imports sessions, observations, and prompts into local DB
   • Records the chunk ID as imported

Duplicate handling:

• Sessions use INSERT OR IGNORE (skip if session ID already exists)
• Observations and prompts are imported as-is (Engram’s deduplication logic handles duplicates at save time)

Auto-import: The OpenCode plugin automatically runs engram sync --import when it detects .engram/manifest.json in the project directory.

Clone a repo → open OpenCode → team memories are loaded automatically.

Check Status

engram sync --status

Shows:

• How many chunks exist locally (in your DB)
• How many chunks exist remotely (in the manifest)
• How many chunks are pending import

Example output:

Local chunks: 3
Remote chunks: 5
Pending import: 2

Why Chunks?

Engram uses a chunked architecture instead of a single large JSON file. Here’s why:

No Merge Conflicts

Each engram sync creates a new chunk — old chunks are never modified.

When multiple developers sync independently:

• Alan creates a3f8c1d2.jsonl.gz
• Juan creates b7d2e4f1.jsonl.gz
• Git just adds both files — no conflicts

The manifest is the only file git diffs, and it’s small and append-only.

Content-Hashed Chunks

Each chunk is identified by the first 8 characters of its SHA-256 content hash.

This means:

• Each chunk is imported only once (tracked in local sync_chunks table)
• If two devs create identical chunks, the hash deduplicates them
• No risk of double-importing the same data

Compressed and Small

Chunks are gzipped JSONL.

Typical sizes:

• 8 sessions + 10 observations + 5 prompts = ~2KB compressed
• 50 sessions + 100 observations = ~10KB compressed

Git handles these small binary files efficiently.

Append-Only Manifest

The manifest is the only file git needs to diff/merge:

{
  "version": 1,
  "chunks": [
    {"id": "a3f8c1d2", "created_by": "alan", ...},
    {"id": "b7d2e4f1", "created_by": "juan", ...}
  ]
}

It’s small, human-readable, and append-only (new chunks are added, old entries never change).

Workflow Examples

Solo Developer (Multiple Machines)

# On laptop
cd ~/projects/my-app
engram sync
git add .engram/ && git commit -m "sync memories" && git push

# On desktop
cd ~/projects/my-app
git pull
engram sync --import

Team Collaboration

# Developer A
cd ~/projects/team-app
engram sync
git add .engram/ && git commit -m "sync engram" && git push

# Developer B
cd ~/projects/team-app
git pull
engram sync --import  # Imports A's memories
# Work, then sync their own memories
engram sync
git add .engram/ && git commit -m "sync engram" && git push

# Developer A
git pull
engram sync --import  # Imports B's memories

No merge conflicts because each dev creates independent chunks. Git just adds new files to .engram/chunks/.

Shared Knowledge Base

Create a separate repo for team-wide memories across multiple projects:

# Create a shared memory repo
mkdir team-knowledge && cd team-knowledge
git init

# From any project, sync ALL memories to this repo
cd ~/projects/project-a
engram sync --all  # Use --all to ignore project filter
cp -r .engram ~/team-knowledge/
cd ~/team-knowledge
git add .engram/ && git commit -m "sync all memories" && git push

# Team members clone and import
git clone <repo-url> team-knowledge
cd team-knowledge
engram sync --import

Data Model

Manifest Entry

type ChunkEntry struct {
    ID        string `json:"id"`         // SHA-256 hash prefix (8 chars)
    CreatedBy string `json:"created_by"` // Username or machine identifier
    CreatedAt string `json:"created_at"` // ISO 8601 timestamp
    Sessions  int    `json:"sessions"`   // Number of sessions in chunk
    Memories  int    `json:"memories"`   // Number of observations in chunk
    Prompts   int    `json:"prompts"`    // Number of prompts in chunk
}

Chunk Data

type ChunkData struct {
    Sessions     []Session     `json:"sessions"`
    Observations []Observation `json:"observations"`
    Prompts      []Prompt      `json:"prompts"`
}

Each chunk is a single gzipped JSON object containing arrays of sessions, observations, and prompts.

Implementation Details

Time-Based Filtering

When exporting, Engram filters data based on the timestamp of the last chunk:

1. Read the manifest
2. Find the most recent chunk’s created_at timestamp
3. Export only sessions/observations/prompts created after that timestamp

First sync: If there are no chunks yet, everything is exported.

Incremental syncs: Only new data is exported (data created since the last chunk).

Project Filtering

When --project is specified (or auto-detected from directory name):

1. Filter sessions by project field
2. Include only observations/prompts from those sessions

Example:

cd ~/projects/my-app
engram sync  # Auto-detects project as "my-app"

This ensures each project’s memories are scoped to that project’s git repo.

Compression

Chunks are gzipped using Go’s compress/gzip:

func writeGzip(path string, data []byte) error {
    f, err := os.Create(path)
    if err != nil {
        return err
    }
    defer f.Close()

    gz := gzip.NewWriter(f)
    if _, err := gz.Write(data); err != nil {
        return err
    }
    return gz.Close()
}

Typical compression ratios: 5-10x (e.g. 20KB JSON → 2KB gzipped).

Deduplication

At export time: Engram checks if a chunk with the same content hash already exists. If yes, skip export.

At import time: Engram checks the sync_chunks table to see if the chunk ID has been imported. If yes, skip import.

At save time: Engram’s normal deduplication logic (normalized hash + project + scope + type + title) prevents duplicate observations even if the same data is imported multiple times.

Related

MCP Tools

All 14 MCP tools for agents

Privacy

Redact sensitive data before syncing

CLI Reference

Full command-line reference

Export/Import

JSON export/import (alternative to git sync)