@lotargo/memory_plugin 1.6.8 → 1.6.10

package/CHANGELOG.md

@@ -5,7 +5,18 @@ All notable changes to `@lotargo/memory_plugin` are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.6.10] - 2026-09-08
+
+### Fixed
+
+- Fixed OAuth callback rejecting every real Turso login: Turso redirects to `/?jwt=<JWT>&username=<USERNAME>` without echoing `state`, so a missing state is now accepted with a warning (the token is still validated against the Turso API); only a present-but-mismatched state is rejected as CSRF.
+
+## [1.6.9] - 2026-09-08
+
+### Fixed
+
+- Fixed Turso browser OAuth on Windows: URLs no longer go through `cmd.exe` (which truncated the query string at `&`), browser launch now uses `rundll32.exe url.dll,FileProtocolHandler`. The OAuth loopback server now binds an ephemeral port before the login URL is built, eliminating the listen race and `EADDRINUSE` on the fixed port.
+- Made the `policy_retrieval` unit test offline-deterministic: ingestion now runs with `generateEmbeddings: false` (BM25/policy path only) and DB/temp cleanup is guaranteed via `try/finally`, so a corrupted ONNX model cache no longer fails the suite and blocks the runner.
 
 ## [1.6.8] - 2026-08-25
 
@@ -289,6 +300,8 @@ a critical retrieval regression introduced after `v1.5.3`.
 - `BENCHMARKS.md` tables were re-derived from the stored JSON artifacts; the
   bge-m3 section had carried e5-small numbers shifted by a column.
 
+[1.6.10]: https://github.com/Lotargo/memory_plugin/releases/tag/v1.6.10
+[1.6.9]: https://github.com/Lotargo/memory_plugin/releases/tag/v1.6.9
 [1.6.8]: https://github.com/Lotargo/memory_plugin/releases/tag/v1.6.8
 [1.6.7]: https://github.com/Lotargo/memory_plugin/releases/tag/v1.6.7
 [1.6.1]: https://github.com/Lotargo/memory_plugin/releases/tag/v1.6.1

package/README.md

@@ -1,10 +1,6 @@
 <div align="center">
 
-<img src="https://raw.githubusercontent.com/Lotargo/memory_plugin/main/assets/hero.jpg" alt="@lotargo/memory_plugin" width="800" style="max-width: 100%; border-radius: 12px; margin-bottom: 16px;">
-
-<br>
-
-<img src="https://raw.githubusercontent.com/Lotargo/memory_plugin/main/assets/title.svg" alt="@lotargo/memory_plugin" width="520" style="max-width: 100%; margin-bottom: 12px;">
+<img src="./assets/01_hero_banner.png" alt="memory_plugin architecture — persistent memory, RAG, persona and CLI runtime" width="100%">
 
 <br>
 
