Skip to main content
Glama

Engram Engram

Persistent memory for AI agents. In-process. No infra.

Give your AI agent the memory of a colleague who's worked with you for years — without cloud, API keys, or Docker.

Useful to you? Star it on GitHub — it's the simplest way to help others find Engram.

CI npm version Website License: MIT Node.js MCP engram MCP server

npm install -g @hbarefoot/engram
engram start

Your AI agent now has long-term memory. Two minutes, no setup, no cloud.

  • 🧠 In-process — runs inside your agent's stack. No separate server to deploy, no IPC overhead, nothing to fork.

  • 📴 Offline — local SQLite + bundled embeddings (~23 MB). No API keys, no data leaving your machine.

  • 🔌 MCP-native — first-class Model Context Protocol integration with Claude Desktop, Claude Code, Cursor, Windsurf, and Cline.

  • 🔐 Safety by default — automatic secret detection on every write. API keys, private keys, connection strings, JWTs blocked before they hit the database.


Why local-first, in numbers

Engram runs inside your agent's process — no service to deploy, no account, nothing leaving your machine. That design choice is measurable:

Metric

Engram

Cold start → first recall

under 200 ms

import → first answer, model load included (M-series; hardware-dependent)

Warm recall (p50, 1k memories)

~4 ms

median query latency once the model is in memory

Package download

~571 KB

the npm package (1.3 MB unpacked)

Embedding model

~23 MB

all-MiniLM-L6-v2, fetched once, cached at ~/.engram/models

External services

0

no database, broker, or cloud account

Works offline

zero network calls on the default path

Measured on an Apple M4 Pro over 1,000 seeded memories — reproduce with npm run bench. These are footprint and latency numbers, not an accuracy claim: Engram doesn't try to out-rank Mem0 or Zep on memory benchmarks. The point is solid recall with none of the operational surface.

Optional accuracy lift — still 100% local. If you already run a local model, the opt-in LLM layer sharpens fact extraction: entity-extraction accuracy climbs from 45.8% (rule-based) to 95.8% with the recommended henrybarefoot1987/engram-extract model (qwen3:1.7b) — +50 pts — without a single byte leaving your device.


Related MCP server: Engram MCP

Support Engram

Engram is free and MIT-licensed — and always will be. No paywalls, no tier-locked features, no telemetry. Every feature ships in the open-source package. Sponsorship is purely a way to fund continued development, not to unlock anything.

Support Engram

If Engram saves you time, you can sponsor it via Polar:

Tier

Price / month

For

🌱 Supporter

$5

Individuals who want the project to keep shipping.

Power User

$25

Heavy users who rely on Engram day to day.

👥 Team

$100

Teams standardizing on Engram across projects.

🏢 Enterprise

$499

Priority response on issues + dedicated integration help.

About Enterprise. Engram is MIT-licensed, so commercial use is already granted — you don't need to buy a license to use it at work. The Enterprise tier buys priority response on issues and dedicated help wiring Engram into your stack. For organizations whose policy precludes depending on MIT-licensed software, an optional commercial-license override is available on request. (Engram is maintained by a solo developer, so this is best-effort priority response, not a contractual SLA.)


Why Engram?

Most agent-memory products are services you run alongside your agent — Postgres, Docker, cloud accounts, API keys. Engram embeds inside your agent's process: a focused, stable npm package with practical guardrails.

Engram

Lodis

Mem0 / OpenMemory

Zep

Letta

Maturity

v1.9.x, stable

v0.5.x, early

mature / SaaS

v0.x

v0.x

Infra to operate

None (npm package)

None (npx package)

Cloud account or multi-container Docker

Docker + Postgres + Graphiti

Docker + Postgres

Install footprint

~23 MB

~22 MB

Hundreds of MB containers (self-hosted)

Hundreds of MB

Hundreds of MB

Works offline

❌ Cloud / ✅ if self-hosted

❌ External embed provider

❌ External LLM provider

MCP-native

✅ Primary

✅ Primary

🟡 OpenMemory ships an MCP server

❌ REST/SDK

❌ REST/SDK

REST API alongside MCP

❌ MCP-only

✅ Cloud

Surface area

6 tools, 5 categories

40 tools, 14 entity types + 4 permanence tiers + temporal supersession

varies

varies

varies

Automatic secret detection

✅ Blocks on every write

🟡 memory_scrub opt-in tool

🟡 Not first-class

🟡 Not first-class

🟡 Not first-class

Agent auto-discovery

✅ Dashboard Integration Wizard

❌ Manual config

Desktop app

✅ macOS Tauri menu bar

LLM-powered extraction

✅ Optional, on-device (Ollama; rule-based default)

❌ LLM-free read/write

✅ Built-in

✅ Built-in

✅ Built-in

Feedback / contradiction workflow

✅ Side-by-side conflict-resolution UI + feedback loop

🟡 Programmatic correct/confirm/supersede tools

