neuralmemory 1.6.1 → 1.6.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 +139 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
# NeuralMemory — OpenClaw Plugin
|
|
2
|
+
|
|
3
|
+
Brain-inspired persistent memory for AI agents. Stores experiences as interconnected neurons and recalls them through spreading activation, mimicking how the human brain works.
|
|
4
|
+
|
|
5
|
+
This is the **OpenClaw plugin** for [Neural Memory](https://github.com/nhadaututheky/neural-memory).
|
|
6
|
+
|
|
7
|
+
## Prerequisites
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pip install neural-memory
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Python 3.11+ required. Verify the install:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
nmem-mcp --help
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Install
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npm install neuralmemory
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Or add to your OpenClaw config directly.
|
|
26
|
+
|
|
27
|
+
## OpenClaw Setup
|
|
28
|
+
|
|
29
|
+
Add to `~/.openclaw/openclaw.json`:
|
|
30
|
+
|
|
31
|
+
```json
|
|
32
|
+
{
|
|
33
|
+
"plugins": {
|
|
34
|
+
"slots": {
|
|
35
|
+
"memory": "neuralmemory"
|
|
36
|
+
},
|
|
37
|
+
"entries": {
|
|
38
|
+
"neuralmemory": {
|
|
39
|
+
"config": {
|
|
40
|
+
"pythonPath": "python",
|
|
41
|
+
"brain": "default",
|
|
42
|
+
"autoContext": true,
|
|
43
|
+
"autoCapture": true
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
> **Important**: Setting `slots.memory = "neuralmemory"` disables the default `memory-core` plugin. Without this, agents may still use `memory_search` instead of NeuralMemory tools.
|
|
52
|
+
|
|
53
|
+
## Tools
|
|
54
|
+
|
|
55
|
+
The plugin exposes 6 core tools to OpenClaw agents:
|
|
56
|
+
|
|
57
|
+
| Tool | Description |
|
|
58
|
+
|------|-------------|
|
|
59
|
+
| `nmem_remember` | Store a memory (auto-detects type: fact, decision, insight, etc.) |
|
|
60
|
+
| `nmem_recall` | Search memories via spreading activation |
|
|
61
|
+
| `nmem_context` | Get recent context for the current session |
|
|
62
|
+
| `nmem_todo` | Quick TODO shortcut |
|
|
63
|
+
| `nmem_stats` | Brain statistics (memory count, freshness) |
|
|
64
|
+
| `nmem_health` | Brain health diagnostics (purity score, warnings) |
|
|
65
|
+
|
|
66
|
+
## Configuration
|
|
67
|
+
|
|
68
|
+
| Option | Type | Default | Description |
|
|
69
|
+
|--------|------|---------|-------------|
|
|
70
|
+
| `pythonPath` | string | `"python"` | Python executable with `neural-memory` installed |
|
|
71
|
+
| `brain` | string | `"default"` | Brain name (each workspace can have its own) |
|
|
72
|
+
| `autoContext` | boolean | `true` | Auto-inject relevant memories before each agent run |
|
|
73
|
+
| `autoCapture` | boolean | `true` | Auto-extract memories after each agent run |
|
|
74
|
+
| `contextDepth` | integer | `1` | Recall depth: 0=instant, 1=context, 2=habits, 3=deep |
|
|
75
|
+
| `maxContextTokens` | integer | `500` | Max tokens for auto-context injection |
|
|
76
|
+
| `timeout` | integer | `30000` | MCP request timeout (ms) |
|
|
77
|
+
|
|
78
|
+
## How It Works
|
|
79
|
+
|
|
80
|
+
```
|
|
81
|
+
OpenClaw Agent
|
|
82
|
+
|
|
|
83
|
+
v
|
|
84
|
+
NeuralMemory Plugin (this package)
|
|
85
|
+
| Spawns + manages lifecycle
|
|
86
|
+
v
|
|
87
|
+
nmem-mcp (Python MCP server, stdio transport)
|
|
88
|
+
|
|
|
89
|
+
v
|
|
90
|
+
~/.neuralmemory/brains/<brain>.db (SQLite)
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
The plugin spawns `nmem-mcp` as a subprocess and communicates via JSON-RPC over stdio. Memories are stored in a local SQLite database.
|
|
94
|
+
|
|
95
|
+
## Troubleshooting
|
|
96
|
+
|
|
97
|
+
**Timeout on startup**: If you see `MCP timeout: initialize (30000ms)`, the Python process is slow to start. Fix:
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
# Pre-install to avoid cold start delays
|
|
101
|
+
pip install neural-memory
|
|
102
|
+
|
|
103
|
+
# Or increase the timeout in your config
|
|
104
|
+
"timeout": 60000
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
**"nmem-mcp not found"**: Ensure `neural-memory` is installed in the Python environment that `pythonPath` points to.
|
|
108
|
+
|
|
109
|
+
**Schema validation errors**: Upgrade to `neural-memory>=2.28.0` which fixes empty schema validation for strict JSON Schema validators.
|
|
110
|
+
|
|
111
|
+
## Full Feature Set
|
|
112
|
+
|
|
113
|
+
The underlying Neural Memory system provides 39 MCP tools including:
|
|
114
|
+
|
|
115
|
+
- Spreading activation recall (not keyword search)
|
|
116
|
+
- Memory maturation (STM -> Working -> Episodic -> Semantic)
|
|
117
|
+
- Trust scores with source-based ceiling caps
|
|
118
|
+
- Batch remember (up to 20 memories per call)
|
|
119
|
+
- Cognitive reasoning (hypotheses, evidence, predictions)
|
|
120
|
+
- Knowledge base training from PDF/DOCX/PPTX/HTML/JSON/CSV
|
|
121
|
+
- Multi-device sync with conflict resolution
|
|
122
|
+
- Fernet encryption for sensitive content
|
|
123
|
+
- React dashboard for visual brain exploration
|
|
124
|
+
|
|
125
|
+
Access the full toolset via [Claude Code](https://claude.com/claude-code) or any MCP-compatible client:
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
claude mcp add --scope user neural-memory -- nmem-mcp
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
## Links
|
|
132
|
+
|
|
133
|
+
- [Neural Memory on GitHub](https://github.com/nhadaututheky/neural-memory)
|
|
134
|
+
- [Neural Memory on PyPI](https://pypi.org/project/neural-memory/)
|
|
135
|
+
- [Documentation](https://nhadaututheky.github.io/neural-memory/)
|
|
136
|
+
|
|
137
|
+
## License
|
|
138
|
+
|
|
139
|
+
MIT
|