neural-memory-pro 0.2.0__tar.gz
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.
- neural_memory_pro-0.2.0/.github/workflows/ci.yml +29 -0
- neural_memory_pro-0.2.0/.github/workflows/publish.yml +28 -0
- neural_memory_pro-0.2.0/.gitignore +19 -0
- neural_memory_pro-0.2.0/CHANGELOG.md +48 -0
- neural_memory_pro-0.2.0/PKG-INFO +195 -0
- neural_memory_pro-0.2.0/README.md +177 -0
- neural_memory_pro-0.2.0/benchmarks/results/stress_test_20260322_215132.json +152 -0
- neural_memory_pro-0.2.0/benchmarks/results/stress_test_20260322_215538.json +236 -0
- neural_memory_pro-0.2.0/benchmarks/stress_test.py +614 -0
- neural_memory_pro-0.2.0/benchmarks/stress_test_output.log +244 -0
- neural_memory_pro-0.2.0/pyproject.toml +48 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/__init__.py +33 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/consolidation/__init__.py +0 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/consolidation/smart_merge.py +198 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/hyperspace/__init__.py +0 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/hyperspace/directional_compress.py +135 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/infinitydb/__init__.py +29 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/infinitydb/compressor.py +196 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/infinitydb/engine.py +982 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/infinitydb/fiber_store.py +227 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/infinitydb/file_format.py +122 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/infinitydb/graph_store.py +327 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/infinitydb/hnsw_index.py +173 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/infinitydb/metadata_store.py +215 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/infinitydb/migrator.py +441 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/infinitydb/query_planner.py +271 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/infinitydb/tier_manager.py +233 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/infinitydb/vector_store.py +214 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/infinitydb/wal.py +241 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/mcp_tools.py +229 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/plugin.py +56 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/retrieval/__init__.py +0 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/retrieval/cone_queries.py +93 -0
- neural_memory_pro-0.2.0/src/neural_memory_pro/storage_adapter.py +629 -0
- neural_memory_pro-0.2.0/tests/test_compression_integration.py +308 -0
- neural_memory_pro-0.2.0/tests/test_infinitydb_compression.py +327 -0
- neural_memory_pro-0.2.0/tests/test_infinitydb_core.py +484 -0
- neural_memory_pro-0.2.0/tests/test_infinitydb_graph.py +704 -0
- neural_memory_pro-0.2.0/tests/test_infinitydb_migration.py +636 -0
- neural_memory_pro-0.2.0/tests/test_infinitydb_query.py +347 -0
- neural_memory_pro-0.2.0/tests/test_infinitydb_wal.py +236 -0
- neural_memory_pro-0.2.0/tests/test_mcp_tools.py +54 -0
- neural_memory_pro-0.2.0/tests/test_plugin.py +32 -0
- neural_memory_pro-0.2.0/tests/test_pro_features.py +292 -0
- neural_memory_pro-0.2.0/tests/test_storage_adapter.py +422 -0
- neural_memory_pro-0.2.0/tests/test_wal_integration.py +458 -0
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
branches: [main]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
lint:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
steps:
|
|
13
|
+
- uses: actions/checkout@v4
|
|
14
|
+
- uses: actions/setup-python@v5
|
|
15
|
+
with:
|
|
16
|
+
python-version: "3.11"
|
|
17
|
+
- run: pip install ruff
|
|
18
|
+
- run: ruff check src/
|
|
19
|
+
- run: ruff format --check src/
|
|
20
|
+
|
|
21
|
+
test:
|
|
22
|
+
runs-on: ubuntu-latest
|
|
23
|
+
steps:
|
|
24
|
+
- uses: actions/checkout@v4
|
|
25
|
+
- uses: actions/setup-python@v5
|
|
26
|
+
with:
|
|
27
|
+
python-version: "3.11"
|
|
28
|
+
- run: pip install -e ".[dev]"
|
|
29
|
+
- run: pytest tests/ -v --timeout=60
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
name: Publish to PyPI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
tags:
|
|
6
|
+
- "v*"
|
|
7
|
+
|
|
8
|
+
permissions:
|
|
9
|
+
id-token: write
|
|
10
|
+
|
|
11
|
+
jobs:
|
|
12
|
+
publish:
|
|
13
|
+
runs-on: ubuntu-latest
|
|
14
|
+
environment: pypi
|
|
15
|
+
steps:
|
|
16
|
+
- uses: actions/checkout@v4
|
|
17
|
+
|
|
18
|
+
- uses: actions/setup-python@v5
|
|
19
|
+
with:
|
|
20
|
+
python-version: "3.11"
|
|
21
|
+
|
|
22
|
+
- name: Build
|
|
23
|
+
run: |
|
|
24
|
+
pip install build
|
|
25
|
+
python -m build
|
|
26
|
+
|
|
27
|
+
- name: Publish to PyPI
|
|
28
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
__pycache__/
|
|
2
|
+
*.py[cod]
|
|
3
|
+
*$py.class
|
|
4
|
+
*.egg-info/
|
|
5
|
+
dist/
|
|
6
|
+
build/
|
|
7
|
+
.eggs/
|
|
8
|
+
*.egg
|
|
9
|
+
.mypy_cache/
|
|
10
|
+
.ruff_cache/
|
|
11
|
+
.pytest_cache/
|
|
12
|
+
.venv/
|
|
13
|
+
venv/
|
|
14
|
+
*.db
|
|
15
|
+
*.sqlite
|
|
16
|
+
.env
|
|
17
|
+
|
|
18
|
+
# Benchmark binary data (multi-GB InfinityDB files)
|
|
19
|
+
benchmarks/data/
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to Neural Memory Pro are documented here.
|
|
4
|
+
|
|
5
|
+
## [0.2.0] - 2026-03-23
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
- **InfinityDB Engine** — Custom multi-dimensional spatial database
|
|
9
|
+
- HNSW approximate nearest neighbor search (hnswlib)
|
|
10
|
+
- Memory-mapped vector store (numpy)
|
|
11
|
+
- Graph store with adjacency lists (msgpack)
|
|
12
|
+
- Metadata store with indexed fields
|
|
13
|
+
- Fiber store for memory groupings
|
|
14
|
+
- Write-ahead log (WAL) for crash safety
|
|
15
|
+
- 5-tier compression system (ACTIVE/WARM/COOL/FROZEN/CRYSTAL)
|
|
16
|
+
- Multi-dimensional query planner with RRF fusion
|
|
17
|
+
- SQLite → InfinityDB migration engine
|
|
18
|
+
- **NeuralStorage Adapter** — Drop-in replacement for SQLite backend
|
|
19
|
+
- Full NeuralStorage interface (24+ methods)
|
|
20
|
+
- Neuron/Synapse/Fiber CRUD with frozen dataclass converters
|
|
21
|
+
- Graph traversal (get_neighbors, get_path via BFS)
|
|
22
|
+
- Brain export/import (BrainSnapshot serialization)
|
|
23
|
+
- Pro-specific: search_similar, demote_sweep, get_tier_stats
|
|
24
|
+
- **Pro MCP Tools** — 3 exclusive tools via plugin system
|
|
25
|
+
- `nmem_cone_query` — HNSW cone recall with similarity threshold
|
|
26
|
+
- `nmem_tier_info` — Tier distribution stats + demote sweep
|
|
27
|
+
- `nmem_pro_merge` — Smart merge with dry_run preview
|
|
28
|
+
- **Plugin Storage Hook** — `get_storage_class()` for auto-upgrade
|
|
29
|
+
- **Cone Queries** — HNSW-accelerated retrieval (O(N) → O(k))
|
|
30
|
+
- **Smart Merge** — HNSW-accelerated consolidation (O(N^2) → O(N*k))
|
|
31
|
+
- **Directional Compress** — Multi-axis semantic compression (4 levels)
|
|
32
|
+
- **Benchmark Results** — Stress tested at 100K/1M/2M neurons
|
|
33
|
+
- 100K (384D): 1.7K inserts/s, 3.3ms search p50, 424MB
|
|
34
|
+
- 1M (64D): 6.5K inserts/s, 4.0ms search p50, 1.4GB
|
|
35
|
+
- 2M (32D): 4.1K inserts/s, 2.2ms search p50, 2.2GB
|
|
36
|
+
|
|
37
|
+
### Tests
|
|
38
|
+
- 304+ tests across 12 test files
|
|
39
|
+
- Full integration tests for WAL, compression, adapter, MCP tools
|
|
40
|
+
|
|
41
|
+
## [0.1.0] - 2026-03-20
|
|
42
|
+
|
|
43
|
+
### Added
|
|
44
|
+
- Initial scaffold with plugin registration
|
|
45
|
+
- Cone queries (brute-force, pre-InfinityDB)
|
|
46
|
+
- Directional compression (basic)
|
|
47
|
+
- Smart merge (basic)
|
|
48
|
+
- Plugin auto-discovery via entry_points
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: neural-memory-pro
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Pro extensions for Neural Memory — advanced retrieval, compression, and consolidation
|
|
5
|
+
Author-email: AIVN Foundation <claude@theio.vn>
|
|
6
|
+
License: MIT
|
|
7
|
+
Requires-Python: >=3.11
|
|
8
|
+
Requires-Dist: hnswlib>=0.8.0
|
|
9
|
+
Requires-Dist: msgpack>=1.0.0
|
|
10
|
+
Requires-Dist: neural-memory>=4.18.0
|
|
11
|
+
Requires-Dist: numpy>=1.24.0
|
|
12
|
+
Provides-Extra: dev
|
|
13
|
+
Requires-Dist: mypy>=1.8; extra == 'dev'
|
|
14
|
+
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
|
|
15
|
+
Requires-Dist: pytest>=7.0; extra == 'dev'
|
|
16
|
+
Requires-Dist: ruff>=0.4; extra == 'dev'
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
|
|
19
|
+
# Neural Memory Pro
|
|
20
|
+
|
|
21
|
+
> Drop-in upgrade for [Neural Memory](https://github.com/nhadaututtheky/neural-memory) — replaces SQLite with a purpose-built spatial database engine.
|
|
22
|
+
|
|
23
|
+
[](https://www.python.org/downloads/)
|
|
24
|
+
[](LICENSE)
|
|
25
|
+
|
|
26
|
+
## Why Pro?
|
|
27
|
+
|
|
28
|
+
Neural Memory (free) uses SQLite — great for getting started, but it hits walls at scale:
|
|
29
|
+
|
|
30
|
+
| Capability | Free (SQLite) | Pro (InfinityDB) |
|
|
31
|
+
|-----------|---------------|-------------------|
|
|
32
|
+
| **Vector search** | Sequential scan | HNSW index, sub-5ms at 1M neurons |
|
|
33
|
+
| **Max neurons** | ~50K practical | 2M+ tested, designed for 10M+ |
|
|
34
|
+
| **Compression** | None | 5-tier adaptive (up to 89% ratio) |
|
|
35
|
+
| **Storage engine** | Generic relational DB | Purpose-built for neural graphs |
|
|
36
|
+
| **Tiered storage** | All in memory | Hot/warm/cold with auto-demotion |
|
|
37
|
+
| **Graph traversal** | SQL JOINs | Native adjacency + BFS (<1ms depth-3) |
|
|
38
|
+
| **MCP tools** | 52 tools | 52 + 3 Pro-exclusive tools |
|
|
39
|
+
| **Recall speed** | ~50ms (small brains) | <5ms p50 at 100K neurons |
|
|
40
|
+
|
|
41
|
+
## Installation
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
# One command — automatically installs neural-memory (free) as dependency
|
|
45
|
+
pip install git+https://github.com/AIVN-Foundation/neural-memory-pro.git
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
That's it. No configuration needed — Pro auto-registers via Python entry_points and upgrades the storage backend transparently.
|
|
49
|
+
|
|
50
|
+
### Verify Installation
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
nmem version
|
|
54
|
+
# neural-memory 4.19.0 (Pro: InfinityDB 0.2.0)
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Or in Python:
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
from neural_memory.plugins import has_pro
|
|
61
|
+
print(has_pro()) # True
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## What You Get
|
|
65
|
+
|
|
66
|
+
### InfinityDB Engine
|
|
67
|
+
|
|
68
|
+
A custom spatial database engine built specifically for neural memory graphs:
|
|
69
|
+
|
|
70
|
+
- **HNSW Vector Index** — Hierarchical Navigable Small World graph for approximate nearest neighbor search. Sub-5ms queries at 1M+ neurons.
|
|
71
|
+
- **Write-Ahead Log (WAL)** — Crash-safe writes with automatic recovery on restart.
|
|
72
|
+
- **5-Tier Compression** — Adaptive compression pipeline (none → LZ4 → zstd → quantization → cold archive). Automatically selects tier based on access patterns.
|
|
73
|
+
- **Tiered Storage** — Hot neurons stay in memory, warm on SSD, cold compressed. Auto-demotion based on access frequency.
|
|
74
|
+
- **Native Graph Store** — Adjacency lists stored alongside vectors. BFS traversal in <1ms for depth-3.
|
|
75
|
+
- **Query Planner** — Optimizes retrieval strategy based on query type (vector similarity, graph traversal, hybrid).
|
|
76
|
+
|
|
77
|
+
### Pro MCP Tools
|
|
78
|
+
|
|
79
|
+
Three additional tools available in Claude Code when Pro is installed:
|
|
80
|
+
|
|
81
|
+
| Tool | Description |
|
|
82
|
+
|------|-------------|
|
|
83
|
+
| `nmem_cone_query` | HNSW cone recall — find all memories within a similarity threshold. Never miss a relevant memory. |
|
|
84
|
+
| `nmem_tier_info` | Storage tier statistics + trigger demote sweep for cold neurons. |
|
|
85
|
+
| `nmem_pro_merge` | Smart merge consolidation with dry-run preview. Priority-aware clustering with temporal coherence. |
|
|
86
|
+
|
|
87
|
+
### Pro Retrieval Strategies
|
|
88
|
+
|
|
89
|
+
- **Cone Queries** — Exhaustive recall via embedding similarity cones. Unlike top-k, cone queries guarantee no relevant memory is missed within a similarity threshold.
|
|
90
|
+
- **Directional Compression** — Multi-axis semantic compression that preserves relationships to multiple concepts simultaneously. Reduces storage while maintaining recall quality.
|
|
91
|
+
- **Smart Merge** — Priority-aware clustering with temporal coherence. Groups related memories and merges them intelligently, respecting priority and recency.
|
|
92
|
+
|
|
93
|
+
## Benchmarks
|
|
94
|
+
|
|
95
|
+
Tested on Windows 11, Python 3.14, consumer hardware (no GPU needed):
|
|
96
|
+
|
|
97
|
+
### Insert Performance
|
|
98
|
+
|
|
99
|
+
| Scale | Neurons/sec | Total Time |
|
|
100
|
+
|-------|------------|------------|
|
|
101
|
+
| 100K neurons (384D) | 1,714/s | 58s |
|
|
102
|
+
| 1M neurons (64D) | 6,463/s | 2.5min |
|
|
103
|
+
| 2M neurons (32D) | 4,119/s | 8min |
|
|
104
|
+
|
|
105
|
+
### Search Latency (p50)
|
|
106
|
+
|
|
107
|
+
| Scale | k=10 | k=50 | k=100 |
|
|
108
|
+
|-------|------|------|-------|
|
|
109
|
+
| 100K | 3.3ms | 8.9ms | 15.3ms |
|
|
110
|
+
| 1M | 4.0ms | 13.7ms | 23.8ms |
|
|
111
|
+
| 2M | 2.2ms | 8.0ms | 14.6ms |
|
|
112
|
+
|
|
113
|
+
### Graph Traversal (BFS, p50)
|
|
114
|
+
|
|
115
|
+
| Scale | Depth 1 | Depth 2 | Depth 3 |
|
|
116
|
+
|-------|---------|---------|---------|
|
|
117
|
+
| 100K | 0.15ms | 0.20ms | 0.53ms |
|
|
118
|
+
| 1M | 0.24ms | 0.36ms | 1.08ms |
|
|
119
|
+
| 2M | 0.17ms | 0.26ms | 0.64ms |
|
|
120
|
+
|
|
121
|
+
### Compression
|
|
122
|
+
|
|
123
|
+
| Scale | Raw Vectors | On Disk | Ratio |
|
|
124
|
+
|-------|------------|---------|-------|
|
|
125
|
+
| 100K (384D) | 146 MB | 424 MB | 35% |
|
|
126
|
+
| 1M (64D) | 244 MB | 1,358 MB | 18% |
|
|
127
|
+
| 2M (32D) | 244 MB | 2,217 MB | 11% |
|
|
128
|
+
|
|
129
|
+
> Full benchmark data: `benchmarks/results/`
|
|
130
|
+
|
|
131
|
+
## Architecture
|
|
132
|
+
|
|
133
|
+
```
|
|
134
|
+
neural-memory-pro/
|
|
135
|
+
src/neural_memory_pro/
|
|
136
|
+
infinitydb/
|
|
137
|
+
engine.py — Core database engine (open, close, CRUD, flush)
|
|
138
|
+
hnsw_index.py — HNSW vector index (hnswlib wrapper)
|
|
139
|
+
vector_store.py — Vector storage with batch operations
|
|
140
|
+
graph_store.py — Native adjacency list graph store
|
|
141
|
+
metadata_store.py — Neuron/synapse metadata (msgpack serialized)
|
|
142
|
+
fiber_store.py — Fiber (memory cluster) storage
|
|
143
|
+
compressor.py — 5-tier adaptive compression
|
|
144
|
+
tier_manager.py — Hot/warm/cold tiered storage
|
|
145
|
+
wal.py — Write-ahead log for crash safety
|
|
146
|
+
query_planner.py — Query optimization and strategy selection
|
|
147
|
+
file_format.py — Binary file format spec
|
|
148
|
+
migrator.py — Schema migration between versions
|
|
149
|
+
retrieval/
|
|
150
|
+
cone_queries.py — Exhaustive similarity cone recall
|
|
151
|
+
consolidation/
|
|
152
|
+
smart_merge.py — Priority-aware memory merging
|
|
153
|
+
hyperspace/
|
|
154
|
+
directional_compress.py — Multi-axis semantic compression
|
|
155
|
+
storage_adapter.py — NeuralStorage interface adapter
|
|
156
|
+
mcp_tools.py — Pro-exclusive MCP tool schemas + handlers
|
|
157
|
+
plugin.py — Plugin registration (auto-discovered)
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
## How It Works
|
|
161
|
+
|
|
162
|
+
1. **Install** — `pip install` pulls Pro + free tier as dependency
|
|
163
|
+
2. **Auto-register** — Python entry_points system discovers `neural_memory_pro:auto_register`
|
|
164
|
+
3. **Storage upgrade** — Free tier's `storage/factory.py` detects Pro plugin → uses InfinityDB instead of SQLite
|
|
165
|
+
4. **Transparent** — All 52 free MCP tools work unchanged. 3 Pro tools are added automatically.
|
|
166
|
+
5. **Fallback** — If Pro is uninstalled, free tier falls back to SQLite with zero errors
|
|
167
|
+
|
|
168
|
+
```
|
|
169
|
+
┌─────────────────────────────────┐
|
|
170
|
+
│ Claude Code / MCP Client │
|
|
171
|
+
├─────────────────────────────────┤
|
|
172
|
+
│ Neural Memory (free) │
|
|
173
|
+
│ 52 MCP tools, retrieval engine │
|
|
174
|
+
├──────────┬──────────────────────┤
|
|
175
|
+
│ SQLite │ InfinityDB (Pro) │
|
|
176
|
+
│ (free) │ HNSW + WAL + Tiers │
|
|
177
|
+
└──────────┴──────────────────────┘
|
|
178
|
+
↑ auto-selected based on
|
|
179
|
+
whether Pro is installed
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
## Requirements
|
|
183
|
+
|
|
184
|
+
- Python 3.11+
|
|
185
|
+
- `neural-memory >= 4.18.0` (auto-installed)
|
|
186
|
+
- `numpy >= 1.24`
|
|
187
|
+
- `hnswlib >= 0.8.0`
|
|
188
|
+
- `msgpack >= 1.0`
|
|
189
|
+
- No GPU required. Runs on consumer hardware.
|
|
190
|
+
|
|
191
|
+
## License
|
|
192
|
+
|
|
193
|
+
Proprietary — AIVN Foundation. All rights reserved.
|
|
194
|
+
|
|
195
|
+
Get access at [theio.vn](https://theio.vn).
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
# Neural Memory Pro
|
|
2
|
+
|
|
3
|
+
> Drop-in upgrade for [Neural Memory](https://github.com/nhadaututtheky/neural-memory) — replaces SQLite with a purpose-built spatial database engine.
|
|
4
|
+
|
|
5
|
+
[](https://www.python.org/downloads/)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
|
|
8
|
+
## Why Pro?
|
|
9
|
+
|
|
10
|
+
Neural Memory (free) uses SQLite — great for getting started, but it hits walls at scale:
|
|
11
|
+
|
|
12
|
+
| Capability | Free (SQLite) | Pro (InfinityDB) |
|
|
13
|
+
|-----------|---------------|-------------------|
|
|
14
|
+
| **Vector search** | Sequential scan | HNSW index, sub-5ms at 1M neurons |
|
|
15
|
+
| **Max neurons** | ~50K practical | 2M+ tested, designed for 10M+ |
|
|
16
|
+
| **Compression** | None | 5-tier adaptive (up to 89% ratio) |
|
|
17
|
+
| **Storage engine** | Generic relational DB | Purpose-built for neural graphs |
|
|
18
|
+
| **Tiered storage** | All in memory | Hot/warm/cold with auto-demotion |
|
|
19
|
+
| **Graph traversal** | SQL JOINs | Native adjacency + BFS (<1ms depth-3) |
|
|
20
|
+
| **MCP tools** | 52 tools | 52 + 3 Pro-exclusive tools |
|
|
21
|
+
| **Recall speed** | ~50ms (small brains) | <5ms p50 at 100K neurons |
|
|
22
|
+
|
|
23
|
+
## Installation
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
# One command — automatically installs neural-memory (free) as dependency
|
|
27
|
+
pip install git+https://github.com/AIVN-Foundation/neural-memory-pro.git
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
That's it. No configuration needed — Pro auto-registers via Python entry_points and upgrades the storage backend transparently.
|
|
31
|
+
|
|
32
|
+
### Verify Installation
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
nmem version
|
|
36
|
+
# neural-memory 4.19.0 (Pro: InfinityDB 0.2.0)
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Or in Python:
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
from neural_memory.plugins import has_pro
|
|
43
|
+
print(has_pro()) # True
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## What You Get
|
|
47
|
+
|
|
48
|
+
### InfinityDB Engine
|
|
49
|
+
|
|
50
|
+
A custom spatial database engine built specifically for neural memory graphs:
|
|
51
|
+
|
|
52
|
+
- **HNSW Vector Index** — Hierarchical Navigable Small World graph for approximate nearest neighbor search. Sub-5ms queries at 1M+ neurons.
|
|
53
|
+
- **Write-Ahead Log (WAL)** — Crash-safe writes with automatic recovery on restart.
|
|
54
|
+
- **5-Tier Compression** — Adaptive compression pipeline (none → LZ4 → zstd → quantization → cold archive). Automatically selects tier based on access patterns.
|
|
55
|
+
- **Tiered Storage** — Hot neurons stay in memory, warm on SSD, cold compressed. Auto-demotion based on access frequency.
|
|
56
|
+
- **Native Graph Store** — Adjacency lists stored alongside vectors. BFS traversal in <1ms for depth-3.
|
|
57
|
+
- **Query Planner** — Optimizes retrieval strategy based on query type (vector similarity, graph traversal, hybrid).
|
|
58
|
+
|
|
59
|
+
### Pro MCP Tools
|
|
60
|
+
|
|
61
|
+
Three additional tools available in Claude Code when Pro is installed:
|
|
62
|
+
|
|
63
|
+
| Tool | Description |
|
|
64
|
+
|------|-------------|
|
|
65
|
+
| `nmem_cone_query` | HNSW cone recall — find all memories within a similarity threshold. Never miss a relevant memory. |
|
|
66
|
+
| `nmem_tier_info` | Storage tier statistics + trigger demote sweep for cold neurons. |
|
|
67
|
+
| `nmem_pro_merge` | Smart merge consolidation with dry-run preview. Priority-aware clustering with temporal coherence. |
|
|
68
|
+
|
|
69
|
+
### Pro Retrieval Strategies
|
|
70
|
+
|
|
71
|
+
- **Cone Queries** — Exhaustive recall via embedding similarity cones. Unlike top-k, cone queries guarantee no relevant memory is missed within a similarity threshold.
|
|
72
|
+
- **Directional Compression** — Multi-axis semantic compression that preserves relationships to multiple concepts simultaneously. Reduces storage while maintaining recall quality.
|
|
73
|
+
- **Smart Merge** — Priority-aware clustering with temporal coherence. Groups related memories and merges them intelligently, respecting priority and recency.
|
|
74
|
+
|
|
75
|
+
## Benchmarks
|
|
76
|
+
|
|
77
|
+
Tested on Windows 11, Python 3.14, consumer hardware (no GPU needed):
|
|
78
|
+
|
|
79
|
+
### Insert Performance
|
|
80
|
+
|
|
81
|
+
| Scale | Neurons/sec | Total Time |
|
|
82
|
+
|-------|------------|------------|
|
|
83
|
+
| 100K neurons (384D) | 1,714/s | 58s |
|
|
84
|
+
| 1M neurons (64D) | 6,463/s | 2.5min |
|
|
85
|
+
| 2M neurons (32D) | 4,119/s | 8min |
|
|
86
|
+
|
|
87
|
+
### Search Latency (p50)
|
|
88
|
+
|
|
89
|
+
| Scale | k=10 | k=50 | k=100 |
|
|
90
|
+
|-------|------|------|-------|
|
|
91
|
+
| 100K | 3.3ms | 8.9ms | 15.3ms |
|
|
92
|
+
| 1M | 4.0ms | 13.7ms | 23.8ms |
|
|
93
|
+
| 2M | 2.2ms | 8.0ms | 14.6ms |
|
|
94
|
+
|
|
95
|
+
### Graph Traversal (BFS, p50)
|
|
96
|
+
|
|
97
|
+
| Scale | Depth 1 | Depth 2 | Depth 3 |
|
|
98
|
+
|-------|---------|---------|---------|
|
|
99
|
+
| 100K | 0.15ms | 0.20ms | 0.53ms |
|
|
100
|
+
| 1M | 0.24ms | 0.36ms | 1.08ms |
|
|
101
|
+
| 2M | 0.17ms | 0.26ms | 0.64ms |
|
|
102
|
+
|
|
103
|
+
### Compression
|
|
104
|
+
|
|
105
|
+
| Scale | Raw Vectors | On Disk | Ratio |
|
|
106
|
+
|-------|------------|---------|-------|
|
|
107
|
+
| 100K (384D) | 146 MB | 424 MB | 35% |
|
|
108
|
+
| 1M (64D) | 244 MB | 1,358 MB | 18% |
|
|
109
|
+
| 2M (32D) | 244 MB | 2,217 MB | 11% |
|
|
110
|
+
|
|
111
|
+
> Full benchmark data: `benchmarks/results/`
|
|
112
|
+
|
|
113
|
+
## Architecture
|
|
114
|
+
|
|
115
|
+
```
|
|
116
|
+
neural-memory-pro/
|
|
117
|
+
src/neural_memory_pro/
|
|
118
|
+
infinitydb/
|
|
119
|
+
engine.py — Core database engine (open, close, CRUD, flush)
|
|
120
|
+
hnsw_index.py — HNSW vector index (hnswlib wrapper)
|
|
121
|
+
vector_store.py — Vector storage with batch operations
|
|
122
|
+
graph_store.py — Native adjacency list graph store
|
|
123
|
+
metadata_store.py — Neuron/synapse metadata (msgpack serialized)
|
|
124
|
+
fiber_store.py — Fiber (memory cluster) storage
|
|
125
|
+
compressor.py — 5-tier adaptive compression
|
|
126
|
+
tier_manager.py — Hot/warm/cold tiered storage
|
|
127
|
+
wal.py — Write-ahead log for crash safety
|
|
128
|
+
query_planner.py — Query optimization and strategy selection
|
|
129
|
+
file_format.py — Binary file format spec
|
|
130
|
+
migrator.py — Schema migration between versions
|
|
131
|
+
retrieval/
|
|
132
|
+
cone_queries.py — Exhaustive similarity cone recall
|
|
133
|
+
consolidation/
|
|
134
|
+
smart_merge.py — Priority-aware memory merging
|
|
135
|
+
hyperspace/
|
|
136
|
+
directional_compress.py — Multi-axis semantic compression
|
|
137
|
+
storage_adapter.py — NeuralStorage interface adapter
|
|
138
|
+
mcp_tools.py — Pro-exclusive MCP tool schemas + handlers
|
|
139
|
+
plugin.py — Plugin registration (auto-discovered)
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## How It Works
|
|
143
|
+
|
|
144
|
+
1. **Install** — `pip install` pulls Pro + free tier as dependency
|
|
145
|
+
2. **Auto-register** — Python entry_points system discovers `neural_memory_pro:auto_register`
|
|
146
|
+
3. **Storage upgrade** — Free tier's `storage/factory.py` detects Pro plugin → uses InfinityDB instead of SQLite
|
|
147
|
+
4. **Transparent** — All 52 free MCP tools work unchanged. 3 Pro tools are added automatically.
|
|
148
|
+
5. **Fallback** — If Pro is uninstalled, free tier falls back to SQLite with zero errors
|
|
149
|
+
|
|
150
|
+
```
|
|
151
|
+
┌─────────────────────────────────┐
|
|
152
|
+
│ Claude Code / MCP Client │
|
|
153
|
+
├─────────────────────────────────┤
|
|
154
|
+
│ Neural Memory (free) │
|
|
155
|
+
│ 52 MCP tools, retrieval engine │
|
|
156
|
+
├──────────┬──────────────────────┤
|
|
157
|
+
│ SQLite │ InfinityDB (Pro) │
|
|
158
|
+
│ (free) │ HNSW + WAL + Tiers │
|
|
159
|
+
└──────────┴──────────────────────┘
|
|
160
|
+
↑ auto-selected based on
|
|
161
|
+
whether Pro is installed
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
## Requirements
|
|
165
|
+
|
|
166
|
+
- Python 3.11+
|
|
167
|
+
- `neural-memory >= 4.18.0` (auto-installed)
|
|
168
|
+
- `numpy >= 1.24`
|
|
169
|
+
- `hnswlib >= 0.8.0`
|
|
170
|
+
- `msgpack >= 1.0`
|
|
171
|
+
- No GPU required. Runs on consumer hardware.
|
|
172
|
+
|
|
173
|
+
## License
|
|
174
|
+
|
|
175
|
+
Proprietary — AIVN Foundation. All rights reserved.
|
|
176
|
+
|
|
177
|
+
Get access at [theio.vn](https://theio.vn).
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
{
|
|
2
|
+
"benchmark_version": "1.0",
|
|
3
|
+
"timestamp": "20260322_215132",
|
|
4
|
+
"python_version": "3.14.2 (tags/v3.14.2:df79316, Dec 5 2025, 17:18:21) [MSC v.1944 64 bit (AMD64)]",
|
|
5
|
+
"platform": "win32",
|
|
6
|
+
"1M": {
|
|
7
|
+
"neuron_count": 1000000,
|
|
8
|
+
"dimensions": 384,
|
|
9
|
+
"batch_size": 5000,
|
|
10
|
+
"started_at": "2026-03-22T21:51:32.864392+00:00",
|
|
11
|
+
"insert": {
|
|
12
|
+
"neuron_count": 1000000,
|
|
13
|
+
"total_seconds": 511.07,
|
|
14
|
+
"neurons_per_second": 1956.7,
|
|
15
|
+
"batch_p50_ms": 2339.66,
|
|
16
|
+
"batch_p95_ms": 4089.35,
|
|
17
|
+
"batch_p99_ms": 5543.99,
|
|
18
|
+
"rss_mb_after_insert": 4420.7
|
|
19
|
+
},
|
|
20
|
+
"synapses": {
|
|
21
|
+
"synapse_count": 3000000,
|
|
22
|
+
"errors": 0,
|
|
23
|
+
"total_seconds": 1267.25,
|
|
24
|
+
"synapses_per_second": 2367.3
|
|
25
|
+
},
|
|
26
|
+
"fibers": {
|
|
27
|
+
"fiber_count": 50,
|
|
28
|
+
"total_seconds": 0.12
|
|
29
|
+
},
|
|
30
|
+
"flush": {
|
|
31
|
+
"flush_seconds": 12.98
|
|
32
|
+
},
|
|
33
|
+
"disk": {
|
|
34
|
+
"total_mb": 3858.2,
|
|
35
|
+
"raw_vectors_mb": 1464.8,
|
|
36
|
+
"compression_ratio": 0.38
|
|
37
|
+
},
|
|
38
|
+
"search": {
|
|
39
|
+
"k10": {
|
|
40
|
+
"p50_ms": 2.02,
|
|
41
|
+
"p95_ms": 2.88,
|
|
42
|
+
"p99_ms": 3.34,
|
|
43
|
+
"mean_ms": 2.14
|
|
44
|
+
},
|
|
45
|
+
"k50": {
|
|
46
|
+
"p50_ms": 6.54,
|
|
47
|
+
"p95_ms": 8.25,
|
|
48
|
+
"p99_ms": 9.2,
|
|
49
|
+
"mean_ms": 6.7
|
|
50
|
+
},
|
|
51
|
+
"k100": {
|
|
52
|
+
"p50_ms": 12.73,
|
|
53
|
+
"p95_ms": 15.83,
|
|
54
|
+
"p99_ms": 17.46,
|
|
55
|
+
"mean_ms": 12.8
|
|
56
|
+
}
|
|
57
|
+
},
|
|
58
|
+
"bfs": {
|
|
59
|
+
"depth_1": {
|
|
60
|
+
"p50_ms": 0.11,
|
|
61
|
+
"p95_ms": 0.2,
|
|
62
|
+
"avg_nodes_reached": 6.4
|
|
63
|
+
},
|
|
64
|
+
"depth_2": {
|
|
65
|
+
"p50_ms": 0.19,
|
|
66
|
+
"p95_ms": 0.36,
|
|
67
|
+
"avg_nodes_reached": 44.3
|
|
68
|
+
},
|
|
69
|
+
"depth_3": {
|
|
70
|
+
"p50_ms": 0.54,
|
|
71
|
+
"p95_ms": 0.97,
|
|
72
|
+
"avg_nodes_reached": 271.6
|
|
73
|
+
}
|
|
74
|
+
},
|
|
75
|
+
"error": "The truth value of an array with more than one element is ambiguous. Use a.any() or a.all()",
|
|
76
|
+
"finished_at": "2026-03-22T22:21:33.567592+00:00",
|
|
77
|
+
"rss_mb_final": 106.2
|
|
78
|
+
},
|
|
79
|
+
"2M": {
|
|
80
|
+
"neuron_count": 2000000,
|
|
81
|
+
"dimensions": 384,
|
|
82
|
+
"batch_size": 5000,
|
|
83
|
+
"started_at": "2026-03-22T22:21:33.584559+00:00",
|
|
84
|
+
"insert": {
|
|
85
|
+
"neuron_count": 2000000,
|
|
86
|
+
"total_seconds": 1389.03,
|
|
87
|
+
"neurons_per_second": 1439.9,
|
|
88
|
+
"batch_p50_ms": 3014.28,
|
|
89
|
+
"batch_p95_ms": 5538.2,
|
|
90
|
+
"batch_p99_ms": 7184.99,
|
|
91
|
+
"rss_mb_after_insert": 8782.9
|
|
92
|
+
},
|
|
93
|
+
"synapses": {
|
|
94
|
+
"synapse_count": 6000000,
|
|
95
|
+
"errors": 0,
|
|
96
|
+
"total_seconds": 2256.0,
|
|
97
|
+
"synapses_per_second": 2659.6
|
|
98
|
+
},
|
|
99
|
+
"fibers": {
|
|
100
|
+
"fiber_count": 50,
|
|
101
|
+
"total_seconds": 0.09
|
|
102
|
+
},
|
|
103
|
+
"flush": {
|
|
104
|
+
"flush_seconds": 25.92
|
|
105
|
+
},
|
|
106
|
+
"disk": {
|
|
107
|
+
"total_mb": 7718.3,
|
|
108
|
+
"raw_vectors_mb": 2929.7,
|
|
109
|
+
"compression_ratio": 0.38
|
|
110
|
+
},
|
|
111
|
+
"search": {
|
|
112
|
+
"k10": {
|
|
113
|
+
"p50_ms": 1.63,
|
|
114
|
+
"p95_ms": 3.08,
|
|
115
|
+
"p99_ms": 7.1,
|
|
116
|
+
"mean_ms": 1.82
|
|
117
|
+
},
|
|
118
|
+
"k50": {
|
|
119
|
+
"p50_ms": 4.43,
|
|
120
|
+
"p95_ms": 10.75,
|
|
121
|
+
"p99_ms": 15.45,
|
|
122
|
+
"mean_ms": 5.44
|
|
123
|
+
},
|
|
124
|
+
"k100": {
|
|
125
|
+
"p50_ms": 7.66,
|
|
126
|
+
"p95_ms": 10.5,
|
|
127
|
+
"p99_ms": 16.57,
|
|
128
|
+
"mean_ms": 8.02
|
|
129
|
+
}
|
|
130
|
+
},
|
|
131
|
+
"bfs": {
|
|
132
|
+
"depth_1": {
|
|
133
|
+
"p50_ms": 0.1,
|
|
134
|
+
"p95_ms": 0.16,
|
|
135
|
+
"avg_nodes_reached": 7.1
|
|
136
|
+
},
|
|
137
|
+
"depth_2": {
|
|
138
|
+
"p50_ms": 0.11,
|
|
139
|
+
"p95_ms": 0.18,
|
|
140
|
+
"avg_nodes_reached": 41.7
|
|
141
|
+
},
|
|
142
|
+
"depth_3": {
|
|
143
|
+
"p50_ms": 0.37,
|
|
144
|
+
"p95_ms": 0.95,
|
|
145
|
+
"avg_nodes_reached": 261.0
|
|
146
|
+
}
|
|
147
|
+
},
|
|
148
|
+
"error": "The truth value of an array with more than one element is ambiguous. Use a.any() or a.all()",
|
|
149
|
+
"finished_at": "2026-03-22T23:22:59.876714+00:00",
|
|
150
|
+
"rss_mb_final": 131.9
|
|
151
|
+
}
|
|
152
|
+
}
|