🟡 No first-class feedback

🟡

🟡

Sources: @sunriselabs/lodis, Sunrise-Labs-Dot-AI/engrams, mem0.ai, github.com/getzep/zep, github.com/letta-ai/letta. See docs/competitive-intel.md for the full breakdown. Engram ships optional, on-device LLM extraction (v1.9+): point llm.* at a local model — the recommended henrybarefoot1987/engram-extract (Qwen3-1.7B, Apache-2.0) or any Ollama / OpenAI-compatible endpoint — to sharpen category/entity extraction (entity recognition +50 pts vs rules — 45.8% → 95.8% — with engram-extract (qwen3:1.7b) in our benchmark), still 100% local and off by default (the zero-config path stays rule-based, offline, and infra-free). Mem0/Zep/Letta build LLM extraction in via a cloud model; Lodis is LLM-free read/write with a broader feature surface — we list it honestly.

TL;DR — when each one fits. Pick Engram if you want a focused, stable, local-first memory layer with practical guardrails (secret detection, agent auto-discovery, desktop app), a simple 5-category mental model, and optional on-device LLM extraction when you want it. Pick Lodis if you want a knowledge-graph-style memory with 14 entity types and temporal supersession. Pick Mem0/Zep/Letta if you want cloud-LLM extraction built in and don't mind operating infrastructure for it.


Quickstart

1. Install

npm install -g @hbarefoot/engram

2. Start the server

engram start             # MCP + REST + Dashboard on localhost:3838
engram start --mcp-only  # MCP server only, stdio mode (for agent integration)

3. Connect your AI agent

Claude Code:

claude mcp add engram -- engram start --mcp-only

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["start", "--mcp-only"]
    }
  }
}

Cline / Cursor / Windsurf — add the same mcpServers block to your editor's MCP config. The built-in dashboard at http://localhost:3838 has an Integration Wizard that auto-detects your installed agents and generates the config for you.

4. Use it

You:    "Remember that our API uses JWT tokens with 24-hour expiry."
Claude: (stores via engram_remember)

You:    (next day) "What authentication approach are we using?"
Claude: (recalls via engram_recall) — "JWT tokens, 24-hour expiry."

Memories persist across sessions, machine restarts, and even between different AI clients sharing the same Engram instance.


Memory that improves over time

Most memory systems are append-only stores: write once, retrieve forever, hope for the best. Engram learns.

  • Feedback loop (engram_feedback) — when an agent recalls a memory, you or the agent can vote it helpful or unhelpful. Memories accumulate a score in [-1, 1]; consistently-unhelpful memories see their confidence decay automatically.

  • Contradiction detection — when two memories conflict ("prefers Fastify" vs "switched to Express"), the consolidation engine flags them. The dashboard's Conflicts tab shows them side-by-side with four resolution actions: keep A, keep B, keep both, or dismiss.

  • Deduplication on insert — identical memories (≥0.95 cosine similarity) are rejected. Near-duplicates (0.92–0.95) absorb the new content into the existing record. The store stays clean without manual pruning.

  • Decay — memories that aren't recalled lose confidence over time and stop polluting future results.

The longer you use Engram, the sharper its recall gets.


MCP Tools

Engram exposes 6 tools to AI agents over stdio:

Tool

Description

engram_remember

Store a memory with category, entity, confidence, namespace, tags. Auto-runs secret detection.

engram_recall

Hybrid semantic + FTS5 search. Supports category, namespace, threshold, and time_filter.

engram_forget

Delete a specific memory by ID.

engram_feedback

Vote a memory helpful/unhelpful. Drives the feedback loop above.

engram_context

Pre-formatted context block (markdown / xml / json / plain) with a token budget for system-prompt injection.

engram_status

Health check: memory count, model status, configuration.

Memory categories

  • fact — Objective truths about setup, architecture, or configuration.

  • preference — User likes, dislikes, style choices.

  • pattern — Recurring workflows and habits.

  • decision — Choices made and the reasoning behind them.

  • outcome — Results of actions taken.


Teach your agent to use Engram

Connecting the MCP server gives your agent the memory tools — but not the judgment to use them well. The bundled engram-memory skill is that judgment layer: it teaches an agent to recall at the start of a session, store durable decisions, corrections, and outcomes as they happen, and write results back at the end — without being told each time.

engram skill install                     # → ~/.claude/skills/engram-memory/
engram skill install --project           # → ./.claude/skills/  (commit it for your team)
engram skill install --platform agents   # → ~/.agents/skills/  (cross-framework)

Works in Claude Code, Claude Desktop, Cowork, or any framework that reads the Agent Skills spec (.agents/skills). The skill is vendored in the package, so it versions with Engram and updates land on the next engram skill install; engram skill uninstall removes it cleanly.


CLI Reference

engram start                       # Start MCP + REST + dashboard
engram start --mcp-only            # MCP server only (stdio mode)
engram start --port 3838           # Custom REST port

