@lotargo/memory_plugin 1.3.1 → 1.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.
Files changed (4) hide show
  1. package/README.md +107 -35
  2. package/mcp-server/index.js +0 -7
  3. package/package.json +20 -5
  4. package/mcp-server/admin/server.js +0 -228
package/README.md CHANGED
@@ -29,7 +29,7 @@ Automatically remembers durable user facts, ingests complex document repositorie
29
29
 
30
30
  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.
31
31
 
32
- `@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
+ `@lotargo/memory_plugin` gives your AI tools durable, **persistent**, 100% local long-term memory and document retrieval capabilities that persist across restarts and work seamlessly across all supported coding environments. Any LLM-based coding agent (OpenCode, Claude Code, Codex, Antigravity) can query its own memory and hybrid knowledge base via the **Model Context Protocol (MCP)**.
33
33
 
34
34
  > **Project Scope & Runtime Notes**:
35
35
  > `@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.
@@ -58,7 +58,7 @@ Standard AI coding assistants lose context as soon as a chat session closes or a
58
58
  Run the setup command to configure all detected AI environments automatically:
59
59
 
60
60
  ```bash
61
- # Recommended: Global installation & setup (works across local CLI, Jules, Docker, and CI)
61
+ # Recommended: Global installation & setup (works across local CLI, Docker, and CI)
62
62
  npm install -g @lotargo/memory_plugin && memory_plugin setup
63
63
 
64
64
  # Or via npx
@@ -81,20 +81,23 @@ npm install -g @lotargo/memory_plugin && memory_plugin setup --claude
81
81
  npm install -g @lotargo/memory_plugin && memory_plugin setup --codex
82
82
  ```
83
83
 
84
+ `setup` also accepts `--gemini` (alias for Antigravity) and `--local` (also registers the MCP server in the project-local `.agents/` directory for Antigravity). Without a specific flag, all detected environments are configured.
85
+
84
86
  ---
85
87
 
86
88
  ## Dual-Layer Architecture
87
89
 
88
90
  1. **Layer 1: Notebook Store (Durable Facts)**
89
- - **Tools**: `remember`, `recall`, `forget`
91
+ - **Tools**: `remember`, `recall`, `forget`, `update_fact`, `memory_info`
90
92
  - **Scope**: User preferences, identity, project conventions, system rules.
91
93
  - **Storage**: Human-readable Markdown format (`global` and per-project stores).
92
94
  - **Performance**: Guaranteed 100% precision instant lookup without vector degradation or threshold filtering.
95
+ - **Project Scoping**: Project stores are bound to their canonical directory path (e.g. `f__projects_plugins_memory.md`), so identical project names in different folders never collide. Legacy basename stores are migrated automatically with a collision guard.
93
96
 
94
97
  2. **Layer 2: RAG Knowledge Base (Technical Documents & Codebases)**
95
- - **Tools**: `ingest_document`, `query_knowledge_base`, `manage_knowledge_base`
96
- - **Capabilities**: Ingests raw text files, Markdown, HTML, and full code repositories.
97
- - **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.
98
+ - **Tools**: `ingest_document`, `query_knowledge_base`, `manage_knowledge_base`, `link_knowledge`
99
+ - **Capabilities**: Ingests raw text files, Markdown, HTML, Web URLs, and full code repositories.
100
+ - **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), cross-encoder reranking (optional), and GraphRAG Lite code symbol extraction.
98
101
 
99
102
  ---
100
103
 
@@ -103,11 +106,14 @@ npm install -g @lotargo/memory_plugin && memory_plugin setup --codex
103
106
  - **Zero Heavy Infrastructure**: No Docker, no Python server, no C++ compilation (`node-gyp`). Uses Node.js native SQLite database.
104
107
  - **Bilingual & Multilingual Support**: State-of-the-art semantic precision across Russian, English, and technical code symbols.
105
108
  - **3-Tier Hierarchy Chunking**: Document (Big) -> Section (Medium) -> Micro-Chunk (Small).
106
- - **Hybrid RRF/RSF Fusion**: Combines SQLite FTS5 keyword precision with ONNX dense vector similarity.
109
+ - **Hybrid RRF/RSF Fusion**: Combines SQLite FTS5 keyword precision with ONNX dense vector similarity; lexical-only fallback when embeddings are disabled.
110
+ - **Semantic Search**: Cosine-similarity vector retrieval with multilingual ONNX embeddings (E5 / BGE model families).
111
+ - **Path-Based Project Memory**: Per-project stores keyed by canonical directory path, with automatic migration of legacy stores.
107
112
  - **GraphRAG Lite**: Automatically links documents and extracted code symbols (classes, functions, types).
