oh-memos-mcp 2.0.1 → 3.0.0

package/.env.example

@@ -1,27 +1,44 @@
-# ============================================================================
-# oh-memos-mcp Environment Configuration
-# ============================================================================
-# Copy this file to .env in your project root and adjust values.
-# Priority: CLI args > environment variables > defaults
-# ============================================================================
-
-# --- Required ---
-MEMOS_URL=http://localhost:18000        # oh-memos API address
-MEMOS_USER=dev_user                     # Default user ID
-MEMOS_DEFAULT_CUBE=dev_cube             # Default memory cube ID
-MEMOS_CUBES_DIR=/path/to/cubes          # Absolute path to cubes directory
-
-# --- Timeouts (seconds) ---
-# MEMOS_TIMEOUT_TOOL=300                # Tool call timeout (default: 300)
-# MEMOS_TIMEOUT_STARTUP=30              # Startup timeout (default: 30)
-# MEMOS_TIMEOUT_HEALTH=5                # Health check timeout (default: 5)
-# MEMOS_API_WAIT_MAX=60                 # Max API wait time (default: 60)
-
-# --- Feature Flags ---
-# MEMOS_ENABLE_DELETE=false             # Enable memory deletion (default: false)
-# MEMOS_LOG_LEVEL=WARNING               # DEBUG | INFO | WARNING | ERROR
-
-# --- Neo4j (optional, for direct graph queries) ---
-# NEO4J_HTTP_URL=http://localhost:7474
-# NEO4J_USER=neo4j
-# NEO4J_PASSWORD=your_password
+# ============================================================================
+# oh-memos-mcp Environment Configuration
+# ============================================================================
+# Copy this file to .env in your project root and adjust values.
+# Priority: CLI flags > explicit env file > inherited environment > discovered .env > defaults
+# A discovered .env only fills gaps; it never overrides MCP client env values.
+# Set MEMOS_ENV_FILE when a specific file must be authoritative (recommended for npx).
+# ============================================================================
+
+# --- Required (Full/API mode) ---
+MEMOS_URL=http://localhost:18000        # oh-memos API address (may be empty in local mode)
+MEMOS_USER=dev_user                     # Default user ID
+MEMOS_DEFAULT_CUBE=dev_cube             # Default memory cube ID
+MEMOS_CUBES_DIR=/path/to/cubes          # Absolute path to cubes directory
+
+# --- Provider selection ---
+# MEMOS_PROVIDER=api                    # api = Full backend via Python API (default)
+# MEMOS_PROVIDER=local                  # local = Lite JSONL store, no Python API needed
+# MEMOS_MODE=lite                       # Shorthand: implies MEMOS_PROVIDER=local
+
+# --- Lite local embeddings (optional, only for MEMOS_PROVIDER=local) ---
+# Semantic ranking for the Lite store talks to an Ollama-compatible endpoint.
+# It expects the Ollama /api/embeddings protocol, so point it at an Ollama
+# host (local or self-hosted remote) — cloud OpenAI-compatible embedding
+# endpoints belong to the Full backend instead (see docker/.env.docker.example,
+# MOS_EMBEDDER_*). Defaults below need no configuration at all.
+# MEMOS_LITE_EMBED_URL=http://127.0.0.1:11434   # Ollama endpoint
+# MEMOS_LITE_EMBED_MODEL=bge-m3                  # any embedding model you pulled
+# MEMOS_LITE_EMBED=off                           # pin lexical-only ranking explicitly
+
+# --- Timeouts (seconds) ---
+# MEMOS_TIMEOUT_TOOL=300                # Tool call timeout (default: 300)
+# MEMOS_TIMEOUT_STARTUP=30              # Startup timeout (default: 30)
+# MEMOS_TIMEOUT_HEALTH=5                # Health check timeout (default: 5)
+# MEMOS_API_WAIT_MAX=60                 # Max API wait time (default: 60)
+
+# --- Feature Flags ---
+# MEMOS_ENABLE_DELETE=false             # Enable memory deletion (default: false)
+# MEMOS_LOG_LEVEL=WARNING               # DEBUG | INFO | WARNING | ERROR
+
+# --- Neo4j (optional, for direct graph queries) ---
+# NEO4J_HTTP_URL=http://localhost:7474
+# NEO4J_USER=neo4j
+# NEO4J_PASSWORD=your_password

