Introduction

Engrams gives your AI coding assistant a persistent memory. Instead of forgetting everything between sessions, your AI remembers the decisions you've made, the patterns you follow, and the progress you've tracked — and brings up the right information exactly when it's needed.

Why Engrams CLI?

Have you ever had to remind your AI assistant — again — that your project uses a specific framework, or that you already decided on a certain database? AI coding tools are powerful, but they start every conversation with a blank slate. The bigger your project gets, the more time you spend catching your AI up.

The Problem: Context Window Bloat & Fragile Servers

Traditionally, developers had to choose between two bad options for giving AIs project context:

• Bloated prompts: Dumping huge README.md, architecture docs, or complete file trees into the prompt. This wastes tokens, costs money, and degrades the AI's reasoning performance (attention decay).
• MCP Daemons: Running background MCP servers. These are notorious for port conflicts, silent failures in sandboxed IDEs, memory leaks, and tedious setup across team members' environments.

The Solution: A Standalone Rust CLI

Engrams solves this by running as a fast, zero-overhead CLI. AI agents simply run engrams commands inside their terminal tool to search or log information.

Key Practical Benefits

1. Zero Background Overhead

Since Engrams is a compiled Rust CLI rather than a server daemon:

• There are no ports to allocate and no socket connections to drop.
• It consumes 0 MB of RAM when idle (it only runs when invoked).
• No risk of background crashes freezing your editor extension.

2. Universal Compatibility

Any AI agent or tool with the ability to run shell commands in the workspace can use Engrams. You don't need editor-specific MCP client integrations. It works seamlessly in:

• Zoo Code (via execution tools)
• Claude Code (running in the terminal)
• Cursor / Antigravity (via terminal commands)
• Zed (via terminal tasks)
• Custom bash/python scripts

3. Blazing Fast FTS5 Search

Instead of relying on heavy local vector models (which eat CPU/GPU) or calling external embedding APIs (which cost money and require internet), Engrams uses SQLite's built-in FTS5 (Full-Text Search) engine. Searches take less than 5 milliseconds and run entirely locally.

4. Git-Friendly Collaboration

You shouldn't commit SQLite binary files to Git. Engrams has native export and import commands that serialize your database to clean, structured Markdown files under engrams_export/. You commit these Markdown files to your repository, allowing:

• Easy peer reviews of architectural decisions (ADRs) and patterns in PRs.
• Automatic local database synchronization upon running git pull && engrams import.

Comparison: Engrams vs. Alternatives

Aspect	Manual Prompts	MCP Servers	Engrams CLI
Setup Time	None	Tedious (config files, uvx, node paths)	1 Minute (binary install)
Token Waste	High (pasting files every time)	Low (query on demand)	Low (query on demand)
IDE Sandbox Issues	None	Common (crashes, permission drops)	None (runs as normal tool)
Offline Support	Yes	Depends on embeddings API	Yes (fully local SQLite)
Git Versioning	Manual files only	Binary DB or None	Automatic via Export/Import

How Engrams Works

Every time you start a new chat with your AI assistant, it has no memory of your previous conversations. Engrams changes that. It quietly sits alongside your AI tool, remembering your project decisions, design patterns, and progress — and automatically provides the right information when it's needed.

How a typical interaction works

1. You ask your AI something. For example: "Implement the DB schema."
2. Your AI queries the Engrams CLI using the shell tool: e.g., engrams decision search "database" or engrams pattern list to orient itself.
3. Engrams returns SQLite search matches as structured JSON.
4. Your AI writes code aligned with project context, respecting prior decisions.
5. New choices get recorded. If a new architectural choice is made, the AI runs engrams decision log.

Architecture Overview

Engrams runs as a standalone CLI tool in your project workspace. It integrates with any AI coding tool supporting shell commands (like Zoo Code, Cursor, Antigravity, Zed, or Claude Code). The CLI maintains a local SQLite database at engrams/context.db for high-performance FTS5 queries and updates. To share context with your team, developers export database state to version-controlled Markdown files in the workspace.

Storage: local SQLite and Markdown exports

Engrams uses a simple, robust storage model designed for git-controlled sharing:

Storage	Location	Purpose
SQLite DB	engrams/context.db (in .gitignore)	Local, high-performance database supporting FTS5 search and relationships.
Markdown Files	engrams_export/ (committed to Git)	Human-readable dumps of the database items, easily version-controlled and shared.

The core design is Git-friendly. The SQLite database is local to your machine, while the exported Markdown files are the source of truth committed to Git.

Team sync via Git

Sharing Engrams project memory across team members is fully manual and transparent:

1. Export: Run engrams export to dump all SQLite items to engrams_export/.
2. Commit: Push the engrams_export/ directory alongside your code.
3. Import: Teammates pull the changes and run engrams import to update their local SQLite database.

Workspace detection

Engrams automatically resolves where your project lives by scanning upwards for indicators like .git, Cargo.toml, or package.json. The database is stored relative to this discovered root.

How Engrams connects to your AI tool

There are no background services or daemons running. Your AI assistant calls the engrams binary directly as a shell/terminal command. This ensures total security, zero background memory footprint, and compatibility with any agent tool that can run terminal commands.

Stored Knowledge Types

Engrams stores structured knowledge across several distinct types. Each type maps to a database table and is managed via specific engrams CLI subcommands.

Type	Description	Example
Decisions	Choices you've made and why (ADRs)	"Use PostgreSQL for the database — it handles complex queries better"
Progress	What's done, what's in progress, what's next	TODO → IN_PROGRESS → DONE
Patterns	Repeatable approaches your team follows (how-to)	"All API responses use the same error format"
Context	The big picture — project goals, current focus	What the project is about and what you're working on now
Custom Data	Anything else worth remembering	Glossary terms, internal specs, style guides

Next steps

• Install Engrams
• Run through the Quick Start
• Set up your AI Assistant