@lotargo/memory_plugin 1.1.6 → 1.1.7
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 +247 -243
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,243 +1,247 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
|
|
3
|
-
<img src="
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
- **
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
- **
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
- **
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
|
138
|
-
|
|
|
139
|
-
| `
|
|
140
|
-
| `
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
#
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
|
173
|
-
|
|
|
174
|
-
|
|
|
175
|
-
| |
|
|
176
|
-
| |
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
**
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
<img src="./assets/hero.jpg" alt="@lotargo/memory_plugin" width="800" style="max-width: 100%; border-radius: 12px; margin-bottom: 16px;">
|
|
4
|
+
|
|
5
|
+
<br>
|
|
6
|
+
|
|
7
|
+
<img src="./assets/title.svg" alt="@lotargo/memory_plugin" width="520" style="max-width: 100%; margin-bottom: 12px;">
|
|
8
|
+
|
|
9
|
+
<br>
|
|
10
|
+
|
|
11
|
+
[](https://www.npmjs.com/package/@lotargo/memory_plugin)
|
|
12
|
+
[](./LICENSE)
|
|
13
|
+
[](https://nodejs.org)
|
|
14
|
+
[](https://modelcontextprotocol.io)
|
|
15
|
+
[](#storage--privacy)
|
|
16
|
+
|
|
17
|
+
<br>
|
|
18
|
+
|
|
19
|
+
**Zero-Docker Local Hybrid RAG Engine & Long-Term Memory for AI Coding Agents**
|
|
20
|
+
|
|
21
|
+
Automatically remembers durable user facts, ingests complex document repositories, and performs high-precision hybrid retrieval across sessions and platforms.
|
|
22
|
+
|
|
23
|
+
</div>
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Overview
|
|
28
|
+
|
|
29
|
+
Standard AI coding assistants lose context as soon as a chat session closes or a conversation is reset. You end up repeatedly re-explaining your preferences, architectural decisions, coding style, or project conventions.
|
|
30
|
+
|
|
31
|
+
`@lotargo/memory_plugin` gives your AI tools durable, 100% local long-term memory and document retrieval capabilities that persist across restarts and work seamlessly across all supported coding environments.
|
|
32
|
+
|
|
33
|
+
> **Project Scope & Runtime Notes**:
|
|
34
|
+
> `@lotargo/memory_plugin` is designed primarily as a practical plugin to expand capabilities and streamline daily interaction with AI coding tools. Benchmark scores in this repository represent internal synthetic evaluation runs and are not intended as generalized RAG benchmarks.
|
|
35
|
+
>
|
|
36
|
+
> **Hardware Acceleration**: GPU execution mode is an experimental feature and may vary in stability across different operating systems or models. For optimal stability and consistent runtime performance, using standard CPU mode with `multilingual-e5-small` or `multilingual-e5-base` is recommended.
|
|
37
|
+
|
|
38
|
+
### Practical Use Cases
|
|
39
|
+
|
|
40
|
+
- **Architectural Decisions**: _"In this project, we use Fastify instead of Express and strict schema validation via Zod."_
|
|
41
|
+
- **Coding Conventions**: _"Place all helper utilities inside `src/utils/` and cover new functions with Vitest tests."_
|
|
42
|
+
- **Environment Constraints**: _"Our target deployment environment is Node.js 20 on AWS Lambda."_
|
|
43
|
+
- **User Profile & Tone**: _"My name is Alex. I prefer concise, direct answers without conversational filler."_
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## Quick Start
|
|
48
|
+
|
|
49
|
+
### Minimum System Requirements
|
|
50
|
+
|
|
51
|
+
- **Node.js**: `18.0.0` or higher
|
|
52
|
+
- **Package Manager**: `npm` / `npx` (included with Node.js)
|
|
53
|
+
- **Supported Environment**: OpenCode, Antigravity / Gemini CLI, Claude Code, or Codex
|
|
54
|
+
|
|
55
|
+
### Installation
|
|
56
|
+
|
|
57
|
+
Run the unified setup command to configure all detected AI environments automatically:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
npx @lotargo/memory_plugin setup
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
To target a specific environment:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
# Antigravity / Gemini CLI
|
|
67
|
+
npx @lotargo/memory_plugin setup --antigravity
|
|
68
|
+
|
|
69
|
+
# OpenCode
|
|
70
|
+
npx @lotargo/memory_plugin setup --opencode
|
|
71
|
+
|
|
72
|
+
# Claude Code
|
|
73
|
+
npx @lotargo/memory_plugin setup --claude
|
|
74
|
+
|
|
75
|
+
# Codex
|
|
76
|
+
npx @lotargo/memory_plugin setup --codex
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## Dual-Layer Architecture
|
|
82
|
+
|
|
83
|
+
1. **Layer 1: Notebook Store (Durable Facts)**
|
|
84
|
+
- **Tools**: `remember`, `recall`, `forget`
|
|
85
|
+
- **Scope**: User preferences, identity, project conventions, system rules.
|
|
86
|
+
- **Storage**: Human-readable Markdown format (`global` and per-project stores).
|
|
87
|
+
- **Performance**: Guaranteed 100% precision instant lookup without vector degradation or threshold filtering.
|
|
88
|
+
|
|
89
|
+
2. **Layer 2: RAG Knowledge Base (Technical Documents & Codebases)**
|
|
90
|
+
- **Tools**: `ingest_document`, `query_knowledge_base`, `manage_knowledge_base`
|
|
91
|
+
- **Capabilities**: Ingests raw text files, Markdown, HTML, and full code repositories.
|
|
92
|
+
- **Engine Components**: 3-tier hierarchy chunking (Big / Medium / Small), SQLite FTS5 BM25 search, ONNX dense vector embeddings (`multilingual-e5-small`), Reciprocal Rank Fusion (RRF / RSF), and GraphRAG Lite code symbol extraction.
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## Key Features
|
|
97
|
+
|
|
98
|
+
- **Zero Heavy Infrastructure**: No Docker, no Python server, no C++ compilation (`node-gyp`). Uses Node.js native SQLite database.
|
|
99
|
+
- **Bilingual & Multilingual Support**: State-of-the-art semantic precision across Russian, English, and technical code symbols.
|
|
100
|
+
- **3-Tier Hierarchy Chunking**: Document (Big) -> Section (Medium) -> Micro-Chunk (Small).
|
|
101
|
+
- **Hybrid RRF/RSF Fusion**: Combines SQLite FTS5 keyword precision with ONNX dense vector similarity.
|
|
102
|
+
- **GraphRAG Lite**: Automatically links documents and extracted code symbols (classes, functions, types).
|
|
103
|
+
- **Content-Addressable Storage (CAS)**: Local S3-style compressed blob store for raw original documents.
|
|
104
|
+
- **Dual-Source Model Failover**: Automatic HuggingFace CDN model downloading with GitHub Repository Mirror fallback.
|
|
105
|
+
- **Interactive CLI Management**: Terminal GUI interface for runtime engine tuning, database maintenance, and diagnostics.
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## Supported Platforms
|
|
110
|
+
|
|
111
|
+
| Platform | Status | Configuration Mechanism |
|
|
112
|
+
| :--------------------------- | :----------- | :-------------------------------------------------------------------------- |
|
|
113
|
+
| **Antigravity / Gemini CLI** | Supported | MCP Server (`~/.gemini/config/mcp_config.json` & `.agents/mcp_config.json`) |
|
|
114
|
+
| **OpenCode** | Native | Native plugin + MCP Server (`~/.config/opencode/opencode.json`) |
|
|
115
|
+
| **Claude Code** | Supported | MCP Server (`~/.claude.json`) |
|
|
116
|
+
| **Codex** | Supported | MCP Server (`~/.codex/config.toml`) |
|
|
117
|
+
| **Google Jules** | Experimental | MCP Server via global install (`npm install -g @lotargo/memory_plugin`) |
|
|
118
|
+
|
|
119
|
+
### Google Jules Integration (Experimental)
|
|
120
|
+
|
|
121
|
+
The plugin has been verified inside the **Google Jules** cloud workspace environment.
|
|
122
|
+
|
|
123
|
+
- **Setup Method**: Global pre-installation:
|
|
124
|
+
```bash
|
|
125
|
+
npm install -g @lotargo/memory_plugin
|
|
126
|
+
```
|
|
127
|
+
- **Verification**: Google Jules automatically discovers the registered MCP server upon workspace initialization and seamlessly interacts with memory & RAG tools (`remember`, `recall`, `ingest_document`, `query_knowledge_base`).
|
|
128
|
+
- **Current Limitation**: All memory stores and vector indexes operate locally within the workspace environment. Cross-session cloud synchronization across different Jules runs is planned for upcoming releases.
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## Available MCP Tools
|
|
133
|
+
|
|
134
|
+
### 1. Memory Tools (Key-Value Notebook)
|
|
135
|
+
|
|
136
|
+
| Tool | Scope / Target | Description |
|
|
137
|
+
| :--------- | :---------------------------- | :------------------------------------------- |
|
|
138
|
+
| `remember` | `global` or `project` | Save an important durable fact or preference |
|
|
139
|
+
| `recall` | `project`, `global`, or `all` | Display saved facts |
|
|
140
|
+
| `forget` | Index ID or query | Remove a saved fact |
|
|
141
|
+
|
|
142
|
+
### 2. Hybrid RAG Knowledge Base Tools
|
|
143
|
+
|
|
144
|
+
| Tool | Target | Description |
|
|
145
|
+
| :---------------------- | :------------------------------ | :--------------------------------------------------------------------------- |
|
|
146
|
+
| `ingest_document` | Local files, Web URLs, Raw text | Ingest into 3-tier index with ONNX vector embeddings & symbol extraction |
|
|
147
|
+
| `query_knowledge_base` | Text / Code query | Perform hybrid RSF/RRF search (BM25 + Vector) to retrieve candidate sections |
|
|
148
|
+
| `manage_knowledge_base` | Actions / Documents | List documents, delete entries, view DB stats, or export/import snapshots |
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## Interactive CLI & Engine Tuning
|
|
153
|
+
|
|
154
|
+
Launch the interactive CLI terminal interface to manage engine settings, inspect databases, and tune retrieval parameters:
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
# From local repository folder:
|
|
158
|
+
node mcp-server/index.js cli
|
|
159
|
+
# or
|
|
160
|
+
npx . cli
|
|
161
|
+
|
|
162
|
+
# If installed / linked globally:
|
|
163
|
+
memory_plugin cli
|
|
164
|
+
# or
|
|
165
|
+
memory-cli
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### CLI Menu Overview
|
|
169
|
+
|
|
170
|
+
The interactive menu exposes runtime parameters that `hybridQuery` honors, allowing search behavior modifications without restarting the MCP server. Use **Up / Down** arrows to navigate, **ENTER** to select, and **BACKSPACE** to go back.
|
|
171
|
+
|
|
172
|
+
| Block | Menu Item | Functionality |
|
|
173
|
+
| :------------------ | :--------------------------- | :----------------------------------------------------------------------------- |
|
|
174
|
+
| **Engine Settings** | Fusion Algorithm | Switch between `rsf`, `rrf`, `semantic_only`, `lexical_only`. |
|
|
175
|
+
| | RSF Alpha Balance | Weight of semantic over lexical in `rsf` fusion (`α ∈ [0,1]`). Default: `0.5`. |
|
|
176
|
+
| | Embedding Model | Select ONNX model (e.g. `Xenova/multilingual-e5-small`). |
|
|
177
|
+
| | Reranker Model | Enable Cross-Encoder reranking or disable for zero-latency fusion. |
|
|
178
|
+
| **Notebook** | Layer 1 Facts | Browse and manage `global` and per-project `.md` fact stores. |
|
|
179
|
+
| **RAG Docs** | Layer 2 RAG Base | List ingested documents, inspect chunk counts, and purge entries. |
|
|
180
|
+
| **Diagnostics** | Run Search Quality Benchmark | Execute in-process search evaluation across benchmark query set. |
|
|
181
|
+
| | Verification Query | Run a test `hybridQuery` against the active index. |
|
|
182
|
+
| | Clear Cache & Reset | Clear cached benchmark corpus or restore factory default config. |
|
|
183
|
+
|
|
184
|
+
Settings persist to `~/.config/opencode/memory/config.json` and are immediately loaded by the MCP server.
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
## Testing & Benchmarking
|
|
189
|
+
|
|
190
|
+
To run the automated test suite and benchmarks locally:
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
cd mcp-server
|
|
194
|
+
|
|
195
|
+
# Run unit and integration tests
|
|
196
|
+
npm test
|
|
197
|
+
|
|
198
|
+
# Run search quality & ingestion benchmarks
|
|
199
|
+
npm run benchmark
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### Benchmark Methodology
|
|
203
|
+
|
|
204
|
+
The benchmark suite (`mcp-server/benchmarks/`) evaluates retrieval quality across three phases:
|
|
205
|
+
|
|
206
|
+
1. **Dual-Layer Verification**: Asserts Notebook and RAG layers are isolated (zero crosstalk, 100% precision on `recall`).
|
|
207
|
+
2. **Ingestion Benchmark**: Ingests test documents with ONNX `multilingual-e5-small` embeddings, reporting throughput, DB size, CAS blob footprint, and heap delta.
|
|
208
|
+
3. **Search Quality Benchmark**: Evaluates cross-lingual and code-keyword queries against 4 retrieval strategies with bootstrap 95% CIs, paired t-tests, and hyperparameter sweeps over RSF $\alpha$ and RRF $k$.
|
|
209
|
+
|
|
210
|
+
### Search Quality Results (Smoke Test)
|
|
211
|
+
|
|
212
|
+
_Note: The following metrics reflect a quick smoke-test evaluation run performed on a reduced subset of documents to verify retrieval logic precision._
|
|
213
|
+
|
|
214
|
+
Evaluated across a reduced document subset using Mean Reciprocal Rank (MRR@5), Recall@5, and Normalized Discounted Cumulative Gain (NDCG@5):
|
|
215
|
+
|
|
216
|
+
| Retrieval Strategy | MRR@5 | Recall@5 | NDCG@5 |
|
|
217
|
+
| :---------------------------- | :--------: | :---------: | :--------: |
|
|
218
|
+
| BM25 Lexical Search Only | 0.6706 | 76.19% | 0.6934 |
|
|
219
|
+
| Dense ONNX Vector Only | 0.8135 | 100.00% | 0.8612 |
|
|
220
|
+
| Hybrid RRF ($k=10$) | 0.8810 | 95.24% | 0.8997 |
|
|
221
|
+
| **Hybrid RSF ($\alpha=0.5$)** | **0.9286** | **100.00%** | **0.9473** |
|
|
222
|
+
|
|
223
|
+
For complete methodology details, see [`docs/BENCHMARKS.md`](./docs/BENCHMARKS.md).
|
|
224
|
+
|
|
225
|
+
---
|
|
226
|
+
|
|
227
|
+
## Documentation & Reports
|
|
228
|
+
|
|
229
|
+
Detailed technical documentation and architectural specifications are available in the [`docs/`](./docs) directory:
|
|
230
|
+
|
|
231
|
+
- [**Verification Report (`MEMORY_PLUGIN_REPORT.md`)**](./docs/MEMORY_PLUGIN_REPORT.md): Summary report covering MCP Tool Registry, JSON-RPC integration testing, layer isolation validation, and search precision.
|
|
232
|
+
- [**Comprehensive Technical Report (`MEMORY_PLUGIN_COMPREHENSIVE_REPORT.md`)**](./docs/MEMORY_PLUGIN_COMPREHENSIVE_REPORT.md): Scientific analysis of system architecture, dual-layer model, hardware environment specifications, mathematical search formulations, and event-loop profiling.
|
|
233
|
+
- [**Benchmark Methodology & Guide (`BENCHMARKS.md`)**](./docs/BENCHMARKS.md): Guide to automated benchmark execution, hyperparameter sweeps (RSF $\alpha$, RRF $k$), search quality metrics, and performance tracking across releases.
|
|
234
|
+
|
|
235
|
+
---
|
|
236
|
+
|
|
237
|
+
## Storage & Privacy
|
|
238
|
+
|
|
239
|
+
- **100% Local Storage**: All SQLite indexes, ONNX models, CAS blobs, and Markdown notebooks are stored locally under `~/.config/opencode/memory/`.
|
|
240
|
+
- **Dual-Source Failover Model Fetching**: Primary model weights are fetched from HuggingFace CDN with automatic failover to GitHub Repository Mirror.
|
|
241
|
+
- **Zero External Telemetry**: No third-party network calls are required after initial model setup.
|
|
242
|
+
|
|
243
|
+
---
|
|
244
|
+
|
|
245
|
+
## License
|
|
246
|
+
|
|
247
|
+
[MIT](./LICENSE)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@lotargo/memory_plugin",
|
|
3
|
-
"version": "1.1.
|
|
3
|
+
"version": "1.1.7",
|
|
4
4
|
"description": "Persistent memory agent for coding AI tools — remembers user preferences and project context across sessions. Works with Antigravity, OpenCode, Claude Code, and Codex.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "opencode-plugin/index.js",
|