@@ -15,8 +11,6 @@
 [![mcp](https://img.shields.io/badge/MCP-Supported-8A2BE2)](https://modelcontextprotocol.io)
 [![storage](https://img.shields.io/badge/Storage-Local%20%2B%20Cloud%20Sync-success)](#storage-privacy-and-security)
 
-<br>
-
 **Local-first long-term memory, hybrid RAG, and agent personalization for AI coding agents**
 
 One memory system for OpenCode, Codex, Claude Code, Gemini CLI, Antigravity, Google Jules, and other MCP clients.
@@ -25,6 +19,16 @@ One memory system for OpenCode, Codex, Claude Code, Gemini CLI, Antigravity, Goo
 
 # @lotargo/memory_plugin — Local-First Memory, Hybrid RAG & Agent Personalization
 
+<p align="center">
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#memory-architecture">Memory Architecture</a> ·
+  <a href="#persona-and-agent-personalization">Persona</a> ·
+  <a href="#retrieval-and-knowledge-graph">RAG & Retrieval</a> ·
+  <a href="#cloud-synchronization">Cloud Sync</a> ·
+  <a href="#client-integration">Clients</a> ·
+  <a href="#storage-privacy-and-security">Security</a>
+</p>
+
 ---
 
 ## Why This Project Exists
@@ -41,6 +45,10 @@ AI coding assistants forget user preferences, architectural decisions, investiga
 
 The same engine adds Git-based project isolation, semantic search, full raw-source expansion, explicit fact-to-document links, optional Turso synchronization, and native OpenCode auto-injection.
 
+### Architecture at a Glance
+
+<img src="./assets/02_project_evolution.png" alt="Evolution of memory_plugin from notebook memory through RAG, persona and cross-client agent state" width="100%">
+
 ### Highlights
 
 - Human-readable Markdown Notebook facts with stable IDs, TTL, protection, tags, superseding, and explicit `fact` / `directive` semantics.
@@ -68,75 +76,83 @@ The same engine adds Git-based project isolation, semantic search, full raw-sour
 
 CPU execution with `Xenova/multilingual-e5-small` is the recommended stable default. WebGPU execution is experimental.
 
-### Install and Configure
+### Install / Uninstall All Clients
 
-Configure every supported client location:
+The normal installation path is one command. It configures every supported client directly, so there is no separate package-only installation step:
 
 ```bash
-npm install -g @lotargo/memory_plugin
-memory_plugin setup
+npx -y @lotargo/memory_plugin setup
 ```
 
-Or run setup without a permanent global installation:
+This registers memory_plugin in OpenCode, Codex, Claude Code, Gemini CLI, and Antigravity, installs the bundled `using-memory` skill, and adds managed memory instructions where supported. Existing unrelated configuration is preserved.
+
+Remove the integration from all clients while keeping Notebook/RAG data:
 
 ```bash
-npx @lotargo/memory_plugin setup
+npx -y @lotargo/memory_plugin uninstall
 ```
 
-Target one client when needed:
+Remove the integrations and delete local memory data:
 
 ```bash
-memory_plugin setup --opencode
-memory_plugin setup --codex
-memory_plugin setup --claude
-memory_plugin setup --antigravity
-memory_plugin setup --gemini        # Gemini CLI (~/.gemini/settings.json)
+npx -y @lotargo/memory_plugin uninstall --purge --yes
 ```
 
-Use `--local` with Antigravity setup to create the workspace-local `.agents/mcp_config.json` even when `.agents/` does not yet exist.
+Preview the uninstall without changing anything:
 
-Claude Code, Gemini CLI, and Codex setup/uninstall use their native MCP lifecycle commands when available. An ownership-checked config edit is retained as a compatibility fallback for missing, older, or non-functional client CLIs. Antigravity remains a separate integration because it uses a different config layout.
+```bash
+npx -y @lotargo/memory_plugin uninstall --dry-run
+```
+
+What `uninstall` removes by default (without `--purge`):
+
+- `~/.config/opencode/opencode.json` - plugin entry, including `file://` dev links.
+- `~/.claude.json` - `mcpServers.memory-agent`.
+- `~/.gemini/settings.json` - Gemini CLI `mcpServers.memory-agent`.
+- `~/.gemini/config/mcp_config.json` and `.agents/mcp_config.json` - Antigravity `mcpServers.memory-agent`.
+- `~/.codex/config.toml` - `[mcp_servers.memory-agent]` only when owned by this plugin.
+- Managed prompt blocks from Codex, Claude Code, Gemini CLI, and Antigravity instruction files.
+- The bundled `using-memory` skill from each client's managed `skills/` directory.
 
-Setup also installs the bundled `using-memory` skill and managed memory instructions for the selected clients. Existing unrelated configuration is preserved.
+Existing user content outside plugin-owned markers is preserved. Foreign `memory-agent` registrations, modified/non-owned skills, unrelated file plugins, and other packages in the `@lotargo` OpenCode cache namespace are left untouched.
 
-### Uninstall
+Normal uninstall keeps OpenCode's package cache. `--purge-cache` removes only exact cache directories owned by this package. With `--purge`, the plugin also deletes `MEMORY_DIR` and its prompt state after resolving and validating every target, rejecting dangerous roots and broad parent paths, and displaying the targets before confirmation.
 
-Remove the plugin from one or all clients without deleting Notebook/RAG data:
+On Linux/macOS, `XDG_CONFIG_HOME` and `XDG_CACHE_HOME` are respected. `OPENCODE_CONFIG_DIR` and `MEMORY_DIR` remain explicit overrides on every platform.
+
+### Install One Client
+
+Use the same one-shot setup command with a client flag when you only want one integration:
 
 ```bash
-memory_plugin uninstall --dry-run   # preview
-memory_plugin uninstall             # remove all clients, keep data
-memory_plugin uninstall --purge --yes  # also delete local data (MEMORY_DIR, prompt state)
-memory_plugin uninstall --opencode --purge-cache  # explicitly remove this plugin's OpenCode cache
-memory_plugin uninstall --opencode --claude  # only selected clients
-npx @lotargo/memory_plugin uninstall --dry-run
-memory_plugin setup --uninstall --purge  # alias
+npx -y @lotargo/memory_plugin setup --opencode
+npx -y @lotargo/memory_plugin setup --codex
+npx -y @lotargo/memory_plugin setup --claude
+npx -y @lotargo/memory_plugin setup --antigravity
+npx -y @lotargo/memory_plugin setup --gemini
 ```
 
-What `uninstall` removes by default (without `--purge`):
-
-- `~/.config/opencode/opencode.json` — plugin entry (including `file://` dev link)
-- `~/.claude.json` — `mcpServers.memory-agent`
-- `~/.gemini/settings.json` — Gemini CLI `mcpServers.memory-agent`
-- `~/.gemini/config/mcp_config.json` and `.agents/mcp_config.json` — Antigravity `mcpServers.memory-agent`
-- `~/.codex/config.toml` — `[mcp_servers.memory-agent]` (only if owned by this plugin)
-- Managed prompt blocks from `~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`, `~/.gemini/GEMINI.md`, and `~/.gemini/config/AGENTS.md`
-- `using-memory` skill from each client's `skills/` directory
+Use `--local` with Antigravity to create the workspace-local `.agents/mcp_config.json` even when `.agents/` does not yet exist:
 
-Existing user content outside the managed prompt/persona markers is preserved. Foreign `memory-agent` registrations, modified/non-owned `using-memory` skills, unrelated file plugins, and other packages in the `@lotargo` OpenCode cache namespace are left untouched.
+```bash
+npx -y @lotargo/memory_plugin setup --antigravity --local
+```
 
-Normal uninstall keeps OpenCode's package cache, matching the host lifecycle. `--purge-cache` removes only exact cache directories owned by this package; unrelated packages, including other packages in the `@lotargo` namespace, remain untouched.
+The same client flags can be used for targeted removal, for example:
 
-With `--purge` it also deletes `MEMORY_DIR` (`~/.config/opencode/memory` by default) and the memory-agent prompt state. Purge resolves and validates every target before changing client configuration, rejects filesystem roots, home/workspace/config roots and broad top-level paths, follows symlinks for validation, and prints the exact targets before interactive confirmation. The npm package itself is removed separately with `npm uninstall -g @lotargo/memory_plugin`. Restart clients after uninstall.
+```bash
+npx -y @lotargo/memory_plugin uninstall --opencode
+npx -y @lotargo/memory_plugin uninstall --codex
+```
 
-On Linux/macOS, `XDG_CONFIG_HOME` and `XDG_CACHE_HOME` are respected for OpenCode configuration, prompt state, and package-cache cleanup. `OPENCODE_CONFIG_DIR` and `MEMORY_DIR` remain explicit overrides on every platform.
+Claude Code, Gemini CLI, and Codex setup/uninstall use their native MCP lifecycle commands when available. An ownership-checked config edit is retained as a compatibility fallback for missing, older, or non-functional client CLIs. Antigravity remains a separate integration because it uses a different config layout.
 
 ### Verify Codex
 
 Codex uses a direct executable chain (`node` -> `mcp-server/boot.js`) instead of an `npx`/`.cmd` launcher, avoiding Windows stdio handshake failures. Setup safely migrates legacy registrations in `~/.codex/config.toml`.
 
 ```bash
-memory_plugin doctor --codex
+npx -y @lotargo/memory_plugin doctor --codex
 ```
 
 The doctor validates the configured Node runtime, MCP initialization, tool discovery, and real `memory_info` and `recall(scope: "all")` calls.
@@ -145,10 +161,11 @@ The doctor validates the configured Node runtime, MCP initialization, tool disco
 
 ```bash
 # Authenticate with a Turso account token and enable hybrid sync
-memory_plugin setup --api-key <TURSO_API_TOKEN> --mode hybrid-sync
+# (--api-token and --token are accepted as aliases for --api-key)
+npx -y @lotargo/memory_plugin setup --api-key <TURSO_API_TOKEN> --mode hybrid-sync
 
 # Or change mode when credentials already exist
-memory_plugin setup --mode only-cloud
+npx -y @lotargo/memory_plugin setup --mode only-cloud
 ```
 
 Prefer `TURSO_API_TOKEN`, `TURSO_DB_URL`, and `TURSO_DB_TOKEN` environment variables over command-line secrets because shell arguments may appear in process lists and history.
@@ -168,6 +185,10 @@ After code changes, restart OpenCode to reload the module. Codex, Claude Code, G
 
 ## Memory Architecture
 
+<img src="./assets/03_hot_memory_vs_cold_rag.png" alt="Hot persistent memory versus cold RAG retrieval architecture in memory_plugin" width="100%">
+
+The architecture deliberately separates **small, always-useful context** from **large, on-demand knowledge**. This keeps session initialization useful without turning persistent memory into an ever-growing prompt.
+
 ### 1. Hot Notebook Memory
 
 Notebook memory stores concise, high-signal context in Markdown:
@@ -238,15 +259,19 @@ This keeps startup context small while preserving the complete reasoning trail w
 
 ## Persona and Agent Personalization
 
+<img src="./assets/04_fact_vs_directive.png" alt="Fact versus directive semantics in memory_plugin" width="100%">
+
 Notebook entries have explicit semantics:
 
 ```text
-kind: "fact"       # descriptive context
-kind: "directive"  # active user-approved personality or working configuration
+kind: "fact"       # descriptive context — what the agent knows
+kind: "directive"  # active configuration — how the agent should behave
 ```
 
 Use `kind: "directive"` for personality, behavior, tone, communication style, preferences, or working conventions the agent should actively apply. Explicit `kind` is authoritative; persuasive wording alone does not turn a fact into an instruction.
 
+<img src="./assets/05_persona_as_runtime_state.png" alt="The same model with neutral, coding-focused and personalized runtime state" width="100%">
+
 ### OpenCode
 
 The native plugin performs complete session initialization automatically:
@@ -425,7 +450,7 @@ The MCP server exposes **16 tools**. The native OpenCode plugin exposes the same
 
 ## CLI Reference
 
-`memory_plugin` and `memory-agent` are MCP stdio entry points. `memory_plugin setup` performs client installation, while `memory_plugin cli` or `memory-cli` opens the interactive control panel. Direct administration commands should use `memory-cli`.
+`memory_plugin` and `memory-agent` are MCP stdio entry points. The Quick Start uses `npx -y @lotargo/memory_plugin ...`, so a separate global npm installation is not required. If the package is installed globally for development or administration, `memory_plugin setup` performs client installation, while `memory_plugin cli` or `memory-cli` opens the interactive control panel. Direct administration commands should use `memory-cli`.
 
 | Command | Purpose |
 | :--- | :--- |
@@ -539,7 +564,9 @@ Spreadsheet ingestion uses SheetJS CE `0.20.3` from the official SheetJS CDN rat
 
 ---
 
-## Testing and Benchmarks
+## Repository Testing and Benchmarks
+
+> These commands are intended for a **source checkout of the repository**. Test suites and benchmark harnesses are intentionally excluded from the published npm tarball.
 
 ```bash
 npm test                   # unified unit, integration, and simulated-cloud suites
@@ -551,7 +578,7 @@ npm run benchmark:table-code
 
 The fast suites use `generateEmbeddings: false` in retrieval paths for deterministic offline coverage. `npm run smoke` covers the dense-vector path with real cached/downloaded model weights and checks multilingual semantic retrieval. Both modes are needed: lexical-only tests cannot catch a broken vector serialization or ONNX execution path.
 
-The unified suites cover fact formatting, typed directives, persona migration/synchronization, client prompt safety, Codex launcher compatibility, Git identity isolation, RAG scopes, policy expansion, RAG Memory Notes, semantic index output, raw blob portability, reverse sync, tombstones, snapshots, MCP contracts, and cloud authentication workflows.
+The unified suites cover fact formatting, typed directives, persona migration/synchronization, client prompt safety, Codex launcher compatibility, Git identity isolation, RAG scopes, policy expansion, RAG Memory Notes, semantic index output, raw blob portability, reverse sync, tombstones, snapshots, MCP contracts, spreadsheet parsing, and cloud authentication workflows.
 
 See [`docs/BENCHMARKS.md`](./docs/BENCHMARKS.md) for methodology and detailed reports.
 
@@ -571,7 +598,7 @@ The stored 32-document / 21-query technical corpus produced:
 ## Troubleshooting
 
 - **`No such built-in module: node:sqlite`**: install Node.js `22.5.0` or newer.
-- **Codex tools are missing**: run `memory_plugin setup --codex`, then `memory_plugin doctor --codex`, and open a new Codex task.
+- **Codex tools are missing**: run `npx -y @lotargo/memory_plugin setup --codex`, then `npx -y @lotargo/memory_plugin doctor --codex`, and open a new Codex task.
 - **OpenCode still runs old code**: restart OpenCode. For repository development, confirm `npm run dev:link` points its plugin entry to `opencode-plugin/main.js`.
 - **Persona changes are not visible**: run `memory-cli sync-persona`, then start a new CLI session/task. Use `memory-cli migrate-persona --dry-run` for legacy entries.
 - **Project recall is empty**: call `memory_info`; if a Git identity is `Registry: unlinked`, run `link_project_memory` or `memory-cli link --dir <repo>`.