@nano-step/nano-brain 2026.7.702 → 2026.7.703

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.
Files changed (3) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +127 -457
  3. package/package.json +1 -1
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 nano-step
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  **Built for agents. Not humans.**
4
4
 
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.
5
+ Agent-oriented memory and code intelligence over MCP. AI agents don't read docs — they call tools. nano-brain gives them structured context, symbol lookup, call-chain tracing, and change-impact analysis across sessions and repos.
6
6
 
7
7
  [![Go 1.23](https://img.shields.io/badge/Go-1.23-00ADD8?logo=go)](https://go.dev/)
8
8
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
@@ -11,8 +11,20 @@ Agent-oriented memory and code intelligence. AI agents don't read docs — they
11
11
  [![Docker](https://img.shields.io/badge/Docker-2496ED?logo=docker&logoColor=white)](https://hub.docker.com/r/nano-step/nano-brain)
12
12
  [![Discord](https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/nano-brain)
13
13
 
14
+ ---
15
+
16
+ ## What it is
17
+
18
+ nano-brain is an infrastructure layer between your AI agent and your code. It solves two problems agents have:
19
+
20
+ 1. **Session amnesia** — agents forget everything when a session ends. nano-brain harvests, indexes, and retrieves past sessions and saved decisions.
21
+ 2. **Codebase blindness** — agents can't cheaply trace dependencies, measure blast radius, or map an execution path. nano-brain builds a code graph and exposes it as MCP tools.
22
+
23
+ Self-hosted (Go binary + PostgreSQL), works with any MCP client (Claude Code, OpenCode, Cursor, …), and returns structured results — not raw file bytes.
14
24
 
15
- ### Install
25
+ ---
26
+
27
+ ## Install
16
28
 
17
29
  ```bash
18
30
  # Recommended — one-line installer (no Node.js needed): downloads the prebuilt
@@ -26,65 +38,87 @@ npm install -g @nano-step/nano-brain
26
38
  CGO_ENABLED=0 go build -o nano-brain ./cmd/nano-brain
27
39
  ```
28
40
 
29
- Prefer to read the installer before running it? Download, inspect, then run:
30
-
31
- ```bash
32
- curl -fsSL -o install.sh https://raw.githubusercontent.com/nano-step/nano-brain/master/install.sh
33
- less install.sh && bash install.sh
34
- ```
41
+ Prefer to read the installer first? `curl -fsSL -o install.sh https://raw.githubusercontent.com/nano-step/nano-brain/master/install.sh && less install.sh && bash install.sh`.
35
42
 
36
- ### Start
43
+ ## Start
37
44
 
38
45
  ```bash
39
- # One command — the interactive wizard provisions PostgreSQL (via Docker or a
40
- # remote URL), configures embeddings, starts the server, registers this
41
- # project, and sets up your MCP client.
46
+ # One command — the interactive wizard provisions PostgreSQL (Docker or remote URL),
47
+ # configures embeddings, starts the server, registers this project, and wires up your MCP client.
42
48
  nano-brain init
43
49
  ```
44
50
 
45
- For a manual, per-step setup (VPS / team, no Docker, or Windows), see [docs/SETUP_AGENT.md](docs/SETUP_AGENT.md).
46
- ---
51
+ Manual, per-step setup (VPS / team / no Docker / Windows): [docs/SETUP_AGENT.md](docs/SETUP_AGENT.md).
47
52
 
48
- ## Why Star This Project?
53
+ ### Connect your agent
49
54
 
50
- **If you've ever wished your AI agent stopped flying blind in your codebase.**
55
+ Add to your MCP client config:
51
56
 
52
- 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.
57
+ ```json
58
+ {
59
+ "mcp": {
60
+ "nano-brain": { "type": "remote", "url": "http://localhost:3100/mcp" }
61
+ }
62
+ }
63
+ ```
53
64
 
54
- nano-brain is:
65
+ Bind a default workspace by appending `?workspace=<name-or-hash>` to the URL (e.g. `…/mcp?workspace=my-project`) so tool calls can omit the `workspace` argument. An explicit `workspace` argument always overrides it; the value must be a name or full hash (not `"all"`). Run `nano-brain workspaces list` to see registered names/hashes.
66
+
67
+ ---
55
68
 
56
- - **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.
57
- - **Self-hosted** — Your data stays on your server. No cloud dependency.
58
- - **Works everywhere** — OpenCode, Claude Code, Cursor, any MCP client.
59
- - **Actually useful** — Not a toy demo. Production-ready with 16 MCP tools, hybrid search, code intelligence, and agent-oriented benchmarks.
60
- - **Built for developers** — Go binary, PostgreSQL, zero magic. You can read the code.
61
- - **Beating competitors** — P@5 of 80% vs LlamaIndex's 55% and Qdrant's 27% on real-world queries.
69
+ ## The agent workflow
62
70
 
63
- Star it if you want agents that understand your code, not just search it.
71
+ A cold agent should follow this order — it maps 1:1 to the tools:
72
+
73
+ 1. **Orient** — `memory_wake_up` for a workspace briefing (recent activity, collections, stats).
74
+ 2. **Locate the workspace** — `memory_workspaces_resolve(path)` returns a deterministic hash and whether it's registered. Registering the repo root also covers its subdirectories, so resolve the root, not a single sub-repo.
75
+ 3. **Understand** — `memory_query` (hybrid, best for natural-language questions), `memory_search` (exact identifiers/errors), or `memory_vsearch` (fuzzy concepts). Search returns 500-char snippets; fetch full text with `memory_get` only for the hits you keep.
76
+ 4. **Navigate code** — `memory_symbols` to find a definition (no indexing needed), then `memory_graph` / `memory_trace` for call chains and `memory_flow` for an HTTP route's execution.
77
+ 5. **Before a risky edit** — `memory_impact(node, direction="in")` for the blast radius (who calls / imports this).
78
+ 6. **Persist** — `memory_write` to save a decision, lesson, or handoff for the next session.
79
+
80
+ ```
81
+ wake_up → resolve ─▶ query / search / symbols ─▶ graph / trace / flow / impact ─▶ (edit) ─▶ write
82
+ ```
64
83
 
65
84
  ---
66
85
 
67
- ## What It Does
86
+ ## MCP tools (18)
87
+
88
+ **Search & recall**
68
89
 
69
- nano-brain is an **agent-oriented infrastructure layer** that sits between your AI agent and your codebase.
90
+ | Tool | Use it for |
91
+ |------|------------|
92
+ | `memory_query` | Hybrid BM25 + vector + RRF + recency — default first tool for broad questions |
93
+ | `memory_search` | Exact keyword/BM25 — error strings, identifiers, config keys, channel/topic names |
94
+ | `memory_vsearch` | Vector similarity — fuzzy concepts (best on single-concept queries) |
95
+ | `memory_get` | Fetch full content (or a line range) for one known document/symbol |
96
+ | `memory_write` | Persist a decision/lesson/handoff (supports `supersedes`) |
97
+ | `memory_ticket` | All sessions tagged with a ticket ID (e.g. `PROJ-1234`) across the workspace |
98
+ | `memory_wake_up` | Session-start briefing: recent memories, active collections, stats |
99
+ | `memory_tags` | List collections and document counts |
70
100
 
71
- It solves two problems agents have:
101
+ **Code intelligence**
72
102
 
73
- 1. **Session amnesia** — Agents forget everything when the session ends. nano-brain persists context across sessions via harvesting, indexing, and retrieval.
74
- 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.
103
+ | Tool | Use it for |
104
+ |------|------------|
105
+ | `memory_symbols` | Find a function/type/interface/const by name (reads the filesystem — no indexing required) |
106
+ | `memory_graph` | One-hop neighbors: direct callers/callees, imports, containment |
107
+ | `memory_trace` | Downstream call chain from an entry symbol |
108
+ | `memory_impact` | Reverse blast radius before an edit: who calls/imports this |
109
+ | `memory_flow` | HTTP route execution flow (middleware → handler → downstream), Mermaid/sequence/JSON |
110
+ | `memory_flowchart` | Control-flow graph of a single function (branches, loops, returns) |
75
111
 
76
- **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.
112
+ **Workspace & ops**
77
113
 
78
- ### How agents use it
114
+ | Tool | Use it for |
115
+ |------|------------|
116
+ | `memory_workspaces_resolve` | Resolve a path to its workspace hash + registration status |
117
+ | `memory_workspaces_list` | List registered workspaces with paths, hashes, document counts |
118
+ | `memory_status` | Server / DB / embedding-queue health |
119
+ | `memory_update` | Trigger a delta re-scan / re-embedding for a workspace |
79
120
 
80
- | Agent needs to... | Tool | What it returns |
81
- |---|---|---|
82
- | Understand a feature | `memory_query` | Hybrid search results with context |
83
- | Check what breaks before editing | `memory_impact` | Blast radius — all dependent files |
84
- | Trace an execution path | `memory_trace` | Call chain from entry point |
85
- | Find a function definition | `memory_symbols` | Symbol location + kind |
86
- | Recall a past decision | `memory_query` | Past session context |
87
- | Save a discovery | `memory_write` | Persisted for future sessions |
121
+ > Every tool is self-describing over MCP — your client lists each tool's name, parameters, and description on connect.
88
122
 
89
123
  ---
90
124
 
@@ -92,479 +126,115 @@ It solves two problems agents have:
92
126
 
93
127
  ```mermaid
94
128
  graph LR
95
- A[Your AI Agent] -->|MCP Protocol| B[nano-brain]
129
+ A[Your AI Agent] -->|MCP| B[nano-brain]
96
130
  B --> C[PostgreSQL + pgvector]
97
131
  B --> D[Session Harvesting]
98
132
  B --> E[Code Intelligence]
99
133
  B --> F[Hybrid Search]
100
-
101
134
  D --> D1[OpenCode Sessions]
102
135
  D --> D2[Claude Code Sessions]
103
-
104
136
  E --> E1[Symbol Graph]
105
137
  E --> E2[Flow Diagrams]
106
138
  E --> E3[Impact Analysis]
107
-
108
139
  F --> F1[BM25 Full-Text]
109
140
  F --> F2[Vector Similarity]
110
141
  F --> F3[RRF Fusion]
111
142
  ```
112
143
 
113
- ---
114
-
115
- ## Agent-Oriented Design
116
-
117
- nano-brain isn't a memory tool with MCP bolted on. It's designed from the ground up around **how agents actually behave**.
118
-
119
- ### The agent workflow loop
120
-
121
- ```
122
- ┌─────────────┐ ┌──────────────┐ ┌─────────────┐
123
- │ Agent │────▶│ memory_query │────▶│ Context │
124
- │ receives │ │ /impact/trace│ │ window │
125
- │ task │ │ │ │ filled │
126
- └─────────────┘ └──────────────┘ └──────┬──────┘
127
- │
128
- ┌──────▼──────┐
129
- │ Agent │
130
- │ implements │
131
- │ change │
132
- └──────┬──────┘
133
- │
134
- ┌──────▼──────┐
135
- │ memory_write │
136
- │ (persist) │
137
- └─────────────┘
138
- ```
139
-
140
- ### Why agent behavior matters
141
-
142
- | Human workflow | Agent workflow | nano-brain response |
143
- |---|---|---|
144
- | Opens file, reads it | `memory_get` or `memory_search` | Returns structured content, not raw bytes |
145
- | Traces call chain manually | `memory_trace` | Returns function-by-function chain with line numbers |
146
- | Greps for callers | `memory_graph(direction="in")` | Returns all callers in one call |
147
- | Thinks "what breaks?" | `memory_impact` | Returns full blast radius in <50ms |
148
- | Remembers past decisions | `memory_query` | Returns cross-session context |
149
-
150
- ### The 50ms rule
151
-
152
- 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.
153
-
154
- ### What agents actually need
155
-
156
- Research from 15+ production code intelligence tools shows:
157
-
158
- 1. **Impact analysis is #1** — "What breaks if I change this?" is the most common agent query
159
- 2. **Call chains > control flow** — Agents trace across files (inter-procedural), not within functions (intra-procedural)
160
- 3. **Component composition > internal logic** — For frontend frameworks, "who uses this component?" matters more than "what does the template do?"
161
-
162
- nano-brain optimizes for exactly these three patterns.
163
-
164
- ---
165
-
166
- ## Key Features
167
-
168
- ### Hybrid Search
169
-
170
- ```mermaid
171
- graph LR
172
- Q[Query] --> BM25[BM25 Full-Text]
173
- Q --> Vector[Vector Similarity]
174
- BM25 --> RRF[RRF Fusion]
175
- Vector --> RRF
176
- RRF --> Results[Ranked Results]
177
- ```
178
-
179
- BM25 full-text + pgvector HNSW cosine similarity + Reciprocal Rank Fusion + recency decay.
180
-
181
- ### Code Intelligence
182
-
183
- ```mermaid
184
- graph TD
185
- A[Entry Point] --> B[Function Call]
186
- B --> C[Method Call]
187
- B --> D[Database Query]
188
- C --> E[External Service]
189
- D --> F[Redis Cache]
190
- ```
144
+ - **Hybrid search** — BM25 full-text + pgvector HNSW cosine similarity + Reciprocal Rank Fusion + recency decay.
145
+ - **Code intelligence** — symbol extraction, cross-file call-chain tracing, reverse-dependency (impact) analysis, and Mermaid flow/flowchart generation. Multi-language, including Ruby/Rails route + control-flow support.
146
+ - **Session harvesting** — auto-ingest from OpenCode and Claude Code sessions, map-reduce LLM summarization, incremental harvest with dedup.
191
147
 
192
- - **Symbol extraction** — Functions, types, interfaces, constants
193
- - **Call chain tracing** — Follow execution paths across files
194
- - **Impact analysis** — "What breaks if I change this?"
195
- - **Flow diagrams** — Mermaid flowcharts and sequence diagrams
196
-
197
- ### Session Harvesting
198
-
199
- ```mermaid
200
- graph LR
201
- S1[OpenCode DB] --> H[Harvester]
202
- S2[Claude Code JSONL] --> H
203
- H --> L[LLM Summarizer]
204
- L --> I[Indexer]
205
- I --> DB[PostgreSQL]
206
- ```
207
-
208
- Auto-ingest from OpenCode and Claude Code sessions. Map-reduce LLM summarization. Incremental harvest with dedup.
209
-
210
- ### 16 MCP Tools
211
-
212
- | Tool | Description |
213
- |------|-------------|
214
- | `memory_query` | Hybrid search — default first tool for broad questions |
215
- | `memory_search` | BM25 keyword search for exact text/errors |
216
- | `memory_vsearch` | Vector similarity for fuzzy concepts |
217
- | `memory_get` | Get document by path or ID |
218
- | `memory_write` | Write/update document |
219
- | `memory_graph` | One-hop callers/callees/imports |
220
- | `memory_trace` | Downstream call chain trace |
221
- | `memory_impact` | Pre-change blast radius analysis |
222
- | `memory_symbols` | Symbol search (functions, types, interfaces) |
223
- | `memory_flow` | HTTP route execution flow |
224
- | `memory_flowchart` | Function-level control-flow graph |
225
- | `memory_workspaces_resolve` | Resolve path to workspace hash |
226
- | `memory_tags` | List tags with counts |
227
- | `memory_status` | Server and queue health |
228
- | `memory_update` | Trigger re-embedding |
229
- | `memory_wake_up` | Session-start workspace briefing |
230
-
231
- ---
232
-
233
- ## Quick Start
234
-
235
- ### Prerequisites
236
-
237
- - **Go 1.23+** OR pre-built binary
238
- - **PostgreSQL 17** with **pgvector 0.8.2**
239
- - **Ollama** (for embeddings) or any OpenAI-compatible provider
240
-
241
- ### Configure Your AI Agent
242
-
243
- Add to your MCP client config (Claude Code, OpenCode, Cursor, etc.):
244
-
245
- ```json
246
- {
247
- "mcp": {
248
- "nano-brain": {
249
- "type": "remote",
250
- "url": "http://localhost:3100/mcp"
251
- }
252
- }
253
- }
254
- ```
255
-
256
- Optionally bind a default workspace to the connection by appending `?workspace=<name-or-hash>` to the URL (e.g. `"url": "http://localhost:3100/mcp?workspace=nano-brain"`) — tool calls can then omit the `workspace` argument. Run `nano-brain workspaces list` to see the registered name/hash for a project. An explicit `workspace` argument always overrides the connection default; the value must be a name or full hash, not `"all"`.
257
-
258
- ---
259
-
260
- ## Demo
261
-
262
- ### Query Your Codebase
263
-
264
- ```bash
265
- # Search for authentication patterns
266
- curl -X POST http://localhost:3100/api/v1/query \
267
- -H "Content-Type: application/json" \
268
- -d '{"workspace": "abc123", "query": "how does authentication work"}'
269
- ```
270
-
271
- ### Trace Call Chains
272
-
273
- ```bash
274
- # Trace from entry point
275
- curl -X POST http://localhost:3100/api/v1/graph/trace \
276
- -H "Content-Type: application/json" \
277
- -d '{"workspace": "abc123", "node": "main.go::main", "max_depth": 5}'
278
- ```
279
-
280
- ### Analyze Impact
281
-
282
- ```bash
283
- # What breaks if I change this file?
284
- curl -X POST http://localhost:3100/api/v1/graph/impact \
285
- -H "Content-Type: application/json" \
286
- -d '{"workspace": "abc123", "node": "src/auth/login.ts", "max_depth": 2}'
287
- ```
288
-
289
- ### Generate Flow Diagrams
290
-
291
- ```bash
292
- # Get flow diagram for a controller
293
- curl -X POST http://localhost:3100/api/v1/graph/flow \
294
- -H "Content-Type: application/json" \
295
- -d '{"workspace": "abc123", "entry": "POST /users"}'
296
- ```
297
-
298
- Returns Mermaid flowchart:
299
-
300
- ```mermaid
301
- flowchart LR
302
- POST_/users["POST /users"]
303
- POST_/users --> UsersController#create
304
- UsersController#create --> User.create
305
- UsersController#create --> Mailer.welcome
306
- ```
307
-
308
- ---
309
-
310
- ## Use Cases
311
-
312
- ### Agent-assisted refactoring
313
- 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.
314
-
315
- ### Multi-session feature development
316
- 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.
317
-
318
- ### Legacy codebase onboarding
319
- 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.
320
-
321
- ### Cross-service debugging
322
- 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.
323
-
324
- ### Team knowledge sharing
325
- 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.
148
+ Collections: `code` (indexed source + docs), `sessions` (harvested agent sessions), `memory` (agent-written decisions/notes).
326
149
 
327
150
  ---
328
151
 
329
152
  ## Performance
330
153
 
331
- ### Search Quality vs Competitors
332
-
333
- | Metric | nano-brain | LlamaIndex | Qdrant/Mem0 | Cognee | GraphRAG | Zep |
334
- |--------|------------|------------|-------------|--------|----------|-----|
335
- | P@5 | **80%** | 55% | 27% | — | — | — |
336
- | MRR | **95%** | — | — | — | — | — |
337
- | Latency | **42ms** | — | — | — | — | — |
338
- | Code Intelligence | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
339
- | Symbol Graph | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
340
- | Impact Analysis | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
341
- | Flow Diagrams | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
342
-
343
- Tested on 60 domain-specific queries across 3 workspaces. nano-brain is the **only** solution with code intelligence — competitors focus on conversation memory and document retrieval.
344
-
345
- ### Competitive Landscape
346
-
347
- **What competitors offer:**
348
- - **Mem0 / Zep** — Conversation memory, temporal ranking, chat history recall
349
- - **Cognee / GraphRAG** — Document-level knowledge graphs, multi-hop reasoning
350
- - **LlamaIndex** — Flexible RAG pipelines, document retrieval
351
-
352
- **What nano-brain adds (agent-oriented):**
353
- - **Impact analysis** — "What breaks if I change this?" — the #1 question agents ask. Pre-computed blast radius in <50ms.
354
- - **Call chain tracing** — Follow execution paths across files. Agent gets a structured trace, not raw source.
355
- - **Symbol graph** — Find definitions, callers, callees. `memory_symbols` + `memory_graph`.
356
- - **Agent-oriented benchmarks** — Measures how well agents find context for domain tasks — not just search precision in isolation.
357
-
358
- **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?"
359
-
360
- At 50ms latency, agents run impact analysis on every edit. At 500ms, they skip it. nano-brain is designed for the 50ms world.
154
+ Code-intelligence lookups (`memory_symbols`, `memory_graph`, `memory_impact`, `memory_vsearch`, exact `memory_search`) return in tens of milliseconds — fast enough that agents can run impact analysis on **every** edit rather than skipping it.
361
155
 
362
- ### Agent-Oriented Capability Benchmarks
156
+ ### Search quality vs. document-memory tools
363
157
 
364
- nano-brain is built for agents. These benchmarks measure how well agents can **find relevant context for real-world domain tasks** using nano-brain's MCP tools — not just search quality in isolation.
158
+ | Metric | nano-brain | LlamaIndex | Qdrant/Mem0 |
159
+ |--------|------------|------------|-------------|
160
+ | P@5 | **80%** | 55% | 27% |
161
+ | MRR | **95%** | — | — |
162
+ | Code intelligence (symbols / impact / flow) | ✅ | ❌ | ❌ |
365
163
 
366
- Each benchmark runs a deterministic agent workflow:
367
- 1. **query_question** — natural-language domain question
368
- 2. **query_input** — optimized search query
369
- 3. **symbols_identifiers** — symbol lookup for known identifiers
164
+ Measured on 60 domain-specific queries across three workspaces (a Go daemon, a TypeScript service, and a Rails app). nano-brain is the only one of these with code intelligence — the others target conversation memory and document retrieval.
370
165
 
371
- This mimics how a real agent explores a codebase: broad understanding first, then targeted retrieval.
166
+ ### Agent-oriented capability benchmarks
372
167
 
373
- #### Scores
168
+ Each benchmark runs a deterministic agent workflow — natural-language question → optimized query → symbol lookup — mirroring how an agent actually explores a codebase.
374
169
 
375
- | Workspace | Domain | Overall | Multi-tool | Search-QA | Symbol-Lookup |
376
- |-----------|--------|---------|------------|-----------|---------------|
377
- | **nano-brain** | Go daemon | **1.000** | 1.000 | 1.000 | 1.000 |
378
- | **TypeScript** | CS2 item trading | **0.885** | 1.000 | 0.817 | 1.000 |
379
- | **Rails** | CS2 item trading | **0.795** | 1.000 | 0.726 | 0.667 |
170
+ | Workspace | Overall | Multi-tool | Search-QA | Symbol-Lookup |
171
+ |-----------|---------|------------|-----------|---------------|
172
+ | Go daemon | **1.000** | 1.000 | 1.000 | 1.000 |
173
+ | TypeScript service | **0.885** | 1.000 | 0.817 | 1.000 |
174
+ | Rails app | **0.795** | 1.000 | 0.726 | 0.667 |
380
175
 
381
- **What this means:**
382
- - **Multi-tool 1.000** — When agents combine search + symbols, they find every expected context item
383
- - **Overall 0.885** — TypeScript workspace: agent finds 88.5% of expected domain artifacts
384
- - **Fixed vs Agent** — Agent workflow improves recall by 15-40% over single-tool queries
385
- - **Unique capability** — No competitor offers agent-oriented benchmarks or code intelligence
386
-
387
- #### How to Run
388
-
389
- ```bash
390
- # TypeScript workspace (CS2 item trading domain)
391
- NANO_BRAIN_URL=http://localhost:3100 \
392
- NANO_BRAIN_WORKSPACE=<your-workspace-hash> \
393
- go test -v -tags=capbench -run TestCapabilityBenchmark \
394
- ./benchmarks/typescript/capability/
395
-
396
- # Rails workspace (CS2 item trading domain)
397
- NANO_BRAIN_URL=http://localhost:3100 \
398
- NANO_BRAIN_WORKSPACE=<your-workspace-hash> \
399
- go test -v -tags=capbench -run TestCapabilityBenchmark \
400
- ./benchmarks/rails/capability/
401
-
402
- # nano-brain itself (Go daemon)
403
- NANO_BRAIN_URL=http://localhost:3100 \
404
- NANO_BRAIN_WORKSPACE=nano-brain \
405
- go test -v -tags=capbench -run TestCapabilityBenchmark \
406
- ./benchmarks/capability/
407
- ```
408
-
409
- #### Task Categories
410
-
411
- | Category | What It Tests | Tools Used |
412
- |----------|---------------|------------|
413
- | **search-qa** | Domain concept retrieval via search | `query_question`, `query_input` |
414
- | **symbol-lookup** | Known identifier resolution | `query_input`, `symbols_identifiers` |
415
- | **multi-tool** | Cross-tool workflow (search → symbols) | All three tools in sequence |
416
-
417
- See individual benchmark READMEs for full task breakdowns:
418
- - [`benchmarks/typescript/capability/README.md`](benchmarks/typescript/capability/README.md)
419
- - [`benchmarks/rails/capability/README.md`](benchmarks/rails/capability/README.md)
420
- - [`benchmarks/capability/README.md`](benchmarks/capability/README.md)
176
+ Run them: see the per-suite READMEs under [`benchmarks/`](benchmarks/).
421
177
 
422
178
  ---
423
179
 
424
- ## Ruby / Rails Support
180
+ ## Tech stack
425
181
 
426
- nano-brain supports Ruby and Ruby on Rails code intelligence:
182
+ Go 1.23 (single static binary, `CGO_ENABLED=0`) · PostgreSQL 17 + pgvector 0.8.2 (HNSW) · Echo v4 · sqlc · goose · zerolog · koanf · fsnotify · Ollama (or any OpenAI-compatible embeddings provider).
427
183
 
428
- - **Rails routes** — `resources`, `get`/`post`/`patch`/`put`/`delete`, `namespace`
429
- - **Control-flow graphs** — `if`/`else`, loops, `begin`/`rescue`, method defs
430
- - **Cross-file resolution** — Class→file index, resolver, reconcile edges
431
- - **Flow diagrams** — Controller→service→model chains (20-34 nodes)
184
+ ## Configuration
432
185
 
433
- Example flow for a Rails controller action:
186
+ `~/.nano-brain/config.yml`:
434
187
 
435
- ```mermaid
436
- flowchart LR
437
- POST_/users["POST /users"]
438
- POST_/users --> UsersController#create
439
- UsersController#create --> User.create
440
- UsersController#create --> Mailer.welcome
188
+ ```yaml
189
+ server: { host: localhost, port: 3100 }
190
+ database: { url: postgres://nanobrain:nanobrain@localhost:5432/nanobrain_dev }
191
+ embedding: { provider: ollama, url: http://localhost:11434, model: nomic-embed-text }
192
+ search: { rrf_k: 60, recency_weight: 0.3, limit: 20 }
441
193
  ```
442
194
 
443
- ---
195
+ Full options: [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
444
196
 
445
- ## Tech Stack
197
+ ## REST API
446
198
 
447
- - **Go 1.23** — Single static binary (`CGO_ENABLED=0`)
448
- - **PostgreSQL 17** — Full-text search (tsvector/tsquery)
449
- - **pgvector 0.8.2** — HNSW vector indexing
450
- - **Echo v4** — HTTP framework
451
- - **sqlc** — Type-safe SQL code generation
452
- - **goose v3** — Database migrations
453
- - **zerolog** — Structured JSON logging
454
- - **koanf** — YAML + env configuration
455
- - **fsnotify** — File system watching
199
+ Everything is available over MCP; a REST surface exists for scripting and ops (writes go through MCP). `GET /api/openapi.json` serves the live OpenAPI 3.0 spec — import it into Postman/Swagger.
456
200
 
457
- ---
458
-
459
- ## Configuration
460
-
461
- Config file: `~/.nano-brain/config.yml`
462
-
463
- ```yaml
464
- server:
465
- host: localhost
466
- port: 3100
467
-
468
- database:
469
- url: postgres://nanobrain:nanobrain@localhost:5432/nanobrain_dev
470
-
471
- embedding:
472
- provider: ollama
473
- url: http://localhost:11434
474
- model: nomic-embed-text
475
-
476
- search:
477
- rrf_k: 60
478
- recency_weight: 0.3
479
- limit: 20
201
+ ```bash
202
+ # Understand
203
+ curl -X POST http://localhost:3100/api/v1/query -H 'Content-Type: application/json' \
204
+ -d '{"workspace":"<hash>","query":"how does authentication work"}'
205
+ # Blast radius
206
+ curl -X POST http://localhost:3100/api/v1/graph/impact -H 'Content-Type: application/json' \
207
+ -d '{"workspace":"<hash>","node":"src/auth/login.ts","direction":"in"}'
480
208
  ```
481
209
 
482
- See [Configuration](docs/CONFIGURATION.md) for full options.
483
-
484
210
  ---
485
211
 
486
212
  ## Documentation
487
213
 
488
- - [Getting Started](docs/GETTING_STARTED.md) — Step-by-step setup guide
489
- - [Configuration](docs/CONFIGURATION.md) — All config options
490
- - [REST API](docs/API.md) — HTTP endpoints
491
- - [CLI Commands](docs/CLI.md) — Command reference
492
- - [MCP Tools](docs/MCP.md) — Tool documentation
493
- - [Architecture](docs/ARCHITECTURE.md) — System design
494
- - [Changelog](CHANGELOG.md) — What's new
495
- - [Roadmap](docs/ROADMAP.md) — What's planned
496
- - [Feature Showcase](docs/FEATURES.md) — Visual examples
497
-
498
- ---
214
+ - [Setup (agent / manual)](docs/SETUP_AGENT.md)
215
+ - [Configuration](docs/CONFIGURATION.md)
216
+ - [Architecture](docs/architecture.md)
217
+ - [Features](docs/FEATURES.md)
218
+ - [Roadmap](docs/ROADMAP.md)
219
+ - [Changelog](CHANGELOG.md)
499
220
 
500
221
  ## Contributing
501
222
 
502
- Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
503
-
504
- ### Development Setup
223
+ Contributions welcome — open an issue or a PR.
505
224
 
506
225
  ```bash
507
- # Clone the repo
508
- git clone https://github.com/nano-step/nano-brain.git
509
- cd nano-brain
510
-
511
- # Build
226
+ git clone https://github.com/nano-step/nano-brain.git && cd nano-brain
512
227
  CGO_ENABLED=0 go build -o nano-brain ./cmd/nano-brain
513
-
514
- # Run tests
515
- go test -race -short ./...
516
-
517
- # Run integration tests (requires PostgreSQL)
518
- go test -race -tags=integration ./...
519
- ```
520
-
521
- `GET /api/openapi.json` serves the current OpenAPI 3.0 spec for the full REST API — import it into Postman, Swagger UI, or any codegen tool to discover the endpoint surface without reading Go source. Regenerate it via `make generate-openapi` after adding or changing routes.
522
-
523
- ### Project Structure
524
-
525
- ```
526
- nano-brain/
527
- ├── cmd/nano-brain/ # CLI dispatcher + server startup
528
- ├── internal/
529
- │ ├── config/ # Configuration management
530
- │ ├── server/ # HTTP server + handlers
531
- │ ├── storage/ # PostgreSQL + sqlc
532
- │ ├── search/ # Hybrid search pipeline
533
- │ ├── embed/ # Embedding queue
534
- │ ├── watcher/ # File system watcher
535
- │ ├── harvest/ # Session harvesting
536
- │ ├── mcp/ # MCP protocol tools
537
- │ ├── graph/ # Code intelligence
538
- │ └── ...
539
- ├── migrations/ # Database migrations
540
- └── benchmarks/ # Performance benchmarks
228
+ go test -race -short ./... # unit
229
+ go test -race -tags=integration ./... # integration (needs PostgreSQL)
541
230
  ```
542
231
 
543
- ---
232
+ Regenerate the OpenAPI spec after route changes: `make generate-openapi`.
544
233
 
545
234
  ## Community
546
235
 
547
- - [GitHub Discussions](https://github.com/nano-step/nano-brain/discussions) — Ask questions, share ideas
548
- - [Discord](https://discord.gg/nano-brain) — Real-time chat
549
- - [Twitter](https://twitter.com/nano_brain) — Updates and announcements
550
-
551
- ---
236
+ [GitHub Discussions](https://github.com/nano-step/nano-brain/discussions) · [Discord](https://discord.gg/nano-brain)
552
237
 
553
238
  ## License
554
239
 
555
- MIT — see [LICENSE](LICENSE) for details.
556
-
557
- ---
558
-
559
- ## Acknowledgments
560
-
561
- Built with:
562
- - [Go](https://go.dev/) — Fast, statically typed language
563
- - [PostgreSQL](https://www.postgresql.org/) — The world's most advanced open source database
564
- - [pgvector](https://github.com/pgvector/pgvector) — Open-source vector similarity search
565
- - [Echo](https://echo.labstack.com/) — High performance, extensible, minimalist Go web framework
566
- - [sqlc](https://sqlc.dev/) — Generate type-safe code from SQL
567
- - [goose](https://github.com/pressly/goose) — Database migration tool
568
- - [zerolog](https://github.com/rs/zerolog) — Zero allocation JSON logger
569
- - [koanf](https://github.com/knadh/koanf) — Configuration manager
570
- - [fsnotify](https://github.com/fsnotify/fsnotify) — Cross-platform file system notifications
240
+ Licensed under the MIT License.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nano-step/nano-brain",
3
- "version": "2026.7.702",
3
+ "version": "2026.7.703",
4
4
  "description": "Persistent memory and code intelligence for AI coding agents",
5
5
  "bin": {
6
6
  "nano-brain": "npm/run.js"