@nano-step/nano-brain 2026.6.2607 → 2026.6.2801
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 +96 -25
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# nano-brain
|
|
2
2
|
|
|
3
|
-
**
|
|
3
|
+
**Built for agents. Not humans.**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Agent-oriented memory and code intelligence. AI agents don't read docs — they need structured context, impact analysis, and call chains. nano-brain provides exactly that via MCP.
|
|
6
6
|
|
|
7
7
|
[](https://go.dev/)
|
|
8
8
|
[](LICENSE)
|
|
@@ -22,37 +22,51 @@ npm install -g @nano-step/nano-brain
|
|
|
22
22
|
# Start
|
|
23
23
|
nano-brain serve -d
|
|
24
24
|
|
|
25
|
-
# Your AI agent now has memory
|
|
25
|
+
# Your AI agent now has persistent memory, code intelligence, and impact analysis
|
|
26
26
|
```
|
|
27
27
|
|
|
28
28
|
---
|
|
29
29
|
|
|
30
30
|
## Why Star This Project?
|
|
31
31
|
|
|
32
|
-
**If you've ever wished your AI agent
|
|
32
|
+
**If you've ever wished your AI agent stopped flying blind in your codebase.**
|
|
33
33
|
|
|
34
|
-
nano-brain
|
|
34
|
+
Most memory tools optimize for conversation recall. nano-brain optimizes for **agent comprehension** — the ability to understand codebases, trace dependencies, and predict the blast radius of changes.
|
|
35
35
|
|
|
36
|
+
nano-brain is:
|
|
37
|
+
|
|
38
|
+
- **Agent-oriented** — Built around how agents actually work: impact analysis before edits, call chain tracing, symbol lookup. Not a document store with MCP slapped on top.
|
|
36
39
|
- **Self-hosted** — Your data stays on your server. No cloud dependency.
|
|
37
40
|
- **Works everywhere** — OpenCode, Claude Code, Cursor, any MCP client.
|
|
38
41
|
- **Actually useful** — Not a toy demo. Production-ready with 16 MCP tools, hybrid search, code intelligence, and agent-oriented benchmarks.
|
|
39
42
|
- **Built for developers** — Go binary, PostgreSQL, zero magic. You can read the code.
|
|
40
43
|
- **Beating competitors** — P@5 of 80% vs LlamaIndex's 55% and Qdrant's 27% on real-world queries.
|
|
41
44
|
|
|
42
|
-
Star it if you want
|
|
45
|
+
Star it if you want agents that understand your code, not just search it.
|
|
43
46
|
|
|
44
47
|
---
|
|
45
48
|
|
|
46
49
|
## What It Does
|
|
47
50
|
|
|
48
|
-
nano-brain
|
|
51
|
+
nano-brain is an **agent-oriented infrastructure layer** that sits between your AI agent and your codebase.
|
|
52
|
+
|
|
53
|
+
It solves two problems agents have:
|
|
54
|
+
|
|
55
|
+
1. **Session amnesia** — Agents forget everything when the session ends. nano-brain persists context across sessions via harvesting, indexing, and retrieval.
|
|
56
|
+
2. **Codebase blindness** — Agents can't trace dependencies, measure blast radius, or understand control flow. nano-brain builds a live code graph and exposes it via 16 MCP tools.
|
|
49
57
|
|
|
50
|
-
|
|
51
|
-
- **Ingests** AI sessions, notes, and codebase files
|
|
52
|
-
- **Indexes** everything with hybrid search (BM25 + pgvector)
|
|
53
|
-
- **Serves** memories via 16 MCP tools and REST API
|
|
58
|
+
**Why MCP?** Because agents don't read docs. They call tools. Every capability is a tool call — no REST API ceremony, no JSON parsing, no manual file reading.
|
|
54
59
|
|
|
55
|
-
|
|
60
|
+
### How agents use it
|
|
61
|
+
|
|
62
|
+
| Agent needs to... | Tool | What it returns |
|
|
63
|
+
|---|---|---|
|
|
64
|
+
| Understand a feature | `memory_query` | Hybrid search results with context |
|
|
65
|
+
| Check what breaks before editing | `memory_impact` | Blast radius — all dependent files |
|
|
66
|
+
| Trace an execution path | `memory_trace` | Call chain from entry point |
|
|
67
|
+
| Find a function definition | `memory_symbols` | Symbol location + kind |
|
|
68
|
+
| Recall a past decision | `memory_query` | Past session context |
|
|
69
|
+
| Save a discovery | `memory_write` | Persisted for future sessions |
|
|
56
70
|
|
|
57
71
|
---
|
|
58
72
|
|
|
@@ -80,6 +94,57 @@ graph LR
|
|
|
80
94
|
|
|
81
95
|
---
|
|
82
96
|
|
|
97
|
+
## Agent-Oriented Design
|
|
98
|
+
|
|
99
|
+
nano-brain isn't a memory tool with MCP bolted on. It's designed from the ground up around **how agents actually behave**.
|
|
100
|
+
|
|
101
|
+
### The agent workflow loop
|
|
102
|
+
|
|
103
|
+
```
|
|
104
|
+
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
|
|
105
|
+
│ Agent │────▶│ memory_query │────▶│ Context │
|
|
106
|
+
│ receives │ │ /impact/trace│ │ window │
|
|
107
|
+
│ task │ │ │ │ filled │
|
|
108
|
+
└─────────────┘ └──────────────┘ └──────┬──────┘
|
|
109
|
+
│
|
|
110
|
+
┌──────▼──────┐
|
|
111
|
+
│ Agent │
|
|
112
|
+
│ implements │
|
|
113
|
+
│ change │
|
|
114
|
+
└──────┬──────┘
|
|
115
|
+
│
|
|
116
|
+
┌──────▼──────┐
|
|
117
|
+
│ memory_write │
|
|
118
|
+
│ (persist) │
|
|
119
|
+
└─────────────┘
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Why agent behavior matters
|
|
123
|
+
|
|
124
|
+
| Human workflow | Agent workflow | nano-brain response |
|
|
125
|
+
|---|---|---|
|
|
126
|
+
| Opens file, reads it | `memory_get` or `memory_search` | Returns structured content, not raw bytes |
|
|
127
|
+
| Traces call chain manually | `memory_trace` | Returns function-by-function chain with line numbers |
|
|
128
|
+
| Greps for callers | `memory_graph(direction="in")` | Returns all callers in one call |
|
|
129
|
+
| Thinks "what breaks?" | `memory_impact` | Returns full blast radius in <50ms |
|
|
130
|
+
| Remembers past decisions | `memory_query` | Returns cross-session context |
|
|
131
|
+
|
|
132
|
+
### The 50ms rule
|
|
133
|
+
|
|
134
|
+
At 50ms latency, agents run impact analysis on every edit. At 500ms, they skip it. nano-brain is designed for the 50ms world — every code intelligence tool call is sub-50ms, making it practical for agents to use them on every operation.
|
|
135
|
+
|
|
136
|
+
### What agents actually need
|
|
137
|
+
|
|
138
|
+
Research from 15+ production code intelligence tools shows:
|
|
139
|
+
|
|
140
|
+
1. **Impact analysis is #1** — "What breaks if I change this?" is the most common agent query
|
|
141
|
+
2. **Call chains > control flow** — Agents trace across files (inter-procedural), not within functions (intra-procedural)
|
|
142
|
+
3. **Component composition > internal logic** — For frontend frameworks, "who uses this component?" matters more than "what does the template do?"
|
|
143
|
+
|
|
144
|
+
nano-brain optimizes for exactly these three patterns.
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
83
148
|
## Key Features
|
|
84
149
|
|
|
85
150
|
### Hybrid Search
|
|
@@ -249,17 +314,20 @@ flowchart LR
|
|
|
249
314
|
|
|
250
315
|
## Use Cases
|
|
251
316
|
|
|
252
|
-
###
|
|
253
|
-
|
|
317
|
+
### Agent-assisted refactoring
|
|
318
|
+
Before refactoring, your agent calls `memory_impact` on the target function. Gets the full blast radius. Decides whether to split the change. After refactoring, runs affected tests only — not the full suite.
|
|
254
319
|
|
|
255
|
-
###
|
|
256
|
-
|
|
320
|
+
### Multi-session feature development
|
|
321
|
+
Session 1: Agent explores the codebase, discovers patterns. `memory_write` saves findings. Session 2: Agent recalls session 1's discoveries via `memory_query`. No context lost between sessions.
|
|
257
322
|
|
|
258
|
-
### Legacy codebase
|
|
259
|
-
|
|
323
|
+
### Legacy codebase onboarding
|
|
324
|
+
Index a 5-year-old codebase. Your agent can now answer "what does this function do?", "why does this class exist?", "if I change this file, what else breaks?" — without reading every file.
|
|
260
325
|
|
|
261
|
-
###
|
|
262
|
-
|
|
326
|
+
### Cross-service debugging
|
|
327
|
+
Agent traces a bug from frontend to backend. `memory_trace` follows the call chain across services. `memory_graph` shows which microservices depend on the failing endpoint.
|
|
328
|
+
|
|
329
|
+
### Team knowledge sharing
|
|
330
|
+
One server, whole team. Every developer's AI agent connects to the same PostgreSQL. Decisions, architecture notes, code intelligence — instantly shared. New hires get full context from day one.
|
|
263
331
|
|
|
264
332
|
---
|
|
265
333
|
|
|
@@ -286,12 +354,15 @@ Tested on 60 domain-specific queries across 3 workspaces. nano-brain is the **on
|
|
|
286
354
|
- **Cognee / GraphRAG** — Document-level knowledge graphs, multi-hop reasoning
|
|
287
355
|
- **LlamaIndex** — Flexible RAG pipelines, document retrieval
|
|
288
356
|
|
|
289
|
-
**What nano-brain adds:**
|
|
290
|
-
- **
|
|
291
|
-
- **
|
|
292
|
-
- **
|
|
357
|
+
**What nano-brain adds (agent-oriented):**
|
|
358
|
+
- **Impact analysis** — "What breaks if I change this?" — the #1 question agents ask. Pre-computed blast radius in <50ms.
|
|
359
|
+
- **Call chain tracing** — Follow execution paths across files. Agent gets a structured trace, not raw source.
|
|
360
|
+
- **Symbol graph** — Find definitions, callers, callees. `memory_symbols` + `memory_graph`.
|
|
361
|
+
- **Agent-oriented benchmarks** — Measures how well agents find context for domain tasks — not just search precision in isolation.
|
|
362
|
+
|
|
363
|
+
**The difference:** Competitors optimize for "did the agent find the right document?" nano-brain optimizes for "did the agent understand the codebase well enough to make the right change?"
|
|
293
364
|
|
|
294
|
-
|
|
365
|
+
At 50ms latency, agents run impact analysis on every edit. At 500ms, they skip it. nano-brain is designed for the 50ms world.
|
|
295
366
|
|
|
296
367
|
### Agent-Oriented Capability Benchmarks
|
|
297
368
|
|