@lotargo/memory_plugin 1.6.4 → 1.6.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotargo/memory_plugin",
-  "version": "1.6.4",
+  "version": "1.6.5",
   "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.",
   "type": "module",
   "main": "opencode-plugin/index.js",
@@ -33,10 +33,10 @@
     "mcp-server/tools",
     "mcp-server/boot.js",
     "mcp-server/cli_boot.js",
-    "mcp-server/cli.js",
-    "mcp-server/codex_config.js",
-    "mcp-server/codex_diagnostics.js",
-    "mcp-server/index.js",
+    "mcp-server/cli.js",
+    "mcp-server/codex_config.js",
+    "mcp-server/codex_diagnostics.js",
+    "mcp-server/index.js",
     "mcp-server/fact_format.js",
     "mcp-server/identity.js",
     "mcp-server/logger.js",

package/skills/using-memory/SKILL.md

@@ -1,96 +1,100 @@
----
-name: using-memory
-description: Comprehensive guide for using the Memory, Hybrid RAG Knowledge Engine & MCP Helper tools (remember, recall, get_fact, forget, update_fact, memory_info, link_knowledge, link_project_memory, unlink_project_memory, relink_project_memory, ingest_document, query_knowledge_base, manage_knowledge_base, reindex_knowledge_base, list-mcp-tools, mcp-reminder). Trigger proactively whenever user preferences, project conventions, technology stack choices, or architecture decisions are introduced, or when querying ingested documentation, indexing files/repos, managing persistent knowledge, or looking up available MCP tool integrations.
----
-
-# Using Memory, Hybrid RAG Knowledge Engine & MCP Helper Tools
-
-You have access to a persistent dual-layer memory engine supercharged with an **Agent-Driven Knowledge Graph** and general MCP integration helpers:
-1. **Layer 1: Notebook Store (Key-Value Facts)**: Stores high-signal personal preferences, project conventions, and durable rules in clean Markdown.
+---
+name: using-memory
+description: Comprehensive guide for using the Memory, Hybrid RAG Knowledge Engine & MCP Helper tools (remember, recall, get_fact, forget, update_fact, memory_info, link_knowledge, link_project_memory, unlink_project_memory, relink_project_memory, ingest_document, query_knowledge_base, manage_knowledge_base, reindex_knowledge_base, list-mcp-tools, mcp-reminder). Trigger proactively whenever user preferences, project conventions, technology stack choices, or architecture decisions are introduced, or when querying ingested documentation, indexing files/repos, managing persistent knowledge, or looking up available MCP tool integrations.
+---
+
+# Using Memory, Hybrid RAG Knowledge Engine & MCP Helper Tools
+
+You have access to a persistent dual-layer memory engine supercharged with an **Agent-Driven Knowledge Graph** and general MCP integration helpers:
+1. **Layer 1: Notebook Store (Key-Value Facts)**: Stores high-signal personal preferences, project conventions, and durable rules in clean Markdown.
 2. **Layer 2: Curated RAG Knowledge Base**: Preserves selected external findings, documentation, repositories, and technical guides that are likely to matter again.
