@lotargo/memory_plugin

v1.6.6

Published

7 days ago

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.

Zero-Docker Local Hybrid RAG Engine & Long-Term Memory for AI Coding Agents

Automatically remembers durable user facts, ingests complex document repositories, and performs high-precision hybrid retrieval across sessions, platforms, and devices.

Overview

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.

@lotargo/memory_plugin gives your AI tools durable, persistent, local-first 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 / Gemini CLI) can query its own memory and hybrid knowledge base via the Model Context Protocol (MCP).

Project Scope & Runtime Notes: @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.
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.

Practical Use Cases

Architectural Decisions: "In this project, we use Fastify instead of Express and strict schema validation via Zod."
Coding Conventions: "Place all helper utilities inside src/utils/ and cover new functions with Vitest tests."
Environment Constraints: "Our target deployment environment is Node.js 20 on AWS Lambda."
User Profile & Tone: "My name is Alex. I prefer concise, direct answers without conversational filler."

Quick Start

Minimum System Requirements

Node.js: 22.5.0 or higher (required by the built-in node:sqlite module)
Package Manager: npm / npx (included with Node.js)
Supported Environment: OpenCode, Antigravity / Gemini CLI, Claude Code, Codex, or Google Jules

Installation & Auto-Setup

Run the setup command to configure all detected AI environments automatically:

# Recommended: Global installation & auto-setup across all environments
npm install -g @lotargo/memory_plugin && memory_plugin setup

# Or via npx
npx @lotargo/memory_plugin setup

To target a specific environment:

# Antigravity / Gemini CLI
memory_plugin setup --antigravity

# OpenCode
memory_plugin setup --opencode

# Claude Code
memory_plugin setup --claude

# Codex
memory_plugin setup --codex

Codex is configured with a direct executable chain (node → mcp-server/boot.js), not npx. This avoids Windows stdio handshake failures caused by .cmd launchers. Running setup again safely migrates legacy npx entries and preserves unrelated sections in ~/.codex/config.toml.

memory_plugin setup --codex updates only the Codex MCP registration, Codex prompt, and the Codex-compatible skill locations (~/.codex/skills and the shared ~/.agents/skills). It does not modify Claude Code, OpenCode, or Antigravity files.

To verify registration, the Node runtime, MCP initialization, tool discovery, and real memory_info / recall(scope="all") calls:

memory_plugin doctor --codex

The doctor checks the server process itself. If it passes but a fresh Codex Desktop task still does not expose the tools, the remaining fault is in Desktop tool exposure rather than the memory MCP launcher.

setup also accepts --gemini (alias for Antigravity) and --local (registers the MCP server in the project-local .agents/ directory). Without a specific flag, all detected environments are configured.

Headless & Cloud Setup (CI / Docker / Cloud Workspaces)

For headless environments (e.g., Google Jules, VPS, CI/CD pipelines), configure auth and sync mode in a single non-interactive command:

# Authenticate via Turso API token and set hybrid sync mode
memory_plugin setup --api-key <TURSO_API_TOKEN> --mode hybrid-sync

# Or set sync mode if already authorized
memory_plugin setup --mode only-cloud

Multi-Layer Architecture

Layer 1: Notebook Store (Durable Facts)
- Tools: remember, recall, get_fact, update_fact, forget, memory_info
- Scope: User preferences, identity, project conventions, system rules.
- Storage: Human-readable Markdown format (global and per-project stores).
- Fact Schema: Every fact is formatted as **Title** — body with inline metadata badges ([id], [ttl], [keep], [tags], [supersedes], [inject]).
- Project Identity: Project stores are bound to a Git-based project identity — the normalized remote URL (git:github.com/owner/repo) or git:local:<repo basename> — never to a directory path. Memories follow the repository across machines, OSes, and subdirectories. Legacy path/basename stores can be linked and merged via link_project_memory.
Layer 2: RAG Knowledge Base (Technical Documents & Codebases)
- Tools: ingest_document, query_knowledge_base, batch_query_knowledge_base, manage_knowledge_base, reindex_knowledge_base
- Capabilities: Ingests raw text files, Markdown, HTML, Web URLs, office documents (PDF, DOCX, XLSX, CSV), and codebases.
- Curation Model: Stores only project-relevant sources likely to be reused—for example important web findings and current library/framework documentation that may be newer than model training. Ingest the useful document or excerpt, then link it to the project memory it supports; do not archive everything the agent encounters.
- Scope Isolation: New documents default to the current linked Git project. scope: "all" searches global sources plus the current project's sources; outside a Git repository it searches global sources only. Use scope: "global" only for genuinely cross-project material.
- Stable Shared Sources: Ingesting the same path or URL in another scope reuses one document and adds a scope association. Re-ingesting updated content preserves the document ID and its fact links; removing one scope does not delete a document still used by another scope.
- 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.
Layer 3: Agent-Driven Knowledge Graph
- Tools: link_knowledge (plus docId, startLine, endLine in remember)
- Capabilities: Connects Layer 1 notebook facts directly to Layer 2 documents, sections, or exact line ranges with semantic edge relations (RULES_FOR, IMPLEMENTS, EXPLAINS, REFERENCES).
- Surfacing: Linked facts automatically highlight target documents and line ranges in recall output (🔗 [Linked Docs: ...]).

