engrams 0.1.0
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 +140 -0
- package/dist/cli.js +2114 -0
- package/dist/http.js +255 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +2113 -0
- package/package.json +60 -0
package/README.md
ADDED
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
# Engrams
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/engrams)
|
|
4
|
+
[](https://github.com/Sunrise-Labs-Dot-AI/engrams/blob/main/LICENSE)
|
|
5
|
+
|
|
6
|
+
**Universal, portable memory layer for AI agents.**
|
|
7
|
+
|
|
8
|
+
Engrams gives your AI tools persistent, cross-tool memory backed by local SQLite. Any MCP-compatible tool — Claude Code, Cursor, Windsurf, Claude Desktop, Cline — connects to the same memory. Your agents remember what you tell them, learn from corrections, and build confidence over time.
|
|
9
|
+
|
|
10
|
+
## Quick Start
|
|
11
|
+
|
|
12
|
+
Add to your MCP config and you're done:
|
|
13
|
+
|
|
14
|
+
```json
|
|
15
|
+
{
|
|
16
|
+
"mcpServers": {
|
|
17
|
+
"engrams": {
|
|
18
|
+
"command": "npx",
|
|
19
|
+
"args": ["-y", "engrams"]
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
That's it. Your AI agent now has persistent memory.
|
|
26
|
+
|
|
27
|
+
## What You Get
|
|
28
|
+
|
|
29
|
+
Engrams provides 12 MCP tools:
|
|
30
|
+
|
|
31
|
+
| Tool | Description |
|
|
32
|
+
|------|-------------|
|
|
33
|
+
| `memory_write` | Create a new memory with content, domain, and source attribution |
|
|
34
|
+
| `memory_search` | Full-text search across all memories (FTS5) |
|
|
35
|
+
| `memory_update` | Modify a memory's content, detail, or domain |
|
|
36
|
+
| `memory_remove` | Soft-delete a memory |
|
|
37
|
+
| `memory_confirm` | Confirm a memory is correct (boosts confidence) |
|
|
38
|
+
| `memory_correct` | Replace content and reset confidence |
|
|
39
|
+
| `memory_flag_mistake` | Flag a memory as incorrect (degrades confidence) |
|
|
40
|
+
| `memory_connect` | Create typed relationships between memories |
|
|
41
|
+
| `memory_get_connections` | View a memory's relationship graph |
|
|
42
|
+
| `memory_list_domains` | List all memory domains with counts |
|
|
43
|
+
| `memory_list` | Browse memories by domain, sorted by confidence or recency |
|
|
44
|
+
| `memory_set_permissions` | Configure per-agent read/write access |
|
|
45
|
+
|
|
46
|
+
## MCP Config Examples
|
|
47
|
+
|
|
48
|
+
### Claude Code
|
|
49
|
+
|
|
50
|
+
In `~/.claude.json` or your project's `.mcp.json`:
|
|
51
|
+
|
|
52
|
+
```json
|
|
53
|
+
{
|
|
54
|
+
"mcpServers": {
|
|
55
|
+
"engrams": {
|
|
56
|
+
"command": "npx",
|
|
57
|
+
"args": ["-y", "engrams"]
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### Claude Desktop
|
|
64
|
+
|
|
65
|
+
In `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
|
|
66
|
+
|
|
67
|
+
```json
|
|
68
|
+
{
|
|
69
|
+
"mcpServers": {
|
|
70
|
+
"engrams": {
|
|
71
|
+
"command": "npx",
|
|
72
|
+
"args": ["-y", "engrams"]
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### Cursor
|
|
79
|
+
|
|
80
|
+
In `.cursor/mcp.json` in your project root:
|
|
81
|
+
|
|
82
|
+
```json
|
|
83
|
+
{
|
|
84
|
+
"mcpServers": {
|
|
85
|
+
"engrams": {
|
|
86
|
+
"command": "npx",
|
|
87
|
+
"args": ["-y", "engrams"]
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### Windsurf
|
|
94
|
+
|
|
95
|
+
In your Windsurf MCP config:
|
|
96
|
+
|
|
97
|
+
```json
|
|
98
|
+
{
|
|
99
|
+
"mcpServers": {
|
|
100
|
+
"engrams": {
|
|
101
|
+
"command": "npx",
|
|
102
|
+
"args": ["-y", "engrams"]
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## How It Works
|
|
109
|
+
|
|
110
|
+
- **Local-first**: All data stored in `~/.engrams/engrams.db` (SQLite). No accounts, no cloud, no API keys.
|
|
111
|
+
- **FTS5 search**: Full-text search across all your memories using SQLite's FTS5 engine.
|
|
112
|
+
- **Confidence scoring**: Memories start with confidence based on source type (stated: 90%, observed: 75%, inferred: 65%). Confirmations boost confidence, corrections reset it, mistakes degrade it.
|
|
113
|
+
- **Source attribution**: Every memory tracks which agent wrote it and how it was acquired.
|
|
114
|
+
- **Audit trail**: All changes are logged in an event timeline.
|
|
115
|
+
- **Cross-tool**: Every MCP-compatible tool shares the same memory database.
|
|
116
|
+
|
|
117
|
+
## Web Dashboard
|
|
118
|
+
|
|
119
|
+
Engrams includes a web dashboard for browsing and managing your memories visually. Clone the repo to use it:
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
git clone https://github.com/Sunrise-Labs-Dot-AI/engrams.git
|
|
123
|
+
cd engrams && pnpm install && pnpm build
|
|
124
|
+
|
|
125
|
+
# Start the MCP server with HTTP API
|
|
126
|
+
node packages/mcp-server/dist/cli.js --http
|
|
127
|
+
|
|
128
|
+
# In another terminal, start the dashboard
|
|
129
|
+
cd packages/dashboard && pnpm dev
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Open `http://localhost:3000` to browse memories, search, confirm, correct, and manage agent permissions.
|
|
133
|
+
|
|
134
|
+
## Contributing
|
|
135
|
+
|
|
136
|
+
Contributions welcome! Please open an issue or pull request on [GitHub](https://github.com/Sunrise-Labs-Dot-AI/engrams).
|
|
137
|
+
|
|
138
|
+
## License
|
|
139
|
+
|
|
140
|
+
MIT
|