-3. **Layer 3: Agent-Driven Knowledge Graph**: Connects Notebook facts (Layer 1) to specific Knowledge Base documents, sections, and **exact line ranges** (Layer 2).
-4. **Integration Layer (General MCP Helpers)**: Quickly discovers connected MCP servers and identifies appropriate tools for specific tasks.
-
----
-
-## 1. Tool Selection Decision Matrix
-
-| Scenario / Intent | Target Tool | Key Parameters |
-|-------------------|-------------|----------------|
-| User shares identity, tech stack preference, or workflow rule | `remember` | `fact` (English), `title` (concise 2-5 word headline), `scope`, optional `docId`, `startLine`, `endLine` |
-| User asks what you remember about them, the project, or linked docs | `recall` | `scope` ("all", "global", "project", "list_projects"), `mode` ("full", "headers"), `offset`, `limit`, optional `query`, `tags`, `since`, `until`, `project` (at session start, MUST fetch all memories with `scope: "all"` without restrictive query filters) |
-| Get a single fact's text and metadata by ID | `get_fact` | `id` (metadata id e.g. "8f3a2c"), `scope` |
-| User corrects/updates an old saved fact | `update_fact` | `id` (number/id/text), `newText`, `scope` |
-| Replace a fact but keep a version trail | `remember` | `fact`, `supersedes` (number/id/text) |
-| Protect a fact from accidental `forget` | `remember` | `keep: true` |
-| Set a time-to-live on a fact | `remember` | `ttl` ("90d", "2w", "24h", "12m") |
-| Filter facts by keyword / tags / date | `recall` | `query`, `tags`, `since`, `until` |
-| Show storage paths, versions, fact & RAG stats, git identity | `memory_info` | — |
-| Connect a Notebook fact to a document, section, or line range | `link_knowledge` | `action` ("link", "list_links", "get_doc_links"), `factText`, `docId`, `startLine`, `endLine`, `relationType` |
+3. **Layer 3: Agent-Driven Knowledge Graph**: Connects Notebook facts (Layer 1) to specific Knowledge Base documents, sections, and **exact line ranges** (Layer 2).
+4. **Integration Layer (General MCP Helpers)**: Quickly discovers connected MCP servers and identifies appropriate tools for specific tasks.
+
+---
+
+## 1. Tool Selection Decision Matrix
+
+| Scenario / Intent | Target Tool | Key Parameters |
+|-------------------|-------------|----------------|
+| User shares identity, tech stack preference, or workflow rule | `remember` | `fact` (English), `title` (concise 2-5 word headline), `scope`, optional `directory` (workspace path), `docId`, `startLine`, `endLine` |
+| User asks what you remember about them, the project, or linked docs | `recall` | `scope` ("all", "global", "project", "list_projects"), `mode` ("full", "headers"), `offset`, `limit`, optional `query`, `tags`, `since`, `until`, `directory` / `project` (at session start, MUST fetch all memories with `scope: "all"` without restrictive query filters) |
+| Get a single fact's text and metadata by ID | `get_fact` | `id` (metadata id e.g. "8f3a2c"), `scope`, optional `directory` |
+| User corrects/updates an old saved fact | `update_fact` | `id` (number/id/text), `newText`, `scope`, optional `directory` |
+| Replace a fact but keep a version trail | `remember` | `fact`, `supersedes` (number/id/text), optional `directory` |
+| Protect a fact from accidental `forget` | `remember` | `keep: true` |
+| Set a time-to-live on a fact | `remember` | `ttl` ("90d", "2w", "24h", "12m") |
+| Filter facts by keyword / tags / date | `recall` | `query`, `tags`, `since`, `until`, optional `directory` |
+| Show storage paths, versions, fact & RAG stats, git identity | `memory_info` | optional `directory` |
+| Connect a Notebook fact to a document, section, or line range | `link_knowledge` | `action` ("link", "list_links", "get_doc_links"), `factText`, `docId`, `startLine`, `endLine`, `relationType`, optional `directory` |
 | Register current Git project identity / migrate legacy stores | `memory_info` then `link_project_memory` when `Registry: unlinked` | `directory`, optional `remote` |
-| Remove path alias or purge project identity | `unlink_project_memory` | `directory`, `purge` (boolean) |
-| Move or merge project memories to new target identity | `relink_project_memory` | `directory`, `remote` (target remote URL) |
-| User asks to index a documentation URL, file, or repository | `ingest_document` | `content` (text/file path/URL), `type` ("text", "file", "url"), `title`, `path`, `scope` (project default) |
-| User asks a complex question about indexed docs or code | `query_knowledge_base` | `query`, `scope` (all default), `limit`, `instruction`, `generateEmbeddings` |
-| User needs multiple queries executed in batch (comparisons, multi-topic) | `batch_query_knowledge_base` | `queries` (array), `scope` (all default), `limit`, `instruction`, `generateEmbeddings` |
-| Read full raw content of an ambiguous/abstract document | `manage_knowledge_base` | `action: "read_document"`, `docId` |
-| View DB stats, list indexed docs, read/delete docs, export/import snapshots | `manage_knowledge_base` | `action` ("stats", "list", "read_document", "delete", "export_snapshot", "import_snapshot"), `docId`, `snapshotPath` |
-| Re-embed all documents after switching embedding model / dimension | `reindex_knowledge_base` | `model`, `dimension` (optional; defaults to active config) |
-| Discover available MCP servers and their specific purposes | `list-mcp-tools` | — |
-| Ask which MCP tool / server is suitable for a specific task | `mcp-reminder` | `task` (string, e.g., "db migration") |
-
----
-
-## 2. Layer 1 & 3: Notebook Store & Agent-Driven Knowledge Graph (`remember`, `recall`, `update_fact`, `forget`, `memory_info`, `link_knowledge`)
-
-### Agent-Driven Knowledge Graph Architecture
-Automatic regex/heuristic algorithms alone CANNOT infer high-level semantic intent or cross-document relationships. **You (the AI Agent) are the primary architect of the Knowledge Graph.**
-
+| Remove path alias or purge project identity | `unlink_project_memory` | `directory`, `purge` (boolean) |
+| Move or merge project memories to new target identity | `relink_project_memory` | `directory`, `remote` (target remote URL) |
+| User asks to index a documentation URL, file, or repository | `ingest_document` | `content` (text/file path/URL), `type` ("text", "file", "url"), `title`, `path`, `scope` (project default), optional `directory` |
+| User asks a complex question about indexed docs or code | `query_knowledge_base` | `query`, `scope` (all default), `limit`, `instruction`, `generateEmbeddings`, optional `directory` |
+| User needs multiple queries executed in batch (comparisons, multi-topic) | `batch_query_knowledge_base` | `queries` (array), `scope` (all default), `limit`, `instruction`, `generateEmbeddings`, optional `directory` |
+| Read full raw content of an ambiguous/abstract document | `manage_knowledge_base` | `action: "read_document"`, `docId` |
+| View DB stats, list indexed docs, read/delete docs, export/import snapshots | `manage_knowledge_base` | `action` ("stats", "list", "read_document", "delete", "export_snapshot", "import_snapshot"), `docId`, `snapshotPath`, optional `directory` |
+| Re-embed all documents after switching embedding model / dimension | `reindex_knowledge_base` | `model`, `dimension` (optional; defaults to active config) |
+| Discover available MCP servers and their specific purposes | `list-mcp-tools` | — |
+| Ask which MCP tool / server is suitable for a specific task | `mcp-reminder` | `task` (string, e.g., "db migration") |
+
+---
+
+## 2. Layer 1 & 3: Notebook Store & Agent-Driven Knowledge Graph (`remember`, `recall`, `update_fact`, `forget`, `memory_info`, `link_knowledge`)
+
+### Agent-Driven Knowledge Graph Architecture
+Automatic regex/heuristic algorithms alone CANNOT infer high-level semantic intent or cross-document relationships. **You (the AI Agent) are the primary architect of the Knowledge Graph.**
+
 When an ingested source supports a durable project decision or rule, link the corresponding Notebook fact directly to the RAG document and, when useful, its exact line range. The Notebook fact is the concise orientation point; the linked RAG source is its detailed evidence and technical context.