Cloud Synchronization & Database Modes (Turso / LibSQL)

The plugin provides local-first SQLite persistence with optional cloud database synchronization powered by Turso (LibSQL):

3 Storage Sync Modes

Cloud Failover & Circuit Breaker

When operating in cloud modes (only-cloud or hybrid-sync), the database engine incorporates a built-in Circuit Breaker:

If the primary cloud database endpoint is unreachable or encounters network failure, queries fail over to the secondary cloud endpoint configured in failoverUrl. Failover is disabled when failoverUrl is empty (the default).
In hybrid-sync the local SQLite copy keeps serving reads regardless; in only-cloud no local database is opened, so an outage with no failoverUrl surfaces as an error.
Prevents agent blocking or crash loops during internet outages or cloud service degradation.

Secure Credential Storage

Cloud authentication tokens are never written to config.json. They are stored in auth_secrets.enc, encrypted with AES-256-GCM using a key derived via PBKDF2-HMAC-SHA256 (600,000 iterations) from a stable machine fingerprint (OS machine ID + platform + architecture). The file is written with owner-only permissions (0600).

Note: this is not an OS keychain (DPAPI / Keychain / Secret Service). The fingerprint components are readable by other processes running as the same user, so the encryption protects against file exfiltration and casual inspection, not against a compromised local account. Secrets are bound to the machine — copying auth_secrets.enc to another computer will not decrypt.
Exception: the headless fallback via MEMORY_DIR/.env (TURSO_DB_URL, TURSO_DB_TOKEN, TURSO_API_TOKEN) stores credentials in plain text by design, for Docker/CI deployments.

Available Tools

The package currently exposes 17 unique tool names across its two integration surfaces:

| Integration surface | Tool count | Composition | | :------------------ | ---------: | :---------- | | MCP server (Codex, Claude Code, Antigravity / Gemini CLI and other MCP clients) | 15 | 6 Notebook + 4 identity/graph + 5 RAG tools | | Native OpenCode plugin | 17 | 15 shared memory/identity/RAG tools + 2 OpenCode-only helpers |

The two surfaces are intentionally counted separately. The OpenCode plugin exposes all 15 shared tools, including batch_query_knowledge_base, and adds the native list-mcp-tools and mcp-reminder helpers.

MCP Server Tools (15)

1. Memory Notebook Tools (Layer 1)

| Tool | Scope / Target | Key Parameters | Description | | :--- | :------------- | :------------- | :---------- | | remember | project / global | fact, title, scope, docId, startLine, endLine, relationType, ttl, keep, tags, supersedes | Save a durable fact or preference. Supports optional title, document linking, TTL, keep protection, tags, and version superseding. | | recall | all, project, global, list_projects | scope, project, query, tags, since, until, mode, offset, limit, includeSuperseded | Display saved facts with metadata badges and linked docs. Superseded facts are hidden by default; opt into history with includeSuperseded: true. Filtered results retain stable storage indices for safe forget operations. | | get_fact | all, project, global | id, scope | Retrieve full text, raw line, and metadata of a single fact by its metadata ID (e.g. "8f3a2c"). | | update_fact | project / global | id, newText, title, scope | Rewrite a fact (and optionally its **Title**) while preserving its original creation date, metadata, and knowledge links. | | forget | project / global | id / range / query, scope, force | Remove a fact by index number, ID, range (e.g. "3-30"), or query. Requires force: true for protected ([KEEP]) facts. | | memory_info | - | - | Show storage paths, fact counts, RAG statistics, git identity bindings, and package version. |

2. Project Identity Tools

3. RAG Knowledge Base & Graph Tools (Layers 2 & 3)