113
+ - **Memory-to-Knowledge Linking**: Associate notebook facts with specific documents or line ranges in the RAG base.
108
114
  - **Content-Addressable Storage (CAS)**: Local S3-style compressed blob store for raw original documents.
109
115
  - **Dual-Source Model Failover**: Automatic HuggingFace CDN model downloading with GitHub Repository Mirror fallback.
110
- - **Interactive CLI Management**: Terminal GUI interface for runtime engine tuning, database maintenance, and diagnostics.
116
+ - **Interactive TUI**: Terminal GUI (CLI menu) for runtime engine tuning, snapshot export/import, model cache management, and diagnostics.
111
117
 
112
118
  ---
113
119
 
@@ -119,17 +125,17 @@ npm install -g @lotargo/memory_plugin && memory_plugin setup --codex
119
125
  | **OpenCode** | Native | Native plugin + MCP Server (`~/.config/opencode/opencode.json`) |
120
126
  | **Claude Code** | Supported | MCP Server (`~/.claude.json`) |
121
127
  | **Codex** | Supported | MCP Server (`~/.codex/config.toml`) |
122
- | **Google Jules** | Experimental | MCP Server via global install (`npm install -g @lotargo/memory_plugin`) |
128
+ | **Google Jules** | Experimental | MCP Server via global install + setup (`npm install -g @lotargo/memory_plugin && memory_plugin setup`) |
123
129
 
124
130
  ### Google Jules Integration (Experimental)
125
131
 
126
- The plugin has been verified inside the **Google Jules** cloud workspace environment.
132
+ The plugin has been verified inside the **Google Jules** cloud workspace environment. This feature is **experimental**.
127
133
 
128
- - **Setup Method**: Global pre-installation:
134
+ - **Setup Method**: Global pre-installation with auto-setup:
129
135
  ```bash
130
- npm install -g @lotargo/memory_plugin
136
+ npm install -g @lotargo/memory_plugin && memory_plugin setup
131
137
  ```
