Engram

Persistent, semantic memory for AI agents. Store, search, and retrieve conversational memory with FTS5 full-text search, optional vector embeddings, graph relationships, and hybrid ranking.

Built by Cartisien.

What it does

Engram gives AI agents long-term memory that persists across sessions. Instead of losing context when a conversation ends, agents can store memories and recall them later using keyword search, semantic similarity, or both.

import { Engram } from '@cartisien/engram';

const engram = new Engram({ dbPath: './memory.db' });
await engram.init();

// Store a memory
await engram.remember('session-1', 'User prefers dark mode and TypeScript');

// Recall by keyword or semantic similarity
const memories = await engram.recall('session-1', 'UI preferences', { limit: 5 });

Features

• SQLite-backed with WAL mode for reliability and zero external dependencies
• FTS5 full-text search with BM25 ranking and Porter stemming
• Vector search via OpenAI or Ollama embeddings (optional)
• Hybrid scoring combines semantic, keyword, importance, and recency signals
• Graph memory extracts entity relationships with multi-hop traversal
• Memory tiers (working, long-term, archived) with automatic consolidation
• Deduplication via content hashing to prevent redundant storage
• User-scoped memory for cross-session persistence
• MCP server for use with Claude Desktop, Cursor, Windsurf, and other MCP clients

Architecture

engram (monorepo)
├── packages/
│   ├── engram/           Core SDK — drop-in memory for any Node/Bun app
│   ├── engram-client/    Typed HTTP client for the hosted API
│   └── engram-mcp/       MCP server (stdio) for AI coding tools
└── services/
    ├── engram-api/       Hosted HTTP API (Hono + Bun)
    └── engram-cloud/     Dashboard and billing (Next.js)

Packages

@cartisien/engram (core)

The core SDK. Runs anywhere Node.js or Bun runs. SQLite storage, FTS5 search, optional embeddings.

npm install @cartisien/engram

See packages/engram/README.md for the full API reference, configuration options, and migration guide.

@cartisien/engram-client

Typed HTTP client for the hosted Engram API. Use this when you want managed infrastructure instead of self-hosting.

npm install @cartisien/engram-client

import { createClient } from '@cartisien/engram-client';

const engram = createClient({ apiKey: process.env.ENGRAM_API_KEY! });
await engram.remember('session-1', 'The user prefers TypeScript');
const hits = await engram.recall('session-1', 'programming preferences');

See packages/engram-client/README.md for all options.

@cartisien/engram-mcp

MCP server that exposes Engram tools over stdio. Works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.

npx @cartisien/engram-mcp

Tools exposed: remember, recall, search, forget, stats.

Services

engram-api

Production HTTP API built with Hono on Bun. Per-workspace SQLite databases, API key authentication, rate limiting.

Endpoints:

• POST /v1/memory — store a memory
• GET /v1/memory — recall memories (keyword + semantic search)
• DELETE /v1/memory — delete memories by ID or timestamp
• GET /health — health check with memory stats
• GET /docs — API reference

engram-cloud

Next.js dashboard for workspace management, API key provisioning, and billing. Magic-link authentication.

Search modes

Engram supports three search modes depending on your configuration:

Mode	Config	What it uses
Keyword only	semanticSearch: false	FTS5 with BM25 ranking
Semantic only	semanticSearch: true, no FTS5	Vector cosine similarity
Hybrid (default)	semanticSearch: true + FTS5	Weighted combination of both

Hybrid scoring weights (configurable):

Signal	Default weight	What it measures
Semantic	0.50	Vector similarity to query
Keyword	0.25	FTS5 BM25 relevance
Importance	0.15	Memory importance score (0-1)
Recency	0.10	Time decay factor

Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck

Project structure

packages/engram/src/
├── index.ts              Main Engram class
├── search/
│   ├── fts5.ts           FTS5 full-text search
│   └── semantic.ts       Vector embedding search
├── graph/
│   ├── extractor.ts      Entity/relationship extraction
│   └── traversal.ts      Multi-hop graph queries
├── scoring/
│   └── importance.ts     Memory importance scoring
└── cache/
    └── embedding.ts      LRU embedding cache

Database migrations

Migrations live in services/engram-cloud/drizzle/ and are tracked in a schema_migrations table.

# Check migration status
./scripts/deploy-migrate.sh --status

# Dry run pending migrations
./scripts/deploy-migrate.sh --dry-run

# Apply pending migrations
./scripts/deploy-migrate.sh

Deployment

The hosted API runs on a DigitalOcean droplet managed with PM2. Deploy process:

git pull origin main
cd packages/engram && pnpm run build
pm2 start ecosystem.config.js

See docs/deploy/ for the deployment readiness report, credential rotation runbook, and smoke test documentation.

License

MIT — see LICENSE.