Batch Operations & Export / Import

Log multiple items in one call, export for backup or snapshots, and import from version-controlled markdown.

Batch logging

You: "Log these tech stack decisions all at once:
      - FastAPI for REST API
      - Pydantic for validation
      - SQLAlchemy for ORM
      - Alembic for migrations
      - pytest for testing"

AI:  Logged 5 decisions:
     Decision #24: Use FastAPI for REST API
     Decision #25: Use Pydantic for validation
     Decision #26: Use SQLAlchemy for ORM
     Decision #27: Use Alembic for migrations
     Decision #28: Use pytest for testing

     All tagged with "tech_stack".

Export to markdown

You: "Export all project knowledge to markdown"

AI:  Exporting Engrams database to markdown...

     Created ./docs/engrams_export/ with:
     decisions.md    (28 decisions)
     patterns.md     (8 patterns)
     progress.md     (15 tasks)
     glossary.md     (12 terms)
     relationships.md (all links)

     You can commit this to version control.

Team-only export (for Git commit)

Pass visibility_filter="team" to export only items that belong to the whole team — personal progress, individual notes, and active-context files are excluded. This is the format used by the pre-commit Git hook.

You: "Export only team-scoped decisions and patterns"

AI:  Exporting with visibility_filter=team...

     Created ./engrams-export/ with:
     decision_log.md    (12 team decisions)
     system_patterns.md (5 patterns)
     custom_data/       (3 category files)

     Personal progress and context files excluded.

Import from markdown

You: "Import the project knowledge from markdown"

AI:  Importing from ./docs/engrams_export/...

     Imported:
     28 decisions
     8 patterns
     15 progress items
     12 glossary terms
     All relationships

     Your project memory is fully restored.

Merge import (additive — for Git pull)

Pass merge=True to import in additive-only mode. Items that already exist locally are skipped rather than overwritten, so personal notes and progress are safe:

• Decisions are matched by a 12-character content-hash slug (SHA-256 of the summary text), so the same decision exported from any machine is recognised as identical.
• Patterns are matched by name (case-insensitive).
• Custom data is matched by category + key.
• Context files (product_context.md, active_context.md, progress_log.md) are always skipped in merge mode — they are personal local state.

You: "Import team knowledge after pulling"

AI:  Importing with merge=True from ./engrams-export/...

     items_logged:  { decision_log: 3, system_patterns: 1 }
     items_skipped: { decision_log: 9, system_patterns: 4, custom_data: 2 }
     (existing local items untouched)

     Your local database is up to date.

Legacy: Team sync via Git hooks

Prior to v1.4, team sync relied on Git hooks to export and import. This approach still works and can serve as a backup mechanism alongside the primary .engrams/ write-through:

Installing the hooks

# From your project root (requires a .git directory)
engrams install-hooks

# Custom export directory
engrams install-hooks --export-dir team-engrams

# Overwrite existing hooks
engrams install-hooks --force

After running install-hooks, commit the engrams-export/ directory once so teammates receive your current team-scoped knowledge on their next pull.

MCP tools

• batch_log_items — log multiple items of the same type in one call
• export_engrams_to_markdown — export knowledge to a markdown directory; supports visibility_filter
• import_markdown_to_engrams — restore knowledge from a markdown export; supports merge

CLI commands

• engrams install-hooks — write pre-commit and post-merge Git hooks for team sync