nuum
AI coding agent with continuous memory - infinite context across sessions
Installation
npx @sanity-labs/nuumAsk AI about nuum
Powered by Claude Β· Grounded in docs
I know everything about nuum. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Nuum
An AI coding agent with "infinite memory" β continuous context across sessions.
Nuum β from "continuum" β maintains persistent memory across conversations, learning your codebase, preferences, and decisions over time.
π How We Solved the Agent Memory Problem β the full technical deep-dive on why agents forget and how Nuum fixes it.
Quick Start
export ANTHROPIC_API_KEY=your-key-here
# Install and run interactively
bunx @sanity-labs/nuum --repl
# Or with npx
npx @sanity-labs/nuum --repl
That's it. Start chatting. Your agent remembers everything.
REPL Commands
/help Show available commands
/inspect Show memory statistics
/dump Show full system prompt
/quit Exit
Other Modes
nuum -p "What files are in src/" # Single prompt
nuum --inspect # View memory stats
nuum --db ./project.db --repl # Custom database
β οΈ Experimental Software
Nuum currently runs in full autonomy mode β no permission prompts, no confirmations. It was created for Miriad as an embedded agent engine, typically running in containerized environments where the host platform manages security.
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 selective, recursive memory compression and active knowledge management.
MCP Servers
Nuum supports Model Context Protocol servers for extended capabilities. Configure via environment variable:
export NUUM_MCP_SERVERS='{
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_TOKEN": "your-token" }
}
}'
Or pass via protocol when embedding:
{"type":"user","message":{...},"mcp_servers":{"name":{"command":"...","args":[...]}}}
MCP tools appear alongside built-in tools. The agent discovers and uses them automatically.
Embedding in Applications
Nuum is designed to be embedded. While it runs standalone, its primary use case is integration into host applications, IDEs, and orchestration platforms.
nuum --stdio # NDJSON protocol over stdin/stdout
nuum --stdio --db ./my.db # With custom database
Key properties:
- Stateless process, stateful memory β Process can restart anytime; all state lives in SQLite
- Simple wire protocol β JSON messages over stdin/stdout, easy to integrate from any language
- Mid-turn injection β Send corrections while the agent is working
- Persistent identity β One database = one agent with continuous memory
See docs/protocol.md for the full wire protocol specification.
Memory Architecture
Nuum has a three-tier memory system that mirrors human cognition.
Key insight: Agents perform best when context is 30-50% full β informed but not overwhelmed. Nuum's memory system maintains this sweet spot automatically.
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β WORKING MEMORY β
β (Temporal Message Store) β
β β
β Recent messages live here in full detail. As context grows, older β
β content is recursively distilled β compressed while retaining what β
β matters for effective action. β
β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β msg msg msg msg msg msg msg msg msg msg msg msg msg msg msg msg ... β β
β β β β β β β β β β β β β β β β β β β β
β β βββββ΄ββββ΄ββββ΄ββββ βββββ΄ββββ΄ββββ βββββ΄ββββ΄ββββ β β β β β
β β β β β β β β β β
β β [distill-1] [distill-2] [distill-3] β β β β β
β β β β β β β β β β
β β βββββββββββββββββββββ΄ββββββββββββββββ β β β β β
β β β β β β β β
β β [distill-4] β β β β β
β β β β β β β β
β β βββββββββββββββββββββββββββ β β β β
β β β β β β β
β β [distill-5] [recent msgs] β β
β β β β
β β Older ββββββββββββββββββββββββββββββββββββββββββββββββββββΊ Newer β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β The agent sees: [distill-5] + [recent messages] β
β 55x compression ratio achieved (1.3M tokens β 25k effective) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β PRESENT STATE β
β β
β βββββββββββββββ βββββββββββββββ βββββββββββββββββββββββββββββββββββ β
β β Mission β β Status β β Tasks β β
β β β β β β β Setup repository β β
β β "Build β β "reviewing β β β Implement auth β β
β β auth β β PR #42" β β β Write tests β β
β β system" β β β β β Deploy to staging β β
β βββββββββββββββ βββββββββββββββ βββββββββββββββββββββββββββββββββββ β
β β
β Agent-managed working state. Updated as work progresses. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β LONG-TERM MEMORY β
β (Knowledge Base Tree) β
β β
β /identity βββββββββββββββ "Who I am, my nature and relationships" β
β /behavior βββββββββββββββ "How I should operate, user preferences" β
β /nuum β
β βββ /cast-integration β "CAST/Miriad integration notes" β
β βββ /memory β
β β βββ /background-reports-system β
β βββ /anthropic-prompt-caching β
β βββ /distillation-improvements-jan2026 β
β /mcp β
β βββ /mcp-implementation β
β βββ /mcp-config-resolution β
β β
β Hierarchical knowledge that persists forever. Background workers β
β extract important information from conversations and organize it here. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Recursive Distillation
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.
The distillation system is not summarization β it's operational intelligence extraction:
RETAIN (actionable intelligence):
- File paths and what they contain
- Decisions made and WHY (rationale matters)
- User preferences and corrections
- Specific values: URLs, configs, commands
- Errors and how they were resolved
EXCISE (noise):
- Back-and-forth debugging that led nowhere
- Missteps and corrections (keep only final approach)
- Verbose tool outputs
- Narrative filler ("Let me check...")
- Casual chatter and acknowledgments
Distillations are recursive β older distillations get distilled again, creating a fractal compression where ancient history becomes highly compressed while recent work stays detailed.
Long-Term Memory Curation
A background worker (the LTM Curator) runs continuously in the background:
- CAPTURES important information into knowledge entries
- STRENGTHENS entries by researching and adding context
- CURATES the knowledge tree structure
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.
Reflection
When the agent needs to recall something specific β a file path, a decision, a value from weeks ago β it uses the reflect tool:
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β REFLECTION β
β β
β Main Agent Reflection Sub-Agent β
β β β β
β β "What was the auth bug fix?" β β
β β βββββββββββββββββββββββββββββββββββββΊβ β
β β β β
β β βββββββββββββ΄ββββββββββββ β
β β β Search FTS index β β
β β β Search LTM entries β β
β β β Read relevant docs β β
β β β Synthesize answer β β
β β βββββββββββββ¬ββββββββββββ β
β β β β
β β "The auth bug was in session.ts, β β
β β line 42. Fixed by adding null β β
β β check. Committed in abc123." β β
β β ββββββββββββββββββββββββββββββββββββββ β
β β β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
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.
Configuration
# Required
ANTHROPIC_API_KEY=your-key-here
# Optional β Web Search
BRAVE_SEARCH_API_KEY=your-key # Brave Search API (recommended)
# Get a free key at https://brave.com/search/api/
# Without this, falls back to DuckDuckGo HTML scraping
# (unreliable from cloud/container IPs)
# Optional β Model Selection (defaults shown)
AGENT_MODEL_REASONING=claude-opus-4-6
AGENT_MODEL_WORKHORSE=claude-sonnet-4-5-20250929
AGENT_MODEL_FAST=claude-haiku-4-5-20251001
AGENT_DB=./agent.db
Development
bun install # Install dependencies
bun run dev # Run in development
bun run typecheck # Type check
bun test # Run tests
bun run build # Build for distribution
Acknowledgments
Letta (formerly MemGPT)
Memory architecture influenced by Letta:
- Core memory always in context
- Agent-editable memory
- Background memory workers
OpenCode
Infrastructure adapted from OpenCode:
- Tool definition patterns
- Permission system
- Process management
License
MIT
Nuum is part of Miriad, experimental software from Sanity.io
