@199-bio/engram 0.1.0

package/README.md

@@ -0,0 +1,304 @@
+# Engram
+
+**Give your AI a perfect memory.**
+
+Engram remembers everything you tell it—names, relationships, preferences, conversations—and recalls exactly what's relevant when you need it. No cloud. No API keys. Just memory that works.
+
+Works with any LLM that supports MCP (Model Context Protocol)—Claude, GPT, Gemini, local models, and more.
+
+> *An engram is a unit of cognitive information imprinted in a physical substance—the biological basis of memory.*
+
+---
+
+## What It Does
+
+Tell your AI about your world:
+
+> "My colleague Sarah is allergic to shellfish and prefers window seats. She's leading the Q1 product launch."
+
+Later, ask:
+
+> "I'm booking a team lunch and flights for the offsite—what should I know?"
+
+Engram connects the dots—*avoid seafood restaurants, book Sarah a window seat, and she's probably busy with the launch*—and gives your AI the context to truly help.
+
+**It's not just search. It's understanding.**
+
+---
+
+## Quick Start
+
+### Install
+
+```bash
+npm install -g engram-mcp
+```
+
+### Add to Your MCP Client
+
+**Claude Desktop** — add to `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "engram": {
+      "command": "engram"
+    }
+  }
+}
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add engram -- engram
+```
+
+**Other MCP clients** — point to the `engram` command. It speaks standard MCP over stdio.
+
+That's it. Your AI now has memory.
+
+---
+
+## How to Use
+
+Just talk naturally. Your AI will remember what matters.
+
+### Storing Memories
+
+Say things like:
+- "Remember that Sarah is allergic to shellfish"
+- "My anniversary is March 15th"
+- "I prefer morning meetings, never schedule anything before 9am"
+
+### Recalling
+
+Just ask:
+- "What do you know about Sarah?"
+- "When is my anniversary?"
+- "What are my meeting preferences?"
+
+Your AI automatically searches its memory and uses what's relevant.
+
+### The Knowledge Graph
+
+Engram doesn't just store text—it understands relationships:
+
+- **People**: Sarah, John, Dr. Martinez
+- **Places**: Office, Conference Room A, Seattle HQ
+- **Organizations**: Acme Corp, Stanford, FDA
+- **Connections**: Sarah → works at → Acme Corp
+- **Observations**: Sarah is allergic to shellfish
+
+This means when you ask about Sarah's work, Engram knows to also surface relevant information about Acme Corp.
+
+---
+
+## What Makes It Special
+
+| Feature | Why It Matters |
+|---------|----------------|
+| **Hybrid Search** | Finds memories by keywords AND meaning |
+| **Knowledge Graph** | Understands relationships between people, places, things |
+| **100% Local** | Your memories never leave your computer |
+| **No API Keys** | Works offline, no subscriptions |
+| **Fast** | ~50ms to recall, feels instant |
+
+---
+
+## The Nine Tools
+
+Your AI gets these capabilities:
+
+| Tool | What It Does |
+|------|--------------|
+| `remember` | Store something new |
+| `recall` | Find relevant memories |
+| `forget` | Remove a memory |
+| `create_entity` | Add a person, place, or concept |
+| `observe` | Note something about an entity |
+| `relate` | Connect two entities |
+| `query_entity` | Get everything about someone/something |
+| `list_entities` | See all people, places, etc. |
+| `stats` | Check memory statistics |
+
+---
+
+## Examples
+
+### Personal Assistant
+
+```
+You: "Remember that my anniversary is March 15th and my partner loves Italian food"
+AI: ✓ Stored. I've noted this as an important date with preferences.
+
+You: "I need to plan something special next month"
+AI: Your anniversary is coming up on March 15th! Given your partner's love for
+    Italian food, perhaps a nice Italian restaurant reservation?
+```
+
+### Relationship Context
+
+```
+You: "My friend David lives in Austin and always recommends great coffee shops."
+AI: ✓ Stored. Created entity: David (person), with observation about Austin and coffee expertise.
+
+You: "I'm visiting Austin next week"
+AI: David is in Austin—he'd probably have great coffee shop recommendations!
+    Want me to remind you to ask him?
+```
+
+### Professional Memory
+
+```
+You: "John Chen is our VP of Engineering. He prefers async communication and hates meetings before 11am."
+Claude: ✓ Stored. Created entity: John Chen (person, VP of Engineering).
+
+You: "I need to schedule a sync with John"
+Claude: Given John's preferences, I'd suggest a late morning slot, maybe 11:30am,
+        or an async Loom video if it doesn't require real-time discussion.
+```
+
+---
+
+## Privacy
+
+**Your memories stay on your machine.**
+
+- All data stored locally in `~/.engram/`
+- No cloud services, no external APIs
+- No telemetry, no tracking
+- You own your data completely
+
+---
+
+## Technical Details
+
+<details>
+<summary>How It Works</summary>
+
+Engram uses a three-layer retrieval system:
+
+1. **BM25 (Keyword Search)**: SQLite FTS5 finds exact matches—names, dates, specific phrases
+2. **ColBERT (Semantic Search)**: Neural embeddings find conceptually related memories
+3. **Knowledge Graph**: Entity relationships expand context
+
+These are fused using Reciprocal Rank Fusion (RRF) to get the best of all approaches.
+
+```
+Query: "What should I know about Sarah?"
+  │
+  ├── BM25 → finds "Sarah" in memories
+  ├── ColBERT → finds semantically related content
+  └── Graph → Sarah → works at → Acme Corp → Q1 launch
+  │
+  └── RRF Fusion → Best combined results
+```
+
+</details>
+
+<details>
+<summary>Architecture</summary>
+
+```
+engram/
+├── src/
+│   ├── index.ts           # MCP server
+│   ├── storage/
+│   │   └── database.ts    # SQLite + FTS5
+│   ├── graph/
+│   │   ├── extractor.ts   # Entity extraction
+│   │   └── knowledge-graph.ts
+│   └── retrieval/
+│       ├── colbert.ts     # ColBERT wrapper
+│       ├── colbert-bridge.py  # Python RAGatouille
+│       └── hybrid.ts      # RRF fusion
+```
+
+</details>
+
+<details>
+<summary>Building from Source</summary>
+
+```bash
+git clone https://github.com/199-biotechnologies/engram.git
+cd engram
+npm install
+npm run build
+
+# Install globally from local build
+npm install -g .
+```
+
+**Python Dependencies** (for ColBERT):
+```bash
+pip install ragatouille torch
+```
+
+If Python/ColBERT isn't available, Engram falls back to a simpler retriever automatically.
+
+</details>
+
+<details>
+<summary>Configuration</summary>
+
+Environment variables:
+- `ENGRAM_DB_PATH`: Database location (default: `~/.engram/engram.db`)
+
+Claude Desktop full config:
+```json
+{
+  "mcpServers": {
+    "engram": {
+      "command": "engram",
+      "env": {
+        "ENGRAM_DB_PATH": "/custom/path/engram.db"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>Performance</summary>
+
+On M1 MacBook Air:
+- **remember**: ~100ms
+- **recall**: ~50ms
+- **graph queries**: ~5ms
+
+Database size: ~1KB per memory (text + embeddings + graph data)
+
+</details>
+
+---
+
+## Roadmap
+
+- [x] Core MCP server
+- [x] Hybrid search (BM25 + ColBERT)
+- [x] Knowledge graph
+- [x] Entity extraction
+- [ ] Temporal memory decay
+- [ ] Memory consolidation
+- [ ] Export/import
+- [ ] Web dashboard
+
+---
+
+## Author
+
+**Boris Djordjevic**
+Founder, [199 Biotechnologies](https://199bio.com)
+
+## License
+
+MIT — use it however you want.
+
+---
+
+<p align="center">
+  <i>Built with care by <a href="https://github.com/199-biotechnologies">199 Biotechnologies</a></i>
+</p>

package/dist/graph/extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractor.d.ts","sourceRoot":"","sources":["../../src/graph/extractor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,cAAc,CAAC;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACtC;AAwFD,qBAAa,eAAe;IAC1B;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,EAAE;IA8D3C;;OAEG;IACH,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,EAAE;IAuFrD;;OAEG;IACH,OAAO,CAAC,WAAW;IAInB;;OAEG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,EAAE;IAe/C;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAyC/B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAuC9B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAiC5B;;OAEG;IACH,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;QACxC,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;CA4BH;AAGD,eAAO,MAAM,eAAe,iBAAwB,CAAC"}

package/dist/graph/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/graph/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC"}

package/dist/graph/knowledge-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-graph.d.ts","sourceRoot":"","sources":["../../src/graph/knowledge-graph.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,cAAc,EACd,MAAM,EACN,WAAW,EACX,QAAQ,EACT,MAAM,wBAAwB,CAAC;AAGhC,MAAM,WAAW,iBAAkB,SAAQ,MAAM;IAC/C,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,aAAa,EAAE,KAAK,CAAC,QAAQ,GAAG;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1D,WAAW,EAAE,KAAK,CAAC,QAAQ,GAAG;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,YAAY,EAAE,WAAW,EAAE,CAAC;CAC7B;AAED,qBAAa,cAAc;IACb,OAAO,CAAC,EAAE;gBAAF,EAAE,EAAE,cAAc;IAItC;;OAEG;IACH,iBAAiB,CACf,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,MAAM,CAAC,MAAM,CAAY,GAC9B,MAAM;IAMT;;OAEG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI;IAoC5D;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE;IAI5D;;OAEG;IACH,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,GAAE,MAAY,GAAG,MAAM,EAAE;IAMlE;;OAEG;IACH,cAAc,CACZ,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EACf,cAAc,CAAC,EAAE,MAAM,EACvB,UAAU,GAAE,MAAY,GACvB,WAAW;IAWd;;OAEG;IACH,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,WAAW,EAAE;IAWtD;;OAEG;IACH,MAAM,CACJ,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,QAAQ;IAgBX;;OAEG;IACH,YAAY,CACV,cAAc,EAAE,MAAM,EACtB,SAAS,GAAE,MAAM,GAAG,IAAI,GAAG,MAAe,GACzC,QAAQ,EAAE;IAWb;;OAEG;IACH,QAAQ,CACN,cAAc,EAAE,MAAM,EACtB,KAAK,GAAE,MAAU,EACjB,aAAa,CAAC,EAAE,MAAM,EAAE,GACvB,cAAc,GAAG,IAAI;IAgBxB;;OAEG;IACH,eAAe,CACb,IAAI,EAAE,MAAM,EACZ,cAAc,CAAC,EAAE,MAAM,GACtB;QAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,YAAY,EAAE,WAAW,EAAE,CAAA;KAAE;IAyCtD;;OAEG;IACH,oBAAoB,CAClB,cAAc,EAAE,MAAM,EACtB,KAAK,GAAE,MAAU,GAChB,MAAM,EAAE;CAcZ"}

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;GAKG"}