engram remember "<content>"        # Store a memory   (-c category -e entity -n namespace --confidence)
engram recall "<query>"            # Search memories  (-l limit -c category -n namespace --threshold)
engram forget <id>                 # Delete by ID
engram list                        # List memories    (-l limit --offset -c category -n namespace)
engram status                      # Health check

engram consolidate                 # Deduplicate, detect contradictions, decay
                                   # (--no-duplicates / --no-contradictions / --no-decay / --cleanup-stale)
engram conflicts                   # List unresolved contradictions
engram export-context              # Export curated context block
                                   # (-o file -f markdown|claude|txt|json -c categories --min-confidence ...)
engram import                      # Import from local sources
                                   # (-s cursorrules|claude|package|git|ssh|shell|obsidian|env --dry-run)

engram skill install               # Install the engram-memory agent skill
                                   # (--project → ./.claude, --platform agents → ~/.agents)
engram skill uninstall             # Remove the engram-memory skill

Run engram --help for the full flag list.


REST API

The REST API runs on http://localhost:3838 by default.

Method

Endpoint

Description

GET

/health

Liveness check

GET

/api/status

System status + stats

GET

/api/installation-info

Detected agents, runtime, install location

POST

/api/memories

Create a memory

GET

/api/memories

List with pagination + filters

POST

/api/memories/search

Semantic search

GET

/api/memories/:id

Read a single memory

DELETE

/api/memories/:id

Delete by ID

POST

/api/memories/bulk-delete

Bulk-delete by ID list

POST

/api/consolidate

Run consolidation pipeline

GET

/api/conflicts

Legacy tag-based conflict view

GET

/api/contradictions

Unresolved contradictions

POST

/api/contradictions/:id/resolve

Resolve (keep_first / keep_second / keep_both / dismiss)

GET

/api/contradictions/count

Unresolved count (for badge)

GET

/api/analytics/overview

Memory health dashboard data

GET

/api/analytics/stale

Memories with no recent recall

GET

/api/analytics/never-recalled

Memories never returned by any query

GET

/api/analytics/duplicates

Detected near-duplicates

GET

/api/analytics/trends

Time-series creation/recall trends

POST

/api/export/static

Export context block as a static file

GET

/api/import/sources

List importable local sources

POST

/api/import/scan

Two-phase import: preview extracted memories

POST

/api/import/commit

Two-phase import: commit selected memories


Web Dashboard

A built-in React dashboard at http://localhost:3838:

  • Dashboard — Memory stats, recent activity, health gauge.

  • Memories — Browse, filter, inline-edit, bulk-delete.

  • Search — Semantic search with score breakdown.

  • Statistics — Charts by category, namespace, and time.

  • Health — Stale, never-recalled, low-feedback memories with one-click cleanup.

  • Conflicts — Side-by-side contradiction resolution.

  • Agents — Integration wizard that auto-detects installed AI clients and writes their MCP configs (with timestamped backups).

  • Import — Wizard for cursorrules, .claude files, package.json, git config, SSH config, shell history, Obsidian, and .env.


How it works

  1. Store: engram_remember runs content through secret detection, then embeds it locally using all-MiniLM-L6-v2 (~23 MB, CPU-only, downloaded once and cached at ~/.engram/models/). The embedding and metadata land in SQLite at ~/.engram/memory.db.

  2. Recall: engram_recall embeds the query, fetches candidates via FTS5 + in-namespace embeddings, and scores them as (similarity × 0.45) + (recency × 0.15) + (confidence × 0.15) + (access × 0.05) + (feedback × 0.10) + fts_boost. Top results are returned and their access stats updated.

  3. Deduplicate: on insert, identical memories (≥0.95 similarity) are rejected; near-duplicates (0.92–0.95) absorb new content into the existing row.

  4. Learn: engram_feedback adjusts a memory's feedback_score and — after 5+ votes — bumps the confidence score up or down.

  5. Protect: every write passes through pattern-based secret detection (OpenAI/Stripe/AWS/GitHub/Slack/Google keys, private keys, connection strings, JWTs, high-entropy strings). Detected secrets either reject the memory or redact the secret portion.


Configuration

Engram stores everything under ~/.engram/:

~/.engram/
├── memory.db          # SQLite database (memories + embeddings + FTS5 index)
├── config.json        # Server configuration
└── models/            # Cached embedding model

Defaults work out of the box. To customize:

{
  "port": 3838,
  "dataDir": "~/.engram",
  "defaults": {
    "namespace": "default",
    "recallLimit": 5,
    "confidenceThreshold": 0.3,
    "tokenBudget": 500,
    "maxRecallResults": 20
  },
  "embedding": {
    "provider": "local",
    "model": "Xenova/all-MiniLM-L6-v2"
  },
  "consolidation": {
    "enabled": true,
    "intervalHours": 24,
    "duplicateThreshold": 0.92,
    "decayEnabled": true
  },
  "security": {
    "secretDetection": true,
    "auditLog": false
  }
}

