convez.ai
MCP ServerAutomaçãoIntermediário
the-long-ride

Engram

the-long-ride/engram

Memória durável e controlada por humanos para agentes de IA

Ver no GitHub
BomPluginScore · de 0 a 100

Sistema de gerenciamento de memória baseado em arquivos para agentes de IA, armazenando conhecimento como Markdown reviável por humanos. Oferece contexto otimizado, controle de privacidade local e sincronização via Git, funcionando de forma agnóstica a qualquer provedor de IA.

Instalação

$npx convez-ai the-long-ride/engram

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
6
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 semana
Versão
v0.0.29
Issues abertas
7
Contribuidores
1

Casos de uso

  • Equipes que usam múltiplos agentes de IA em projetos compartilhados
  • Armazenamento de conhecimento corporativo e workflows reutilizáveis
  • Gestão de contexto otimizado para reduzir token waste em agents

Veredito

Engram oferece uma abordagem inovadora para memória de agentes, colocando controle nas mãos humanas através de revisão explícita e armazenamento portável. Ideal para equipes que buscam escalabilidade com governança, sem lock-in de vendor.

README

A tradução para o português deste README ainda está na fila.

Engram

License: GPL v3 GitHub npm version npm

Engram cover

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:

Tactical ChallengeEngram Answer
Too many rules bloating contextRoutes and refines task-matching memory into a compact context pack, defaulting to 8 memories.
Silent writes & secret leakageRequires human A/B/C approval and scans for secrets/injections.
Vendor lock-inUses plain, readable Markdown files portable across any agent or model.
No offline accessRuns locally as a lightweight file-based protocol—no server or internet required.
Context drift in team projectsSynchronizes rules and guidelines team-wide via Git.
Broken or outdated memoryProvides validation and cleanup utilities (engram repair, engram quality-check).

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

TaskCLI CommandAI Agent Suggestion
Load Memoryengram load "<task>"/engram load "<task>"
Dry Run Loadengram load --dry-run "<task>"/engram load --dry-run "<task>"
Save Single Memoryengram save <type> "<text>"/engram save <type> "<text>"
Propose Memoriesengram save-session/engram ss
Mine Recent Sessionsengram save-session --query-level <n>/engram save-session --query-level <n>
Auto-Approve Savesengram save-session --accept-all/engram ss -a
Import Files / Docsengram take-control --all/engram take-control --all
Import & Metacognizeengram take-control --all --metacognize --accept-all/engram take control accept all metacognize
Restructure Memoryengram metacognize --workspace/engram restructure workspace memory accept all
Resolve Conflictsengram resolve-conflicts --metacognize/engram resolve conflicts and metacognize
Check Config / Pathsengram entry/engram entry
Manage Profilesengram profile status / create / use/engram profile status
Configure Save Targetengram set-save-target <workspace/global/both>/engram set-save-target <target>
Configure Load Limitengram set-load-limit <1..32>/engram set-load-limit <count>
Update Global Pathengram update-global-folder <new-path>/engram set global memory path to <new-path>
Clone Memoryengram clone-memory <src> <dest>/engram clone workspace memory to global
Set Active Rolesengram set-role <roles>/engram set-role <roles>
Set Rule Strictnessengram set-rule-variant <variant>/engram set-rule-variant <variant>
Verify & Repairengram verify / engram repair/engram verify / /engram repair
Scan Contradictionsengram quality-check/engram quality-check
Sync Memoriesengram sync/engram sync

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.

DimensionEngramagentmemory
Source of truthHuman-approved MarkdownMemory server/store
Trust boundaryA/B/C approval before writesAutomatic capture
Default shapeFile protocol (no daemon)Running service recommended
Review modelGit diff and Markdown reviewViewer/API/session history
Best forHuman-owned team memoryAutomatic recall and replay
Main riskRequires save disciplineInvisible state

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.

DimensionEngramTolaria
Source of truthMemories in .agents/.engram/Markdown vault notes
Primary interfaceCLI, slash adapters, agent skillDesktop app
Write modelAgents propose; humans approveHumans directly manage Markdown
Best forAuditable memory governanceBrowsing and managing vaults

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.

DimensionEngramObsidian
Source of truthMemories in .agents/.engram/Local Markdown notes
Write modelAgents propose; humans approveDirectly edit notes
Best forAuditable cross-agent memoryNote-taking and second brains

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.

EngramHermes Agent
PhilosophyHuman-owned, file-first protocol (automation optional)Autonomous, always-active memory
StorageTyped Markdown files in .agents/.engram/MEMORY.md + USER.md (hard char caps)
Write modelHuman-approved by default (A/B/C gate; automatable via rules)Agent writes autonomously
RecallOn-demand: engram load "<task>" injects relevant filesAlways-on: core files frozen into system prompt each session
Vector searchOptional local sqlite-vecVia external provider (agentmemory)
OverheadNo daemon, requires save discipline (unless automated)Server process + viewer UI, REST API, MCP server

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.

DimensionEngramBuilt-In Agent Memory
PortabilityPlain Markdown readable by any agentLocked to a single platform
Human ControlExplicit A/B/C approval before writesSilent background updates
CollaborationGit-friendly team sharingSingle-user only
SecurityLocal-first, scans for PII/secretsCloud-first, high risk of secret leakage

Documentation

Full documentation lives in documentation/:

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.

Ver o original no GitHub

Bom para

Relacionados