132
- - **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`).
138
+ - **Verification**: All current tools and capabilities have been verified inside the Google Jules cloud workspace. Google Jules automatically discovers the registered MCP server upon workspace initialization and seamlessly interacts with the full set of memory & RAG tools — `remember`, `recall`, `forget`, `update_fact`, `memory_info`, `link_knowledge`, `ingest_document`, `query_knowledge_base`, and `manage_knowledge_base` — including project-scoped memory, knowledge linking, and snapshot export/import.
133
139
  - **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.
134
140
 
135
141
  ---
@@ -138,11 +144,13 @@ The plugin has been verified inside the **Google Jules** cloud workspace environ
138
144
 
139
145
  ### 1. Memory Tools (Key-Value Notebook)
140
146
 
141
- | Tool | Scope / Target | Description |
142
- | :--------- | :---------------------------- | :------------------------------------------- |
143
- | `remember` | `global` or `project` | Save an important durable fact or preference |
144
- | `recall` | `project`, `global`, or `all` | Display saved facts |
145
- | `forget` | Index ID or query | Remove a saved fact |
147
+ | Tool | Scope / Target | Description |
148
+ | :-------------- | :-------------------------------------- | :---------------------------------------------------------------- |
149
+ | `remember` | `global` or `project` | Save an important durable fact or preference |
150
+ | `recall` | `project`, `global`, `all`, `list_projects` | Display saved facts; read another project's store via `project: '<path>'` |
151
+ | `forget` | Index ID, range, or query | Remove a saved fact (e.g. `"3-30"` ranges; `force` for protected) |
152
+ | `update_fact` | Index ID, metadata id, or text | Rewrite a fact while preserving its original date and links |
153
+ | `memory_info` | - | Show storage paths, fact counts, RAG stats, and package version |
146
154
 
147
155
  ### 2. Hybrid RAG Knowledge Base Tools
148
156
 
@@ -150,13 +158,50 @@ The plugin has been verified inside the **Google Jules** cloud workspace environ
150
158
  | :---------------------- | :------------------------------ | :--------------------------------------------------------------------------- |
151
159
  | `ingest_document` | Local files, Web URLs, Raw text | Ingest into 3-tier index with ONNX vector embeddings & symbol extraction |
152
160
  | `query_knowledge_base` | Text / Code query | Perform hybrid RSF/RRF search (BM25 + Vector) to retrieve candidate sections |
153
- | `manage_knowledge_base` | Actions / Documents | List documents, delete entries, view DB stats, or export/import snapshots |
161
+ | `manage_knowledge_base` | Actions / Documents | Stats, list, read, delete documents, or export/import snapshots |
162
+ | `link_knowledge` | Facts + Document ranges | Explicitly link a memory fact to a KB document or line range |
163
+
164
+ ### 3. Native OpenCode Plugin
165
+
166
+ When installed as an OpenCode plugin, all MCP tools above plus `list-mcp-tools` and `mcp-reminder` are exposed. A chat hook (`experimental.chat.messages.transform`) automatically injects your saved memory into every conversation as a `<MEMORY>` block, so your agent starts each session already knowing your preferences and project context.
167
+
168
+ ---
169
+
170
+ ## GraphRAG Lite
171
+
172
+ The RAG engine includes a lightweight graph layer built on the same SQLite database. It combines code symbol extraction, hierarchy edges, and explicit memory-to-document links without requiring a separate graph store or an LLM at ingest time.
173
+
174
+ **Code Symbol Extraction** — during `ingest_document`, code symbols are extracted from the chunk content using fast regex heuristics (no language model needed):
175
+
176
+ - JavaScript / TypeScript: `function`, `class`, `interface`, `type`, `enum`, `const`, `let`, `var`
177
+ - Python: `def`, `class`
178
+ - Symbols shorter than 3 characters and reserved keywords (`const`, `let`, `var`, `function`, `class`, `import`, `export`, `from`, `return`, `if`, `for`, `while`, `def`, `self`) are filtered out.
179
+
180
+ **Graph Edges** — three built-in relation types are created automatically, and custom relation types are supported for explicit linking:
181
+
182
+ | Relation Type | Direction / Example |
183
+ | :------------------ | :----------------------------------------------------------- |
184
+ | `CONTAINS` | Document -> Section -> Micro-Chunk (3-tier hierarchy) |
185
+ | `DEFINES_SYMBOL` | Section -> `symbol:<name>` (extracted code symbol) |
186
+ | `LINKS_TO` (default) | Memory fact -> Document or line range (via `link_knowledge`) |
187
+
188
+ **Memory-to-Knowledge Linking** — the `link_knowledge` tool connects a notebook fact to a specific document or line range (`RULES_FOR`, `IMPLEMENTS`, `EXPLAINS`, `REFERENCES`, ...):
189
+
190
+ - `link` — create the link and its graph edge
191
+ - `list_links` — list all links, optionally filtered by fact key
192
+ - `get_doc_links` — list all links pointing to a given document
193
+
194
+ Linked facts are surfaced automatically in `recall` results as `🔗 [Linked Docs: ...]`, and `remember` accepts an optional `docId` to link immediately.
195
+
196
+ **Retrieval Integration** — `query_knowledge_base` augments each retrieved section with `defined_symbols`: the code symbols defined in that same section (a single-hop lookup along `DEFINES_SYMBOL` edges). Symbol extraction also improves BM25 scoring, since symbol names become searchable tokens.
197
+
198
+ **Lifecycle** — edges are rebuilt transactionally on re-ingest of the same document, and `manage_knowledge_base` delete operations clean up all graph edges and knowledge links owned by the document (including `GLOB`-matched section/micro-chunk suffixes).
154
199
 
155
200
  ---
156
201
 
157
- ## Interactive CLI & Engine Tuning
202
+ ## Interactive TUI (CLI Menu)
158
203
 
159
- Launch the interactive CLI terminal interface to manage engine settings, inspect databases, and tune retrieval parameters:
204
+ Launch the interactive terminal UI to manage engine settings, inspect databases, tune retrieval parameters, and run diagnostics:
160
205
 
161
206
  ```bash
162
207
  # From local repository folder:
@@ -170,23 +215,50 @@ memory_plugin cli
170
215
  memory-cli