| Tool | Key Parameters | Description | | :--- | :------------- | :---------- | | ingest_document | content, type, title, path, scope, generateEmbeddings | Ingest local files, URLs, or raw text into the 3-tier index. Defaults to the current linked Git project; use scope: "global" for intentionally shared knowledge. | | query_knowledge_base | query, scope, limit, instruction, generateEmbeddings | Perform hybrid search (RSF/RRF BM25 + dense vectors). all means global plus the current project, while project and global restrict retrieval explicitly. | | batch_query_knowledge_base | queries (array), scope, limit, instruction, generateEmbeddings | Execute multiple scoped queries in one call. All embeddings are computed in one ONNX pass, making this the preferred API for comparisons and multi-part research. | | manage_knowledge_base | action, scope, docId, snapshotPath | Inspect, list, read, or unlink documents within the selected scope, or export/import complete snapshots. Delete defaults to the current project (global outside Git); broader removal requires explicit global or all. | | reindex_knowledge_base | model, dimension | Re-embed all stored vectors with the active (or specified) embedding model and vector dimension. Use after switching the embedding model or vector dimension so previously indexed documents remain retrievable. Preserves documents, FTS index, graph edges, and fact links. | | link_knowledge | action, factText, docId, scope, startLine, endLine, relationType | Create, list, or retrieve semantic graph links connecting Notebook facts to Knowledge Base documents, sections, or line ranges. Actions: link, list_links, get_doc_links. |

Native OpenCode Plugin Tools (17)

| Group | Count | Tools | | :---- | ----: | :---- | | Memory Notebook | 6 | remember, recall, get_fact, forget, update_fact, memory_info | | Project Identity & Knowledge Graph | 4 | link_knowledge, link_project_memory, unlink_project_memory, relink_project_memory | | RAG Knowledge Base | 5 | ingest_document, query_knowledge_base, batch_query_knowledge_base, manage_knowledge_base, reindex_knowledge_base | | OpenCode-only helpers | 2 | list-mcp-tools, mcp-reminder |

The OpenCode-only helpers have the following purpose:

CLI Command Reference

The plugin provides both direct non-interactive CLI commands and an interactive terminal UI (TUI):

# Executable commands (available globally or via npx)
memory_plugin <command> [options]
# or
memory-cli <command> [options]

Both binaries accept the same commands. memory_plugin with no command starts the MCP server on stdio; memory-cli with no command opens the interactive TUI. Use --help on either for the full usage text.

Secrets: prefer the environment variables TURSO_API_TOKEN, TURSO_DB_URL and TURSO_DB_TOKEN over --api-key / --db-token flags — arguments passed on the command line are visible in the process list and shell history. Without a flag or env var, login prompts for the token on stdin with echo disabled.

Direct Non-Interactive Commands

Interactive TUI (CLI Menu)

Launch the interactive terminal UI to manage engine settings, tune retrieval algorithms, inspect databases, and run diagnostics:

memory_plugin cli
# or
memory-cli

TUI Menu Navigation

Use Up / Down arrows to navigate, ENTER to select, and BACKSPACE to go back.

Engine & Hybrid Search Settings: Switch fusion algorithms (rsf, rrf, semantic_only, lexical_only), adjust RSF $\alpha$ balance, select ONNX embedding models, set a fixed embedding vector dimension, toggle Cross-Encoder rerankers, configure GPU attention budget, and set WASM threads.
Knowledge Base & Storage Management: Browse Layer 1 facts, manage Layer 2 RAG docs, re-embed all vectors after switching model/dimension ([REINDEX]), export/import JSON snapshots, purge model cache, or perform a hard reset.
Global Prompt & Integration: Toggle memory instruction sync across client configurations (~/.gemini/config/AGENTS.md, ~/.codex/AGENTS.md, ~/.claude/CLAUDE.md).
Diagnostics & System Actions: Execute a hybrid search verification query, run the graph & notebook linking check, and reset config to factory defaults.

Agent Skill & System Prompt Integration

Built-in Agent Skill (`using-memory`)

The plugin bundles a pre-configured Agent Skill located at skills/using-memory/SKILL.md. When installed in supported environments (such as Antigravity / Gemini CLI or OpenCode), coding agents automatically read this skill to:

Initialize Sessions: Invoke full-body recall(scope: "all") first, loading global memory plus only the current Git project's memory (or global-only outside Git).
Register Git Projects: Inspect memory_info after recall and automatically call link_project_memory when the current Git identity reports Registry: unlinked.
Proactively Save Context: Automatically call remember whenever you share durable facts, tech stack choices, or coding guidelines.
Curate and Use RAG Deliberately: Preserve important web findings and current technical documentation only when they are likely to matter again. Store project-specific sources in the current project scope, reserve global scope for reusable cross-project material, query with concept-dense searches, and avoid low-value bulk ingestion.
Architect Knowledge Graphs: Use link_knowledge or remember(docId, startLine, endLine) to connect concise project memories to their supporting technical sources.

