Batch Operations & Export / Import

Engrams provides robust commands for committing data in bulk and moving your project memory back and forth between a local SQLite database and version-controlled Markdown files.

Batch Operations

The engrams batch command allows you to insert multiple records of the same type in a single transaction. This is useful for seeding a new project or importing existing data.

You pass a JSON array of items directly via the --items flag, or pass - to read from standard input:

Examples

Provide JSON inline:

engrams batch --type decision --items '[{"summary": "Use Rust", "rationale": "Speed"}, {"summary": "Use SQLite", "rationale": "Local"}]'

Provide JSON via standard input:

cat items.json | engrams batch --type custom_data --items -

Supported batch types are: decision, progress_entry, system_pattern, custom_data.

Export to Markdown

To make your database contents readable by developers and commit-safe for Git, serialize it to human-readable Markdown files: 

engrams export --path ./engrams_export

This dumps decisions, patterns, progress, custom configurations, and relationships as individual Markdown files and a links.json file in the target directory (defaults to ./engrams_export).

Import from Markdown

When pulling updates from colleagues or restoring context after checkout, import the Markdown files back into your local SQLite database: 

engrams import --path ./engrams_export

The import command automatically resolves duplicates (using summary-derived slugs) and updates existing items, ensuring your local SQLite database remains in sync with the repository.

Summary of Sync Commands

  • engrams batch --type <type> --items <json> — Commit bulk records programmatically.
  • engrams export [--path <DIR>] — Dump SQLite tables to Markdown files.
  • engrams import [--path <DIR>] — Sync the SQLite database using the Markdown directory contents.