-
-### What to Save and Link (`remember` & `link_knowledge`)
-- **High-Signal Facts**: User name, role, language preferences, architectural constraints, framework choices, coding standards, test rules.
-- **Formatting & Fact Titles**:
-  - Always translate the fact into clear, concise English before calling `remember`.
-  - **Always specify a descriptive `title` parameter** (a 2-5 word headline, e.g., `title: "Backend Framework Preference"`).
+
+### What to Save and Link (`remember` & `link_knowledge`)
+- **High-Signal Facts**: User name, role, language preferences, architectural constraints, framework choices, coding standards, test rules.
+- **Formatting & Fact Titles**:
+  - Always translate the fact into clear, concise English before calling `remember`.
+  - **Always specify a descriptive `title` parameter** (a 2-5 word headline, e.g., `title: "Backend Framework Preference"`).
   - Facts are stored in `**Title** — body` format. Initial session recall and auto-injected `<MEMORY>` blocks MUST include full fact bodies. Header-only recall was tested and rejected because it loses essential context. Use `mode: "headers"` only when the user explicitly asks for a compact inventory, never for session initialization.
-- **Linking to Knowledge Base Documents**:
-  - Pass `docId` (or document title/path) and optional `startLine` / `endLine` when calling `remember` or `link_knowledge`.
-  - Example: `remember(title: "Backend Framework Preference", fact: "Use Fastify instead of Express for backend services", scope: "project", docId: "arch_specs.md", startLine: 5, endLine: 7)`
-  - Example: `link_knowledge(factText: "Use PostgreSQL 16 for primary persistence", docId: "database_guide.md", startLine: 20, endLine: 35, relationType: "IMPLEMENTS")`
-
-### How Linked Memory Appears (`recall`)
-When `recall` is invoked, the engine returns saved facts along with their Agent-linked Knowledge Base documents and exact line ranges:
-```
---- memory_plugin ---
-1. Use Fastify instead of Express for backend services 🔗 [Linked Docs: Project Architecture Specs:L5-7]
-2. PostgreSQL 16 is primary database 🔗 [Linked Docs: database_guide.md:L20-35]
-```
-
-### Fact Line Format & Metadata
-Each fact is stored as a single Markdown line with an optional invisible HTML comment carrying metadata:
-```
-- [2026-08-02 06:08] user prefers TypeScript <!-- id:8f3a2c, ttl:90d, keep:1, tags:pref,arch -->
-```
-Supported metadata keys (set via `remember`, rendered as badges by `recall`):
-- `id` — auto-generated short id; stable reference for `update_fact` / `forget` / `supersedes`.
-- `ttl` — time-to-live ("90d", "2w", "24h", "12m", bare number = days). Expired facts are marked `[EXPIRED]` but never auto-deleted.
-- `keep` — protection flag; `forget` skips it unless `force: true`.
-- `tags` — comma-separated free-form tags for filtering.
-- `supersedes` / `supersededBy` — versioning: the old fact gets `[SUPERSEDED]` and is excluded from the injected memory block while staying in the store for history.
-
-### Remember Options (`remember`)
-- `ttl`: "90d", "2w", "24h", "12m" — mark the fact for expiry; it will show `[EXPIRED]` once past.
-- `keep: true`: protect the fact from `forget` (unless `force: true`).
-- `tags`: comma-separated tags for later filtering, e.g. `"pref,arch"`.
-- `supersedes`: number (as listed by `recall`), metadata `id`, or text of the fact this one replaces.
-
-### Filtering & Viewing Facts (`recall` & `get_fact`)
-- `scope`: `"all"` (default), `"global"`, `"project"`, or `"list_projects"` (lists all project stores, total facts, file paths, and git identity bindings).
-- `query`: all space-separated terms must match (case-insensitive); searches text, id, tags, and date.
-- `tags`: comma-separated; returns facts with ANY matching tag.
-- `since` / `until`: "YYYY-MM-DD" (inclusive) to filter by fact date.
-- `project`: read a specific project's store from any working directory.
+- **Targeting Project Directory (`directory`)**:
+  - Pass `directory: "<project directory path>"` (or `project`) when calling `remember` or `recall` to ensure the call routes to the target project store even when the MCP server runs in an external folder or outside Git.
+  - Example: `remember(title: "Backend Framework Preference", fact: "Use Fastify instead of Express for backend services", scope: "project", directory: "F:/projects/my-app")`
+- **Linking to Knowledge Base Documents**:
+  - Pass `docId` (or document title/path) and optional `startLine` / `endLine` when calling `remember` or `link_knowledge`.
+  - Example: `remember(title: "Backend Framework Preference", fact: "Use Fastify instead of Express for backend services", scope: "project", docId: "arch_specs.md", startLine: 5, endLine: 7)`
+  - Example: `link_knowledge(factText: "Use PostgreSQL 16 for primary persistence", docId: "database_guide.md", startLine: 20, endLine: 35, relationType: "IMPLEMENTS")`
+
+### How Linked Memory Appears (`recall`)
+When `recall` is invoked, the engine returns saved facts along with their Agent-linked Knowledge Base documents and exact line ranges:
+```
+--- memory_plugin ---
+1. Use Fastify instead of Express for backend services 🔗 [Linked Docs: Project Architecture Specs:L5-7]
+2. PostgreSQL 16 is primary database 🔗 [Linked Docs: database_guide.md:L20-35]
+```
+
+### Fact Line Format & Metadata
+Each fact is stored as a single Markdown line with an optional invisible HTML comment carrying metadata:
+```
+- [2026-08-02 06:08] user prefers TypeScript <!-- id:8f3a2c, ttl:90d, keep:1, tags:pref,arch -->
+```
+Supported metadata keys (set via `remember`, rendered as badges by `recall`):
+- `id` — auto-generated short id; stable reference for `update_fact` / `forget` / `supersedes`.
+- `ttl` — time-to-live ("90d", "2w", "24h", "12m", bare number = days). Expired facts are marked `[EXPIRED]` but never auto-deleted.
+- `keep` — protection flag; `forget` skips it unless `force: true`.
+- `tags` — comma-separated free-form tags for filtering.
+- `supersedes` / `supersededBy` — versioning: the old fact gets `[SUPERSEDED]` and is excluded from the injected memory block while staying in the store for history.
+
+### Remember Options (`remember`)
+- `directory` / `project`: optional workspace/project directory path to target when saving project facts from outside cwd.
+- `ttl`: "90d", "2w", "24h", "12m" — mark the fact for expiry; it will show `[EXPIRED]` once past.
+- `keep: true`: protect the fact from `forget` (unless `force: true`).
+- `tags`: comma-separated tags for later filtering, e.g. `"pref,arch"`.
+- `supersedes`: number (as listed by `recall`), metadata `id`, or text of the fact this one replaces.
+
+### Filtering & Viewing Facts (`recall` & `get_fact`)
+- `scope`: `"all"` (default), `"global"`, `"project"`, or `"list_projects"` (lists all project stores, total facts, file paths, and git identity bindings).
+- `directory` / `project`: read a specific project's store from any working directory.
+- `query`: all space-separated terms must match (case-insensitive); searches text, id, tags, and date.
+- `tags`: comma-separated; returns facts with ANY matching tag.
+- `since` / `until`: "YYYY-MM-DD" (inclusive) to filter by fact date.
 - `mode`: `"full"` (default) or `"headers"` (returns title and badges only, omitting full text body).
 - `includeSuperseded`: `false` by default so obsolete history does not enter active context; set `true` only to inspect version history.
 - `offset` / `limit`: optional numeric pagination parameters.