Global System Prompt Synchronization

Run memory_plugin enable-prompt to automatically inject memory agent guidance into your global LLM configuration files:

~/.gemini/config/AGENTS.md (Antigravity / Gemini CLI)
~/.codex/AGENTS.md (Codex)
~/.claude/CLAUDE.md (Claude Code)

This ensures your coding assistant is always aware of its memory capabilities even in fresh workspace sessions.

GraphRAG Lite

The RAG engine includes a lightweight graph layer built on SQLite. It combines code symbol extraction, hierarchy edges, and explicit memory-to-document links without requiring external graph databases or LLM calls at ingest time.

Multilingual Code Symbol Parsing

During ingest_document, code symbols are extracted from code blocks using fast regex heuristics across the following language families:

JavaScript / TypeScript: function, class, interface, type, enum, const, let, var
Python: def, class
Go: struct, interface, func (including methods with receivers)
Rust: struct, enum, trait, fn (including async/pub)
C++: class, struct, namespace, functions and methods
Java & Kotlin: class, interface, record, enum, fun, synchronized methods
C#: class, interface, struct, record, methods (properties without a parameter list are not captured)
PHP: class, interface, trait, functions
Ruby: module, class, methods

Graph Edges

Supported Platforms

Configuration

The engine is configured through <memory-dir>/config.json (created with defaults on first run):

ingest_document(type: "file") reads only from the current working directory and the plugin data directory by default. This prevents a prompt-injected agent from pulling ~/.ssh/id_rsa or .env into the knowledge base (and, in hybrid-sync, into the cloud). Widen it deliberately via ingestAllowedPaths.

Testing & Benchmarking

To run the automated test suite and benchmarks locally, from the repository root:

# Unit + integration + cloud suites (18 files) — fast and fully offline
npm test

# End-to-end smoke test with REAL ONNX embeddings — run before a release
npm run smoke

# Search quality & ingestion benchmarks
npm run benchmark

Two testing modes, and why both exist

npm test runs every suite with generateEmbeddings: false. That keeps it fast and offline (no model download, no network), but it means the dense-vector half of the engine is never exercised — retrieval falls back to BM25-only.

npm run smoke covers exactly that blind spot: it ingests a document with real ONNX vectors and asserts that hybrid retrieval returns a non-zero cosine similarity, plus that a Russian query still reaches an English document (something BM25 cannot do). It also walks the full user journey — remember → recall → ingest → query → link → update → get → forget — and checks the ingest path guard.

This split is not academic: a regression in v1.5.3+ disabled vector search entirely (node:sqlite returns BLOBs as Uint8Array, and a Buffer.isBuffer() guard discarded every stored vector) while all offline suites stayed green. The smoke test exists so that class of failure cannot ship unnoticed again.

The smoke test reuses the model weights already cached in your data directory, so it does not re-download them. Point MEMORY_MODEL_CACHE at a cache directory to override the lookup; without any cache the weights are fetched once.

For complete methodology details and search quality evaluation metrics, see docs/BENCHMARKS.md.

Empirical Search Quality Results

Evaluated across a 32-document technical corpus (21 queries) using Mean Reciprocal Rank (MRR@5), Recall@5, and Normalized Discounted Cumulative Gain (NDCG@5):

| Retrieval Strategy | MRR@5 | Recall@5 | NDCG@5 | | :---------------------------- | :--------: | :---------: | :--------: | | BM25 Lexical Search Only | 0.6706 | 76.19% | 0.6934 | | Dense ONNX Vector Only | 0.8135 | 100.00% | 0.8612 | | Hybrid RRF ($k=60$) | 0.8810 | 95.24% | 0.8997 | | Hybrid RSF ($\alpha=0.5$) | 0.9286 | 100.00% | 0.9473 |

Storage & Privacy

Local-First Storage: All SQLite indexes, ONNX models, CAS blobs, and Markdown notebooks are stored locally in the memory directory. Resolution order: $MEMORY_DIR → $OPENCODE_CONFIG_DIR/memory → the legacy ~/.config/opencode/memory directory when it already exists (this takes precedence on Windows too) → %LOCALAPPDATA%\opencode\memory.
Model Weights: ONNX weights are downloaded on first use from https://huggingface.co and cached locally; later runs are fully offline.
Zero Telemetry: No third-party analytics or telemetry calls are made. The only outbound traffic is the one-off model download, plus Turso requests in the cloud sync modes.

Known Dependency Advisories

npm audit reports three high-severity advisories with no upstream fix available. Both affected packages are only reachable through explicit user action:

License

MIT