convez.ai
MCP ServerAutomaçãoIntermediário
ricoaiproject-cmd

Engram — Memória Persistente para Agentes de IA

ricoaiproject-cmd/engram

Memória persistente e adaptativa para seus agentes de IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que implementa memória compartilhada para agentes de IA (Claude, Codex, Gemini) com dinâmica semelhante à memória humana: reforça-se com uso, enfraquece quando inativa e ressurge por associação. Local-first, sem dependência de servidores externos.

Instalação

$npx convez-ai ricoaiproject-cmd/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
3
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 2 semanas
Versão
v0.4.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Agentes que precisam reter contexto entre múltiplas conversas
  • Sistemas multi-agente que compartilham conhecimento
  • Automação que se adapta ao padrão de uso do usuário

Veredito

Engram é uma solução inovadora para persistência de memória em agentes de IA, com instalação simples e integração nativa com os principais CLIs. O modelo de memória humano-like é diferenciador, mas ainda está em fase de consolidação (interface em japonês, modelo padrão JA-focused).

README

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

English | 日本語

engram — Human-like memory for AI agents (MCP server)

Persistent memory shared by Claude Code, Codex, and Antigravity (Gemini CLI). The more a memory is used, the easier it is to recall; unused memories sink but never disappear — the same dynamics as human memory.

Note: the setup wizard and CLI messages are currently in Japanese, and the default embedding model (Ruri-v3) is Japanese-focused. The engine itself is language-agnostic; you can switch models with embed_model in ~/.engram/config.toml (re-run engram reindex after changing it).


Quick start

Option 1: one-line install

Windows (PowerShell):

irm https://raw.githubusercontent.com/ricoaiproject-cmd/engram/main/install.ps1 | iex

macOS / Linux:

curl -LsSf https://raw.githubusercontent.com/ricoaiproject-cmd/engram/main/install.sh | sh

