engram-sdk 0.1.0 → 0.1.2

package/README.md

@@ -1,309 +1,350 @@
 # 🧠 Engram
 
-**Universal memory protocol for AI agents.**
+**Universal memory layer for AI agents**
 
-AI agents have amnesia. Every session starts blank. Engram fixes this — a memory protocol with a REST API, knowledge graph, and consolidation engine that turns raw episodes into structured knowledge. Think of it as giving your agent a hippocampus.
+[![npm version](https://img.shields.io/npm/v/engram-sdk)](https://www.npmjs.com/package/engram-sdk)
+[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![GitHub stars](https://img.shields.io/github/stars/tstockham96/engram)](https://github.com/tstockham96/engram)
 
-## Why
+Engram gives AI agents knowledge graphs, consolidation, and spreading activation. Not storage. Understanding.
 
-Every AI agent framework bolts on memory as an afterthought — a flat file, a vector DB, maybe a conversation log. None of them solve the real problem:
+---
+
+## Quick Start
 
-- **Amnesia**: Agents forget everything between sessions
-- **No consolidation**: Raw episodes pile up, never distilled into knowledge
-- **No relationships**: Memories exist in isolation, no graph of connections
-- **No decay**: Everything is equally important forever
-- **No portability**: Memory locked into one framework
+### MCP Setup (recommended — Claude Code / Cursor)
 
-Engram is a protocol, not a plugin. It works with any agent, any framework, any language.
+```bash
+npm install -g engram-sdk
+engram init
+```
 
-## Quick Start (60 seconds)
+That's it. 10 memory tools available via MCP.
 
-### 1. Install & run
+### REST API (non-Node environments)
 
 ```bash
-npm install engram-sdk
-export GEMINI_API_KEY=your-key-here  # Get one free at ai.google.dev
+npm install -g engram-sdk
+export GEMINI_API_KEY=your-key-here
 npx engram-serve
-# → Engram listening on http://localhost:3800
 ```
 
-That's it. Engram is running with vector search, auto-extraction, and consolidation.
+Server starts on `http://127.0.0.1:3800`.
 
-> **No Gemini key?** Engram works without one — you just won't get embeddings or LLM-powered features. Or use our [hosted API](https://engram-site.vercel.app) and skip setup entirely.
+---
 
-### 2. Remember & recall
+## Why Engram
 
-```bash
-# Store a memory
-curl -X POST http://localhost:3800/v1/memories \
-  -H 'Content-Type: application/json' \
-  -d '{"content": "User prefers dark mode and concise answers"}'
+| | Traditional memory | Engram |
+|---|---|---|
+| **Storage** | Flat vectors or files | Knowledge graph with typed edges |
+| **Maintenance** | Manual curation | Sleep-cycle consolidation (LLM-powered) |
+| **Retrieval** | You ask, it answers | Spreading activation surfaces context you didn't ask for |
 
-# Recall relevant memories
-curl -X POST http://localhost:3800/v1/memories/recall \
-  -H 'Content-Type: application/json' \
-  -d '{"query": "user preferences", "context": "settings page"}'
+**Benchmarks (LOCOMO):**
 
-# Consolidate (distill episodes into knowledge)
-curl -X POST http://localhost:3800/v1/consolidate
-```
+- **79.6%** accuracy (vs 66.9% Mem0, 74.5% manual memory files)
+- **44% fewer tokens** than manual memory files (776 vs 1,373 per query)
 
-### TypeScript SDK
+---
 
-```typescript
-import { Vault } from 'engram-sdk';
+## MCP Tools Reference
+
+| Tool | Description |
+|------|-------------|
+| `engram_remember` | Store a memory. Auto-extracts entities and topics. |
+| `engram_recall` | Recall relevant memories via semantic search. |
+| `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_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. |
+
+---
 
-const vault = new Vault();
+## REST API Reference
 
-// Remember
-await vault.remember('User prefers dark mode and concise answers');
-await vault.remember('User is training for a marathon in April');
+All endpoints return JSON. Base URL: `http://127.0.0.1:3800`
 
-// Recall
-const memories = await vault.recall('What are the user preferences?');
-console.log(memories);
+### `POST /v1/memories` — Store a memory
 
-// Consolidate
-await vault.consolidate();
-vault.close();
+```bash
+curl -X POST http://localhost:3800/v1/memories \
+  -H "Content-Type: application/json" \
+  -d '{"content": "User prefers TypeScript over JavaScript", "type": "semantic"}'
 ```
 
-### Python (via REST API)
+```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"
+}
+```
 
-```python
-import requests
+### `GET /v1/memories/recall` — Recall memories
 
-API = "http://localhost:3800/v1"
+```bash
+curl "http://localhost:3800/v1/memories/recall?context=language+preferences&limit=5"
+```
 
-# Store a memory
-requests.post(f"{API}/memories", json={
-    "content": "User prefers dark mode and concise answers",
-    "entities": ["User"],
-    "topics": ["preferences"],
-    "salience": 0.8,
-})
+Query parameters: `context` (required), `entities`, `topics`, `types`, `limit`, `spread`, `spreadHops`, `spreadDecay`, `spreadEntityHops`
 
-# Recall
-memories = requests.get(f"{API}/memories/recall", params={"context": "user preferences"}).json()
+```json
+{
+  "memories": [
+    {
+      "id": "m_abc123",
+      "content": "User prefers TypeScript over JavaScript",
+      "type": "semantic",
+      "salience": 0.7
+    }
+  ],
+  "count": 1
+}
 ```
 
-Python SDK coming soon. The REST API works with any language — no SDK required.
+### `POST /v1/memories/recall` — Recall (complex query)
 
-## REST API Reference
+```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.
 
-Start the server:
+### `DELETE /v1/memories/:id` — Forget a memory
 
 ```bash
-# Environment variables
-ENGRAM_OWNER=my-agent        # Vault owner ID (required)
-ENGRAM_DB_PATH=./my.db       # Database path (optional)
-ENGRAM_PORT=3800             # Port (default: 3800)
-ENGRAM_HOST=127.0.0.1        # Host (default: 127.0.0.1)
-ENGRAM_LLM_PROVIDER=anthropic # LLM for consolidation (optional)
-ENGRAM_LLM_API_KEY=sk-...    # LLM API key (optional)
-
-npx engram serve
-# or
-npm run serve
+curl -X DELETE "http://localhost:3800/v1/memories/m_abc123?hard=true"
 ```
 
-### Endpoints
+```json
+{ "deleted": "m_abc123", "hard": true }
+```
 
-| Method | Path | Description |
-|--------|------|-------------|
-| `POST` | `/v1/memories` | Store a memory |
-| `GET` | `/v1/memories/recall?context=...` | Recall memories (simple) |
-| `POST` | `/v1/memories/recall` | Recall memories (complex query) |
-| `DELETE` | `/v1/memories/:id` | Forget a memory |
-| `GET` | `/v1/memories/:id/neighbors` | Graph traversal |
-| `POST` | `/v1/connections` | Connect two memories |
-| `POST` | `/v1/consolidate` | Run consolidation engine |
-| `GET` | `/v1/entities` | List tracked entities |
-| `GET` | `/v1/stats` | Vault statistics |
-| `POST` | `/v1/export` | Export full vault as JSON |
-| `GET` | `/health` | Health check |
+### `GET /v1/memories/:id/neighbors` — Graph neighbors
 
-### POST /v1/memories
+```bash
+curl "http://localhost:3800/v1/memories/m_abc123/neighbors?depth=2"
+```
 
 ```json
 {
-  "content": "User prefers TypeScript over JavaScript",
-  "type": "episodic",           // episodic | semantic | procedural
-  "entities": ["User", "TypeScript", "JavaScript"],
-  "topics": ["preferences", "engineering"],
-  "salience": 0.8,              // 0-1, importance
-  "confidence": 0.9,            // 0-1, certainty
-  "visibility": "owner_agents"  // private | owner_agents | shared | public
+  "memories": [ ... ],
+  "count": 3
 }
 ```
 
-### GET /v1/memories/recall
+### `POST /v1/consolidate` — Run consolidation
 
-Query params: `context` (required), `entities`, `topics`, `types`, `limit`
+```bash
+curl -X POST http://localhost:3800/v1/consolidate
+```
 
-### POST /v1/memories/recall
+```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
 {
-  "context": "project status",
-  "entities": ["Engram"],
-  "topics": ["engineering"],
-  "types": ["semantic"],
-  "minSalience": 0.5,
-  "limit": 10
+  "summary": "...",
+  "keyFacts": [{ "content": "...", "salience": 0.9 }],
+  "activeCommitments": [{ "content": "...", "status": "pending" }],
+  "recentActivity": [{ "content": "..." }]
 }
 ```
 
-### POST /v1/connections
+Also available as `POST /v1/briefing` with JSON body.
+
+### `GET /v1/stats` — Vault statistics
+
+```bash
+curl http://localhost:3800/v1/stats
+```
 
 ```json
 {
-  "sourceId": "memory-uuid-1",
-  "targetId": "memory-uuid-2",
-  "type": "supports",           // supports | contradicts | elaborates | supersedes | causes | caused_by | ...
-  "strength": 0.7
+  "total": 142,
+  "byType": { "episodic": 89, "semantic": 41, "procedural": 12 },
+  "entities": 27,
+  "edges": 63
 }
 ```
 
-## Core Concepts
+### `GET /v1/entities` — List entities
 
-### Memory Types
+```bash
+curl http://localhost:3800/v1/entities
+```
 
-| Type | What | Example |
-|------|------|---------|
-| **Episodic** | Events, conversations, observations | "User asked about React performance" |
-| **Semantic** | Facts, knowledge, patterns | "User prefers TypeScript over JavaScript" |
-| **Procedural** | How-to knowledge, workflows | "To deploy: run tests → build → push to main" |
+```json
+{
+  "entities": [
+    { "name": "TypeScript", "count": 12 },
+    { "name": "React", "count": 8 }
+  ],
+  "count": 27
+}
+```
 
-### The Memory Lifecycle
+### `GET /health` — Health check
 
+```bash
+curl http://localhost:3800/health
 ```
-Episode → Remember → Store → Recall → Consolidate → Knowledge
-                                           ↓
-                                    Decay / Archive
+
+```json
+{ "status": "ok", "version": "0.1.0", "timestamp": "2025-01-15T10:30:00.000Z" }
 ```
 
-1. **Remember**: Raw episodes go in with metadata (entities, topics, salience)
-2. **Recall**: Hybrid retrieval — entity matching, topic matching, semantic search, recency
-3. **Consolidate**: The "sleep cycle" — episodes get distilled into semantic memories, entities get discovered, connections form, contradictions surface
-4. **Decay**: Memories naturally fade unless reinforced by access. High-salience memories resist decay.
+---
 
-### Memory Graph
+## TypeScript SDK
 
-Memories aren't flat — they're a graph. Edges connect related memories:
+```typescript
+import { Vault } from 'engram-sdk';
 
-- `supports` / `contradicts` — agreement or conflict
-- `elaborates` — adds detail
-- `supersedes` — replaces outdated info
-- `causes` / `caused_by` — causal chains
-- `temporal_next` — sequential events
-- `derived_from` — consolidation lineage
+const vault = new Vault({ owner: 'my-agent' });
 
-### Entities
+await vault.remember('User prefers TypeScript');
+const memories = await vault.recall('language preferences');
+await vault.consolidate();
+```
 
-Engram automatically tracks entities (people, places, projects, concepts) across memories. Entity frequency and co-occurrence drive importance scores and recall relevance.
+---
+
+## CLI Reference
 
-## LLM-Powered Consolidation
+```
+engram init                        Set up Engram for Claude Code / Cursor / MCP clients
+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 search <query>              Full-text search
+engram export                      Export entire vault as JSON
+engram eval                        Health report & value assessment
+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
+```
 
-For the full consolidation experience, configure an LLM:
+**Options:**
 
-```typescript
-const vault = new Vault({
-  owner: 'my-agent',
-  llm: {
-    provider: 'anthropic',
-    apiKey: process.env.ANTHROPIC_API_KEY!,
-    model: 'claude-3-5-haiku-20241022',
-  },
-});
+```
+--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
 ```
 
-Or via environment variables with the REST API:
+---
+
+## Configuration
+
+### Gemini API Key
+
+Required for embeddings, consolidation, and LLM-powered extraction:
 
 ```bash
-ENGRAM_LLM_PROVIDER=anthropic ENGRAM_LLM_API_KEY=sk-... npx engram serve
+export GEMINI_API_KEY=your-key-here
 ```
 
-The LLM analyzes episodes and extracts:
-- **Semantic memories**: General facts and patterns
-- **Entities**: People, places, projects with properties
-- **Contradictions**: Conflicting information
-- **Connections**: How episodes relate to each other
+### Database Location
 
-## CLI
+Engram stores data in `~/.engram/` by default. Override with:
 
 ```bash
-npx engram remember "User prefers React over Vue"
-npx engram recall "frontend preferences"
-npx engram stats
-npx engram entities
-npx engram consolidate
-npx engram export > backup.json
-npx engram repl          # Interactive mode
-npx engram serve         # Start REST API server
+export ENGRAM_DB_PATH=/path/to/engram.db
 ```
 
-## Architecture
+### 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_DB_PATH` | SQLite database path | `~/.engram/default.db` |
+| `ENGRAM_OWNER` | Vault owner name | `default` |
+| `ENGRAM_HOST` | Server bind address | `127.0.0.1` |
+| `PORT` | Server port | `3800` |
+| `ENGRAM_AUTH_TOKEN` | Bearer token for API auth | — |
+| `ENGRAM_CORS_ORIGIN` | CORS allowed origin | localhost only |
+| `ENGRAM_TELEMETRY` | Set to `off` to disable telemetry | on |
 
-```
-┌─────────────────────────────────────────────────┐
-│                  REST API Server                  │
-│  POST /v1/memories · GET /v1/memories/recall · …  │
-├─────────────────────────────────────────────────┤
-│                    Vault API                      │
-│  remember() · recall() · consolidate() · forget() │
-├─────────────────────────────────────────────────┤
-│               Retrieval Engine                    │
-│  Entity match · Topic match · Vector search · FTS │
-├─────────────────────────────────────────────────┤
-│            Consolidation Engine                   │
-│  Rule-based │ LLM-powered (Anthropic/OpenAI)      │
-├─────────────────────────────────────────────────┤
-│              SQLite Storage Layer                  │
-│  Memories · Edges · Entities · Embeddings          │
-└─────────────────────────────────────────────────┘
-```
+---
 
-**Open source**: Fully MIT licensed. Memory is sensitive data — you should be able to see exactly what happens with it. Self-host, fork, contribute, or use the hosted API for production.
+## Benchmarks
 
-**Portable**: Export your entire vault as JSON. Import it elsewhere. Your agent's memory belongs to you.
+| System | LOCOMO Score | Tokens/Query |
+|--------|-------------|--------------|
+| **Engram** | **79.6%** | **776** |
+| Mem0 | 66.9% | — |
+| Manual files | 74.5% | 1,373 |
+| Full Context | 86.2% | 22,976 |
 
-## Comparison
+[Full research methodology →](https://www.engram.fyi/#/research)
 
-| Feature | Engram | Mem0 | Zep | Letta/MemGPT |
-|---------|--------|------|-----|-------------|
-| Spreading activation | ✅ | ❌ | ❌ | ❌ |
-| LLM consolidation | ✅ | ❌ | ❌ | Partial |
-| Knowledge graph | ✅ | ✅ (graph memory) | ✅ | ❌ |
-| Entity tracking | ✅ | ✅ | ✅ | ❌ |
-| Memory decay | ✅ | ❌ | ❌ | ❌ |
-| REST API | ✅ | ✅ | ✅ | ✅ |
-| Local-first | ✅ | Cloud-default | Cloud-default | ✅ |
-| Language-agnostic | ✅ | Python-first | Python-first | Python-first |
-| Source-available | ✅ | Partial | Partial | ✅ |
+---
 
-## Roadmap
+## Telemetry
 
-- [x] TypeScript SDK
-- [x] REST API server
-- [x] sqlite-vec vector search
-- [x] LLM-powered consolidation
-- [x] CLI with REPL
-- [ ] Hosted service (api.engram.ai)
-- [ ] Python SDK
-- [ ] Framework integrations (OpenClaw, LangChain, CrewAI)
-- [ ] Protocol spec (open standard)
-- [ ] Multi-agent vault sharing
-- [ ] Conflict resolution across agents
+Engram collects lightweight, anonymous usage data:
 
-## Contributing
+- Random anonymous ID (UUID, not tied to personal info)
+- Event type (`server_start`, `init`, `daily_heartbeat`)
+- Version, platform, architecture, Node.js version
+- Vault stats (memory count, entity count — **no content**)
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+**Opt out:**
+
+```bash
+export ENGRAM_TELEMETRY=off
+# or
+export DO_NOT_TRACK=1
+```
+
+All telemetry is fire-and-forget — never blocks, never throws, fails silently with a 2-second timeout.
+
+---
 
 ## License
 
-MIT. See [LICENSE](LICENSE) for details.
+[AGPL-3.0-or-later](https://www.gnu.org/licenses/agpl-3.0)
 
 ---
 
-*Built by [Thomas Stockham](https://tstockham.com). Engram is the memory layer the AI agent ecosystem is missing.*
+## Links
+
+- 🌐 [Website](https://www.engram.fyi)
+- 📊 [Research](https://www.engram.fyi/#/research)
+- 📦 [npm](https://www.npmjs.com/package/engram-sdk)
+- 💻 [GitHub](https://github.com/tstockham96/engram)

package/dist/accounts.d.ts

@@ -0,0 +1,40 @@
+export type Plan = 'free' | 'growth' | 'pro' | 'enterprise';
+export interface Account {
+    id: string;
+    email: string;
+    apiKey: string;
+    plan: Plan;
+    createdAt: string;
+    memoriesStored: number;
+    recallsThisMonth: number;
+    consolidationsThisMonth: number;
+    usageResetAt: string;
+}
+export declare const PLAN_LIMITS: Record<Plan, {
+    memories: number;
+    recalls: number;
+    consolidations: number;
+    agents: number;
+}>;
+export type UsageType = 'memory' | 'recall' | 'consolidation';
+export declare class AccountStore {
+    private db;
+    constructor(dbPath: string);
+    generateApiKey(): string;
+    private nextResetDate;
+    createAccount(email: string, plan?: Plan): Account;
+    getAccountByKey(apiKey: string): Account | null;
+    getAccountById(id: string): Account | null;
+    listAccounts(): Account[];
+    trackUsage(accountId: string, type: UsageType): void;
+    decrementMemories(accountId: string): void;
+    checkLimit(account: Account, type: UsageType): {
+        allowed: boolean;
+        limit: number;
+        used: number;
+        resetAt: string;
+    };
+    close(): void;
+    private rowToAccount;
+}
+//# sourceMappingURL=accounts.d.ts.map

package/dist/accounts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accounts.d.ts","sourceRoot":"","sources":["../src/accounts.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,YAAY,CAAC;AAE5D,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,IAAI,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,uBAAuB,EAAE,MAAM,CAAC;IAChC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAKnH,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,eAAe,CAAC;AAE9D,qBAAa,YAAY;IACvB,OAAO,CAAC,EAAE,CAAoB;gBAElB,MAAM,EAAE,MAAM;IAmB1B,cAAc,IAAI,MAAM;IAIxB,OAAO,CAAC,aAAa;IAMrB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,IAAa,GAAG,OAAO;IAc1D,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI;IAiB/C,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI;IAM1C,YAAY,IAAI,OAAO,EAAE;IAKzB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI;IAcpD,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI1C,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAkBjH,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,YAAY;CAarB"}