@sanity-labs/nuum 0.2.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
ADDED
|
@@ -0,0 +1,284 @@
|
|
|
1
|
+
# Nuum
|
|
2
|
+
|
|
3
|
+
An AI coding agent with **"infinite memory"** — continuous context across sessions.
|
|
4
|
+
|
|
5
|
+
*Nuum* — from "continuum" — maintains persistent memory across conversations, learning your codebase, preferences, and decisions over time.
|
|
6
|
+
|
|
7
|
+
## Quick Start
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
export ANTHROPIC_API_KEY=your-key-here
|
|
11
|
+
|
|
12
|
+
# Install and run interactively
|
|
13
|
+
bunx @sanity-labs/nuum --repl
|
|
14
|
+
|
|
15
|
+
# Or with npx
|
|
16
|
+
npx @sanity-labs/nuum --repl
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
That's it. Start chatting. Your agent remembers everything.
|
|
20
|
+
|
|
21
|
+
### REPL Commands
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
/help Show available commands
|
|
25
|
+
/inspect Show memory statistics
|
|
26
|
+
/dump Show full system prompt
|
|
27
|
+
/quit Exit
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
### Other Modes
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
nuum -p "What files are in src/" # Single prompt
|
|
34
|
+
nuum --inspect # View memory stats
|
|
35
|
+
nuum --db ./project.db --repl # Custom database
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## ⚠️ Experimental Software
|
|
41
|
+
|
|
42
|
+
Nuum currently runs in **full autonomy mode** — no permission prompts, no confirmations. It was created for [Miriad](https://miriad.systems) as an embedded agent engine, typically running in containerized environments where the host platform manages security.
|
|
43
|
+
|
|
44
|
+
**Why we built this:** We were frustrated with how traditional coding agents seem to suffer some kind of contextual collapse after prolonged use — getting mixed up, repeating mistakes, losing track of decisions. Nuum explores how to keep agents effective indefinitely through recursive memory compression and persistent knowledge.
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## MCP Servers
|
|
49
|
+
|
|
50
|
+
Nuum supports [Model Context Protocol](https://modelcontextprotocol.io/) servers for extended capabilities. Configure via environment variable:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
export NUUM_MCP_SERVERS='{
|
|
54
|
+
"filesystem": {
|
|
55
|
+
"command": "npx",
|
|
56
|
+
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
|
|
57
|
+
},
|
|
58
|
+
"github": {
|
|
59
|
+
"command": "npx",
|
|
60
|
+
"args": ["-y", "@modelcontextprotocol/server-github"],
|
|
61
|
+
"env": { "GITHUB_TOKEN": "your-token" }
|
|
62
|
+
}
|
|
63
|
+
}'
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Or pass via protocol when embedding:
|
|
67
|
+
|
|
68
|
+
```json
|
|
69
|
+
{"type":"user","message":{...},"mcp_servers":{"name":{"command":"...","args":[...]}}}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
MCP tools appear alongside built-in tools. The agent discovers and uses them automatically.
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## Embedding in Applications
|
|
77
|
+
|
|
78
|
+
Nuum is designed to be **embedded**. While it runs standalone, its primary use case is integration into host applications, IDEs, and orchestration platforms.
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
nuum --stdio # NDJSON protocol over stdin/stdout
|
|
82
|
+
nuum --stdio --db ./my.db # With custom database
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
**Key properties:**
|
|
86
|
+
- **Stateless process, stateful memory** — Process can restart anytime; all state lives in SQLite
|
|
87
|
+
- **Simple wire protocol** — JSON messages over stdin/stdout, easy to integrate from any language
|
|
88
|
+
- **Mid-turn injection** — Send corrections while the agent is working
|
|
89
|
+
- **Persistent identity** — One database = one agent with continuous memory
|
|
90
|
+
|
|
91
|
+
See **[docs/protocol.md](docs/protocol.md)** for the full wire protocol specification.
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## Memory Architecture
|
|
96
|
+
|
|
97
|
+
Nuum has a three-tier memory system that mirrors human cognition.
|
|
98
|
+
|
|
99
|
+
**Key insight:** Agents perform best when context is **30-50% full** — informed but not overwhelmed. Nuum's memory system maintains this sweet spot automatically.
|
|
100
|
+
|
|
101
|
+
```
|
|
102
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
103
|
+
│ WORKING MEMORY │
|
|
104
|
+
│ (Temporal Message Store) │
|
|
105
|
+
│ │
|
|
106
|
+
│ Recent messages live here in full detail. As context grows, older │
|
|
107
|
+
│ content is recursively distilled — compressed while retaining what │
|
|
108
|
+
│ matters for effective action. │
|
|
109
|
+
│ │
|
|
110
|
+
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
|
111
|
+
│ │ msg msg msg msg msg msg msg msg msg msg msg msg msg msg msg msg ... │ │
|
|
112
|
+
│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
|
|
113
|
+
│ │ └───┴───┴───┴───┘ └───┴───┴───┘ └───┴───┴───┘ │ │ │ │ │
|
|
114
|
+
│ │ │ │ │ │ │ │ │ │
|
|
115
|
+
│ │ [distill-1] [distill-2] [distill-3] │ │ │ │ │
|
|
116
|
+
│ │ │ │ │ │ │ │ │ │
|
|
117
|
+
│ │ └───────────────────┴───────────────┘ │ │ │ │ │
|
|
118
|
+
│ │ │ │ │ │ │ │
|
|
119
|
+
│ │ [distill-4] │ │ │ │ │
|
|
120
|
+
│ │ │ │ │ │ │ │
|
|
121
|
+
│ │ └─────────────────────────┘ │ │ │ │
|
|
122
|
+
│ │ │ │ │ │ │
|
|
123
|
+
│ │ [distill-5] [recent msgs] │ │
|
|
124
|
+
│ │ │ │
|
|
125
|
+
│ │ Older ◄──────────────────────────────────────────────────► Newer │ │
|
|
126
|
+
│ └─────────────────────────────────────────────────────────────────────┘ │
|
|
127
|
+
│ │
|
|
128
|
+
│ The agent sees: [distill-5] + [recent messages] │
|
|
129
|
+
│ 55x compression ratio achieved (1.3M tokens → 25k effective) │
|
|
130
|
+
└─────────────────────────────────────────────────────────────────────────────┘
|
|
131
|
+
|
|
132
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
133
|
+
│ PRESENT STATE │
|
|
134
|
+
│ │
|
|
135
|
+
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────────────┐ │
|
|
136
|
+
│ │ Mission │ │ Status │ │ Tasks │ │
|
|
137
|
+
│ │ │ │ │ │ ☑ Setup repository │ │
|
|
138
|
+
│ │ "Build │ │ "reviewing │ │ ☑ Implement auth │ │
|
|
139
|
+
│ │ auth │ │ PR #42" │ │ ☐ Write tests │ │
|
|
140
|
+
│ │ system" │ │ │ │ ☐ Deploy to staging │ │
|
|
141
|
+
│ └─────────────┘ └─────────────┘ └─────────────────────────────────┘ │
|
|
142
|
+
│ │
|
|
143
|
+
│ Agent-managed working state. Updated as work progresses. │
|
|
144
|
+
└─────────────────────────────────────────────────────────────────────────────┘
|
|
145
|
+
|
|
146
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
147
|
+
│ LONG-TERM MEMORY │
|
|
148
|
+
│ (Knowledge Base Tree) │
|
|
149
|
+
│ │
|
|
150
|
+
│ /identity ─────────────── "Who I am, my nature and relationships" │
|
|
151
|
+
│ /behavior ─────────────── "How I should operate, user preferences" │
|
|
152
|
+
│ /miriad-code │
|
|
153
|
+
│ ├── /cast-integration ─ "CAST/Miriad integration notes" │
|
|
154
|
+
│ ├── /memory │
|
|
155
|
+
│ │ └── /background-reports-system │
|
|
156
|
+
│ ├── /anthropic-prompt-caching │
|
|
157
|
+
│ └── /distillation-improvements-jan2026 │
|
|
158
|
+
│ /mcp │
|
|
159
|
+
│ ├── /mcp-implementation │
|
|
160
|
+
│ └── /mcp-config-resolution │
|
|
161
|
+
│ │
|
|
162
|
+
│ Hierarchical knowledge that persists forever. Background workers │
|
|
163
|
+
│ extract important information from conversations and organize it here. │
|
|
164
|
+
└─────────────────────────────────────────────────────────────────────────────┘
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### Recursive Distillation
|
|
168
|
+
|
|
169
|
+
**No pause for compaction.** Unlike most coding agents that stop mid-conversation to "compact memory," Nuum's distillation runs concurrently while you work. You never wait for memory management — it happens invisibly in the background.
|
|
170
|
+
|
|
171
|
+
The distillation system is **not summarization** — it's operational intelligence extraction:
|
|
172
|
+
|
|
173
|
+
**RETAIN** (actionable intelligence):
|
|
174
|
+
- File paths and what they contain
|
|
175
|
+
- Decisions made and WHY (rationale matters)
|
|
176
|
+
- User preferences and corrections
|
|
177
|
+
- Specific values: URLs, configs, commands
|
|
178
|
+
- Errors and how they were resolved
|
|
179
|
+
|
|
180
|
+
**EXCISE** (noise):
|
|
181
|
+
- Back-and-forth debugging that led nowhere
|
|
182
|
+
- Missteps and corrections (keep only final approach)
|
|
183
|
+
- Verbose tool outputs
|
|
184
|
+
- Narrative filler ("Let me check...")
|
|
185
|
+
- Casual chatter and acknowledgments
|
|
186
|
+
|
|
187
|
+
Distillations are recursive — older distillations get distilled again, creating a fractal compression where ancient history becomes highly compressed while recent work stays detailed.
|
|
188
|
+
|
|
189
|
+
### Long-Term Memory Curation
|
|
190
|
+
|
|
191
|
+
A background worker (the **LTM Curator**) runs continuously in the background:
|
|
192
|
+
|
|
193
|
+
1. **CAPTURES** important information into knowledge entries
|
|
194
|
+
2. **STRENGTHENS** entries by researching and adding context
|
|
195
|
+
3. **CURATES** the knowledge tree structure
|
|
196
|
+
|
|
197
|
+
The curator has access to web search, file reading, and the full knowledge base. It works autonomously — you never see it running, but the agent's knowledge grows over time. Reports are filed silently and surfaced to the main agent on the next interaction.
|
|
198
|
+
|
|
199
|
+
### Reflection
|
|
200
|
+
|
|
201
|
+
When the agent needs to recall something specific — a file path, a decision, a value from weeks ago — it uses the **reflect** tool:
|
|
202
|
+
|
|
203
|
+
```
|
|
204
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
205
|
+
│ REFLECTION │
|
|
206
|
+
│ │
|
|
207
|
+
│ Main Agent Reflection Sub-Agent │
|
|
208
|
+
│ │ │ │
|
|
209
|
+
│ │ "What was the auth bug fix?" │ │
|
|
210
|
+
│ │ ────────────────────────────────────►│ │
|
|
211
|
+
│ │ │ │
|
|
212
|
+
│ │ ┌───────────┴───────────┐ │
|
|
213
|
+
│ │ │ Search FTS index │ │
|
|
214
|
+
│ │ │ Search LTM entries │ │
|
|
215
|
+
│ │ │ Read relevant docs │ │
|
|
216
|
+
│ │ │ Synthesize answer │ │
|
|
217
|
+
│ │ └───────────┬───────────┘ │
|
|
218
|
+
│ │ │ │
|
|
219
|
+
│ │ "The auth bug was in session.ts, │ │
|
|
220
|
+
│ │ line 42. Fixed by adding null │ │
|
|
221
|
+
│ │ check. Committed in abc123." │ │
|
|
222
|
+
│ │ ◄────────────────────────────────────│ │
|
|
223
|
+
│ │ │ │
|
|
224
|
+
└─────────────────────────────────────────────────────────────────────────────┘
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
Reflection searches the full conversation history (via FTS5 full-text search) and the knowledge base, then synthesizes an answer. It's like the agent asking its own memory system a question.
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## Configuration
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
# Required
|
|
235
|
+
ANTHROPIC_API_KEY=your-key-here
|
|
236
|
+
|
|
237
|
+
# Optional (defaults shown)
|
|
238
|
+
AGENT_MODEL_REASONING=claude-opus-4-5-20251101
|
|
239
|
+
AGENT_MODEL_WORKHORSE=claude-sonnet-4-5-20250929
|
|
240
|
+
AGENT_MODEL_FAST=claude-haiku-4-5-20251001
|
|
241
|
+
AGENT_DB=./agent.db
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
---
|
|
245
|
+
|
|
246
|
+
## Development
|
|
247
|
+
|
|
248
|
+
```bash
|
|
249
|
+
bun install # Install dependencies
|
|
250
|
+
bun run dev # Run in development
|
|
251
|
+
bun run typecheck # Type check
|
|
252
|
+
bun test # Run tests
|
|
253
|
+
bun run build # Build for distribution
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
---
|
|
257
|
+
|
|
258
|
+
## Acknowledgments
|
|
259
|
+
|
|
260
|
+
### Letta (formerly MemGPT)
|
|
261
|
+
|
|
262
|
+
Memory architecture influenced by [Letta](https://github.com/letta-ai/letta):
|
|
263
|
+
- Core memory always in context
|
|
264
|
+
- Agent-editable memory
|
|
265
|
+
- Background memory workers
|
|
266
|
+
|
|
267
|
+
### OpenCode
|
|
268
|
+
|
|
269
|
+
Infrastructure adapted from [OpenCode](https://github.com/anthropics/opencode):
|
|
270
|
+
- Tool definition patterns
|
|
271
|
+
- Permission system
|
|
272
|
+
- Process management
|
|
273
|
+
|
|
274
|
+
---
|
|
275
|
+
|
|
276
|
+
## License
|
|
277
|
+
|
|
278
|
+
MIT
|
|
279
|
+
|
|
280
|
+
---
|
|
281
|
+
|
|
282
|
+
<p align="center">
|
|
283
|
+
Nuum is part of <a href="https://miriad.systems">Miriad</a>, experimental software from <a href="https://sanity.io">Sanity.io</a>
|
|
284
|
+
</p>
|