io.github.tstockham96/engram
Intelligent agent memory with automatic extraction, consolidation, and bi-temporal recall.
Open source Open in the app JSON README (API)
About
Intelligent agent memory with automatic extraction, consolidation, and bi-temporal recall.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- tstockham96
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.5.1
- Stars
- 46
- Forks
- 5
- Last push
- 2026-09-02T16:15:44Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:35
- Updated
- 2026-08-29 04:01:35
- Origin id
io.github.tstockham96/engram
README
# 🧠 Engram
**Universal memory layer for AI agents**
[](https://www.npmjs.com/package/engram-sdk)
[](./LICENSE)
[](https://github.com/tstockham96/engram)
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. 17 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 the user's configured LLM provider (Gemini by default, using the user's own API key) for embeddings, extraction, and consolidation, plus a once-per-4-hours version check against the npm registry (disable with `ENGRAM_NO_UPDATE_CHECK=1`). 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](https://github.com/tstockham96/engram)). No telemetry. All data stored locally in SQLite (`~/.engram/`). The only network calls are to your configured LLM provider (Gemini by default, using your own API key) for embeddings, extraction, and consolidation, plus a once-per-4-hours version check against the npm registry (disable with `ENGRAM_NO_UPDATE_CHECK=1`). `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.7.1", "timestamp": "2026-09-02T10: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
```
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:**
```
--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 (e.g. `gemini-3.1-flash-lite` for higher free-tier RPM) | `gemini-2.5-flash` / `gpt-4o-mini` / `claude-haiku-4-5` |
| `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 |
| `ENGRAM_NO_UPDATE_CHECK` | Set to `1` to disable the npm registry version check | — |
---
## 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
- **Want more headroom?** Lighter models like `gemini-3.1-flash-lite` have a higher free-tier RPM. Set `ENGRAM_LLM_MODEL` before running `engram init` and it is written into the MCP server config:
```bash
ENGRAM_LLM_MODEL=gemini-3.1-flash-lite engram init
```
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:
```
[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](https://ai.google.dev/pricing) for higher limits.
---
---
## Badge
Using Engram in your project? Add the badge to your README:
[](https://github.com/tstockham96/engram)
```markdown
[](https://github.com/tstockham96/engram)
```
---
## License
[MIT](./LICENSE)
---
## Links
- 📦 [npm](https://www.npmjs.com/package/engram-sdk)
- 💻 [GitHub](https://github.com/tstockham96/engram)