This single line installs uv, installs engram, and runs the setup wizard. (macOS: git is required — run xcode-select --install first if you don't have it.)

Option 2: manual install in three commands

Windows (PowerShell):

# 1. Install uv (skip if you already have it)
irm https://astral.sh/uv/install.ps1 | iex

# 2. Install engram
uv tool install --python 3.12 git+https://github.com/ricoaiproject-cmd/engram.git

# 3. Run the setup wizard
engram setup

macOS / Linux:

# 1. Install uv (skip if you already have it)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Install engram (force a uv-managed Python — see note below)
UV_PYTHON_PREFERENCE=only-managed uv tool install --python 3.12 git+https://github.com/ricoaiproject-cmd/engram.git

# 3. Run the setup wizard
engram setup

Why a uv-managed Python? engram needs a Python whose SQLite supports loadable extensions (for sqlite-vec). uv-managed Python provides this; system / python.org builds on macOS do not, and uv would otherwise prefer them when present — hence UV_PYTHON_PREFERENCE=only-managed (install.sh sets it for you). engram doctor has a check row for this.

The setup wizard automatically:

  • creates the config file (~/.engram/config.toml)
  • initializes the memory folder
  • downloads the embedding model (first run only, ~500 MB)
  • registers engram with Claude Code / Codex / Antigravity
  • registers the hooks for auto-encoding and proactive recall (Claude Code)

After installation

Just talk to your agent

Your agent performs every engram operation on its own. You simply have normal conversations, and memories accumulate and get used automatically.

Take the onboarding interview first (recommended)

Ask your agent:

Read ~/.engram/ONBOARDING.md and interview me.

Seeding your working style, preferences, and background makes the memory useful from day one.

Check your environment

engram doctor

Shows Python version, config file, model cache, and per-agent registration status as [OK] / [NG] / [--].

Re-run setup (e.g. after installing a new agent)

engram setup

Safe to run any number of times (idempotent). Only unregistered agents are added.

Choose which agents to register

Even with multiple agents installed, you can connect engram to just the ones you want.

# Register with Claude Code only
engram setup --agents claude

# Register with both Claude Code and Codex
engram setup --agents claude,codex

Valid names: claude / codex / gemini (antigravity is an alias for gemini). Without --agents, interactive mode lists the detected agents and lets you pick by number (Enter selects all); --non-interactive registers all detected agents as before.


More like real memory (new in v0.3)

Auto-encoding — sessions become memories by themselves

When a Claude Code session ends, a hook summarizes the conversation and saves it as an episode memory (engram setup registers the hook for you). Even if the agent forgets to call remember, "what we did yesterday" is preserved. Disable with auto_encode = false in config.toml.

Proactive recall — memory speaks up on its own

Every time you say something, a hook runs a lightweight search (a fast path that never loads the embedding model) for related memories. The mode is set by surface_mode in config.toml:

ModeBehavior
shadow (default)Injects nothing; logs "this is what I would have surfaced" (for observation and tuning)
activeActually injects strongly related memories into the agent's context
offDoes nothing

The log lives at ~/.engram/surface/surface_log.jsonl. We recommend watching shadow mode for a while and switching to active once the surfaced candidates look right. Use engram surface "some text" to check manually what would surface.

Tuning parameters: surface_threshold (score threshold, default 0.45) / surface_min_relevance (relevance floor, default 0.25 — a gate that keeps even important memories from surfacing when they are unrelated to what you said) / surface_max_items (max items per prompt, default 2).

Memory rooms — separating work and personal contexts

Every memory carries a room label. Map folders to rooms in config.toml and the room is resolved automatically from the working directory:

[room_paths]
'C:/Users/you/work-projects' = 'work'
'C:/Users/you/personal' = 'personal'
  • Unmapped folders and pre-existing memories are all common
  • recall searches only "current room + common" (room="*" searches across all rooms)
  • Auto-encoding and proactive recall respect rooms too, so work memories never leak into personal contexts (and vice versa)

How the memory works

Core design

Embeddings (where a memory sits in meaning-space) stay fixed; a separate axis — activation — modulates search ranking. Meaning = where it is, activation = how easily it comes to mind.

The same properties as human memory

  • The more you use it, the easier it is to recall — ACT-R activation model; every use by the agent reinforces it automatically
  • Unused memories sink but never disappear — power-law decay; deep recall can always reach them through associative links
  • Memories from striking contexts are engraved deeply — initial encoding boost by importance + slower decay = flashbulb memory
  • Corrected mistakes are engraved deepest of all — the correct tool records the error together with the fix = hypercorrection effect

Memory dynamics in brief

  • Activation: B = ln(Σ w_j·(now−t_j)^(−d_i)), normalized to 0..1 with a sigmoid; computed on the fly from the access log
  • d_i = clamp(0.5 − 0.2·(imp−5)/5, 0.3, 0.6) — higher importance forgets slower
  • create event weight 1 + 2·(imp/10) — critical memories start strong
  • merely recalled: weight 0.3 / actually useful (reinforce): weight 1.0×strength
  • Memories reinforced together get co_recall links (Hebbian learning), growing an associative network that deep recall's spreading activation can traverse

Search

Vector neighbors (Ruri-v3 embeddings) + BM25 full-text search merged with RRF, then re-ranked by 0.6·relevance + 0.25·activation + 0.15·importance.

Memory types

typeContents
knowledgeInsights, solutions to problems, how to use tools
preferenceThe user's preferences, style, patterns in instructions
projectGoals, constraints, history, and background of the work
episodeA summary of what happened in a session

File layout

~/.engram/
  config.toml        Config file (generated by engram setup)
  index.db           SQLite index (rebuildable from Markdown via reindex)
  MEMORY_PROTOCOL.md Agent operating instructions (imported into each agent's instruction file)
  ONBOARDING.md      Initial interview script
  surface/           Proactive recall log and session state
  hooks.log          Hook activity log

<memories_dir>/      Source of truth: Markdown (opens and edits fine in Obsidian)
  knowledge/
  preferences/
  projects/
  episodes/YYYY/MM/
  _trash/

memories_dir defaults to ~/.engram/memories, but pointing it at a Google Drive or OneDrive synced folder gives you backup and multi-device sharing. The SQLite index always stays local, so there is no sync-conflict risk.

MCP tools

ToolWhen to use
recall(query, mode, limit, type, room)At task start. fast = normal / deep = explores associative links, cold tier, and episodes
remember(content, type, importance, tags, related_ids, room)When you learn an insight, preference, context, or event. importance 1–10 scores how critical the context is
reinforce(ids, strength)At task end, report which memories actually helped (the nutrient for consolidation)
correct(id, corrected_content, reason)When a memory was wrong. Use this, not forget (engraves the mistake itself deeply)
link / forget / stats / reindexAuxiliary operations
consolidation_candidates / mark_consolidatedConsolidation (below)

Consolidation (the sleep of the system)

Clusters old episode memories and distills them into knowledge. The server only returns candidates; the summarization is done by the LLM (your agent). Example nightly run:

claude -p "Call engram's consolidation_candidates, summarize each cluster with remember (type=knowledge or project, related_ids=the source episodes), finish with mark_consolidated, then report stats."

For developers

Setting up to develop in this repository (run at the repo root):

# Virtual env (for development; distribution uses uv tool install)
python -m venv "$env:USERPROFILE\.engram\venv"
& "$env:USERPROFILE\.engram\venv\Scripts\python.exe" -m pip install -e ".[dev]"

Tests and verification

$py = "$env:USERPROFILE\.engram\venv\Scripts\python.exe"

& $py -m pytest                          # all tests
& $py -m pytest tests\test_setup.py -q   # setup logic only
& $py scripts\simulate.py                # simulate access patterns (30 days)
& $py scripts\check_mcp_e2e.py           # MCP end-to-end check

Diagnostics / CLI (for manual checks)

$engram = "$env:USERPROFILE\.engram\venv\Scripts\engram.exe"

& $engram doctor
& $engram remember "content" --type knowledge --importance 7
& $engram recall "query" --deep
& $engram surface "utterance text"
& $engram stats

Project structure

src/engram/
  config.py        Settings (defaults < config.toml < env vars) + room resolution
  engine.py        The memory engine
  store.py         Markdown source-of-truth store
  db.py            SQLite index (sqlite-vec + FTS5)
  dynamics.py      ACT-R activation model
  embedder.py      RuriEmbedder / FakeEmbedder
  server.py        MCP server (stdio)
  cli.py           CLI entry point
  setup.py         Setup wizard & doctor & hook registration
  hooks.py         Hook entry points (auto-encoding / proactive recall)
  transcript.py    Deterministic transcript summarization (auto-encoding)
  surface.py       Lightweight search path for proactive recall (no model)
  templates/       MEMORY_PROTOCOL.md / ONBOARDING.md
tests/
  test_setup.py    Setup pure-logic tests
  test_config.py   Settings precedence tests
  test_store.py    Markdown store tests
  test_db.py       DB operation tests
  test_engine.py   Engine tests
  test_room.py     Memory room tests
  test_surface.py  Proactive recall tests
  test_transcript.py  Transcript summarization tests
  test_hooks.py    Hook and hook-registration tests
  test_integration.py  Integration tests

Uninstall

# 1. Remove the registration from each agent
claude mcp remove engram

# 1b. Manually remove the engram entries from hooks in ~/.claude/settings.json
#     (the "engram hook ..." commands under SessionEnd / UserPromptSubmit)
# 2. Manually remove the engram block from ~/.claude/CLAUDE.md
# 3. Manually remove the [mcp_servers.engram] block from ~/.codex/config.toml
# 4. Manually remove the engram entry from ~/.gemini/config/mcp_config.json

# 5. Uninstall engram itself
uv tool uninstall engram

# 6. To delete the data as well (memories, config, model cache)
Remove-Item -Recurse -Force "$env:USERPROFILE\.engram"
Remove-Item -Recurse -Force "$env:USERPROFILE\.cache\huggingface\hub\models--cl-nagoya--ruri*"

On macOS / Linux, steps 5–6 are:

uv tool uninstall engram
rm -rf ~/.engram
rm -rf ~/.cache/huggingface/hub/models--cl-nagoya--ruri*
Ver o original no GitHub

Bom para

Relacionados