Installation

Clone the repository

git clone https://github.com/your-username/engram.git cd engram

Install dependencies

npm install

Start the server

npm start The REST API will be available at http://localhost:3838 and the dashboard at http://localhost:5173.

Basic Usage

Store a memory

engram remember "User prefers Fastify over Express for APIs" --category preference

Search for memories

engram recall "What framework does the user prefer?"

List all memories

engram list

Check system status

engram status Usage Modes

1. CLI (Command Line Interface) Perfect for quick interactions and scripting:

Remember something

node bin/engram.js remember "Project uses PostgreSQL 15" --category fact --entity postgresql

Search with options

node bin/engram.js recall "database" --limit 3 --threshold 0.5

Filter by namespace

node bin/engram.js list --namespace project-alpha

Delete a memory

node bin/engram.js forget

Run consolidation

node bin/engram.js consolidate

View conflicts

node bin/engram.js conflicts 2. MCP Server (Claude Desktop/Code) Integrate with Claude Desktop or Claude Code.

✨ Easiest Method: Use the Integration Wizard

Run npm run dev to start the dashboard Open http://localhost:5173 and go to the Agents tab Click Quick Setup → Launch Setup Wizard Select your platform and copy the auto-generated configuration Alternative: Manual Setup

macOS: Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{ "mcpServers": { "engram": { "command": "node", "args": [ "/path/to/engram/bin/engram.js", "start", "--mcp-only" ] } } } Available MCP Tools:

engram_remember - Store a memory engram_recall - Search for relevant memories engram_forget - Delete a memory engram_status - Get system status See docs/mcp-setup.md for detailed configuration.

3. REST API Full HTTP API for programmatic access:

Create a memory

curl -X POST http://localhost:3838/api/memories
-H "Content-Type: application/json"
-d '{ "content": "User prefers Svelte for frontend", "category": "preference", "entity": "svelte", "confidence": 0.9 }'

Search memories

curl -X POST http://localhost:3838/api/memories/search
-H "Content-Type: application/json"
-d '{ "query": "frontend preferences", "limit": 5 }'

Get system status

curl http://localhost:3838/api/status

List memories with filters

curl "http://localhost:3838/api/memories?namespace=default&limit=10"

Delete a memory

curl -X DELETE http://localhost:3838/api/memories/

4. Web Dashboard Visual interface for managing memories:

npm start Then open http://localhost:5173 in your browser.

Dashboard Features:

📊 System overview with statistics 📝 Browse and filter memories 🔍 Semantic search with score visualization ➕ Create new memories 🗑️ Delete memories 📈 View category and namespace distributions ⚠️ Detect and resolve conflicts 🔄 Run consolidation 5. PM2 Process Manager (Production Service) Run Engram as a persistent background service using PM2:

Install PM2 globally (if not already installed)

npm install -g pm2

Start Engram as a PM2 service

npm run pm2:start

Check status

npm run pm2:status

View logs

npm run pm2:logs

Restart service

npm run pm2:restart

Stop service

npm run pm2:stop

Remove from PM2

npm run pm2:delete

Monitor in real-time

npm run pm2:monit Auto-start on boot:

Generate startup script

pm2 startup

Save current PM2 process list

pm2 save PM2 configuration is in ecosystem.config.cjs. Logs are stored in ~/.engram/logs/.

Architecture Memory Categories Engram organizes memories into five categories:

preference - User likes/dislikes ("prefers Fastify over Express") fact - Objective truth about their setup ("uses PostgreSQL 15") pattern - Recurring workflow ("always runs tests before commit") decision - Choice they made and why ("chose React for its ecosystem") outcome - Result of an action ("deployment succeeded after fixing port") Hybrid Recall Algorithm Memories are ranked using a weighted formula:

score = (similarity × 0.5) + (recency × 0.15) + (confidence × 0.2) + (access × 0.05) + fts_boost Similarity: Cosine similarity of embeddings (0-1) Recency: Time-based decay using last access time Confidence: User-specified or auto-calculated confidence (0-1) Access: Normalized access count (0-1, capped at 10 accesses) FTS Boost: +0.1 if found via full-text search Database Schema CREATE TABLE memories ( id TEXT PRIMARY KEY, content TEXT NOT NULL, entity TEXT, category TEXT DEFAULT 'fact', confidence REAL DEFAULT 0.8, embedding BLOB, source TEXT, namespace TEXT DEFAULT 'default', tags TEXT, -- JSON array access_count INTEGER DEFAULT 0, decay_rate REAL DEFAULT 0.01, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, last_accessed INTEGER );