171
216
  ```
172
217
 
173
- ### CLI Menu Overview
218
+ ### TUI Menu Overview
174
219
 
175
220
  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.
176
221
 
177
- | Block | Menu Item | Functionality |
178
- | :------------------ | :--------------------------- | :----------------------------------------------------------------------------- |
179
- | **Engine Settings** | Fusion Algorithm | Switch between `rsf`, `rrf`, `semantic_only`, `lexical_only`. |
180
- | | RSF Alpha Balance | Weight of semantic over lexical in `rsf` fusion (`α ∈ [0,1]`). Default: `0.5`. |
181
- | | Embedding Model | Select ONNX model (e.g. `Xenova/multilingual-e5-small`). |
182
- | | Reranker Model | Enable Cross-Encoder reranking or disable for zero-latency fusion. |
183
- | **Notebook** | Layer 1 Facts | Browse and manage `global` and per-project `.md` fact stores. |
184
- | **RAG Docs** | Layer 2 RAG Base | List ingested documents, inspect chunk counts, and purge entries. |
185
- | **Diagnostics** | Run Search Quality Benchmark | Execute in-process search evaluation across benchmark query set. |
186
- | | Verification Query | Run a test `hybridQuery` against the active index. |
187
- | | Clear Cache & Reset | Clear cached benchmark corpus or restore factory default config. |
222
+ | Block | Menu Item | Functionality |
223
+ | :-------------------------------------- | :------------------------------ | :----------------------------------------------------------------------------- |
224
+ | **Engine & Hybrid Search Settings** | Fusion Algorithm | Switch between `rsf`, `rrf`, `semantic_only`, `lexical_only`. |
225
+ | | RSF Alpha Balance | Weight of semantic over lexical in `rsf` fusion (`α ∈ [0,1]`). Default: `0.5`. |
226
+ | | Embedding Model | Select ONNX model (e.g. `Xenova/multilingual-e5-small`, custom HF models). |
227
+ | | Reranker Model | Enable Cross-Encoder reranking or disable for zero-latency fusion. |
228
+ | | Vector Batch Size | Ingestion vector batch size `[1 - 256]` (default `12`). |
229
+ | | GPU Attention Budget | GPU micro-batch attention budget `[1M - 16M]` (default `2.0M`, ~1.5 GB VRAM). |
230
+ | | CPU WASM Threads | ONNX WASM threads: `0` auto-detect or `1-16`. |
231
+ | | Execution Hardware | `cpu` or `webgpu` (experimental). |
232
+ | **Knowledge Base & Storage Management** | Notebook (Layer 1 Facts) | Browse and manage `global` and per-project `.md` fact stores. |
233
+ | | RAG Docs (Layer 2 Base) | List ingested documents, inspect chunk counts, and purge entries. |
234
+ | | Snapshot Export / Import | Export or restore the full RAG base + blob store as a JSON snapshot. |
235
+ | | Manage & Purge ML Model Cache | Inspect or purge downloaded ONNX model weights. |
236
+ | | Hard Reset | Purge RAG base, blob storage, and graph edges. |
237
+ | **Global Prompt & Integration** | Enable / Disable Global Prompt | Inject memory instructions into `~/.gemini/config/AGENTS.md`, `~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`. |
238
+ | **Diagnostics & System Actions** | Search Quality Benchmark | Execute in-process search evaluation across the benchmark query set. |
239
+ | | Verification Query | Run a test `hybridQuery` against the active index. |
240
+ | | Clear Benchmark Corpus Cache | Clear cached benchmark corpus. |
241
+ | | Reset Config to Factory Defaults| Restore default engine configuration. |
242
+
243
+ Settings persist to `<memory-dir>/config.json` and are immediately loaded by the MCP server.
244
+
245
+ ---
246
+
247
+ ## Configuration
248
+
249
+ The engine is configured through `<memory-dir>/config.json` (created with defaults on first run):
188
250
 
189
- Settings persist to `~/.config/opencode/memory/config.json` and are immediately loaded by the MCP server.
251
+ | Key | Default | Description |
252
+ | :-------------------- | :--------------------------------- | :-------------------------------------------------------------- |
253
+ | `fusionAlgorithm` | `rsf` | `rsf`, `rrf`, `semantic_only`, or `lexical_only` |
254
+ | `alpha` | `0.5` | Vector vs BM25 weight in RSF `[0.0 - 1.0]` |
255
+ | `embeddingModel` | `Xenova/multilingual-e5-small` | ONNX dense embedding model (E5 / BGE families supported) |
256
+ | `rerankerModel` | `none` | Cross-encoder reranker, or `Xenova/bge-reranker-base` |
257
+ | `rerankerEnabled` | `false` | Enable cross-encoder re-ranking |
258
+ | `batchSize` | `12` | Ingestion vector batch size `[1 - 256]` |
259
+ | `gpuAttentionBudget` | `2000000` | GPU micro-batch attention budget `[1M - 16M]` |
260
+ | `onnxThreads` | `0` | ONNX WASM threads: `0` auto-detect, or `1-16` |
261
+ | `executionDevice` | `cpu` | `cpu` or `webgpu` (experimental) |
190
262
 
191
263
  ---
192
264
 
@@ -241,7 +313,7 @@ Detailed technical documentation and architectural specifications are available
241
313
 
242
314
  ## Storage & Privacy
243
315
 
244
- - **100% Local Storage**: All SQLite indexes, ONNX models, CAS blobs, and Markdown notebooks are stored locally under `~/.config/opencode/memory/`.
316
+ - **100% Local Storage**: All SQLite indexes, ONNX models, CAS blobs, and Markdown notebooks are stored locally in the memory directory. The location resolves to, in order of priority: `$MEMORY_DIR`, `$OPENCODE_CONFIG_DIR/memory`, the legacy `~/.config/opencode/memory` (on Windows: `%LOCALAPPDATA%\opencode\memory`), or `$XDG_CONFIG_HOME/opencode/memory`.
245
317
  - **Dual-Source Failover Model Fetching**: Primary model weights are fetched from HuggingFace CDN with automatic failover to GitHub Repository Mirror.
246
318
  - **Zero External Telemetry**: No third-party network calls are required after initial model setup.
247
319
 
package/mcp-server/index.js CHANGED
@@ -39,13 +39,6 @@ if (cliArgs.includes("setup") || cliArgs.includes("install") || cliArgs.includes
39
39
  process.exit(0);
40
40
  }
41
41
 
42
- if (cliArgs.includes("admin") || cliArgs.includes("--admin") || cliArgs.includes("-a")) {
43
- const { startAdminServer } = await import("./admin/server.js");
44
- await startAdminServer();
45
- // Keep process running for web server
46
- await new Promise(() => {});
47
- }
48
-
49
42
  if (cliArgs.includes("cli") || cliArgs.includes("config") || cliArgs.includes("--cli") || cliArgs.includes("-c")) {
50
43
  const { runCli } = await import("./cli.js");
51
44
  await runCli();
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@lotargo/memory_plugin",
3
- "version": "1.3.1",
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.",
3
+ "version": "1.3.2",
4
+ "description": "100% local hybrid RAG memory for AI coding agents (OpenCode, Claude Code, Codex, Antigravity). MCP server + plugin: persistent user facts, document ingestion, vector + SQLite FTS5 retrieval across sessions.",
5
5
  "type": "module",
6
6
  "main": "opencode-plugin/index.js",
7
7
  "scripts": {
@@ -33,14 +33,29 @@
33
33
  "skills"
34
34
  ],
35
35
  "keywords": [
36
+ "memory",
37
+ "persistent-memory",
38
+ "ai-memory",
39
+ "ai-agent",
40
+ "ai-agents",
41
+ "rag",
42
+ "knowledge-base",
43
+ "llm",
44
+ "mcp",
45
+ "mcp-server",
46
+ "model-context-protocol",
47
+ "mcp-tools",
36
48
  "opencode",
37
49
  "claude-code",
38
50
  "codex",
39
51
  "antigravity",
40
52
  "plugin",
41
- "memory",
42
- "mcp",
43
- "ai",
53
+ "vector-search",
54
+ "hybrid-search",
55
+ "semantic-search",
56
+ "embeddings",
57
+ "sqlite",
58
+ "fts5",
44
59
  "context"
45
60
  ],
46
61
  "author": "Lotargo",
package/mcp-server/admin/server.js DELETED
@@ -1,228 +0,0 @@
1
- import { createServer } from "node:http";
2
- import { readFileSync, existsSync, statSync } from "node:fs";
3
- import { join, dirname } from "node:path";
4
- import { fileURLToPath } from "node:url";
5
- import { getDatabase, DB_PATH, BLOBS_DIR } from "../db/database.js";
6
- import { ingestDocument, deleteDocument } from "../ingest/pipeline.js";
7
- import { hybridQuery } from "../retrieval/retriever.js";
8
- import { exportSnapshot, importSnapshot } from "./snapshot.js";
9
- import { readBlob } from "../storage/blob_store.js";
10
-
11
- const __filename = fileURLToPath(import.meta.url);
12
- const __dirname = dirname(__filename);
13
-
14
- export function findAvailablePort(startPort = 8765, maxPort = 8785) {
15
- return new Promise((resolve, reject) => {
16
- let port = startPort;
17
- const tryPort = () => {
18
- if (port > maxPort) {
19
- return reject(new Error(`No free port found between ${startPort} and ${maxPort}`));
20
- }
21
- const server = createServer();
22
- server.listen(port, () => {
23
- server.close(() => resolve(port));
24
- });
25
- server.on("error", () => {
26
- port++;
27
- tryPort();
28
- });
29
- };
30
- tryPort();
31
- });
32
- }
33
-
34
- function parseJsonBody(req) {
35
- return new Promise((resolve, reject) => {
36
- let body = "";
37
- req.on("data", (chunk) => {
38
- body += chunk.toString();
39
- });
40
- req.on("end", () => {
41
- try {
42
- resolve(body ? JSON.parse(body) : {});
43
- } catch (err) {
44
- reject(err);
45
- }
46
- });
47
- req.on("error", reject);
48
- });
49
- }
50
-
51
- export async function startAdminServer({ port = null, customDb = null, customBlobDir = BLOBS_DIR } = {}) {
52
- const db = customDb || getDatabase();
53
- const selectedPort = port || (await findAvailablePort());
54
- const htmlPath = join(__dirname, "index.html");
55
-
56
- const server = createServer(async (req, res) => {
57
- const url = new URL(req.url, `http://${req.headers.host || "localhost"}`);
58
- const pathname = url.pathname;
59
-
60
- // Helper for CORS and JSON response
61
- const sendJson = (data, status = 200) => {
62
- res.writeHead(status, {
63
- "Content-Type": "application/json",
64
- "Access-Control-Allow-Origin": "*",
65
- "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
66
- "Access-Control-Allow-Headers": "Content-Type",
67
- });
68
- res.end(JSON.stringify(data));
69
- };
70
-
71
- if (req.method === "OPTIONS") {
72
- res.writeHead(204, {
73
- "Access-Control-Allow-Origin": "*",
74
- "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
75
- "Access-Control-Allow-Headers": "Content-Type",
76
- });
77
- return res.end();
78
- }
79
-
80
- try {
81
- // 1. Static HTML SPA
82
- if (pathname === "/" || pathname === "/index.html") {
83
- if (!existsSync(htmlPath)) {
84
- res.writeHead(404, { "Content-Type": "text/plain" });
85
- return res.end("index.html not found");
86
- }
87
- const html = readFileSync(htmlPath, "utf-8");
88
- res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
89
- return res.end(html);
90
- }
91
-
92
- // 2. API: Stats
93
- if (pathname === "/api/stats" && req.method === "GET") {
94
- const docCount = db.prepare("SELECT COUNT(*) as cnt FROM documents").get().cnt;
95
- const secCount = db.prepare("SELECT COUNT(*) as cnt FROM sections").get().cnt;
96
- const chunkCount = db.prepare("SELECT COUNT(*) as cnt FROM micro_chunks").get().cnt;
97
- const edgeCount = db.prepare("SELECT COUNT(*) as cnt FROM graph_edges").get().cnt;
98
- let dbSize = 0;
99
- if (existsSync(DB_PATH)) {
100
- try {
101
- dbSize = statSync(DB_PATH).size;
102
- } catch {}
103
- }
104
- return sendJson({
105
- documents: docCount,
106
- sections: secCount,
107
- micro_chunks: chunkCount,
108
- graph_edges: edgeCount,
109
- db_size_bytes: dbSize,
110
- });
111
- }
112
-
113
- // 3. API: Documents List
114
- if (pathname === "/api/documents" && req.method === "GET") {
115
- const docs = db.prepare("SELECT * FROM documents ORDER BY updated_at DESC").all();
116
- return sendJson(docs);
117
- }
118
-
119
- // 4. API: Document Detail
120
- if (pathname.startsWith("/api/documents/") && req.method === "GET") {
121
- const docId = pathname.replace("/api/documents/", "");
122
- const doc = db.prepare("SELECT * FROM documents WHERE id = ?").get(docId);
123
- if (!doc) return sendJson({ error: "Document not found" }, 404);
124
-
125
- const sections = db.prepare("SELECT * FROM sections WHERE doc_id = ?").all(docId);
126
- const microChunks = db.prepare("SELECT id, section_id, token_count FROM micro_chunks WHERE doc_id = ?").all(docId);
127
- const edges = db.prepare("SELECT * FROM graph_edges WHERE source_id = ? OR target_id = ?").all(docId, docId);
128
-
129
- let blobContent = null;
130
- if (doc.blob_hash) {
131
- try {
132
- blobContent = await readBlob(doc.blob_hash, customBlobDir);
133
- } catch {}
134
- }
135
-
136
- return sendJson({ doc, sections, microChunks, edges, blobContent });
137
- }
138
-
139
- // 5. API: Delete Document
140
- if (pathname.startsWith("/api/documents/") && req.method === "DELETE") {
141
- const docId = pathname.replace("/api/documents/", "");
142
- const result = await deleteDocument(docId, db, customBlobDir);
143
- return sendJson(result);
144
- }
145
-
146
- // 6. API: Ingest Document
147
- if (pathname === "/api/ingest" && req.method === "POST") {
148
- const body = await parseJsonBody(req);
149
- const result = await ingestDocument({
150
- content: body.content,
151
- type: body.type || "text",
152
- path: body.path || null,
153
- title: body.title || null,
154
- generateEmbeddings: body.generateEmbeddings !== false,
155
- customDb: db,
156
- customBlobDir,
157
- });
158
- return sendJson(result, 201);
159
- }
160
-
161
- // 7. API: Query Knowledge Base
162
- if (pathname === "/api/query" && req.method === "POST") {
163
- const body = await parseJsonBody(req);
164
- const results = await hybridQuery({
165
- query: body.query,
166
- limit: body.limit || 5,
167
- generateEmbeddings: body.generateEmbeddings !== false,
168
- customDb: db,
169
- });
170
- return sendJson({ results });
171
- }
172
-
173
- // 8. API: Graph Visualizer Data
174
- if (pathname === "/api/graph" && req.method === "GET") {
175
- const docs = db.prepare("SELECT id, title, path FROM documents").all();
176
- const edges = db.prepare("SELECT * FROM graph_edges").all();
177
-
178
- const nodes = docs.map((d) => ({
179
- id: d.id,
180
- label: d.title || d.path || d.id,
181
- type: "DOCUMENT",
182
- }));
183
-
184
- // Add code symbol nodes
185
- const symbolEdges = edges.filter((e) => e.relation_type === "DEFINES_SYMBOL");
186
- for (const se of symbolEdges) {
187
- if (!nodes.some((n) => n.id === se.target_id)) {
188
- nodes.push({
189
- id: se.target_id,
190
- label: se.target_id,
191
- type: "CODE_SYMBOL",
192
- });
193
- }
194
- }
195
-
196
- return sendJson({ nodes, edges });
197
- }
198
-
199
- // 9. API: Export Snapshot
200
- if (pathname === "/api/snapshot/export" && (req.method === "GET" || req.method === "POST")) {
201
- const snapshot = await exportSnapshot({ customDb: db, customBlobDir });
202
- return sendJson(snapshot);
203
- }
204
-
205
- // 10. API: Import Snapshot
206
- if (pathname === "/api/snapshot/import" && req.method === "POST") {
207
- const body = await parseJsonBody(req);
208
- const result = await importSnapshot({ customDb: db, customBlobDir, snapshotPathOrData: body });
209
- return sendJson(result);
210
- }
211
-
212
- // 404 Fallback
213
- res.writeHead(404, { "Content-Type": "text/plain" });
214
- res.end("Not Found");
215
- } catch (err) {
216
- console.error("Admin server error:", err);
217
- sendJson({ error: err.message }, 500);
218
- }
219
- });
220
-
221
- return new Promise((resolve) => {
222
- server.listen(selectedPort, () => {
223
- const url = `http://localhost:${selectedPort}`;
224
- console.log(`🚀 memory-agent Web Admin Dashboard running at ${url}`);
225
- resolve({ server, port: selectedPort, url });
226
- });
227
- });
228
- }