The llm.* block powers the optional local AI enhancement below. It is off by default (llm.provider: null); the zero-config path uses rule-based extraction and makes no LLM calls.


Optional: local AI enhancement (Ollama)

Engram works fully offline with zero AI dependencies. If you want a little more accuracy and already run a local model, you can optionally turn on "Layer 1" — and it stays 100% on your machine.

  • Free, opt-in, off by default. Nothing changes unless you enable it.

  • Local-first. Uses your own Ollama (default) or any OpenAI-compatible local server (LM Studio, llama.cpp). No cloud, no API key, no telemetry — your memory content never leaves your device.

  • Graceful. Every call has a timeout and falls back to the built-in rule-based path if the model is slow, unreachable, or returns junk. Engram never crashes because a model is down.

What it improves when enabled: sharper category/entity/confidence on new memories, and an LLM confirmation step that reduces false-positive contradiction flags.

Recommended model: henrybarefoot1987/engram-extract. The layer's two jobs are classification, not generation — so a small model with constrained decoding (the model is forced to emit valid JSON) and thinking turned off is fast (sub-second), cool, and accurate. Pull it (or build it locally from the Modelfile):

ollama pull henrybarefoot1987/engram-extract
# …or build from source:
ollama create henrybarefoot1987/engram-extract -f models/engram-extract.Modelfile

Then set the model to henrybarefoot1987/engram-extract. It's a recommendation, not a lock-in — any Ollama or OpenAI-compatible model still works. See docs/llm/recommended-model.md for the base model, licensing, and how to pick the smallest model that beats rules on your hardware.

Attribution. henrybarefoot1987/engram-extract is built on Qwen3-1.7B (© Alibaba Cloud, Apache-2.0). Engram only adds the extraction prompt and the constrained-output configuration; the base model's weights, license, and notice are unchanged.

Enable it (desktop app): Preferences → AI Enhancement → toggle on, pick a model, Test connection, Save. The same tab shows a live status badge, activity stats (enhanced vs fallback extractions, contradictions filtered, average latency), and a recent-events list so you can see the layer actually working. Programmatically, GET /api/llm/status and GET /api/llm/stats expose the same data (all local — no telemetry).

Enable it (config file)~/.engram/config.json:

{
  "llm": {
    "provider": "ollama",
    "endpoint": "http://localhost:11434",
    "model": "llama3.2:3b",
    "apiKey": null
  }
}