-- FTS5 virtual table for full-text search CREATE VIRTUAL TABLE memories_fts USING fts5( content, entity, category, namespace, content='memories', content_rowid='rowid' ); Configuration Engram uses a YAML configuration file at ~/.engram/config.yml:

dataDir: ~/.engram port: 3838

defaults: namespace: default recallLimit: 5 confidenceThreshold: 0.3

security: secretDetection: true

consolidation: duplicateThreshold: 0.92 decayEnabled: true staleCleanupDays: 90 Advanced Features Secret Detection Engram automatically detects and redacts common secrets:

OpenAI API keys (sk-...) Stripe keys (pk_..., sk_live_...) AWS keys (AKIA...) GitHub tokens (ghp_..., gho_...) Slack tokens (xoxb-..., xoxp-...) Google API keys (AIza...) Private keys (BEGIN PRIVATE KEY) Database connection strings JWT tokens Consolidation Run periodic consolidation to maintain memory quality:

node bin/engram.js consolidate What it does:

Removes duplicate memories (>0.92 similarity) Detects contradictions between memories Applies confidence decay to old, unused memories Marks stale memories for review Namespaces Organize memories by project or context:

Create memories in different namespaces

engram remember "Uses Docker" --namespace project-alpha engram remember "Prefers Kubernetes" --namespace project-beta

Filter by namespace

engram list --namespace project-alpha engram recall "container tech" --namespace project-alpha Development Project Structure engram/ ├── bin/ │ └── engram.js # CLI entry point ├── src/ │ ├── config/ │ │ └── index.js # Configuration management │ ├── memory/ │ │ ├── store.js # SQLite operations │ │ ├── recall.js # Hybrid search │ │ └── consolidate.js # Memory consolidation │ ├── embed/ │ │ └── index.js # Embedding generation │ ├── extract/ │ │ ├── rules.js # Category/entity extraction │ │ └── secrets.js # Secret detection │ ├── server/ │ │ ├── mcp.js # MCP server │ │ └── rest.js # REST API server │ └── utils/ │ ├── id.js # UUID generation │ └── logger.js # Structured logging ├── dashboard/ # React web UI ├── test/ # Test suites ├── docs/ # Documentation └── examples/ # Usage examples Running Tests

Run all tests

npm test

Run tests once (no watch)

npm run test:run

Run specific test file

npx vitest test/memory/store.test.js Building

No build step required - uses ESM modules directly

node bin/engram.js start API Reference See docs/api.md for complete REST API documentation.

Key Endpoints POST /api/memories - Create memory GET /api/memories - List memories POST /api/memories/search - Search memories GET /api/memories/:id - Get single memory DELETE /api/memories/:id - Delete memory POST /api/consolidate - Run consolidation GET /api/conflicts - Get detected conflicts GET /api/status - System status GET /health - Health check Examples Example 1: Project Context Memory // Store project decisions await api.createMemory({ content: "Chose Fastify over Express because of better TypeScript support and performance", category: "decision", entity: "fastify", confidence: 1.0, namespace: "project-api", tags: ["backend", "framework"] });

// Later, recall why you chose it const results = await api.searchMemories("why did we choose Fastify?", { namespace: "project-api", limit: 3 }); Example 2: User Preferences // Store user preferences await api.createMemory({ content: "User prefers compact code without unnecessary comments", category: "preference", entity: "coding-style", confidence: 0.9 });

// Recall preferences before generating code const prefs = await api.searchMemories("coding style preferences", { category: "preference", limit: 5 }); Example 3: Infrastructure Facts // Document infrastructure await api.createMemory({ content: "Production database is PostgreSQL 15 on AWS RDS (db.t3.medium)", category: "fact", entity: "postgresql", namespace: "production" });

// Quick lookup const infra = await api.searchMemories("production database", { namespace: "production" }); See examples/ directory for more detailed examples.

Performance Memory Storage: ~1ms per memory (with embedding) Recall Search: ~10-50ms for 5 results (depends on database size) Database Size: ~2KB per memory (including embedding) Embedding Model: 23MB (downloaded on first use) Memory Usage: ~50MB base + loaded model Troubleshooting Embedding model not downloading

Check internet connection and disk space

Model downloads to ~/.engram/models/

ls -lh ~/.engram/models/

Manual download if needed

mkdir -p ~/.engram/models

The model will auto-download on first use

Port already in use

Change the port

node bin/engram.js start --port 8080 Database locked

SQLite WAL mode should prevent this, but if it happens:

Close all connections and restart

pkill -f "node bin/engram.js" node bin/engram.js start Tests failing

Clean test databases

rm -rf /tmp/engram-*

Run tests

npm test