nexo-brain 0.3.1 → 0.3.2
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 +144 -70
- package/package.json +1 -1
- package/src/cognitive.py +37 -4
package/README.md
CHANGED
|
@@ -1,60 +1,66 @@
|
|
|
1
|
-
# NEXO — Your
|
|
1
|
+
# NEXO Brain — Your AI Gets a Brain
|
|
2
2
|
|
|
3
|
-
**NEXO transforms
|
|
3
|
+
**NEXO Brain transforms any MCP-compatible AI agent from a stateless assistant into a cognitive partner that remembers, learns, forgets, adapts, and builds a relationship with you over time.**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
[Watch the overview on YouTube](https://www.youtube.com/watch?v=-uvhicUhGTY)
|
|
6
|
+
|
|
7
|
+
Every time you close a session, everything is lost. Your agent doesn't remember yesterday's decisions, repeats the same mistakes, and starts from zero. NEXO Brain fixes this with a cognitive architecture modeled after how human memory actually works.
|
|
6
8
|
|
|
7
9
|
## The Problem
|
|
8
10
|
|
|
9
|
-
|
|
11
|
+
AI coding agents are powerful but amnesic:
|
|
10
12
|
- **No memory** — closes a session, forgets everything
|
|
11
13
|
- **Repeats mistakes** — makes the same error you corrected yesterday
|
|
12
14
|
- **No context** — can't connect today's work with last week's decisions
|
|
13
15
|
- **Reactive** — waits for instructions instead of anticipating needs
|
|
14
16
|
- **No learning** — doesn't improve from experience
|
|
17
|
+
- **No safety** — stores anything it's told, including poisoned or redundant data
|
|
15
18
|
|
|
16
19
|
## The Solution: A Cognitive Architecture
|
|
17
20
|
|
|
18
|
-
NEXO implements the **Atkinson-Shiffrin memory model** from cognitive psychology (1968) — the same model that explains how human memory works:
|
|
21
|
+
NEXO Brain implements the **Atkinson-Shiffrin memory model** from cognitive psychology (1968) — the same model that explains how human memory works:
|
|
19
22
|
|
|
20
23
|
```
|
|
21
24
|
What you say and do
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
25
|
+
|
|
|
26
|
+
+---> Sensory Register (raw capture, 48h)
|
|
27
|
+
| |
|
|
28
|
+
| +---> Attention filter: "Is this worth remembering?"
|
|
29
|
+
| |
|
|
30
|
+
| v
|
|
31
|
+
+---> Short-Term Memory (7-day half-life)
|
|
32
|
+
| |
|
|
33
|
+
| +---> Used often? --> Consolidate to Long-Term Memory
|
|
34
|
+
| +---> Not accessed? --> Gradually forgotten
|
|
35
|
+
|
|
|
36
|
+
+---> Long-Term Memory (60-day half-life)
|
|
37
|
+
|
|
|
38
|
+
+---> Active: instantly searchable by meaning
|
|
39
|
+
+---> Dormant: faded but recoverable ("oh right, I remember now!")
|
|
40
|
+
+---> Near-duplicates auto-merged to prevent clutter
|
|
38
41
|
```
|
|
39
42
|
|
|
40
|
-
This isn't a metaphor. NEXO literally implements Ebbinghaus forgetting curves, rehearsal-based reinforcement, and memory consolidation during automated "sleep" processes.
|
|
43
|
+
This isn't a metaphor. NEXO Brain literally implements Ebbinghaus forgetting curves, rehearsal-based reinforcement, and memory consolidation during automated "sleep" processes.
|
|
41
44
|
|
|
42
|
-
## What Makes NEXO Different
|
|
45
|
+
## What Makes NEXO Brain Different
|
|
43
46
|
|
|
44
|
-
| Without NEXO | With NEXO |
|
|
45
|
-
|
|
47
|
+
| Without NEXO Brain | With NEXO Brain |
|
|
48
|
+
|---------------------|-----------------|
|
|
46
49
|
| Memory gone after each session | Persistent across sessions with natural decay and reinforcement |
|
|
47
50
|
| Repeats the same mistakes | Checks "have I made this mistake before?" before every action |
|
|
48
51
|
| Keyword search only | Finds memories by **meaning**, not just words |
|
|
49
52
|
| Starts cold every time | Resumes from the mental state of the last session |
|
|
50
53
|
| Same behavior regardless of context | Adapts tone and approach based on your mood |
|
|
51
54
|
| No relationship | Trust score that evolves — makes fewer redundant checks as alignment grows |
|
|
55
|
+
| Stores everything blindly | Prediction error gating rejects redundant information at write time |
|
|
56
|
+
| Vulnerable to memory poisoning | 4-layer security pipeline scans every memory before storage |
|
|
57
|
+
| No proactive behavior | Context-triggered reminders fire when topics match, not just by date |
|
|
52
58
|
|
|
53
59
|
## How the Brain Works
|
|
54
60
|
|
|
55
61
|
### Memory That Forgets (And That's a Feature)
|
|
56
62
|
|
|
57
|
-
NEXO uses **Ebbinghaus forgetting curves** — memories naturally fade over time unless reinforced by use. This isn't a bug, it's how useful memory works:
|
|
63
|
+
NEXO Brain uses **Ebbinghaus forgetting curves** — memories naturally fade over time unless reinforced by use. This isn't a bug, it's how useful memory works:
|
|
58
64
|
|
|
59
65
|
- A lesson learned yesterday is strong. If you never encounter it again, it fades — because it probably wasn't important.
|
|
60
66
|
- A lesson accessed 5 times in 2 weeks gets promoted to long-term memory — because repeated use proves it matters.
|
|
@@ -62,19 +68,19 @@ NEXO uses **Ebbinghaus forgetting curves** — memories naturally fade over time
|
|
|
62
68
|
|
|
63
69
|
### Semantic Search (Finding by Meaning)
|
|
64
70
|
|
|
65
|
-
NEXO doesn't search by keywords. It searches by **meaning** using vector embeddings (fastembed, 384 dimensions).
|
|
71
|
+
NEXO Brain doesn't search by keywords. It searches by **meaning** using vector embeddings (fastembed, 384 dimensions).
|
|
66
72
|
|
|
67
|
-
Example: If you search for "deploy problems", NEXO will find a memory about "SSH connection timeout on production server" — even though they share zero words. This is how human associative memory works.
|
|
73
|
+
Example: If you search for "deploy problems", NEXO Brain will find a memory about "SSH connection timeout on production server" — even though they share zero words. This is how human associative memory works.
|
|
68
74
|
|
|
69
75
|
### Metacognition (Thinking About Thinking)
|
|
70
76
|
|
|
71
|
-
Before every code change, NEXO asks itself: **"Have I made a mistake like this before?"**
|
|
77
|
+
Before every code change, NEXO Brain asks itself: **"Have I made a mistake like this before?"**
|
|
72
78
|
|
|
73
79
|
It searches its memory for related errors, warnings, and lessons learned. If it finds something relevant, it surfaces the warning BEFORE acting — not after you've already broken production.
|
|
74
80
|
|
|
75
81
|
### Cognitive Dissonance
|
|
76
82
|
|
|
77
|
-
When you give an instruction that contradicts
|
|
83
|
+
When you give an instruction that contradicts established knowledge, NEXO Brain doesn't silently obey or silently resist. It **verbalizes the conflict**:
|
|
78
84
|
|
|
79
85
|
> "My memory says you prefer Tailwind over plain CSS, but you're asking me to write inline styles. Is this a permanent change or a one-time exception?"
|
|
80
86
|
|
|
@@ -82,42 +88,80 @@ You decide: **paradigm shift** (permanent change), **exception** (one-time), or
|
|
|
82
88
|
|
|
83
89
|
### Sibling Memories
|
|
84
90
|
|
|
85
|
-
Some memories look identical but apply to different contexts. "How to deploy" for Project A is different from Project B. NEXO detects discriminating entities (different OS, platform, language) and links them as **siblings** instead of merging them:
|
|
91
|
+
Some memories look identical but apply to different contexts. "How to deploy" for Project A is different from Project B. NEXO Brain detects discriminating entities (different OS, platform, language) and links them as **siblings** instead of merging them:
|
|
86
92
|
|
|
87
93
|
> "Applying the Linux deploy procedure. Note: there's a sibling for macOS that uses a different port."
|
|
88
94
|
|
|
89
95
|
### Trust Score (0-100)
|
|
90
96
|
|
|
91
|
-
NEXO tracks alignment with you through a trust score:
|
|
97
|
+
NEXO Brain tracks alignment with you through a trust score:
|
|
92
98
|
|
|
93
|
-
- **You say thanks**
|
|
94
|
-
- **
|
|
95
|
-
- **The score doesn't control permissions** — you're always in control. It's a mirror that helps
|
|
99
|
+
- **You say thanks** --> score goes up --> reduces redundant verification checks
|
|
100
|
+
- **Makes a mistake you already taught it** --> score drops --> becomes more careful, checks more thoroughly
|
|
101
|
+
- **The score doesn't control permissions** — you're always in control. It's a mirror that helps calibrate rigor.
|
|
96
102
|
|
|
97
103
|
### Sentiment Detection
|
|
98
104
|
|
|
99
|
-
NEXO reads your tone (keywords, message length, urgency signals) and adapts:
|
|
105
|
+
NEXO Brain reads your tone (keywords, message length, urgency signals) and adapts:
|
|
100
106
|
|
|
101
|
-
- **Frustrated?**
|
|
102
|
-
- **In flow?**
|
|
103
|
-
- **Urgent?**
|
|
107
|
+
- **Frustrated?** --> Ultra-concise mode. Zero explanations. Just solve the problem.
|
|
108
|
+
- **In flow?** --> Good moment to suggest that backlog item from last Tuesday.
|
|
109
|
+
- **Urgent?** --> Immediate action, no preamble.
|
|
104
110
|
|
|
105
111
|
### Sleep Cycle
|
|
106
112
|
|
|
107
|
-
Like a human brain, NEXO has automated processes that run while you're not using it:
|
|
113
|
+
Like a human brain, NEXO Brain has automated processes that run while you're not using it:
|
|
108
114
|
|
|
109
115
|
| Time | Process | Human Analogy |
|
|
110
116
|
|------|---------|---------------|
|
|
111
|
-
| 03:00 | Decay + memory consolidation + merge duplicates | Deep sleep consolidation |
|
|
117
|
+
| 03:00 | Decay + memory consolidation + merge duplicates + dreaming | Deep sleep consolidation |
|
|
112
118
|
| 04:00 | Clean expired data, prune redundant memories | Synaptic pruning |
|
|
113
119
|
| 07:00 | Self-audit, health checks, metrics | Waking up + orientation |
|
|
114
120
|
| 23:30 | Process day's events, extract patterns | Pre-sleep reflection |
|
|
115
|
-
| Boot | Catch-up: run anything missed while computer was off |
|
|
121
|
+
| Boot | Catch-up: run anything missed while computer was off | -- |
|
|
122
|
+
|
|
123
|
+
If your Mac was asleep during any scheduled process, NEXO Brain catches up in order when it wakes.
|
|
124
|
+
|
|
125
|
+
## Cognitive Features (v0.3.1)
|
|
126
|
+
|
|
127
|
+
NEXO Brain v0.3.1 adds 21 cognitive tools on top of the 76 base tools, bringing the total to **97+ MCP tools**. These features implement cognitive science concepts that go beyond basic memory:
|
|
128
|
+
|
|
129
|
+
### Input Pipeline
|
|
130
|
+
|
|
131
|
+
| Feature | What It Does |
|
|
132
|
+
|---------|-------------|
|
|
133
|
+
| **Prediction Error Gating** | Only novel information is stored. Redundant content that matches existing memories is rejected at write time, keeping your memory clean without manual curation. |
|
|
134
|
+
| **Security Pipeline** | 4-layer defense against memory poisoning: injection detection, encoding analysis, behavioral anomaly scoring, and credential scanning. Every memory passes through all four layers before storage. |
|
|
135
|
+
| **Quarantine Queue** | New facts enter quarantine status and must pass a promotion policy before becoming trusted knowledge. Prevents unverified information from influencing decisions. |
|
|
136
|
+
| **Secret Redaction** | Auto-detects and redacts API keys, tokens, passwords, and other sensitive data before storage. Secrets never reach the vector database. |
|
|
137
|
+
|
|
138
|
+
### Memory Management
|
|
116
139
|
|
|
117
|
-
|
|
140
|
+
| Feature | What It Does |
|
|
141
|
+
|---------|-------------|
|
|
142
|
+
| **Pin / Snooze / Archive** | Granular lifecycle states for memories. Pin = never decays (critical knowledge). Snooze = temporarily hidden (revisit later). Archive = cold storage (searchable but inactive). |
|
|
143
|
+
| **Auto-Merge Duplicates** | Batch cosine deduplication during the 03:00 sleep cycle. Respects sibling discrimination — similar memories about different contexts are kept separate. |
|
|
144
|
+
| **Memory Dreaming** | Discovers hidden connections between recent memories during the 03:00 sleep cycle. Surfaces non-obvious patterns like "these three bugs all relate to the same root cause." |
|
|
145
|
+
|
|
146
|
+
### Retrieval
|
|
147
|
+
|
|
148
|
+
| Feature | What It Does |
|
|
149
|
+
|---------|-------------|
|
|
150
|
+
| **HyDE Query Expansion** | Generates hypothetical answer embeddings for richer semantic search. Instead of searching for "deploy error", it imagines what a helpful memory about deploy errors would look like, then searches for that. |
|
|
151
|
+
| **Spreading Activation** | Graph-based co-activation network. Memories retrieved together reinforce each other's connections, building an associative web that improves over time. |
|
|
152
|
+
| **Recall Explanations** | Transparent score breakdown for every retrieval result. Shows exactly why a memory was returned: semantic similarity, recency, access frequency, and co-activation bonuses. |
|
|
153
|
+
|
|
154
|
+
### Proactive
|
|
155
|
+
|
|
156
|
+
| Feature | What It Does |
|
|
157
|
+
|---------|-------------|
|
|
158
|
+
| **Prospective Memory** | Context-triggered reminders that fire when conversation topics match, not just by date. "Remind me about X when we discuss Y" works naturally. |
|
|
159
|
+
| **Hook Auto-capture** | Extracts decisions, corrections, and factual statements from conversations automatically. You don't need to explicitly say "remember this" — the system detects what's worth storing. |
|
|
118
160
|
|
|
119
161
|
## Quick Start
|
|
120
162
|
|
|
163
|
+
### Claude Code (Primary)
|
|
164
|
+
|
|
121
165
|
```bash
|
|
122
166
|
npx nexo-brain
|
|
123
167
|
```
|
|
@@ -136,15 +180,15 @@ The installer handles everything:
|
|
|
136
180
|
Scanning workspace...
|
|
137
181
|
- 3 git repositories
|
|
138
182
|
- Node.js project detected
|
|
139
|
-
Configuring
|
|
183
|
+
Configuring MCP server...
|
|
140
184
|
Setting up automated processes...
|
|
141
185
|
5 automated processes configured.
|
|
142
186
|
Caffeinate enabled.
|
|
143
187
|
Generating operator instructions...
|
|
144
188
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
189
|
+
+----------------------------------------------------------+
|
|
190
|
+
| Atlas is ready. Type 'atlas' to start. |
|
|
191
|
+
+----------------------------------------------------------+
|
|
148
192
|
```
|
|
149
193
|
|
|
150
194
|
### Starting a Session
|
|
@@ -162,7 +206,7 @@ That's it. No need to run `claude` manually. Atlas will greet you immediately
|
|
|
162
206
|
| Component | What | Where |
|
|
163
207
|
|-----------|------|-------|
|
|
164
208
|
| Cognitive engine | Python: fastembed, numpy, vector search | pip packages |
|
|
165
|
-
| MCP server |
|
|
209
|
+
| MCP server | 97+ tools for memory, cognition, learning, guard | ~/.nexo/ |
|
|
166
210
|
| Plugins | Guard, episodic memory, cognitive memory, entities, preferences | ~/.nexo/plugins/ |
|
|
167
211
|
| Hooks | Session capture, briefing, stop detection | ~/.nexo/hooks/ |
|
|
168
212
|
| LaunchAgents | Decay, sleep, audit, postmortem, catch-up | ~/Library/LaunchAgents/ |
|
|
@@ -173,16 +217,18 @@ That's it. No need to run `claude` manually. Atlas will greet you immediately
|
|
|
173
217
|
|
|
174
218
|
- **macOS** (Linux support planned)
|
|
175
219
|
- **Node.js 18+** (for the installer)
|
|
176
|
-
- **Claude Opus (latest version) strongly recommended.** NEXO provides
|
|
220
|
+
- **Claude Opus (latest version) strongly recommended.** NEXO Brain provides 97+ MCP tools across 17 categories. This cognitive load requires a top-tier model with large context window. Smaller models (Haiku, Sonnet) may struggle with tool selection and produce inconsistent results. Opus handles all 97+ tools without hesitation.
|
|
177
221
|
- Python 3, Homebrew, and Claude Code are installed automatically if missing.
|
|
178
222
|
|
|
179
223
|
## Architecture
|
|
180
224
|
|
|
181
|
-
###
|
|
225
|
+
### 97+ MCP Tools across 17 Categories
|
|
182
226
|
|
|
183
227
|
| Category | Count | Tools | Purpose |
|
|
184
228
|
|----------|-------|-------|---------|
|
|
185
229
|
| Cognitive | 8 | retrieve, stats, inspect, metrics, dissonance, resolve, sentiment, trust | The brain — memory, RAG, trust, mood |
|
|
230
|
+
| Cognitive Input | 5 | prediction_gate, security_scan, quarantine, promote, redact | Input pipeline — gating, security, quarantine |
|
|
231
|
+
| Cognitive Advanced | 8 | hyde_search, spread_activate, explain_recall, dream, prospect, hook_capture, pin, archive | Advanced retrieval, proactive, lifecycle |
|
|
186
232
|
| Guard | 3 | check, stats, log_repetition | Metacognitive error prevention |
|
|
187
233
|
| Episodic | 10 | change_log/search/commit, decision_log/outcome/search, review_queue, diary_write/read, recall | What happened and why |
|
|
188
234
|
| Sessions | 4 | startup, heartbeat, stop, status | Session lifecycle + context shift detection |
|
|
@@ -201,7 +247,7 @@ That's it. No need to run `claude` manually. Atlas will greet you immediately
|
|
|
201
247
|
|
|
202
248
|
### Plugin System
|
|
203
249
|
|
|
204
|
-
NEXO supports hot-loadable plugins. Drop a `.py` file in `~/.nexo/plugins/`:
|
|
250
|
+
NEXO Brain supports hot-loadable plugins. Drop a `.py` file in `~/.nexo/plugins/`:
|
|
205
251
|
|
|
206
252
|
```python
|
|
207
253
|
# my_plugin.py
|
|
@@ -222,28 +268,46 @@ Reload without restarting: `nexo_plugin_load("my_plugin.py")`
|
|
|
222
268
|
- **No telemetry.** No analytics. No phone-home.
|
|
223
269
|
- **No cloud dependencies.** Vector search runs on CPU (fastembed), not an API.
|
|
224
270
|
- **Auto-update is opt-in.** Checks GitHub releases, never sends data.
|
|
271
|
+
- **Secret redaction.** API keys and tokens are stripped before they ever reach memory storage.
|
|
225
272
|
|
|
226
|
-
## The Psychology Behind NEXO
|
|
273
|
+
## The Psychology Behind NEXO Brain
|
|
227
274
|
|
|
228
|
-
NEXO isn't just engineering — it's applied cognitive psychology:
|
|
275
|
+
NEXO Brain isn't just engineering — it's applied cognitive psychology:
|
|
229
276
|
|
|
230
|
-
| Psychological Concept | How NEXO Implements It |
|
|
277
|
+
| Psychological Concept | How NEXO Brain Implements It |
|
|
231
278
|
|----------------------|----------------------|
|
|
232
|
-
| Atkinson-Shiffrin (1968) | Three memory stores: sensory register
|
|
233
|
-
| Ebbinghaus Forgetting Curve (1885) | Exponential decay: `strength = strength
|
|
279
|
+
| Atkinson-Shiffrin (1968) | Three memory stores: sensory register --> STM --> LTM |
|
|
280
|
+
| Ebbinghaus Forgetting Curve (1885) | Exponential decay: `strength = strength * e^(-lambda * time)` |
|
|
234
281
|
| Rehearsal Effect | Accessing a memory resets its strength to 1.0 |
|
|
235
282
|
| Memory Consolidation | Nightly process promotes frequently-used STM to LTM |
|
|
283
|
+
| Prediction Error | Only surprising (novel) information gets stored — redundant input is gated |
|
|
284
|
+
| Spreading Activation (Collins & Loftus, 1975) | Retrieving a memory co-activates related memories through an associative graph |
|
|
285
|
+
| HyDE (Gao et al., 2022) | Hypothetical document embeddings improve semantic recall |
|
|
286
|
+
| Prospective Memory (Einstein & McDaniel, 1990) | Context-triggered intentions fire when cue conditions match |
|
|
236
287
|
| Metacognition | Guard system checks past errors before acting |
|
|
237
|
-
| Cognitive Dissonance | Detects and verbalizes conflicts between old and new knowledge |
|
|
288
|
+
| Cognitive Dissonance (Festinger, 1957) | Detects and verbalizes conflicts between old and new knowledge |
|
|
238
289
|
| Theory of Mind | Models user behavior, preferences, and mood |
|
|
239
290
|
| Synaptic Pruning | Automated cleanup of weak, unused memories |
|
|
240
291
|
| Associative Memory | Semantic search finds related concepts, not just matching words |
|
|
292
|
+
| Memory Reconsolidation | Dreaming process discovers hidden connections during sleep |
|
|
293
|
+
|
|
294
|
+
## Integrations
|
|
295
|
+
|
|
296
|
+
### Claude Code (Primary)
|
|
241
297
|
|
|
242
|
-
|
|
298
|
+
NEXO Brain is designed as an MCP server. Claude Code is the primary supported client:
|
|
243
299
|
|
|
244
|
-
|
|
300
|
+
```bash
|
|
301
|
+
npx nexo-brain
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
All 97+ tools are available immediately after installation. The installer configures Claude Code's `~/.claude/settings.json` automatically.
|
|
245
305
|
|
|
246
|
-
###
|
|
306
|
+
### OpenClaw
|
|
307
|
+
|
|
308
|
+
NEXO Brain also works as a cognitive memory backend for [OpenClaw](https://github.com/openclaw/openclaw):
|
|
309
|
+
|
|
310
|
+
#### MCP Bridge (Zero Code)
|
|
247
311
|
|
|
248
312
|
Add NEXO Brain to your OpenClaw config at `~/.openclaw/openclaw.json`:
|
|
249
313
|
|
|
@@ -270,24 +334,18 @@ openclaw mcp set nexo-brain '{"command":"python3","args":["~/.nexo/src/server.py
|
|
|
270
334
|
openclaw gateway restart
|
|
271
335
|
```
|
|
272
336
|
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
> **First time?** Run `npx nexo-brain` first to install the cognitive engine and dependencies.
|
|
276
|
-
|
|
277
|
-
### Path 2: ClawHub Skill (Install in Seconds)
|
|
337
|
+
#### ClawHub Skill
|
|
278
338
|
|
|
279
339
|
```bash
|
|
280
340
|
npx clawhub@latest install nexo-brain
|
|
281
341
|
```
|
|
282
342
|
|
|
283
|
-
|
|
343
|
+
#### Native Memory Plugin
|
|
284
344
|
|
|
285
345
|
```bash
|
|
286
346
|
npm install @wazionapps/openclaw-memory-nexo-brain
|
|
287
347
|
```
|
|
288
348
|
|
|
289
|
-
Configure in `~/.openclaw/openclaw.json`:
|
|
290
|
-
|
|
291
349
|
```json
|
|
292
350
|
{
|
|
293
351
|
"plugins": {
|
|
@@ -298,7 +356,11 @@ Configure in `~/.openclaw/openclaw.json`:
|
|
|
298
356
|
}
|
|
299
357
|
```
|
|
300
358
|
|
|
301
|
-
This replaces OpenClaw's default memory system with NEXO's full cognitive architecture
|
|
359
|
+
This replaces OpenClaw's default memory system with NEXO Brain's full cognitive architecture.
|
|
360
|
+
|
|
361
|
+
### Any MCP Client
|
|
362
|
+
|
|
363
|
+
NEXO Brain works with any application that supports the MCP protocol. Configure it as an MCP server pointing to `~/.nexo/src/server.py`.
|
|
302
364
|
|
|
303
365
|
## Listed On
|
|
304
366
|
|
|
@@ -312,13 +374,25 @@ This replaces OpenClaw's default memory system with NEXO's full cognitive archit
|
|
|
312
374
|
| dev.to | Technical Article | [How I Applied Cognitive Psychology to AI Agents](https://dev.to/wazionapps/how-i-applied-cognitive-psychology-to-give-ai-agents-real-memory-2oce) |
|
|
313
375
|
| nexo-brain.com | Official Website | [nexo-brain.com](https://nexo-brain.com) |
|
|
314
376
|
|
|
377
|
+
## Inspired By
|
|
378
|
+
|
|
379
|
+
NEXO Brain builds on ideas from several open-source projects. We're grateful for the research and implementations that inspired specific features:
|
|
380
|
+
|
|
381
|
+
| Project | Inspired Features |
|
|
382
|
+
|---------|------------------|
|
|
383
|
+
| [Vestige](https://github.com/pchaganti/gx-vestige) | HyDE query expansion, spreading activation, prediction error gating, memory dreaming, prospective memory |
|
|
384
|
+
| [ShieldCortex](https://github.com/PShieldCortex/ShieldCortex) | Security pipeline (4-layer memory poisoning defense) |
|
|
385
|
+
| [Bicameral](https://github.com/nicobailey/Bicameral) | Quarantine queue (trust promotion policy for new facts) |
|
|
386
|
+
| [claude-mem](https://github.com/nicobailey/claude-mem) | Hook auto-capture (extracting decisions and facts from conversations) |
|
|
387
|
+
| [ClawMem](https://github.com/nicobailey/ClawMem) | Co-activation reinforcement (memories retrieved together strengthen connections) |
|
|
388
|
+
|
|
315
389
|
## Contributing
|
|
316
390
|
|
|
317
391
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Issues and PRs welcome.
|
|
318
392
|
|
|
319
393
|
## License
|
|
320
394
|
|
|
321
|
-
MIT
|
|
395
|
+
MIT -- see [LICENSE](LICENSE)
|
|
322
396
|
|
|
323
397
|
---
|
|
324
398
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "nexo-brain",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.2",
|
|
4
4
|
"mcpName": "io.github.wazionapps/nexo",
|
|
5
5
|
"description": "NEXO — Cognitive co-operator for Claude Code. Atkinson-Shiffrin memory, semantic RAG, trust scoring, and metacognitive error prevention.",
|
|
6
6
|
"bin": {
|
package/src/cognitive.py
CHANGED
|
@@ -52,6 +52,10 @@ NEGATIVE_SIGNALS = {
|
|
|
52
52
|
"cansad", "siempre", "nunca", "por qué no", "no funciona", "roto",
|
|
53
53
|
"no sirve", "horrible", "desastre", "qué coño", "joder", "mierda",
|
|
54
54
|
"hostia", "me cago", "irritad", "harto",
|
|
55
|
+
"broken", "nothing works", "doesn't work", "not working", "fix it",
|
|
56
|
+
"wrong", "failed", "failing", "annoying", "frustrated", "damn", "shit",
|
|
57
|
+
"wtf", "terrible", "useless", "stupid", "hate", "worst", "sucks",
|
|
58
|
+
"again",
|
|
55
59
|
}
|
|
56
60
|
URGENCY_SIGNALS = {
|
|
57
61
|
"rápido", "ya", "ahora", "urgente", "asap", "inmediatamente", "corre",
|
|
@@ -80,12 +84,12 @@ _conn = None
|
|
|
80
84
|
_REDACT_PATTERNS = [
|
|
81
85
|
# Specific API key formats
|
|
82
86
|
(re.compile(r'sk-[a-zA-Z0-9_\-]{20,}'), '[REDACTED:api_key]'),
|
|
83
|
-
(re.compile(r'ghp_[a-zA-Z0-9]{
|
|
84
|
-
(re.compile(r'shpat_[a-f0-9]{
|
|
87
|
+
(re.compile(r'ghp_[a-zA-Z0-9]{20,}'), '[REDACTED:api_key]'),
|
|
88
|
+
(re.compile(r'shpat_[a-f0-9]{20,}'), '[REDACTED:api_key]'),
|
|
85
89
|
(re.compile(r'AKIA[A-Z0-9]{16}'), '[REDACTED:api_key]'),
|
|
86
90
|
(re.compile(r'xox[bp]-[a-zA-Z0-9\-]{20,}'), '[REDACTED:api_key]'),
|
|
87
91
|
# Bearer tokens
|
|
88
|
-
(re.compile(r'Bearer\s+[a-zA-Z0-9_
|
|
92
|
+
(re.compile(r'Bearer\s+[a-zA-Z0-9_\-\.=+/]{20,}'), '[REDACTED:bearer_token]'),
|
|
89
93
|
# Connection strings with credentials
|
|
90
94
|
(re.compile(r'(mysql|postgresql|postgres|mongodb|redis)://[^\s"\']+@[^\s"\']+'), '[REDACTED:connection_string]'),
|
|
91
95
|
# Generic token assignments
|
|
@@ -780,13 +784,42 @@ def search(
|
|
|
780
784
|
|
|
781
785
|
if neighbor_boosts:
|
|
782
786
|
co_activation_applied = True
|
|
787
|
+
# Boost existing results that are neighbors
|
|
788
|
+
existing_hashes = set()
|
|
783
789
|
for r in results:
|
|
784
790
|
co_hash = _canonical_co_id(r["store"], r["id"])
|
|
791
|
+
existing_hashes.add(co_hash)
|
|
785
792
|
if co_hash in neighbor_boosts:
|
|
786
793
|
boost = neighbor_boosts[co_hash]
|
|
787
794
|
r["score"] = min(1.0, r["score"] + boost)
|
|
788
795
|
r["co_activation_boost"] = boost
|
|
789
796
|
|
|
797
|
+
# Add neighbor memories not already in results
|
|
798
|
+
new_neighbor_hashes = set(neighbor_boosts.keys()) - existing_hashes
|
|
799
|
+
if new_neighbor_hashes:
|
|
800
|
+
for store_name, table in [("stm", "stm_memories"), ("ltm", "ltm_memories")]:
|
|
801
|
+
rows = db.execute(f"SELECT * FROM {table}").fetchall()
|
|
802
|
+
for row in rows:
|
|
803
|
+
nh = _canonical_co_id(store_name, row["id"])
|
|
804
|
+
if nh in new_neighbor_hashes:
|
|
805
|
+
boost = neighbor_boosts[nh]
|
|
806
|
+
results.append({
|
|
807
|
+
"store": store_name,
|
|
808
|
+
"id": row["id"],
|
|
809
|
+
"content": row["content"],
|
|
810
|
+
"source_type": row.get("source_type", ""),
|
|
811
|
+
"source_id": row.get("source_id", ""),
|
|
812
|
+
"tags": row.get("tags", ""),
|
|
813
|
+
"domain": row.get("domain", ""),
|
|
814
|
+
"created_at": row.get("created_at", ""),
|
|
815
|
+
"strength": row.get("strength", 0.0),
|
|
816
|
+
"access_count": row.get("access_count", 0),
|
|
817
|
+
"score": min(1.0, boost),
|
|
818
|
+
"co_activation_boost": boost,
|
|
819
|
+
"lifecycle_state": row.get("lifecycle_state", "active"),
|
|
820
|
+
})
|
|
821
|
+
new_neighbor_hashes.discard(nh)
|
|
822
|
+
|
|
790
823
|
# Re-sort after applying boosts
|
|
791
824
|
results.sort(key=lambda x: x["score"], reverse=True)
|
|
792
825
|
|
|
@@ -881,7 +914,7 @@ def ingest(
|
|
|
881
914
|
# Security scan BEFORE prediction error gate (adapted from ShieldCortex pipeline)
|
|
882
915
|
if not bypass_security:
|
|
883
916
|
scan = security_scan(content)
|
|
884
|
-
if scan["risk_score"]
|
|
917
|
+
if scan["risk_score"] >= 0.8:
|
|
885
918
|
# High risk — reject with reason logged
|
|
886
919
|
return 0
|
|
887
920
|
if scan["sanitized_content"] != content:
|