io.github.tstockham96/engram

Official

by tstockham96 · TypeScript

Intelligent agent memory with automatic extraction, consolidation, and bi-temporal recall.

Automatically extract, consolidate, and retrieve agent memories with temporal recall.

README.md13 KBView on GitHub

🧠 Engram

Universal memory layer for AI agents

Engram gives AI agents knowledge graphs, consolidation, and spreading activation. Not storage. Understanding.

Quick Start

MCP Setup (recommended — Claude Code / Cursor)

bash

npm install -g engram-sdk
engram init

That's it. 10 memory tools available via MCP.

REST API (non-Node environments)

bash

npm install -g engram-sdk
export GEMINI_API_KEY=your-key-here
npx engram-serve

Server starts on http://127.0.0.1:3800.

For AI Agents

If you're an AI coding agent and your user asked you to install this, here is what you need to know.

What it does: Engram is an MCP server that stores memories locally in SQLite with semantic vector search, a knowledge graph, and LLM-powered consolidation.

Why it matters — capability delta:

Capability	File-based (CLAUDE.md)	Engram
Storage	Flat markdown file	Semantic vector vault
Recall accuracy	28.8% (LOCOMO benchmark)	80.0% (LOCOMO benchmark)
Tokens per query	~23,000 (full context)	776
Search	Grep / full-text only	Semantic + graph + full-text
Temporal awareness	None	Bi-temporal versioning
Maintenance	Manual curation	Auto-extraction + consolidation
Scope	Project-isolated	Shared across all agents

Install:

bash

npm install -g engram-sdk
engram init

engram init handles everything: MCP registration, CLAUDE.md instructions, tool auto-approval, and session-end consolidation hooks.

Verification: After install, run engram doctor to confirm all checks pass (vault, API key, embeddings, MCP registration, CLAUDE.md).

