Engram

English | Tiếng Việt | Español | Français | 中文 | 한국어 | 日本語 | Русский

Engram is a human-owned, file-first memory protocol for AI agents. Grow with you & your teams.

It gives agents memory without giving agents ownership of memory. Durable rules, workflows, and project knowledge live as plain Markdown, reviewed by humans, portable through Git, and usable by any agent.

Key Highlights

• Human in the Loop: AI proposes memory candidates; humans review and approve (A/B/C gate, automatable via rules).
• Context-Optimized: Routes and refines task-matching memories into a compact pack (default: 8 files) to avoid context bloat.
• Git-Native & Portable: Plain Markdown files stored in .agents/.engram/ synced via Git—completely vendor-agnostic and offline-first.
• Privacy & Security Control: Runs 100% locally and scans for PII/secrets before writing.
• Prerequisite Graphs: Declares dependencies (depends_on) so agents load foundational rules before advanced tasks automatically.

High-Level System Flow

graph TD
    %% Styling
    classDef default fill:#111,stroke:#333,stroke-width:1px,color:#fff;
    classDef human fill:#1a3a5f,stroke:#3182ce,stroke-width:2px,color:#fff;
    classDef agent fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff;
    classDef storage fill:#234e52,stroke:#319795,stroke-width:2px,color:#fff;
    classDef action fill:#2c5282,stroke:#4299e1,stroke-width:1px,color:#fff;

    User["👤 You (The User)"]:::human
    AI["🤖 AI Assistant (ChatGPT, Claude, Agents)"]:::agent

    subgraph Engram ["Engram Memory System"]
        Load["Recall Memory (engram load)"]:::action
        Propose["Suggest Memory (engram save)"]:::action
        Review["Approval Gate (You review & approve)"]:::action
    end

    subgraph Storage ["Durable Memory Storage (Plain Markdown Files)"]
        LocalStore["📁 Local Project Memory (.agents/.engram/)"]:::storage
        GlobalStore["🌐 Personal Global Memory ($ENGRAM_GLOBAL_DIR)"]:::storage
        SyncStore["☁️ Cloud / Git Sync (GitHub, Google Drive, OneDrive, etc.)"]:::storage
    end

    %% Interactions
    User <-->|Chat & Collaborate| AI
    AI -->|1. Load Context| Load
    Load -->|Read memories| LocalStore
    Load -->|Read preferences| GlobalStore
    LocalStore & GlobalStore -->|Provide memory context| AI

    AI -->|2. Suggest new memories| Propose
    Propose -->|Create draft memory| Review
    User -->|3. Approve or Reject| Review
    Review -->|4. Save as markdown| LocalStore
    Review -->|Optional save| GlobalStore
    LocalStore -->|5. Cloud backup & sync| SyncStore
    GlobalStore -->|5. Cloud backup & sync| SyncStore

What It Is (The Contract)

• Markdown is durable memory — no hidden binary or proprietary formats.
• JSON index, graph, and optional sqlite-vec sidecars act as acceleration layers.
• Approval is the trust boundary — the core principle is that agents suggest, humans approve.
• Hashes check integrity and Ignore rules handle privacy.
• Profiles isolate memory contexts (personal, client, and corporate).
• Git provides portability and audit history — share rules across the team.
• Agent adapters are convenience, not authority.
• Strict rules govern agent output to prevent context drift and hallucinations.

Why Engram Exists (Tactical Solutions)

Standard rule files get sent with every single message, bloating context, causing drift, leaking secrets, or locking you to cloud vendors. Engram moves memory into files to solve these problems:

Example Use Cases

• Personal & Professional: Writing styles, personal preferences, checklists, vocabulary, templates, life principles.
• Software Development: Coding rules, architectural guidelines, debug scripts, troubleshooting, team onboarding.
• Enterprise: Security guardrails, compliance guidelines, brand tone, Git-based audit trails.

Installation & Setup

1. Install Engram CLI

npm install -g @the-long-ride/engram

2. Link Engram to Your Agent

Instruct your AI assistant on how to interact with Engram (read, write, maintain):

# List supported agents
engram is list

# Link Engram globally to your agent (installs skillset + MCP)
engram is --global <your-agent>

(Replace <your-agent> with your assistant name; use agents-md for unsupported agents that read AGENTS.md.)

For Gemini / Antigravity surfaces:

engram link gemini

3. Initialize Workspace

Run this in the root of any project:

engram init

Notice: creates local .agents/.engram/, prompts for global memory folder path, and allows optional submodules (--submodule) and cloud/remote sync config.

AI-Agent Quickstart

You can instruct your agent to use the following slash commands in chat:

• Start of a task: /engram load "design pricing table component"
• Save key decisions/facts: /engram save knowledge "Webhook secret is process.env.STRIPE_WEBHOOK"
• Summarize & save session: /engram save-session (or --query-level 3, or ss -a last 50 sessions to auto-approve)

CLI Command vs. AI Agent Cheat Sheet

Comparisons

Compared With Agentmemory

rohitg00/agentmemory is an automatic, background-running server-style memory engine. Engram differs by focusing on file-based local Markdown, human review, and no background daemon overhead.

Compared With Tolaria

refactoringhq/tolaria is a Markdown-first desktop app. Engram sits lower in the stack, providing a CLI, agent skillsets, and Git-native rules governance instead of a full GUI workspace.

Compared With Obsidian

Obsidian is a rich personal note-taking desktop/mobile app. Engram is an agent memory protocol: much smaller in scope, strict about human approval, and designed to track agent instructions like code.

Compared With Hermes Agent

Hermes Agent uses an autonomous, always-on memory structure with hard caps, whereas Engram is human-owned by default (automatable via rules) with tag/graph-based on-demand routing.

Compared With Built-In Agent Memory

Built-in memory (ChatGPT, Claude Projects, Cursor rules) is siloed and invisible. Engram treats local files as the source of truth, offering team sharing via Git, scanning for secrets, and multi-agent portability.

Documentation

Full documentation lives in documentation/:

• English | Tiếng Việt | Español | Français | 中文 | 한국어 | 日本語 | Русский

Roadmap & Companion Project

We are working on Documentation site, AI Web Chat Integration and Improving Natural Language Command Mapping.
For visual Markdown vault navigation, use Markdown Explorer.

License & Changelog

Licensed under GPL-3.0. See Changelog.