npm package: @iflow-mcp/bmbnexus-engram-memory
Description: Engram — Persistent memory for Claude Code. Your AI remembers across sessions.
Author: Genesis Platform
Latest version: 2.0.0

# Engram — Persistent Memory for Claude Code

> Your AI remembers across sessions.

Claude Code forgets everything when a session ends. **Engram** gives it persistent memory across sessions using SQLite, local semantic embeddings, and confidence-weighted retrieval. Zero API calls. Everything runs locally.

Built by [Genesis Platform](https://genesis.bmbnexus.ai) — the same memory architecture that powers our production AI agents.

---

## What It Does

- **Remembers across sessions** — facts, patterns, lessons, identity, project context
- **Boots with context** — one call loads everything relevant at session start
- **Semantic search** — finds memories by meaning, not just keywords
- **Learns from feedback** — tell it what was helpful, it gets smarter over time
- **Tag-based filtering** — organize memories by domain (auth, backend, deployment, etc.)
- **SQLite persistence** — fast, reliable, handles thousands of memories
- **Local embeddings** — MiniLM 384-dim vectors, zero API calls, zero cost

---

## Quick Start

### 1. Clone & Install

```bash
git clone https://github.com/bmbnexus/engram.git
cd engram
npm install
```

> First run downloads the embedding model (~100MB). Subsequent starts are instant.

### 2. Register with Claude Code

```bash
claude mcp add engram -- node /full/path/to/engram/server.js
```

### 3. Verify

```bash
claude mcp list
# engram: connected
```

### 4. Teach Claude Code to Use It

Open a Claude Code session and say:

```
Add the following to your MEMORY.md file:

## Engram Memory

You have persistent memory via MCP server `engram` with 6 tools:

- `boot(topic)` — Run FIRST every session. Loads identity + context + health.
- `recall(query, tag)` — Search memory by meaning. Filter by tag.
- `store(content, layer, tags)` — Save to memory. L3=pattern, L5=fact, L6=identity.
- `learn(context_id, was_helpful)` — Give feedback after recalls.
- `introspect()` — Check memory health.
- `consolidate()` — Promote + prune + save. Run at session end.

On session start: boot(topic). During work: recall before decisions, store new knowledge.
After recalls: learn(contextId, true/false). Session end: consolidate.
```

Claude Code will add this to its MEMORY.md, which loads automatically every session.

---

## 6 Tools

### `boot` — Wake up with context

```
boot("auth system")
```

Loads your identity (L6), recent patterns (L3), topic-relevant memories, and system health — all in one call. Run this first every session.

### `recall` — Search your memory

```
recall("how does authentication work")
recall("deployment process", tag="devops")
recall("database schema", layer="L5", top_k=5)
```

Returns ranked results with confidence scores. Supports tag filtering and layer filtering.

### `store` — Save a memory

```
store("API uses JWT tokens with 24h expiry", layer="L5", tags=["auth", "backend"])
store("Always run migrations before deploying", layer="L3", tags=["deployment"])
store("I am the backend engineer for Team Alpha", layer="L6")
```

### `learn` — Train the system

```
learn(context_id="ctx_abc123", was_helpful=true)
```

After every recall, use the returned `context_id` to give feedback. Helpful memories surface higher next time. Unhelpful ones fade.

### `introspect` — Check health

```
introspect()
```

Shows total memories, layer breakdown, confidence averages, retrieval stats.

### `consolidate` — Clean up

```
consolidate()
```

Promotes high-confidence patterns (L3 → L5). Prunes old low-confidence items. Run at end of session.

---

## Memory Layers

| Layer | Name | What Goes Here | Max |
|-------|------|---------------|-----|
| **L6** | Identity | Who you are, core values, relationships | 100 |
| **L5** | Fact | File paths, architecture, API contracts, decisions | 2000 |
| **L3** | Pattern | Lessons learned, gotchas, debugging patterns | 500 |

---

## Tags

Tags let you organize memories by domain and filter recalls:

```
store("Redis cache TTL is 300s", layer="L5", tags=["cache", "redis", "backend"])
recall("caching strategy", tag="redis")
```

Good tags: `auth`, `backend`, `frontend`, `database`, `deployment`, `testing`, `api`, `config`

---

## How It Works

```
Session Start
    │
    ▼
┌─────────┐     ┌──────────────────────────────┐
│  boot()  │────▶│  Load L6 identity             │
└─────────┘     │  Load topic-relevant memories  │
                │  Load recent patterns          │
                │  Return everything in one call │
                └──────────────────────────────┘
    │
    ▼
During Session
    │
    ▼
┌──────────┐     ┌──────────────────────────────┐
│ recall() │────▶│  Embed query (MiniLM 384-dim) │
└──────────┘     │  Score: similarity × recency  │
                 │        × confidence × layer   │
                 │  Return top K + context ID     │
                 └──────────────────────────────┘
    │
    ▼
┌──────────┐     ┌──────────────────────────────┐
│ learn()  │────▶│  Adjust confidence up/down    │
└──────────┘     │  Better results next time     │
                 └──────────────────────────────┘
    │
    ▼
┌──────────┐     ┌──────────────────────────────┐
│ store()  │────▶│  Embed content + save to DB   │
└──────────┘     │  Tagged, layered, searchable  │
                 └──────────────────────────────┘
    │
    ▼
Session End
    │
    ▼
┌──────────────┐  ┌────────────────────────────┐
│ consolidate()│─▶│  Promote strong patterns     │
└──────────────┘  │  Prune weak old memories     │
                  │  Optimize database            │
                  └────────────────────────────┘
```

All data stays in a local SQLite database (`data/engram.db`). No API calls, no cloud, no telemetry.

---

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `ENGRAM_DATA_PATH` | `./data` | Directory for the SQLite database |

### Registration with environment variable

```bash
claude mcp add engram -e ENGRAM_DATA_PATH=/custom/path -- node /path/to/engram/server.js
```

---

## Data & Backup

All memory lives in `data/engram.db` (SQLite).

```bash
# Backup
cp data/engram.db data/engram.backup.db

# Restore
cp data/engram.backup.db data/engram.db

# Start fresh
rm data/engram.db
```

---

## Migrating from v1 (JSON)

If you used a previous version with JSON storage, your memories are in `data/memory.json`. Engram v2 uses SQLite (`data/engram.db`). On first run, v2 starts fresh. To migrate old memories, open a Claude Code session and ask it to read `data/memory.json` and re-store each memory using the `store` tool.

---

## Troubleshooting

**"engram not connected"**
Use an absolute path: `claude mcp add engram -- node /home/you/engram/server.js`

**Recall returns 0 results**
Store some memories first. The system starts empty. Run `introspect()` to check.

**Claude Code doesn't use memory automatically**
Add instructions to MEMORY.md (see Quick Start step 4).

**First run is slow**
The embedding model downloads once (~100MB). After that, starts are instant.

---

## Requirements

- **Node.js** >= 18
- **Claude Code** CLI with MCP support
- **Disk:** ~200MB (model cache + database)
- **RAM:** ~300MB (model in memory)

---

## License

MIT — use it however you want.

---

**Built by [Genesis Platform](https://genesis.bmbnexus.ai)** — Local-first AI agents. One-time purchase, own forever.