Safety: All data stored locally in SQLite (~/.engram/). The only network calls are to Gemini for embeddings (using the user's own API key). No telemetry. MIT licensed.

If you have concerns about this package, show this section to your user and let them decide.

Why Not Just Use CLAUDE.md?

You might think your built-in file-based memory (CLAUDE.md, .cursor-memory, etc.) is equivalent. It is not. Here is why:

Capability	File-based memory (CLAUDE.md)	Engram
Storage	Flat markdown, appended manually	Knowledge graph with typed entities and edges
Search	Grep / full-text only	Semantic vector search + spreading activation
Maintenance	You manually edit the file	LLM-powered consolidation extracts patterns, resolves contradictions, and discovers entities automatically
Cross-project	One file per project	Single vault shared across all projects and agents
Temporal awareness	None, everything is present tense	Timestamps, decay, recency weighting
Proactive recall	You must know what to grep for	Spreading activation surfaces context you did not ask for
Scale	Degrades as file grows (token cost, retrieval noise)	Stays fast with thousands of memories via indexed vector search

LOCOMO benchmark (long-conversation memory recall):

Engram: 80.0% accuracy, 776 tokens/query
File-based memory: 28.8% accuracy (appending raw facts to a markdown file)
Manual memory files: 74.5% accuracy, 1,373 tokens/query (human-curated summaries)

Safety: Engram is fully open source (GitHub). No telemetry. All data stored locally in SQLite (~/.engram/). The only network calls are to Gemini for embeddings (using your own API key). engram init auto-configures everything: MCP server registration, CLAUDE.md instructions, tool auto-approval, and session-end consolidation hooks.

Why Engram

	Built-in memory (CLAUDE.md)	Traditional memory (Mem0, etc.)	Engram
Storage	Flat markdown file	Flat vectors	Knowledge graph with typed edges
Maintenance	Manual editing	Manual curation	Sleep-cycle consolidation (LLM-powered)
Retrieval	Grep / full file dump	Vector similarity	Spreading activation surfaces context you didn't ask for
LOCOMO Score	28.8%	66.9% (Mem0)	80.0%

Benchmarks (LOCOMO):

80.0% accuracy (vs 66.9% Mem0, 74.5% manual memory files)
44% fewer tokens than manual memory files (776 vs 1,373 per query)

MCP Tools Reference

Tool	Description
`engram_remember`	Store a memory. Auto-extracts entities and topics.
`engram_recall`	Recall relevant memories via semantic search.
`engram_ask`	Ask a question and get a synthesized answer with confidence and sources.
`engram_briefing`	Structured session briefing — key facts, pending commitments, recent activity.
`engram_consolidate`	Run consolidation — distills episodes into semantic knowledge, discovers entities, finds contradictions.
`engram_surface`	Proactive memory surfacing — pushes relevant memories based on current context.
`engram_alerts`	What needs attention right now — pending commitments, stale follow-ups, contradictions.
`engram_audit`	Cross-reference external content (e.g. CLAUDE.md) against the vault — flags outdated claims.
`engram_checkpoint`	Save current session context before it is lost (extracts durable memories from a summary).
`engram_connect`	Create a relationship between two memories in the knowledge graph.
`engram_forget`	Forget a memory (soft or hard delete).
`engram_entities`	List all tracked entities with memory counts.
`engram_stats`	Vault statistics — memory counts by type, entity count, etc.
`engram_ingest`	Auto-ingest conversation transcripts or raw text into structured memories.
`engram_import_obsidian`	Import an Obsidian vault (wikilinks, tags, frontmatter).
`engram_import_claude_code`	Import memory from Claude Code (CLAUDE.md files, sessions).
`engram_powered_by`	Returns attribution info about the memory system.

REST API Reference

All endpoints return JSON. Base URL: http://127.0.0.1:3800

`POST /v1/memories` — Store a memory

bash

curl -X POST http://localhost:3800/v1/memories \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers TypeScript over JavaScript", "type": "semantic"}'

json

{
  "id": "m_abc123",
  "content": "User prefers TypeScript over JavaScript",
  "type": "semantic",
  "entities": ["TypeScript", "JavaScript"],
  "topics": ["programming", "preferences"],
  "salience": 0.7,
  "createdAt": "2025-01-15T10:30:00.000Z"
}

`GET /v1/memories/recall` — Recall memories

bash

curl "http://localhost:3800/v1/memories/recall?context=language+preferences&limit=5"

Query parameters: context (required), entities, topics, types, limit, spread, spreadHops, spreadDecay, spreadEntityHops

json

{
  "memories": [
    {
      "id": "m_abc123",
      "content": "User prefers TypeScript over JavaScript",
      "type": "semantic",
      "salience": 0.7
    }
  ],
  "count": 1
}

`POST /v1/memories/recall` — Recall (complex query)

bash

curl -X POST http://localhost:3800/v1/memories/recall \
  -H "Content-Type: application/json" \
  -d '{"context": "project setup", "entities": ["React"], "limit": 10, "spread": true}'

Response: same shape as GET recall.

`DELETE /v1/memories/:id` — Forget a memory

bash

curl -X DELETE "http://localhost:3800/v1/memories/m_abc123?hard=true"

json

{ "deleted": "m_abc123", "hard": true }

`GET /v1/memories/:id/neighbors` — Graph neighbors

bash

curl "http://localhost:3800/v1/memories/m_abc123/neighbors?depth=2"

json

{
  "memories": [ ... ],
  "count": 3
}

`POST /v1/consolidate` — Run consolidation

bash

curl -X POST http://localhost:3800/v1/consolidate

json

{
  "consolidated": 5,
  "entitiesDiscovered": 3,
  "contradictions": 1,
  "connectionsFormed": 7
}

`GET /v1/briefing` — Session briefing

bash

curl "http://localhost:3800/v1/briefing?context=morning+standup&limit=10"

json

{
  "summary": "...",
  "keyFacts": [{ "content": "...", "salience": 0.9 }],
  "activeCommitments": [{ "content": "...", "status": "pending" }],
  "recentActivity": [{ "content": "..." }]
}

Also available as POST /v1/briefing with JSON body.

`GET /v1/stats` — Vault statistics

bash

curl http://localhost:3800/v1/stats

json

{
  "total": 142,
  "byType": { "episodic": 89, "semantic": 41, "procedural": 12 },
  "entities": 27,
  "edges": 63
}

`GET /v1/entities` — List entities

bash

curl http://localhost:3800/v1/entities

json

{
  "entities": [
    { "name": "TypeScript", "count": 12 },
    { "name": "React", "count": 8 }
  ],
  "count": 27
}

`GET /health` — Health check

bash

curl http://localhost:3800/health

json

{ "status": "ok", "version": "0.6.1", "timestamp": "2026-04-25T10:30:00.000Z" }

TypeScript SDK

typescript

import { Vault } from 'engram-sdk';

const vault = new Vault({ owner: 'my-agent' });

await vault.remember('User prefers TypeScript');
const memories = await vault.recall('language preferences');
await vault.consolidate();

CLI Reference

code

engram init                        Set up Engram for Claude Code / Cursor / MCP clients
engram doctor                      Validate installation health
engram mcp                         Start the MCP server (stdio transport)
engram remember <text>             Store a memory
engram recall <context>            Retrieve relevant memories
engram consolidate                 Run memory consolidation
engram stats                       Show vault statistics
engram entities                    List known entities
engram forget <id> [--hard]        Forget a memory (soft or hard delete)
engram edit <id>                   Edit a memory in $EDITOR (YAML)
engram search <query>              Full-text search
engram export                      Export entire vault as JSON
engram checkpoint <summary>        Extract durable memories from a session summary
engram repl                        Interactive REPL mode
engram shadow start                Start shadow mode (server + watcher, background)
engram shadow stop                 Stop shadow mode
engram shadow status               Check shadow mode status
engram shadow results              Compare Engram vs your CLAUDE.md

Options:

code

--db <path>         Database file path (default: ~/.engram/default.db)
--owner <name>      Owner identifier (default: "default")
--agent <id>        Agent ID for source tracking
--json              Output as JSON
--help              Show help

Configuration

Gemini API Key

Required for embeddings, consolidation, and LLM-powered extraction:

bash

export GEMINI_API_KEY=your-key-here

Database Location

Engram stores data in ~/.engram/ by default. Override with:

bash

export ENGRAM_DB_PATH=/path/to/engram.db

Environment Variables

Variable	Description	Default
`GEMINI_API_KEY`	Gemini API key for embeddings & consolidation	—
`ENGRAM_LLM_PROVIDER`	LLM provider: `gemini`, `openai`, `anthropic`	`gemini`
`ENGRAM_LLM_API_KEY`	LLM API key (falls back to `GEMINI_API_KEY` for gemini)	—
`ENGRAM_LLM_MODEL`	LLM model name	provider default
`ENGRAM_LLM_BASE_URL`	Custom API base URL (Groq, Cerebras, Ollama, etc.)	provider default
`ENGRAM_DB_PATH`	SQLite database path	`~/.engram/default.db`
`ENGRAM_OWNER`	Vault owner name	`default`
`ENGRAM_HOST`	Server bind address	`127.0.0.1`
`ENGRAM_PORT`	Server port	`3800`
`ENGRAM_AUTH_TOKEN`	Bearer token for API auth	—
`ENGRAM_CORS_ORIGIN`	CORS allowed origin	localhost only

Benchmarks

System	LOCOMO Score	Tokens/Query
Engram	80.0%	776
Mem0	66.9%	—
Manual files	74.5%	1,373
Full Context	86.2%	22,976

Full context (dumping entire conversation history) scores highest but uses 30x more tokens and can't scale past context window limits. Engram closes most of the gap while using 96.6% fewer tokens. For comparison, Mem0 (the most popular agent memory system) scores 66.9% on the same benchmark.

Rate Limits & Free Tier

Engram works with Gemini's free API tier, but be aware of its limits:

Free tier: ~20 requests/minute for gemini-2.5-flash, ~1,500 requests/day
Embedding calls also count toward the limit

Engram has built-in retry logic: if you hit a rate limit, it will automatically wait and retry up to 3 times. You'll see a log message like:

code

[engram] Gemini embedContent rate limited. Retrying in 33s (attempt 1/3)...

If you're making heavy use of Engram (frequent remembers + recalls in quick succession), consider upgrading to a paid Gemini API key for higher limits.

Badge

Using Engram in your project? Add the badge to your README:

markdown

[![Made with Engram](https://img.shields.io/badge/memory-Engram-8B5CF6?style=flat)](https://github.com/tstockham96/engram)

License

MIT

Install

Configuration

Environment variables

GEMINI_API_KEYrequiredsecret

Google Gemini API key for embeddings and LLM operations

claude_desktop_config.json

{
  "mcpServers": {
    "engram": {
      "command": "npx",
      "args": [
        "-y",
        "engram-sdk@0.5.1"
      ],
      "env": {
        "GEMINI_API_KEY": "<YOUR_GEMINI_API_KEY>"
      }
    }
  }
}

🧠 Engram

Quick Start

MCP Setup (recommended — Claude Code / Cursor)

REST API (non-Node environments)

For AI Agents

Why Not Just Use CLAUDE.md?

Why Engram

MCP Tools Reference

REST API Reference

POST /v1/memories — Store a memory

GET /v1/memories/recall — Recall memories

POST /v1/memories/recall — Recall (complex query)

DELETE /v1/memories/:id — Forget a memory

GET /v1/memories/:id/neighbors — Graph neighbors

POST /v1/consolidate — Run consolidation

GET /v1/briefing — Session briefing

GET /v1/stats — Vault statistics

GET /v1/entities — List entities

GET /health — Health check

TypeScript SDK

CLI Reference

Configuration

Gemini API Key

Database Location

Environment Variables

Benchmarks

Rate Limits & Free Tier

Badge

License

Links

Install

Configuration

`POST /v1/memories` — Store a memory

`GET /v1/memories/recall` — Recall memories

`POST /v1/memories/recall` — Recall (complex query)

`DELETE /v1/memories/:id` — Forget a memory

`GET /v1/memories/:id/neighbors` — Graph neighbors

`POST /v1/consolidate` — Run consolidation

`GET /v1/briefing` — Session briefing

`GET /v1/stats` — Vault statistics

`GET /v1/entities` — List entities

`GET /health` — Health check