package/CHANGELOG.md

@@ -1,95 +1,266 @@
-# Changelog
-
-All notable changes to `oh-memos-mcp` are documented here.
-
-This project follows [Semantic Versioning](https://semver.org/).
-
----
-
-## [2.0.1] — 2026-08-02
-
-### Fixed
-
-- MCP `serverInfo` was hardcoded in `server.ts` and reported
-  `{name: "memos-memory", version: "1.0.1"}` — a name matching neither the
-  package (`oh-memos-mcp`) nor the conventional server key (`oh-memos`), and a
-  version that 2.0.0 shipped stale. Clients display this during the handshake.
-  It is now read from `package.json` at startup, so it cannot drift again.
-
----
-
-## [2.0.0] — 2026-08-02
-
-### ⚠️ Breaking — tool surface consolidated from 18 to 10
-
-Eleven tools were merged into three dispatching tools. **There is no compatibility
-shim**: the MCP SDK only dispatches registered tools, so calling a removed name now
-returns `Unknown tool`.
-
-If your MCP client config pins tool names (e.g. Claude Code's `alwaysAllow` list),
-you must update it before upgrading.
-
-#### Migration
-
-| 1.x tool | 2.0 replacement |
-|----------|-----------------|
-| `memos_search_context` | `memos_search` — pass the `context` array (recent turns) |
-| `memos_get_graph` | `memos_graph(mode="related")` |
-| `memos_trace_path` | `memos_graph(mode="path")` |
-| `memos_impact` | `memos_graph(mode="impact")` |
-| `memos_export_schema` | `memos_graph(mode="schema")` |
-| `memos_list_cubes` | `memos_admin(action="list_cubes")` |
-| `memos_register_cube` | `memos_admin(action="register_cube")` |
-| `memos_create_user` | `memos_admin(action="create_user")` |
-| `memos_validate_cubes` | `memos_admin(action="validate_cubes")` |
-| `memos_get_stats` | `memos_admin(action="stats")` |
-| `memos_calendar` | `memos_admin(action="calendar")` |
-
-Unchanged: `memos_context_resume`, `memos_search`, `memos_save`, `memos_list_v2`,
-`memos_get`, `memos_suggest`, `memos_delete`.
-
-`alwaysAllow` for 2.0:
-
-```json
-"alwaysAllow": [
-  "memos_context_resume", "memos_search", "memos_save",
-  "memos_list_v2", "memos_get", "memos_suggest",
-  "memos_think", "memos_graph", "memos_admin", "memos_export_wiki"
-]
-```
-
-### Added
-
-- **`memos_think`** — evidence pack for a question. Runs semantic retrieval plus a
-  recent-72h temporal pass, deduplicates, and returns numbered evidence with graph
-  relationships between items, contradiction/evolution candidates, staleness
-  candidates, and gap analysis. Synthesis is deliberately left to the calling model;
-  the server emits no prose. Results can be persisted back as `SYNTHESIS`.
-- **`memos_export_wiki`** — export a cube as an interlinked markdown wiki: one page
-  per memory (YAML frontmatter, `[[wikilink]]` relations), plus `index.md` and a
-  mermaid `graph.md`. Only files carrying the generator marker are ever replaced;
-  foreign files in the output directory are preserved. Defaults to
-  `<project_path>/docs/memory-wiki`.
-- **`SYNTHESIS`** memory type, for answers synthesized from retrieved evidence.
-
-### Changed
-
-- Tool-surface cost dropped ~51%: `tools/list` payload 22.9 KB → 11.2 KB
-  (≈5850 → ≈2856 tokens). Shared `project_path` / `cube_id` parameter descriptions
-  were deduplicated; the full cube-routing rules are now stated once, on
-  `memos_save` and `memos_search`.
-- Runtime error `suggestions` now name the 2.0 call forms, so a model reading a
-  failure message is no longer told to call a tool that does not exist.
-
-### Fixed
-
-- `memos_admin`'s `cube_id` no longer carries a `MEMOS_DEFAULT_CUBE` default.
-  Previously, calling `register_cube` without `cube_id` would silently register the
-  default cube instead of failing.
-
----
-
-## [1.0.0] — 2026-03-04
-
-Initial npm release. 18 tools, Node-only MCP server for oh-memos — no Python
-required, runs via `npx`.
+# Changelog
+
+All notable changes to `oh-memos-mcp` are documented here.
+
+This project follows [Semantic Versioning](https://semver.org/).
+
+---
+
+## [3.0.0] - 2026-08-19
+
+### Breaking
+
+- **Node.js 20 is now the minimum runtime.** Node 18 users must stay on
+  `oh-memos-mcp@2` (`npx -y oh-memos-mcp@2`) until they can upgrade their
+  runtime. The entry point exits with an actionable message on Node 18 instead
+  of failing with an opaque module error.
+- The MCP runtime now uses the role-split `@modelcontextprotocol/server@2` and
+  Zod 4 instead of the monolithic v1 SDK and Zod 3.
+
+### Added
+
+- **Dual-era stdio serving.** The same package accepts legacy 2025-era
+  initialize clients and clients pinned to MCP `2026-07-28` through
+  `serveStdio(..., { legacy: "serve" })`.
+- Stringified `tools/call` arguments are normalized before era classification
+  and schema validation, preserving the existing client compatibility path.
+- Protocol, lifecycle, semantic-schema and package-boundary release gates now
+  cover legacy/auto/modern clients, Full/Lite providers, 16/17 tools, large
+  requests, probe fallback and graceful process shutdown.
+
+### Migration
+
+- Install with `npx -y oh-memos-mcp` (npm `latest`) or pin `oh-memos-mcp@3.0.0`.
+- No memory, cube or Lite JSONL migration is required. Existing Full and Lite
+  data formats, tool names and input schemas remain unchanged, so Agent
+  configurations only need the package reference updated.
+- Clients that still negotiate the 2025-era wire keep working unchanged; no
+  client-side protocol migration is required to adopt 3.0.
+
+### Rollback
+
+- Pin Agent configurations to `npx -y oh-memos-mcp@2.1.0`. No data rollback is
+  necessary because this release does not change persisted formats.
+- `2.x` remains installable from npm; this release does not unpublish or
+  deprecate it.
+
+## [2.1.0] - 2026-08-16
+
+### Fixed
+
+- **Auto-discovered `.env` no longer overrides launcher environment.** A `.env`
+  found in the working directory or package root now only fills missing values,
+  so MCP client `env` blocks and shell exports such as `MEMOS_PROVIDER=local`
+  stay in effect. A file selected explicitly through `MEMOS_ENV_FILE` or
+  `--memos-env-file` remains authoritative.
+
+### Added
+
+- **Local Lite provider.** `MEMOS_PROVIDER=local` (implied by `MEMOS_MODE=lite`)
+  serves `memos_save`, `memos_get`, `memos_list_v2`, `memos_search`, and
+  `memos_context_resume` from a per-cube `memories.jsonl` with deterministic
+  lexical ranking, durable appends, and a cross-process lock. Graph, Think,
+  Wiki, and admin tools report `LOCAL_PROVIDER_UNSUPPORTED` rather than
+  pretending a graph backend exists.
+
+- **Skill candidate lifecycle.** `memos_review_skill_candidate` records
+  approve/reject with reviewer audit metadata, and
+  `memos_install_skill_candidate` installs only approved candidates into
+  `.claude/skills/<slug>/SKILL.md` without overwriting, following symlinks, or
+  executing anything.
+
+- **Explainable graph provenance.** `memos_graph(mode="related"|"path"|"impact")`
+  now reports normalized evidence categories (`EXTRACTED`, `INFERRED`,
+  `AMBIGUOUS`, or `UNKNOWN`) and includes confidence, evidence references,
+  source file/location, extractor version and verification time when those
+  fields exist. Legacy graph data without provenance remains readable and is
+  reported as `UNKNOWN` rather than assigned invented evidence.
+
+- **`memos_graph(mode="import")` Graphify boundary.** Accepts up to 5 MB of
+  Graphify/NetworkX node-link JSON through `graph_json`, validates `nodes` plus
+  `links` (or the `edges` alias), and produces a deterministic import plan with
+  portable stable Code Graph ids. Duplicate ids, dangling edges, unsafe source
+  paths, invalid confidence values and oversized graphs are rejected before
+  any persistence boundary. This mode is intentionally **dry-run only**: it
+  never writes to Neo4j, Qdrant or a memory cube.
+
+- **`memos_canvas`** — a symbolic task canvas: short-term task state that survives
+  context compaction. One Mermaid file per task under
+  `{MEMOS_CUBES_DIR}/{cube_id}/canvas/`, whose nodes carry a greppable id
+  (`000-N1`) and an optional `ref` anchoring them to evidence:
+  `mem:<memory_id>` (a memory in the graph), `file:<path>` (any file, including
+  the large tool results the harness already offloads), or `note:<text>`.
+
+  `action`: `open` (needs `goal`) · `update` (appends a node; `node_id` edits one
+  in place) · `show` · `list`.
+
+  Canvases are deliberately **not** written to Neo4j or Qdrant. A canvas changes
+  several times an hour, and paying an embedding round trip for a `doing→done`
+  flip would be absurd. Durable facts still go through `memos_save`; the canvas
+  points at them with a `mem:` ref.
+
+  This is **not** a token-saving feature. The design it borrows from
+  ([TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory))
+  achieves its reduction by intercepting and replacing tool output before the
+  model sees it, which a Claude Code hook cannot do — `PreToolUse` can rewrite a
+  tool's *input* via `updatedInput`, but no hook can rewrite its *output*. What
+  this offers instead is task state that survives compaction, and a path from a
+  summary back to the evidence behind it.
+
+  Node ids and canvas prefixes are allocated as max+1 and **never reuse a gap**:
+  a deleted `000-N2` may still be cited from a commit message, a memory body or
+  another node's ref, and handing that id to a new node would silently repoint
+  every one of those citations.
+
+- `memos_context_resume` now lists **unfinished** canvases first — headlines and
+  counts only, a few dozen tokens — so the first thing visible after a compaction
+  is the open work rather than a memory feed. Injecting canvas bodies here would
+  rebuild the very context bloat the canvas exists to avoid; the model opens what
+  it needs with `show`.
+
+- **Test infrastructure.** This package previously had none: no test script, no
+  `*.test.ts`. Adds vitest and `npm test`, with 65 unit tests covering the
+  parse/render round trip, node-id allocation, Mermaid label injection, path
+  traversal refusal and atomic writes. `scripts/canvas-e2e.mjs` adds 18 checks
+  driven over real MCP stdio rather than mocks.
+
+- `MEMOS_ENV_FILE` env var and `--memos-env-file` flag, to point the server at an
+  explicit `.env`. Previously the file was located only by guessing from position
+  (cwd, two levels above the package, dotenv's upward search) — which works from
+  a checkout and never works under `npx`, where the package root sits in the npm
+  cache and every candidate misses, loading not one variable. A path that does
+  not exist now warns on stderr rather than falling through silently.
+
+### Fixed
+
+- `toLocalPath()` rewrote Windows cube paths to `/mnt/...` unconditionally. That
+  mapping only resolves inside WSL; under native Windows Node the result is not
+  absolute, so it resolved against the current drive and every cube write landed
+  in a phantom tree while the API kept reading the real path. Registration
+  reported success, then `/search` and `/memories` failed 400 — the loaded cube
+  had no memory backend.
+
+### Security
+
+- `canvasPath` is the one place caller text becomes a filesystem path. It uses a
+  **whitelist** (`[a-z0-9-]`) rather than a blacklist of dangerous characters,
+  because a blacklist is always missing an entry. `.` is outside the whitelist,
+  so `..` cannot survive it — traversal is structurally impossible rather than
+  merely checked for — and a post-resolve containment check backs that up
+  independently. `cube_id` is treated as untrusted too, since it is derived from
+  a caller-supplied `project_path`.
+
+### Documentation
+
+- The `alwaysAllow` example carried two defects. `memos_search` appeared twice,
+  and several entries were **call forms** — `memos_admin(action=list_cubes)` and
+  the like. `alwaysAllow` matches tool names, so those entries matched nothing:
+  a reader would believe those calls were pre-approved and still be prompted for
+  every one. Replaced with bare tool names, which auto-approve every action of
+  the tool.
+- `memos_delete` was dropped from that example, which also set
+  `MEMOS_ENABLE_DELETE: "true"` — together they auto-approve deleting memories
+  with no prompt. Enabling that is a decision worth making deliberately.
+- The `.env` note claimed the working directory's file loads "automatically with
+  highest priority". Under `npx` no file loads at all. Documented `MEMOS_ENV_FILE`
+  and what actually happens.
+
+### Notes
+
+- Tool surface grew 12488 B → 13680 B (+9.5%), past the +5% drift budget, and the
+  baseline was re-frozen. This is the cost of a new tool rather than description
+  drift; the description was trimmed from 1333 B to 1192 B first, moving detail
+  into `show`'s output (the same move `memos_suggest` made with the memory-type
+  decision tree).
+- `tsconfig.json` now excludes `src/**/*.test.ts`. Without it the test files
+  compile into `dist` and ship with `npm publish`.
+
+---
+
+## [2.0.1] — 2026-08-02
+
+### Fixed
+
+- MCP `serverInfo` was hardcoded in `server.ts` and reported
+  `{name: "memos-memory", version: "1.0.1"}` — a name matching neither the
+  package (`oh-memos-mcp`) nor the conventional server key (`oh-memos`), and a
+  version that 2.0.0 shipped stale. Clients display this during the handshake.
+  It is now read from `package.json` at startup, so it cannot drift again.
+
+---
+
+## [2.0.0] — 2026-08-02
+
+### ⚠️ Breaking — tool surface consolidated from 18 to 10
+
+Eleven tools were merged into three dispatching tools. **There is no compatibility
+shim**: the MCP SDK only dispatches registered tools, so calling a removed name now
+returns `Unknown tool`.
+
+If your MCP client config pins tool names (e.g. Claude Code's `alwaysAllow` list),
+you must update it before upgrading.
+
+#### Migration
+
+| 1.x tool | 2.0 replacement |
+|----------|-----------------|
+| `memos_search_context` | `memos_search` — pass the `context` array (recent turns) |
+| `memos_get_graph` | `memos_graph(mode="related")` |
+| `memos_trace_path` | `memos_graph(mode="path")` |
+| `memos_impact` | `memos_graph(mode="impact")` |
+| `memos_export_schema` | `memos_graph(mode="schema")` |
+| `memos_list_cubes` | `memos_admin(action="list_cubes")` |
+| `memos_register_cube` | `memos_admin(action="register_cube")` |
+| `memos_create_user` | `memos_admin(action="create_user")` |
+| `memos_validate_cubes` | `memos_admin(action="validate_cubes")` |
+| `memos_get_stats` | `memos_admin(action="stats")` |
+| `memos_calendar` | `memos_admin(action="calendar")` |
+
+Unchanged: `memos_context_resume`, `memos_search`, `memos_save`, `memos_list_v2`,
+`memos_get`, `memos_suggest`, `memos_delete`.
+
+`alwaysAllow` for 2.0:
+
+```json
+"alwaysAllow": [
+  "memos_context_resume", "memos_search", "memos_save",
+  "memos_list_v2", "memos_get", "memos_suggest",
+  "memos_think", "memos_graph", "memos_admin", "memos_export_wiki"
+]
+```
+
+### Added
+
+- **`memos_think`** — evidence pack for a question. Runs semantic retrieval plus a
+  recent-72h temporal pass, deduplicates, and returns numbered evidence with graph
+  relationships between items, contradiction/evolution candidates, staleness
+  candidates, and gap analysis. Synthesis is deliberately left to the calling model;
+  the server emits no prose. Results can be persisted back as `SYNTHESIS`.
+- **`memos_export_wiki`** — export a cube as an interlinked markdown wiki: one page
+  per memory (YAML frontmatter, `[[wikilink]]` relations), plus `index.md` and a
+  mermaid `graph.md`. Only files carrying the generator marker are ever replaced;
+  foreign files in the output directory are preserved. Defaults to
+  `<project_path>/docs/memory-wiki`.
+- **`SYNTHESIS`** memory type, for answers synthesized from retrieved evidence.
+
+### Changed
+
+- Tool-surface cost dropped ~51%: `tools/list` payload 22.9 KB → 11.2 KB
+  (≈5850 → ≈2856 tokens). Shared `project_path` / `cube_id` parameter descriptions
+  were deduplicated; the full cube-routing rules are now stated once, on
+  `memos_save` and `memos_search`.
+- Runtime error `suggestions` now name the 2.0 call forms, so a model reading a
+  failure message is no longer told to call a tool that does not exist.
+
+### Fixed
+
+- `memos_admin`'s `cube_id` no longer carries a `MEMOS_DEFAULT_CUBE` default.
+  Previously, calling `register_cube` without `cube_id` would silently register the
+  default cube instead of failing.
+
+---
+
+## [1.0.0] — 2026-03-04
+
+Initial npm release. 18 tools, Node-only MCP server for oh-memos — no Python
+required, runs via `npx`.

package/README.md

@@ -1,17 +1,28 @@
 # oh-memos-mcp
 
 [![npm version](https://img.shields.io/npm/v/oh-memos-mcp.svg)](https://www.npmjs.com/package/oh-memos-mcp)
-[![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![Node.js >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 MCP Server for **oh-memos** — Intelligent Persistent Memory for AI Assistants.
 
 Pure Node.js. No Python required. Works with `npx` out of the box.
 
+> **3.0:** requires Node.js 20+, serves legacy 2025-era and MCP `2026-07-28`
+> clients from the same stdio package, and requires no data migration. Still on
+> Node 18? Pin `oh-memos-mcp@2` until you can upgrade the runtime.
+
 ---
 
 ## Prerequisites
 
+- **Node.js 20 or newer**
+
+```bash
+npx -y oh-memos-mcp        # 3.x, npm latest — needs Node.js 20+
+npx -y oh-memos-mcp@2      # 2.x maintenance line — still runs on Node.js 18
+```
+
 oh-memos backend API must be running before connecting this MCP server:
 
 - **oh-memos API** on `http://localhost:18000`
@@ -48,7 +59,7 @@ Or use a `.env` file in your working directory (the server auto-discovers it):
 ```bash
 cp node_modules/oh-memos-mcp/.env.example .env
 # Edit .env with your paths
-npx oh-memos-mcp
+npx -y oh-memos-mcp
 ```
 
 ---
@@ -114,6 +125,13 @@ npx oh-memos-mcp
 
 ### With `alwaysAllow` (skip per-tool confirmation)
 
+`alwaysAllow` matches **tool names**, so a call form like
+`memos_admin(action=list_cubes)` matches nothing — list the bare name and every
+action of that tool is auto-approved.
+
+`memos_delete` is deliberately absent below. Auto-approving it means memories can
+be deleted without a prompt; add it only if you have decided you want that.
+
 ```json
 {
   "mcpServers": {
@@ -125,28 +143,20 @@ npx oh-memos-mcp
         "MEMOS_URL": "http://localhost:18000",
         "MEMOS_USER": "dev_user",
         "MEMOS_DEFAULT_CUBE": "dev_cube",
-        "MEMOS_CUBES_DIR": "/path/to/oh-memos/data/oh-memos_cubes",
-        "MEMOS_ENABLE_DELETE": "true"
+        "MEMOS_CUBES_DIR": "/path/to/oh-memos/data/oh-memos_cubes"
       },
       "alwaysAllow": [
         "memos_context_resume",
         "memos_search",
-        "memos_search",
         "memos_save",
         "memos_list_v2",
         "memos_get",
         "memos_suggest",
-        "memos_admin(action=list_cubes)",
-        "memos_admin(action=stats)",
-        "memos_graph(mode=related)",
-        "memos_graph(mode=path)",
-        "memos_graph(mode=schema)",
-        "memos_admin(action=register_cube)",
-        "memos_admin(action=create_user)",
-        "memos_admin(action=validate_cubes)",
-        "memos_graph(mode=impact)",
-        "memos_admin(action=calendar)",
-        "memos_delete"
+        "memos_think",
+        "memos_graph",
+        "memos_admin",
+        "memos_export_wiki",
+        "memos_canvas"
       ]
     }
   }
@@ -171,14 +181,26 @@ npx oh-memos-mcp
 | `NEO4J_HTTP_URL` | No | — | Neo4j HTTP endpoint (for direct graph queries) |
 | `NEO4J_USER` | No | — | Neo4j username |
 | `NEO4J_PASSWORD` | No | — | Neo4j password |
-
-> **Tip**: `.env` file in your working directory is loaded automatically with highest priority.
+| `MEMOS_ENV_FILE` | No | — | Explicit path to a `.env` file. Highest priority — see below |
+
+> **On locating `.env`**: without `MEMOS_ENV_FILE`, the file is found by guessing
+> from position (working directory, two levels above the package, then dotenv's
+> upward search). That works from a checkout and **never works under `npx`**,
+> where the package root sits in the npm cache and every candidate misses — so no
+> variable loads at all. Set `MEMOS_ENV_FILE` (or pass `--memos-env-file`) when the
+> client's working directory and the install location are both outside the project.
+> A path that does not exist warns on stderr rather than failing silently.
+>
 > Copy `.env.example` to get started.
 
 ---
 
-## Tools (10)
+## Tools (17)
 
+The package defines 17 tool schemas. `memos_delete` is exposed by `tools/list`
+only when `MEMOS_ENABLE_DELETE=true`; the other 16 are available by default.
+
+<!-- mcp-tool-inventory:start -->
 | Tool | Description |
 |------|-------------|
 | `memos_context_resume` | Recover project context after compaction (recent 24h + project state) |
@@ -188,23 +210,46 @@ npx oh-memos-mcp
 | `memos_get` | Get full memory details by ID |
 | `memos_suggest` | Smart search query suggestions + `memory_type` decision tree |
 | `memos_think` | Evidence pack for a question: retrieval + contradiction/staleness flags + gap analysis. The caller synthesizes the answer and may persist it as `SYNTHESIS` |
-| `memos_graph` | Knowledge graph queries — `mode`: `related` / `path` / `impact` / `schema` |
+| `memos_graph` | Explainable graph queries plus strict Graphify node-link validation — `mode`: `related` / `path` / `impact` / `schema` / `import` |
 | `memos_admin` | Maintenance — `action`: `list_cubes` / `register_cube` / `create_user` / `validate_cubes` / `stats` / `calendar` |
 | `memos_export_wiki` | Export a cube as an interlinked markdown wiki (page per memory + index + mermaid graph) |
-
-Plus `memos_delete`, hidden from `tools/list` unless `MEMOS_ENABLE_DELETE=true`.
+| `memos_import_wiki` | Import an exported wiki back into a cube; supports dry-run and versioning edited pages, never deletes memories |
+| `memos_canvas` | Symbolic task canvas — short-term task state that survives context compaction. `action`: `open` / `update` / `show` / `list`. Nodes carry greppable ids (`000-N1`) and a `ref` anchoring them to evidence: `mem:<memory_id>` / `file:<path>` / `note:<text>` |
+| `memos_distill_skill` | Create an inert, reviewable Skill candidate under `<project_path>/skill-candidates`; it never installs the candidate automatically |
+| `memos_list_skill_candidates` | List generated Skill candidates without modifying or installing them |
+| `memos_review_skill_candidate` | Approve or reject a candidate with reviewer audit metadata; approval does not install |
+| `memos_install_skill_candidate` | Install an approved candidate only into `.claude/skills/<slug>/SKILL.md`, without overwrite or script execution |
+| `memos_delete` | Delete selected or all memories. Disabled by default and requires explicit user confirmation when enabled |
+<!-- mcp-tool-inventory:end -->
+
+### `memos_graph` modes
+
+| Mode | Main input | Result |
+|------|------------|--------|
+| `related` | `query` | Related memories and edges, with provenance explanations when available |
+| `path` | `source_id`, `target_id` | A bounded path between two graph nodes, including relationship evidence |
+| `impact` | `memory_id`, optional `max_depth` | Forward blast radius from one memory |
+| `schema` | Optional `sample_size` | Graph structure and statistics |
+| `import` | `graph_json`, optional `project_key` | Deterministic validation and dry-run plan for Graphify NetworkX node-link JSON |
+
+`import` accepts at most 5 MB of JSON and rejects duplicate node ids, dangling
+edges, unsafe source paths, invalid confidence values, and oversized graphs. It
+does **not** write Code Graph nodes to Neo4j, Qdrant, or a memory cube.
 
 ---
 
 ## How .env Loading Works
 
-Priority order (highest first):
+Priority order for configuration values (highest first):
 
-1. **`process.cwd()/.env`** — your project working directory
-2. **Package root `.env`** — where oh-memos-mcp is installed
-3. **dotenv default search** — walks up from cwd
+1. **CLI configuration flags** such as `--memos-url`
+2. **Explicit env file** selected by `--memos-env-file` or inherited `MEMOS_ENV_FILE`
+3. **Inherited process environment** — this is where MCP client `env` values belong
+4. **Auto-discovered `process.cwd()/.env`** — provides only missing defaults
+5. **Auto-discovered package-root `.env`** — provides only missing defaults
+6. **dotenv upward fallback**, then built-in defaults
 
-This means you can place a `.env` in your project root and `npx oh-memos-mcp` will pick it up automatically — no need to repeat env vars in every MCP config.
+The automatic file search never overrides explicit MCP/launcher environment values. Use `MEMOS_ENV_FILE` only when the selected file should deliberately be authoritative; this is also the reliable option for `npx` installs.
 
 ---
 
@@ -222,5 +267,5 @@ npm run build  # Compile to dist/
 
 ## Requirements
 
-- Node.js >= 18.0.0
+- Node.js >= 20.0.0
 - oh-memos backend API running (`scripts\local\start.bat`)