First: ollama pull llama3.2:3b. Set "provider": null to turn it back off (the default). For an OpenAI-compatible local server, use "provider": "openai-compatible" and point endpoint at it (e.g. http://localhost:1234); apiKey is sent only if set.

Privacy note: "no memory data leaves your device" is only literally true when endpoint is local (localhost/127.0.0.1). If you point it at a non-local host, memory content is sent there for classification — the desktop AI Enhancement tab shows an explicit warning in that case. If the model is unreachable, a circuit breaker pauses the layer and Engram falls back to rule-based extraction with no added latency.


Advanced usage

Sandboxed evaluation

Redirect Engram's data directory to a throwaway location so it doesn't touch ~/.engram/memory.db. Useful for first-time evaluators, CI runs, or testing the desktop sidecar against a fresh DB:

# Via CLI flag (highest priority)
engram start --data-dir /tmp/engram-eval

# Or via env var
ENGRAM_DATA_DIR=/tmp/engram-eval engram start

# Works on every Engram command that touches the DB:
ENGRAM_DATA_DIR=/tmp/engram-eval engram remember "test memory" -c fact
ENGRAM_DATA_DIR=/tmp/engram-eval engram recall "test"
ENGRAM_DATA_DIR=/tmp/engram-eval engram status

Override priority: --data-dir flag > ENGRAM_DATA_DIR env var > dataDir in ~/.engram/config.json > default (~/.engram).

Namespace isolation

engram remember "Uses Next.js 14 app router" -n my-saas
engram remember "WordPress multisite + Redis" -n client-site

engram recall "what framework?" -n my-saas

Temporal queries

Time-range filtering is available via MCP and REST. Agents pass a time_filter object to engram_recall:

{
  "query": "deployment changes",
  "time_filter": { "after": "last week" }
}
{
  "query": "API decisions",
  "time_filter": { "after": "2026-01-01", "before": "2026-06-01" }
}

Supported shapes: after / before (ISO date or relative string like "3 days ago"), or period shorthand (today, yesterday, this_week, last_week, this_month, last_month, this_year, last_year).

Export context for documentation

engram export-context -f markdown -n my-project -o PROJECT_CONTEXT.md
engram export-context -f claude -o CLAUDE.md

Programmatic usage

Engram also works as a library inside your Node.js app:

import {
  loadConfig,
  getDatabasePath,
  getModelsPath,
  initDatabase,
  createMemory,
  recallMemories
} from '@hbarefoot/engram';

const config = loadConfig();
const db = initDatabase(getDatabasePath(config));

createMemory(db, {
  content: 'User prefers Fastify over Express',
  category: 'preference',
  confidence: 0.9
});

const results = await recallMemories(
  db,
  'preferred web framework',
  { limit: 5 },
  getModelsPath(config)
);

Contributing

See CONTRIBUTING.md for development setup, the versioning policy (npm + desktop bump together), and the release checklist. The project's licensing and sustainability stance is in BUSINESS_MODEL.md — short version: pure OSS, MIT forever, no paywalls.

git clone https://github.com/HBarefoot/engram.git
cd engram
npm install
npm run dev

If Engram is useful to you, here's how to help:

  • Star the repo — the loudest signal that this is worth continuing.

  • 🐛 Open an issue — bug, feature request, or "we use Engram at <company> for <thing>" stories all welcome.

  • 💬 Start a discussion — design questions, integration ideas, "how would I…" — all good.

  • 💜 Support Engram — sponsor via Polar to fund continued development. No tier-locked features; sponsorship goes straight to keeping the project shipping.


Feedback

Using Engram? Tell me what's working and what isn't — open a Discussion, file feedback, or run engram feedback from the CLI. No telemetry, ever — Engram never phones home, so the only feedback I get is what you choose to send.


Find Engram on Glama

Engram is listed in the Glama MCP directory and the official MCP Registry as io.github.HBarefoot/engram.


License

MIT © 2026 HBarefoot

Available Tools

6 tools
engram_contextA

Build a single pre-formatted context block from relevant memories, ready to inject into a system prompt at session start. With a query it selects semantically relevant memories; with no query it returns the top memories by access frequency and recency. The block is rendered in the requested format and truncated to fit max_tokens. Returns: one formatted string (not an array) — contrast with engram_recall, which returns raw scored memory objects. Use when you want drop-in context text; use engram_recall when you need structured results to reason over.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum memories to include, 1–25 (default 10).
queryNoOptional query to select relevant memories. If omitted, returns top memories by access frequency and recency.
formatNoOutput format (default markdown): markdown=human-readable headings, xml=structured tags, json=machine-parseable, plain=raw text.markdown
namespaceNoNamespace to pull memories from (default "default").default
categoriesNoOptional list of memory types to include, e.g. ["preference", "fact"]; omit for all.
max_tokensNoApproximate token budget for the block; lower-priority memories are dropped to fit (default 1000).
include_metadataNoIf true, append each memory's id and confidence to the output (markdown and xml formats only). Default false.

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses key behaviors: semantic search with query, frequency/recency fallback, formatting options, token truncation, single string return. No annotations provided, but description covers all essential behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is well-structured and concise: starts with main purpose, explains query/no-query, output format, sibling comparison, and usage guidance. No redundant sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers main functionality, usage guidelines, and parameter interplay. Lacks mention of error handling (e.g., no memories found), but given the tool's purpose and seven parameters, it is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds context on how parameters (e.g., limit, max_tokens, format) interact to produce the final block. Provides integration-level meaning beyond individual schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it builds a pre-formatted context block from memories, distinguishes from engram_recall by noting formatted string vs raw objects. Also describes behavior with and without query.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises when to use this tool vs engram_recall: 'Use when you want drop-in context text; use engram_recall when you need structured results to reason over.' Also implies usage at session start.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

engram_feedbackA

Record a helpful/unhelpful vote on a recalled memory to tune future ranking. Updates the memory's aggregated feedback_score (−1 to 1), which feeds the recall score (weight 0.10); after 5+ votes it may auto-adjust the memory's confidence (strongly negative lowers it, strongly positive raises it). Returns: the updated feedback stats for that memory. Call right after acting on a memory from engram_recall to close the learning loop; to remove a bad memory outright, use engram_forget instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
contextNoOptional note describing the query or situation that prompted this vote; stored for later review.
helpfulYestrue if the memory was useful in this context (raises its feedback_score and future ranking), false if not (lowers it).
memory_idYesThe id of the memory being rated, taken from a prior engram_recall result.

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description fully carries burden. It details the feedback_score range, weight on recall score, confidence auto-adjustment after 5+ votes, and return value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single paragraph but well-structured: purpose first, then effects, then usage guidance. Dense with information, no superfluous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 3-param tool with no output schema, the description fully explains effects, return value, and integration with workflow (recall->feedback). Complete enough for accurate use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline 3. Description adds context: explains that 'helpful' raises/lowers score and that memory_id comes from engram_recall. Provides value beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool records a helpful/unhelpful vote on a recalled memory to tune future ranking. It distinguishes from sibling tools like engram_forget, which removes memories.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs when to call it ('right after acting on a memory from engram_recall') and provides an alternative (engram_forget) for removal.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

engram_forgetA

Permanently delete one memory by id. Irreversible — also removes that memory's feedback rows. Returns: whether a memory with the given id was found and deleted; reports not-found without error if the id doesn't exist. Use when a memory is wrong, outdated, or the user asks you to forget it. If you're unsure, downvote with engram_feedback (helpful:false) instead of deleting.

ParametersJSON Schema
NameRequiredDescriptionDefault
memory_idYesThe id of the memory to delete, as returned by engram_recall or engram_remember.

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully carries the burden: declares irreversibility, removal of feedback rows, return type (boolean), and error handling (reports not-found without error).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences; front-loaded with action and key constraint ('Permanently delete'); every sentence adds essential information with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool without output schema, the description covers all necessary context: what action, side effects, return behavior, and error handling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema already provides 100% coverage with description for memory_id. Description adds value by specifying the source ('as returned by engram_recall or engram_remember').

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verb-resource pairing ('Permanently delete one memory by id'), distinguishes from siblings like engram_feedback and engram_recall, and clearly states the return value.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use ('when a memory is wrong, outdated, or the user asks you to forget it') and when to use an alternative ('If you're unsure, downvote with engram_feedback instead').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

engram_recallA

Retrieve memories relevant to a query, ranked by a hybrid score. Embeds the query, gathers candidates (FTS5 top-20 plus in-namespace embeddings, optionally time-filtered), and scores each by similarity×0.45 + recency×0.15 + confidence×0.15 + access×0.05 + feedback×0.10 + a 0.1 FTS boost, then filters by category/threshold and returns the top results. If embedding generation fails it falls back to FTS-only search. Reading a memory bumps its last_accessed and access_count. Returns: an array of memory objects — each with id, content, category, entity, confidence, namespace, tags, timestamps, score, and scoreBreakdown — or an empty array if nothing clears the threshold (with a time_filter, the array also carries timeRange metadata). Use at session start or to look up a specific fact; prefer engram_context when you want a ready-to-inject block instead of raw results.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum memories to return, 1–20 (default 5). Keep low to avoid context pollution.
queryYesWhat you want to remember. Can be a question ("what is their deployment setup?") or a topic ("docker configuration"). Be specific for better results.
categoryNoOptional filter by memory type (preference/fact/pattern/decision/outcome). Omit to search all types.
namespaceNoOptional project/scope filter. Omit to search across all namespaces.
thresholdNoMinimum relevance score to include a result, 0.0–1.0 (default 0.3). Raise for fewer, more precise results.
time_filterNoRestrict results to a time range by created/updated time. Provide after/before, or a period shorthand. Supports relative times like "3 days ago", "last week", or ISO dates.

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so description fully bears the burden. It details the scoring formula, fallback to FTS, side effects (bumps timestamps), and return structure. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Long but well-organized: purpose, scoring details, fallback, side effects, return format, usage guidelines. Every sentence adds value; minor trimming possible but still effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but description fully explains return array structure (fields like id, content, score). Covers input, process, output, side effects, fallback. Complete for a complex tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. Description adds extra context for query (be specific), limit (keep low), and time_filter (supports relative times), going beyond schema docs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves memories relevant to a query, ranked by a hybrid score, and distinguishes from sibling engram_context by contrasting raw results vs. ready-to-inject block.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use ('at session start or to look up a specific fact') and when to prefer an alternative ('prefer engram_context when you want a ready-to-inject block').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

engram_rememberA

Store a durable memory (fact/preference/pattern/decision/outcome) that persists across sessions. Every write is scanned for secrets (16+ patterns — OpenAI/Stripe/AWS/GitHub/Slack/Google keys, private keys, connection strings, JWTs): by default detected secrets are redacted to [REDACTED] before storage, or the write is rejected if auto-redaction is disabled. Category and entity are auto-extracted when omitted, a local embedding is generated, and the content is deduplicated against existing memories. Returns: the memory id plus an outcome — "created" (new), "merged" (0.92–0.95 cosine to an existing memory; content/tags/confidence folded into it), or "duplicate" (≥0.95 cosine; not stored unless force:true). Use when you learn something worth remembering about the user, project, setup, or workflow; recall with engram_recall, delete with engram_forget.

ParametersJSON Schema
NameRequiredDescriptionDefault
tagsNoOptional string tags for categorization and retrieval, e.g. ["backend", "api"].
forceNoIf true, bypass the duplicate check and store even when a ≥0.95-similar memory already exists (creates a near-identical copy — use sparingly). Default false.
entityNoWhat this memory is about (e.g., "nginx", "deployment", "coding-style", "project-api"). Helps with retrieval.
contentYesThe memory to store. Be specific and factual. Good: "User prefers Fastify over Express for Node.js APIs". Bad: "User likes stuff".
categoryNoType of memory. preference=user likes/dislikes, fact=objective truth about their setup, pattern=recurring workflow, decision=choice they made and why, outcome=result of an actionfact
namespaceNoProject/scope to store under (default "default"). Use a project name to isolate project-specific memories; "default" for general ones.default
confidenceNoHow confident this memory is accurate, 0.0–1.0 (default 0.8). Use 1.0 for facts the user explicitly stated, 0.5–0.7 for inferred preferences.

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behaviors: secret scanning/redaction, auto-extraction of category and entity, local embedding generation, deduplication logic (three outcomes with cosine thresholds), and force flag behavior. This is comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is relatively long but every sentence adds value. It front-loads the main purpose and includes detailed side effects. Could be slightly more concise but remains efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite 7 parameters and no output schema, the description is very complete: explains return type (memory id + outcome), deduplication behavior, secret scanning, and parameter details. No gaps in context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds meaningful context beyond schema: deduplication thresholds (0.92-0.95, ≥0.95), 'use sparingly' for force, examples for content, and explanation for category enum values. This justifies a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it stores durable memories (facts, preferences, patterns, decisions, outcomes) persisting across sessions, and distinguishes itself from sibling tools engram_recall (retrieval) and engram_forget (deletion). The verb 'store' and resource 'memory' are specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance: 'Use when you learn something worth remembering about the user, project, setup, or workflow; recall with engram_recall, delete with engram_forget.' Also mentions auto-extraction and deduplication, providing context for when to use versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

engram_statusA

Report Engram health and statistics. Read-only and parameter-free. Returns: memory counts by category and namespace, embedding-model status (name, cached/loaded state, size), the database location, and key config (default namespace, recall limit, confidence threshold, secret-detection on/off). Use as a diagnostics/health check — to confirm the model is loaded and see how many memories exist — before relying on recall.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It fully discloses read-only nature, no parameters, and details return fields: memory counts, embedding-model status, database location, key config. Highly transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is concise with front-loaded purpose, then detailed listing of returns, ending with usage guidance. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters and no output schema, the description fully covers what the tool does, what it returns, and when to use it. Complete for a health-check tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters; baseline is 4. Description adds value by confirming parameter-free and documenting what information is returned, which is more than just the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reports Engram health and statistics, is read-only and parameter-free. It distinguishes from sibling tools by being a diagnostics/health check, not performing memory operations like recall or remember.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use as a diagnostics/health check — to confirm the model is loaded and see how many memories exist — before relying on recall.' Provides clear when-to-use context and implies engram_recall as alternative, but could more explicitly list when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 5 tool updatesv1.6.6
    • Changedengram_context10 fields changed
      • changedInput schema / properties / categories / description
        Previous value: -"Filter by categories (e.g., [\"preference\", \"fact\"])"New value: +"Optional list of memory types to include, e.g. [\"preference\", \"fact\"]; omit for all."
      • changedInput schema / properties / format / description
        Previous value: -"Output format. markdown=human-readable, xml=structured, json=programmatic, plain=raw text"New value: +"Output format (default markdown): markdown=human-readable headings, xml=structured tags, json=machine-parseable, plain=raw text."
      • changedInput schema / properties / include_metadata / description
        Previous value: -"Include memory IDs and confidence scores in output"New value: +"If true, append each memory's id and confidence to the output (markdown and xml formats only). Default false."
      • changedInput schema / properties / limit / description
        Previous value: -"Maximum memories to include (1-25). Default 10."New value: +"Maximum memories to include, 1–25 (default 10)."
      • addedInput schema / properties / limit / maximum
        Added value: +25
      • addedInput schema / properties / limit / minimum
        Added value: +1
      • changedInput schema / properties / max_tokens / description
        Previous value: -"Approximate token budget. Will truncate to fit. Default 1000."New value: +"Approximate token budget for the block; lower-priority memories are dropped to fit (default 1000)."
      • addedInput schema / properties / max_tokens / minimum
        Added value: +50
      • changedInput schema / properties / namespace / description
        Previous value: -"Namespace to pull context from (default: \"default\")"New value: +"Namespace to pull memories from (default \"default\")."
      • changedInput schema / properties / query / description
        Previous value: -"Optional query to filter relevant memories. If omitted, returns top memories by access frequency and recency."New value: +"Optional query to select relevant memories. If omitted, returns top memories by access frequency and recency."
    • Changedengram_feedback3 fields changed
      • changedInput schema / properties / context / description
        Previous value: -"Optional: describe the context or query that prompted this feedback"New value: +"Optional note describing the query or situation that prompted this vote; stored for later review."
      • changedInput schema / properties / helpful / description
        Previous value: -"Was this memory helpful in the current context? true = helpful, false = not helpful"New value: +"true if the memory was useful in this context (raises its feedback_score and future ranking), false if not (lowers it)."
      • changedInput schema / properties / memory_id / description
        Previous value: -"The ID of the memory to provide feedback on (returned by engram_recall)"New value: +"The id of the memory being rated, taken from a prior engram_recall result."
    • Changedengram_forget1 field changed
      • changedInput schema / properties / memory_id / description
        Previous value: -"The ID of the memory to remove (returned by engram_recall)"New value: +"The id of the memory to delete, as returned by engram_recall or engram_remember."
    • Changedengram_recall9 fields changed
      • changedInput schema / properties / category / description
        Previous value: -"Optional: filter by memory type"New value: +"Optional filter by memory type (preference/fact/pattern/decision/outcome). Omit to search all types."
      • changedInput schema / properties / limit / description
        Previous value: -"Maximum memories to return (1-20). Default 5. Keep low to avoid context pollution."New value: +"Maximum memories to return, 1–20 (default 5). Keep low to avoid context pollution."
      • addedInput schema / properties / limit / maximum
        Added value: +20
      • addedInput schema / properties / limit / minimum
        Added value: +1
      • changedInput schema / properties / namespace / description
        Previous value: -"Optional: filter by project/scope. Omit to search all namespaces."New value: +"Optional project/scope filter. Omit to search across all namespaces."
      • changedInput schema / properties / threshold / description
        Previous value: -"Minimum relevance score (0.0-1.0). Default 0.3. Increase to get fewer, more relevant results."New value: +"Minimum relevance score to include a result, 0.0–1.0 (default 0.3). Raise for fewer, more precise results."
      • addedInput schema / properties / threshold / maximum
        Added value: +1
      • addedInput schema / properties / threshold / minimum
        Added value: +0
      • changedInput schema / properties / time_filter / description
        Previous value: -"Filter memories by time range. Supports relative times like \"3 days ago\", \"last week\", or ISO dates."New value: +"Restrict results to a time range by created/updated time. Provide after/before, or a period shorthand. Supports relative times like \"3 days ago\", \"last week\", or ISO dates."
    • Changedengram_remember6 fields changed
      • changedInput schema / properties / confidence / description
        Previous value: -"How confident you are this is accurate (0.0-1.0). Default 0.8. Use 1.0 for things the user explicitly stated. Use 0.5-0.7 for inferred preferences."New value: +"How confident this memory is accurate, 0.0–1.0 (default 0.8). Use 1.0 for facts the user explicitly stated, 0.5–0.7 for inferred preferences."
      • addedInput schema / properties / confidence / maximum
        Added value: +1
      • addedInput schema / properties / confidence / minimum
        Added value: +0
      • changedInput schema / properties / force / description
        Previous value: -"Bypass deduplication check. If true, memory will be stored even if a similar one exists. Default: false"New value: +"If true, bypass the duplicate check and store even when a ≥0.95-similar memory already exists (creates a near-identical copy — use sparingly). Default false."
      • changedInput schema / properties / namespace / description
        Previous value: -"Project or scope for this memory. Use \"default\" for general memories, or a project name for project-specific ones."New value: +"Project/scope to store under (default \"default\"). Use a project name to isolate project-specific memories; \"default\" for general ones."
      • changedInput schema / properties / tags / description
        Previous value: -"Optional tags for categorization"New value: +"Optional string tags for categorization and retrieval, e.g. [\"backend\", \"api\"]."
  2. 6 tool updates
    • First observedengram_context
    • First observedengram_feedback
    • First observedengram_forget
    • First observedengram_recall
    • First observedengram_remember
    • First observedengram_status

TDQS

A4.8/5.0
Disambiguation5/5

Each tool has a unique, well-defined purpose: context formatting, feedback, deletion, recall, storage, and status. No overlap exists; descriptions explicitly contrast pairs like engram_context vs engram_recall.

Naming Consistency5/5

All tool names follow a consistent 'engram_verb' pattern using snake_case (e.g., engram_remember, engram_forget). The verbs clearly indicate the action, and there are no deviations or mixed conventions.

Tool Count5/5

Six tools cover the essential operations for a memory system (create, read in two forms, feedback, delete, status) without unnecessary bloat. The count feels natural and well-scoped for the server's purpose.

Completeness4/5

The tool surface covers create (remember), read (recall, context), update confidence via feedback, delete (forget), and status. The only noteworthy gap is the lack of a direct tool to edit a memory's content, though merging in 'remember' partially addresses it.

Maintenance

ActivityStale
ResponsivenessResponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Engram MCP provides persistent, cross-session memory for AI agents by automatically encoding errors, decisions, and discoveries during development sessions. It enables local, intelligent recall and automated context management to help AI learn from experience and avoid recurring mistakes.
    21
    Business Source 1.1
  • A
    license
    Not graded
    quality
    B
    maintenance
    Local-first, multi-user shared memory for AI agents with semantic search, offline support, and team synchronization.
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/HBarefoot/engram'

If you have feedback or need assistance with the MCP directory API, please join our Discord server