engram-sdk 0.1.1 โ†’ 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,313 +1,330 @@
1
1
  # ๐Ÿง  Engram
2
2
 
3
- **Universal memory protocol for AI agents.**
3
+ **Universal memory layer for AI agents**
4
4
 
5
- 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.
5
+ [![npm version](https://img.shields.io/npm/v/engram-sdk)](https://www.npmjs.com/package/engram-sdk)
6
+ [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
7
+ [![GitHub stars](https://img.shields.io/github/stars/tstockham96/engram)](https://github.com/tstockham96/engram)
6
8
 
7
- ## Why
9
+ Engram gives AI agents knowledge graphs, consolidation, and spreading activation. Not storage. Understanding.
8
10
 
9
- 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:
11
+ ---
12
+
13
+ ## Quick Start
10
14
 
11
- - **Amnesia**: Agents forget everything between sessions
12
- - **No consolidation**: Raw episodes pile up, never distilled into knowledge
13
- - **No relationships**: Memories exist in isolation, no graph of connections
14
- - **No decay**: Everything is equally important forever
15
- - **No portability**: Memory locked into one framework
15
+ ### MCP Setup (recommended โ€” Claude Code / Cursor)
16
16
 
17
- Engram is a protocol, not a plugin. It works with any agent, any framework, any language.
17
+ ```bash
18
+ npm install -g engram-sdk
19
+ engram init
20
+ ```
18
21
 
19
- ## Quick Start (60 seconds)
22
+ That's it. 10 memory tools available via MCP.
20
23
 
21
- ### 1. Install & run
24
+ ### REST API (non-Node environments)
22
25
 
23
26
  ```bash
24
- npm install engram-sdk
25
- export GEMINI_API_KEY=your-key-here # Get one free at ai.google.dev
27
+ npm install -g engram-sdk
28
+ export GEMINI_API_KEY=your-key-here
26
29
  npx engram-serve
27
- # โ†’ Engram listening on http://localhost:3800
28
30
  ```
29
31
 
30
- That's it. Engram is running with vector search, auto-extraction, and consolidation.
32
+ Server starts on `http://127.0.0.1:3800`.
31
33
 
32
- > **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.
34
+ ---
33
35
 
34
- ### 2. Remember & recall
36
+ ## Why Engram
35
37
 
36
- ```bash
37
- # Store a memory
38
- curl -X POST http://localhost:3800/v1/memories \
39
- -H 'Content-Type: application/json' \
40
- -d '{"content": "User prefers dark mode and concise answers"}'
38
+ | | Traditional memory | Engram |
39
+ |---|---|---|
40
+ | **Storage** | Flat vectors or files | Knowledge graph with typed edges |
41
+ | **Maintenance** | Manual curation | Sleep-cycle consolidation (LLM-powered) |
42
+ | **Retrieval** | You ask, it answers | Spreading activation surfaces context you didn't ask for |
41
43
 
42
- # Recall relevant memories
43
- curl -X POST http://localhost:3800/v1/memories/recall \
44
- -H 'Content-Type: application/json' \
45
- -d '{"query": "user preferences", "context": "settings page"}'
44
+ **Benchmarks (LOCOMO):**
46
45
 
47
- # Consolidate (distill episodes into knowledge)
48
- curl -X POST http://localhost:3800/v1/consolidate
49
- ```
46
+ - **79.6%** accuracy (vs 66.9% Mem0, 74.5% manual memory files)
47
+ - **44% fewer tokens** than manual memory files (776 vs 1,373 per query)
50
48
 
51
- ### TypeScript SDK
49
+ ---
52
50
 
53
- ```typescript
54
- import { Vault } from 'engram-sdk';
51
+ ## MCP Tools Reference
52
+
53
+ | Tool | Description |
54
+ |------|-------------|
55
+ | `engram_remember` | Store a memory. Auto-extracts entities and topics. |
56
+ | `engram_recall` | Recall relevant memories via semantic search. |
57
+ | `engram_briefing` | Structured session briefing โ€” key facts, pending commitments, recent activity. |
58
+ | `engram_consolidate` | Run consolidation โ€” distills episodes into semantic knowledge, discovers entities, finds contradictions. |
59
+ | `engram_surface` | Proactive memory surfacing โ€” pushes relevant memories based on current context. |
60
+ | `engram_connect` | Create a relationship between two memories in the knowledge graph. |
61
+ | `engram_forget` | Forget a memory (soft or hard delete). |
62
+ | `engram_entities` | List all tracked entities with memory counts. |
63
+ | `engram_stats` | Vault statistics โ€” memory counts by type, entity count, etc. |
64
+ | `engram_ingest` | Auto-ingest conversation transcripts or raw text into structured memories. |
65
+
66
+ ---
55
67
 
56
- const vault = new Vault();
68
+ ## REST API Reference
57
69
 
58
- // Remember
59
- await vault.remember('User prefers dark mode and concise answers');
60
- await vault.remember('User is training for a marathon in April');
70
+ All endpoints return JSON. Base URL: `http://127.0.0.1:3800`
61
71
 
62
- // Recall
63
- const memories = await vault.recall('What are the user preferences?');
64
- console.log(memories);
72
+ ### `POST /v1/memories` โ€” Store a memory
65
73
 
66
- // Consolidate
67
- await vault.consolidate();
68
- vault.close();
74
+ ```bash
75
+ curl -X POST http://localhost:3800/v1/memories \
76
+ -H "Content-Type: application/json" \
77
+ -d '{"content": "User prefers TypeScript over JavaScript", "type": "semantic"}'
69
78
  ```
70
79
 
71
- ### Python (via REST API)
80
+ ```json
81
+ {
82
+ "id": "m_abc123",
83
+ "content": "User prefers TypeScript over JavaScript",
84
+ "type": "semantic",
85
+ "entities": ["TypeScript", "JavaScript"],
86
+ "topics": ["programming", "preferences"],
87
+ "salience": 0.7,
88
+ "createdAt": "2025-01-15T10:30:00.000Z"
89
+ }
90
+ ```
72
91
 
73
- ```python
74
- import requests
92
+ ### `GET /v1/memories/recall` โ€” Recall memories
75
93
 
76
- API = "http://localhost:3800/v1"
94
+ ```bash
95
+ curl "http://localhost:3800/v1/memories/recall?context=language+preferences&limit=5"
96
+ ```
77
97
 
78
- # Store a memory
79
- requests.post(f"{API}/memories", json={
80
- "content": "User prefers dark mode and concise answers",
81
- "entities": ["User"],
82
- "topics": ["preferences"],
83
- "salience": 0.8,
84
- })
98
+ Query parameters: `context` (required), `entities`, `topics`, `types`, `limit`, `spread`, `spreadHops`, `spreadDecay`, `spreadEntityHops`
85
99
 
86
- # Recall
87
- memories = requests.get(f"{API}/memories/recall", params={"context": "user preferences"}).json()
100
+ ```json
101
+ {
102
+ "memories": [
103
+ {
104
+ "id": "m_abc123",
105
+ "content": "User prefers TypeScript over JavaScript",
106
+ "type": "semantic",
107
+ "salience": 0.7
108
+ }
109
+ ],
110
+ "count": 1
111
+ }
88
112
  ```
89
113
 
90
- Python SDK coming soon. The REST API works with any language โ€” no SDK required.
114
+ ### `POST /v1/memories/recall` โ€” Recall (complex query)
91
115
 
92
- ## REST API Reference
116
+ ```bash
117
+ curl -X POST http://localhost:3800/v1/memories/recall \
118
+ -H "Content-Type: application/json" \
119
+ -d '{"context": "project setup", "entities": ["React"], "limit": 10, "spread": true}'
120
+ ```
121
+
122
+ Response: same shape as GET recall.
93
123
 
94
- Start the server:
124
+ ### `DELETE /v1/memories/:id` โ€” Forget a memory
95
125
 
96
126
  ```bash
97
- # Environment variables
98
- ENGRAM_OWNER=my-agent # Vault owner ID (required)
99
- ENGRAM_DB_PATH=./my.db # Database path (optional)
100
- ENGRAM_PORT=3800 # Port (default: 3800)
101
- ENGRAM_HOST=127.0.0.1 # Host (default: 127.0.0.1)
102
- ENGRAM_LLM_PROVIDER=anthropic # LLM for consolidation (optional)
103
- ENGRAM_LLM_API_KEY=sk-... # LLM API key (optional)
104
-
105
- npx engram serve
106
- # or
107
- npm run serve
127
+ curl -X DELETE "http://localhost:3800/v1/memories/m_abc123?hard=true"
108
128
  ```
109
129
 
110
- ### Endpoints
130
+ ```json
131
+ { "deleted": "m_abc123", "hard": true }
132
+ ```
111
133
 
112
- | Method | Path | Description |
113
- |--------|------|-------------|
114
- | `POST` | `/v1/memories` | Store a memory |
115
- | `GET` | `/v1/memories/recall?context=...` | Recall memories (simple) |
116
- | `POST` | `/v1/memories/recall` | Recall memories (complex query) |
117
- | `DELETE` | `/v1/memories/:id` | Forget a memory |
118
- | `GET` | `/v1/memories/:id/neighbors` | Graph traversal |
119
- | `POST` | `/v1/connections` | Connect two memories |
120
- | `POST` | `/v1/consolidate` | Run consolidation engine |
121
- | `GET` | `/v1/entities` | List tracked entities |
122
- | `GET` | `/v1/stats` | Vault statistics |
123
- | `POST` | `/v1/export` | Export full vault as JSON |
124
- | `GET` | `/health` | Health check |
134
+ ### `GET /v1/memories/:id/neighbors` โ€” Graph neighbors
125
135
 
126
- ### POST /v1/memories
136
+ ```bash
137
+ curl "http://localhost:3800/v1/memories/m_abc123/neighbors?depth=2"
138
+ ```
127
139
 
128
140
  ```json
129
141
  {
130
- "content": "User prefers TypeScript over JavaScript",
131
- "type": "episodic", // episodic | semantic | procedural
132
- "entities": ["User", "TypeScript", "JavaScript"],
133
- "topics": ["preferences", "engineering"],
134
- "salience": 0.8, // 0-1, importance
135
- "confidence": 0.9, // 0-1, certainty
136
- "visibility": "owner_agents" // private | owner_agents | shared | public
142
+ "memories": [ ... ],
143
+ "count": 3
137
144
  }
138
145
  ```
139
146
 
140
- ### GET /v1/memories/recall
147
+ ### `POST /v1/consolidate` โ€” Run consolidation
141
148
 
142
- Query params: `context` (required), `entities`, `topics`, `types`, `limit`
149
+ ```bash
150
+ curl -X POST http://localhost:3800/v1/consolidate
151
+ ```
143
152
 
144
- ### POST /v1/memories/recall
153
+ ```json
154
+ {
155
+ "consolidated": 5,
156
+ "entitiesDiscovered": 3,
157
+ "contradictions": 1,
158
+ "connectionsFormed": 7
159
+ }
160
+ ```
161
+
162
+ ### `GET /v1/briefing` โ€” Session briefing
163
+
164
+ ```bash
165
+ curl "http://localhost:3800/v1/briefing?context=morning+standup&limit=10"
166
+ ```
145
167
 
146
168
  ```json
147
169
  {
148
- "context": "project status",
149
- "entities": ["Engram"],
150
- "topics": ["engineering"],
151
- "types": ["semantic"],
152
- "minSalience": 0.5,
153
- "limit": 10
170
+ "summary": "...",
171
+ "keyFacts": [{ "content": "...", "salience": 0.9 }],
172
+ "activeCommitments": [{ "content": "...", "status": "pending" }],
173
+ "recentActivity": [{ "content": "..." }]
154
174
  }
155
175
  ```
156
176
 
157
- ### POST /v1/connections
177
+ Also available as `POST /v1/briefing` with JSON body.
178
+
179
+ ### `GET /v1/stats` โ€” Vault statistics
180
+
181
+ ```bash
182
+ curl http://localhost:3800/v1/stats
183
+ ```
158
184
 
159
185
  ```json
160
186
  {
161
- "sourceId": "memory-uuid-1",
162
- "targetId": "memory-uuid-2",
163
- "type": "supports", // supports | contradicts | elaborates | supersedes | causes | caused_by | ...
164
- "strength": 0.7
187
+ "total": 142,
188
+ "byType": { "episodic": 89, "semantic": 41, "procedural": 12 },
189
+ "entities": 27,
190
+ "edges": 63
165
191
  }
166
192
  ```
167
193
 
168
- ## Core Concepts
194
+ ### `GET /v1/entities` โ€” List entities
169
195
 
170
- ### Memory Types
196
+ ```bash
197
+ curl http://localhost:3800/v1/entities
198
+ ```
171
199
 
172
- | Type | What | Example |
173
- |------|------|---------|
174
- | **Episodic** | Events, conversations, observations | "User asked about React performance" |
175
- | **Semantic** | Facts, knowledge, patterns | "User prefers TypeScript over JavaScript" |
176
- | **Procedural** | How-to knowledge, workflows | "To deploy: run tests โ†’ build โ†’ push to main" |
200
+ ```json
201
+ {
202
+ "entities": [
203
+ { "name": "TypeScript", "count": 12 },
204
+ { "name": "React", "count": 8 }
205
+ ],
206
+ "count": 27
207
+ }
208
+ ```
177
209
 
178
- ### The Memory Lifecycle
210
+ ### `GET /health` โ€” Health check
179
211
 
212
+ ```bash
213
+ curl http://localhost:3800/health
180
214
  ```
181
- Episode โ†’ Remember โ†’ Store โ†’ Recall โ†’ Consolidate โ†’ Knowledge
182
- โ†“
183
- Decay / Archive
215
+
216
+ ```json
217
+ { "status": "ok", "version": "0.1.0", "timestamp": "2025-01-15T10:30:00.000Z" }
184
218
  ```
185
219
 
186
- 1. **Remember**: Raw episodes go in with metadata (entities, topics, salience)
187
- 2. **Recall**: Hybrid retrieval โ€” entity matching, topic matching, semantic search, recency
188
- 3. **Consolidate**: The "sleep cycle" โ€” episodes get distilled into semantic memories, entities get discovered, connections form, contradictions surface
189
- 4. **Decay**: Memories naturally fade unless reinforced by access. High-salience memories resist decay.
220
+ ---
190
221
 
191
- ### Memory Graph
222
+ ## TypeScript SDK
223
+
224
+ ```typescript
225
+ import { Vault } from 'engram-sdk';
192
226
 
193
- Memories aren't flat โ€” they're a graph. Edges connect related memories:
227
+ const vault = new Vault({ owner: 'my-agent' });
194
228
 
195
- - `supports` / `contradicts` โ€” agreement or conflict
196
- - `elaborates` โ€” adds detail
197
- - `supersedes` โ€” replaces outdated info
198
- - `causes` / `caused_by` โ€” causal chains
199
- - `temporal_next` โ€” sequential events
200
- - `derived_from` โ€” consolidation lineage
229
+ await vault.remember('User prefers TypeScript');
230
+ const memories = await vault.recall('language preferences');
231
+ await vault.consolidate();
232
+ ```
201
233
 
202
- ### Entities
234
+ ---
203
235
 
204
- Engram automatically tracks entities (people, places, projects, concepts) across memories. Entity frequency and co-occurrence drive importance scores and recall relevance.
236
+ ## CLI Reference
205
237
 
206
- ## LLM-Powered Consolidation
238
+ ```
239
+ engram init Set up Engram for Claude Code / Cursor / MCP clients
240
+ engram mcp Start the MCP server (stdio transport)
241
+ engram remember <text> Store a memory
242
+ engram recall <context> Retrieve relevant memories
243
+ engram consolidate Run memory consolidation
244
+ engram stats Show vault statistics
245
+ engram entities List known entities
246
+ engram forget <id> [--hard] Forget a memory (soft or hard delete)
247
+ engram search <query> Full-text search
248
+ engram export Export entire vault as JSON
249
+ engram eval Health report & value assessment
250
+ engram repl Interactive REPL mode
251
+ engram shadow start Start shadow mode (server + watcher, background)
252
+ engram shadow stop Stop shadow mode
253
+ engram shadow status Check shadow mode status
254
+ engram shadow results Compare Engram vs your CLAUDE.md
255
+ ```
207
256
 
208
- For the full consolidation experience, configure an LLM:
257
+ **Options:**
209
258
 
210
- ```typescript
211
- const vault = new Vault({
212
- owner: 'my-agent',
213
- llm: {
214
- provider: 'anthropic',
215
- apiKey: process.env.ANTHROPIC_API_KEY!,
216
- model: 'claude-3-5-haiku-20241022',
217
- },
218
- });
219
259
  ```
260
+ --db <path> Database file path (default: ~/.engram/default.db)
261
+ --owner <name> Owner identifier (default: "default")
262
+ --agent <id> Agent ID for source tracking
263
+ --json Output as JSON
264
+ --help Show help
265
+ ```
266
+
267
+ ---
268
+
269
+ ## Configuration
220
270
 
221
- Or via environment variables with the REST API:
271
+ ### Gemini API Key
272
+
273
+ Required for embeddings, consolidation, and LLM-powered extraction:
222
274
 
223
275
  ```bash
224
- ENGRAM_LLM_PROVIDER=anthropic ENGRAM_LLM_API_KEY=sk-... npx engram serve
276
+ export GEMINI_API_KEY=your-key-here
225
277
  ```
226
278
 
227
- The LLM analyzes episodes and extracts:
228
- - **Semantic memories**: General facts and patterns
229
- - **Entities**: People, places, projects with properties
230
- - **Contradictions**: Conflicting information
231
- - **Connections**: How episodes relate to each other
279
+ ### Database Location
232
280
 
233
- ## CLI
281
+ Engram stores data in `~/.engram/` by default. Override with:
234
282
 
235
283
  ```bash
236
- npx engram remember "User prefers React over Vue"
237
- npx engram recall "frontend preferences"
238
- npx engram stats
239
- npx engram entities
240
- npx engram consolidate
241
- npx engram export > backup.json
242
- npx engram repl # Interactive mode
243
- npx engram serve # Start REST API server
284
+ export ENGRAM_DB_PATH=/path/to/engram.db
244
285
  ```
245
286
 
246
- ## Architecture
287
+ ### Environment Variables
288
+
289
+ | Variable | Description | Default |
290
+ |----------|-------------|---------|
291
+ | `GEMINI_API_KEY` | Gemini API key for embeddings & consolidation | โ€” |
292
+ | `ENGRAM_LLM_PROVIDER` | LLM provider: `gemini`, `openai`, `anthropic` | `gemini` |
293
+ | `ENGRAM_LLM_API_KEY` | LLM API key (falls back to `GEMINI_API_KEY` for gemini) | โ€” |
294
+ | `ENGRAM_LLM_MODEL` | LLM model name | provider default |
295
+ | `ENGRAM_DB_PATH` | SQLite database path | `~/.engram/default.db` |
296
+ | `ENGRAM_OWNER` | Vault owner name | `default` |
297
+ | `ENGRAM_HOST` | Server bind address | `127.0.0.1` |
298
+ | `PORT` | Server port | `3800` |
299
+ | `ENGRAM_AUTH_TOKEN` | Bearer token for API auth | โ€” |
300
+ | `ENGRAM_CORS_ORIGIN` | CORS allowed origin | localhost only |
301
+ | `ENGRAM_TELEMETRY` | Set to `off` to disable telemetry | on |
247
302
 
248
- ```
249
- โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
250
- โ”‚ REST API Server โ”‚
251
- โ”‚ POST /v1/memories ยท GET /v1/memories/recall ยท โ€ฆ โ”‚
252
- โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
253
- โ”‚ Vault API โ”‚
254
- โ”‚ remember() ยท recall() ยท consolidate() ยท forget() โ”‚
255
- โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
256
- โ”‚ Retrieval Engine โ”‚
257
- โ”‚ Entity match ยท Topic match ยท Vector search ยท FTS โ”‚
258
- โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
259
- โ”‚ Consolidation Engine โ”‚
260
- โ”‚ Rule-based โ”‚ LLM-powered (Anthropic/OpenAI) โ”‚
261
- โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
262
- โ”‚ SQLite Storage Layer โ”‚
263
- โ”‚ Memories ยท Edges ยท Entities ยท Embeddings โ”‚
264
- โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
265
- ```
303
+ ---
266
304
 
267
- **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.
268
-
269
- **Portable**: Export your entire vault as JSON. Import it elsewhere. Your agent's memory belongs to you.
270
-
271
- ## Comparison
272
-
273
- | Feature | Engram | Mem0 | Zep | Letta/MemGPT |
274
- |---------|--------|------|-----|-------------|
275
- | Spreading activation | โœ… | โŒ | โŒ | โŒ |
276
- | LLM consolidation | โœ… | โŒ | โŒ | Partial |
277
- | Knowledge graph | โœ… | โœ… (graph memory) | โœ… | โŒ |
278
- | Entity tracking | โœ… | โœ… | โœ… | โŒ |
279
- | Memory decay | โœ… | โŒ | โŒ | โŒ |
280
- | REST API | โœ… | โœ… | โœ… | โœ… |
281
- | Local-first | โœ… | Cloud-default | Cloud-default | โœ… |
282
- | Language-agnostic | โœ… | Python-first | Python-first | Python-first |
283
- | Source-available | โœ… | Partial | Partial | โœ… |
284
-
285
- ## Roadmap
286
-
287
- - [x] TypeScript SDK
288
- - [x] REST API server
289
- - [x] sqlite-vec vector search
290
- - [x] LLM-powered consolidation
291
- - [x] CLI with REPL
292
- - [ ] Hosted service (api.engram.ai)
293
- - [ ] Python SDK
294
- - [ ] Framework integrations (OpenClaw, LangChain, CrewAI)
295
- - [ ] Protocol spec (open standard)
296
- - [ ] Multi-agent vault sharing
297
- - [ ] Conflict resolution across agents
305
+ ## Benchmarks
298
306
 
299
- ## Telemetry
307
+ | System | LOCOMO Score | Tokens/Query |
308
+ |--------|-------------|--------------|
309
+ | **Engram** | **79.6%** | **776** |
310
+ | Mem0 | 66.9% | โ€” |
311
+ | Manual files | 74.5% | 1,373 |
312
+ | Full Context | 86.2% | 22,976 |
300
313
 
301
- Engram collects anonymous usage telemetry to help improve the project. This includes:
314
+ [Full research methodology โ†’](https://www.engram.fyi/#/research)
302
315
 
303
- - A random anonymous ID (not tied to any personal information)
304
- - Event type (server start, init, daily heartbeat)
305
- - Engram version, platform, architecture, Node.js version
306
- - Vault stats (memory count, entity count โ€” **no memory content is ever sent**)
316
+ ---
307
317
 
308
- **No personal data, memory content, or identifiable information is collected.**
318
+ ## Telemetry
319
+
320
+ Engram collects lightweight, anonymous usage data:
321
+
322
+ - Random anonymous ID (UUID, not tied to personal info)
323
+ - Event type (`server_start`, `init`, `daily_heartbeat`)
324
+ - Version, platform, architecture, Node.js version
325
+ - Vault stats (memory count, entity count โ€” **no content**)
309
326
 
310
- To opt out, set either environment variable:
327
+ **Opt out:**
311
328
 
312
329
  ```bash
313
330
  export ENGRAM_TELEMETRY=off
@@ -315,14 +332,19 @@ export ENGRAM_TELEMETRY=off
315
332
  export DO_NOT_TRACK=1
316
333
  ```
317
334
 
318
- ## Contributing
335
+ All telemetry is fire-and-forget โ€” never blocks, never throws, fails silently with a 2-second timeout.
319
336
 
320
- See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
337
+ ---
321
338
 
322
339
  ## License
323
340
 
324
- MIT. See [LICENSE](LICENSE) for details.
341
+ [AGPL-3.0-or-later](https://www.gnu.org/licenses/agpl-3.0)
325
342
 
326
343
  ---
327
344
 
328
- *Built by [Thomas Stockham](https://tstockham.com). Engram is the memory layer the AI agent ecosystem is missing.*
345
+ ## Links
346
+
347
+ - ๐ŸŒ [Website](https://www.engram.fyi)
348
+ - ๐Ÿ“Š [Research](https://www.engram.fyi/#/research)
349
+ - ๐Ÿ“ฆ [npm](https://www.npmjs.com/package/engram-sdk)
350
+ - ๐Ÿ’ป [GitHub](https://github.com/tstockham96/engram)
@@ -0,0 +1,40 @@
1
+ export type Plan = 'free' | 'growth' | 'pro' | 'enterprise';
2
+ export interface Account {
3
+ id: string;
4
+ email: string;
5
+ apiKey: string;
6
+ plan: Plan;
7
+ createdAt: string;
8
+ memoriesStored: number;
9
+ recallsThisMonth: number;
10
+ consolidationsThisMonth: number;
11
+ usageResetAt: string;
12
+ }
13
+ export declare const PLAN_LIMITS: Record<Plan, {
14
+ memories: number;
15
+ recalls: number;
16
+ consolidations: number;
17
+ agents: number;
18
+ }>;
19
+ export type UsageType = 'memory' | 'recall' | 'consolidation';
20
+ export declare class AccountStore {
21
+ private db;
22
+ constructor(dbPath: string);
23
+ generateApiKey(): string;
24
+ private nextResetDate;
25
+ createAccount(email: string, plan?: Plan): Account;
26
+ getAccountByKey(apiKey: string): Account | null;
27
+ getAccountById(id: string): Account | null;
28
+ listAccounts(): Account[];
29
+ trackUsage(accountId: string, type: UsageType): void;
30
+ decrementMemories(accountId: string): void;
31
+ checkLimit(account: Account, type: UsageType): {
32
+ allowed: boolean;
33
+ limit: number;
34
+ used: number;
35
+ resetAt: string;
36
+ };
37
+ close(): void;
38
+ private rowToAccount;
39
+ }
40
+ //# sourceMappingURL=accounts.d.ts.map
@@ -0,0 +1 @@
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"}