memorix 0.9.18 → 0.9.20

package/README.md

@@ -21,7 +21,7 @@
     <img src="https://img.shields.io/badge/Works%20with-Gemini%20CLI-4285F4?style=flat-square" alt="Gemini CLI">
   </p>
   <p align="center">
-    <a href="#-stop-re-explaining-your-project">Why</a> •
+    <a href="#%EF%B8%8F-stop-re-explaining-your-project">Why</a> •
     <a href="#-get-started-in-30-seconds">Quick Start</a> •
     <a href="#-real-world-scenarios">Scenarios</a> •
     <a href="#-what-memorix-can-do">Features</a> •
@@ -32,7 +32,7 @@
 
 ---
 
-## 😤 Stop Re-Explaining Your Project
+## ⚠️ Stop Re-Explaining Your Project
 
 Your AI assistant forgets everything when you start a new chat. You spend 10 minutes re-explaining your architecture. **Again.** And if you switch from Cursor to Claude Code? Everything is gone. **Again.**
 
@@ -67,7 +67,7 @@ Run in terminal:
 ```bash
 claude mcp add memorix -- memorix serve
 ```
-Or manually add to `~/.claude.json`:
+Or manually add to `~/.claude.json` (global) or `.claude/settings.json` (project):
 ```json
 {
   "mcpServers": {
@@ -78,6 +78,7 @@ Or manually add to `~/.claude.json`:
   }
 }
 ```
+> **Windows:** `~/.claude.json` is at `C:\Users\<YourUsername>\.claude.json`
 </details>
 
 <details>
@@ -113,12 +114,12 @@ Add to Windsurf MCP settings (`~/.codeium/windsurf/mcp_config.json`):
 </details>
 
 <details>
-<summary><strong>VS Code Copilot / Codex / Kiro</strong></summary>
+<summary><strong>VS Code Copilot</strong></summary>
 
-Same format — add to the agent's MCP config file:
+Add to `.vscode/mcp.json` in your project:
 ```json
 {
-  "mcpServers": {
+  "servers": {
     "memorix": {
       "command": "memorix",
       "args": ["serve"]
@@ -129,9 +130,20 @@ Same format — add to the agent's MCP config file:
 </details>
 
 <details>
-<summary><strong>Antigravity / Gemini CLI</strong></summary>
+<summary><strong>Codex</strong></summary>
 
-Add to `.gemini/settings.json` (project) or `~/.gemini/settings.json` (global):
+Add to `~/.codex/config.toml`:
+```toml
+[mcp_servers.memorix]
+command = "memorix"
+args = ["serve"]
+```
+</details>
+
+<details>
+<summary><strong>Kiro</strong></summary>
+
+Add to `.kiro/settings/mcp.json` (project) or `~/.kiro/settings/mcp.json` (global):
 ```json
 {
   "mcpServers": {
@@ -142,8 +154,12 @@ Add to `.gemini/settings.json` (project) or `~/.gemini/settings.json` (global):
   }
 }
 ```
+</details>
+
+<details>
+<summary><strong>Antigravity</strong></summary>
 
-**Antigravity IDE only:** Antigravity uses its own install path as CWD. You **must** add:
+Add to `~/.gemini/antigravity/mcp_config.json`. Antigravity requires `MEMORIX_PROJECT_ROOT`:
 ```json
 {
   "mcpServers": {
@@ -157,8 +173,22 @@ Add to `.gemini/settings.json` (project) or `~/.gemini/settings.json` (global):
   }
 }
 ```
+</details>
 
-**Gemini CLI** reads MCP config from the same path. Hooks are automatically installed to `.gemini/settings.json`.
+<details>
+<summary><strong>Gemini CLI</strong></summary>
+
+Add to `.gemini/settings.json` (project) or `~/.gemini/settings.json` (global):
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "memorix",
+      "args": ["serve"]
+    }
+  }
+}
+```
 </details>
 
 ### Step 3: Restart your agent — done!
@@ -167,17 +197,39 @@ No API keys. No cloud accounts. No dependencies. Works with any directory (git r
 
 > 📖 **Full setup guide for all 8 agents** → [docs/SETUP.md](docs/SETUP.md)
 
-<details>
-<summary><strong>🔧 Troubleshooting</strong></summary>
+### 🔧 Troubleshooting — MCP Connection Issues
 
-| Problem | Solution |
-|---------|----------|
-| `MCP server initialization timed out after 60 seconds` | You're using `npx`. Run `npm install -g memorix` and change config to `"command": "memorix"` |
-| `Cannot start Memorix: no valid project detected` | Your CWD is a system directory (home, Desktop, etc). Open a real project folder or set `MEMORIX_PROJECT_ROOT` |
-| `memorix: command not found` | Run `npm install -g memorix` first. Verify with `memorix --version` |
-| Parameter type errors (GLM/non-Anthropic models) | Update to v0.9.1+: `npm install -g memorix@latest` |
+> **⚠️ #1 Mistake: Do NOT manually run `memorix serve` in a terminal.**
+> MCP uses **stdio transport** — your IDE (Claude Code, Cursor, etc.) launches memorix as a subprocess automatically. Running it manually in PowerShell/Terminal does nothing for the IDE connection.
 
-</details>
+**Quick diagnostic** — run this first:
+```bash
+memorix --version       # Should print version number
+memorix serve --cwd .   # Should show "[memorix] MCP Server running on stdio"
+```
+If either fails, follow the table below:
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `memorix · ✗ failed` in IDE | IDE can't find the `memorix` command | Run `npm install -g memorix`. On Windows, **restart your IDE** after install so it picks up the new PATH |
+| `MCP server initialization timed out` | Using `npx` (downloads every time) | Switch to global install: `npm install -g memorix`, change config to `"command": "memorix"` |
+| Repeated "Reconnected to memorix" then fails | memorix process crashes on startup | Check: 1) Node.js ≥ 18 (`node -v`), 2) open a **real project folder** (not Desktop/Home), 3) set `MEMORIX_PROJECT_ROOT` in MCP config |
+| `Cannot start Memorix: no valid project detected` | CWD is a system directory | Open a project folder with code, or add `"env": { "MEMORIX_PROJECT_ROOT": "/path/to/project" }` to your MCP config |
+| `memorix: command not found` | npm global bin not in PATH | Run `npm config get prefix` to find install location, add its `bin/` to your system PATH, then restart IDE |
+| Works in terminal but not in IDE | IDE uses a different PATH than your shell | **Windows:** restart IDE after `npm install -g`. **macOS/Linux:** ensure `~/.bashrc` or `~/.zshrc` exports the npm global bin path |
+| Parameter type errors | Old version or non-Anthropic model quirks | Update: `npm install -g memorix@latest` |
+
+**Correct config:**
+```json
+"command": "memorix", "args": ["serve"]
+```
+
+**❌ Wrong:**
+```
+"command": "npx"                    ← will timeout
+"command": "npx -y memorix serve"   ← wrong format
+"command": "node memorix serve"     ← not how it works
+```
 
 ---
 
@@ -236,138 +288,33 @@ Now you want to try Kiro.
   → Kiro is ready in seconds, not hours!
 ```
 
-### Scenario 5: Auto-Generated Project Skills
-
-```
-After 2 weeks of development, you have 50+ observations:
-  - 8 gotchas about Windows path issues
-  - 5 decisions about the auth module
-  - 3 problem-solutions for database migrations
-
-  You: "Generate project skills"
-  → memorix_skills clusters observations by entity
-  → Auto-generates SKILL.md files:
-    - "auth-module-guide.md" — JWT setup, refresh flow, common pitfalls
-    - "database-migrations.md" — Prisma patterns, rollback strategies
-  → Syncs skills to any agent: Cursor, Claude Code, Kiro...
-  → New team members' AI instantly knows your project's patterns!
-```
-
-### Scenario 6: Session Lifecycle (v0.8.0)
-
-```
-Morning — Start a new session in Windsurf:
-  → memorix_session_start auto-injects:
-    📋 Previous Session: "Implemented JWT auth middleware"
-    🔴 JWT tokens expire silently (gotcha)
-    🟤 Use Docker for deployment (decision)
-  → AI instantly knows what you did yesterday!
-
-Evening — End the session:
-  → memorix_session_end saves structured summary
-  → Next session (any agent!) gets this context automatically
-```
-
-### Scenario 7: Topic Key Upsert — No More Duplicates (v0.8.0)
-
-```
-You update your architecture decision 3 times over a week:
-
-  Day 1: memorix_store(topicKey="architecture/auth-model", ...)
-  → Creates observation #42 (rev 1)
-
-  Day 3: memorix_store(topicKey="architecture/auth-model", ...)
-  → Updates #42 in-place (rev 2) — NOT a new #43!
-
-  Day 5: memorix_store(topicKey="architecture/auth-model", ...)
-  → Updates #42 again (rev 3)
-
-  Result: 1 observation with latest content, not 3 duplicates!
-```
-
 ---
 
 ## 🧠 What Memorix Can Do
 
-### Smart Memory (24 MCP Tools)
-
-| What You Say | What Memorix Does |
-|-------------|-------------------|
-| "Remember this architecture decision" | `memorix_store` — Classifies as 🟤 decision, extracts entities, creates graph relations, auto-associates session |
-| "What did we decide about auth?" | `memorix_search` → `memorix_detail` — 3-layer progressive disclosure, ~10x token savings |
-| "What auth decisions last week?" | `memorix_search` with `since`/`until` — Temporal queries with date range filtering |
-| "What happened around that bug fix?" | `memorix_timeline` — Shows chronological context before/after |
-| "Show me the knowledge graph" | `memorix_dashboard` — Opens interactive web UI with D3.js graph + sessions panel |
-| "Which memories are getting stale?" | `memorix_retention` — Exponential decay scores, identifies archive candidates |
-| "Start a new session" | `memorix_session_start` — Tracks session lifecycle, auto-injects previous session summaries + key memories |
-| "End this session" | `memorix_session_end` — Saves structured summary (Goal/Discoveries/Accomplished/Files) for next session |
-| "What did we do last session?" | `memorix_session_context` — Retrieves session history and key observations |
-| "Suggest a topic key for this" | `memorix_suggest_topic_key` — Generates stable keys for deduplication (e.g. `architecture/auth-model`) |
-| "Clean up duplicate memories" | `memorix_consolidate` — Find & merge similar observations by text similarity, preserving all facts |
-| "Export this project's memories" | `memorix_export` — JSON (importable) or Markdown (human-readable for PRs/docs) |
-| "Import memories from teammate" | `memorix_import` — Restore from JSON export, re-assigns IDs, deduplicates by topicKey |
-
-### Cross-Agent Workspace Sync
-
-| What You Say | What Memorix Does |
-|-------------|-------------------|
-| "Sync my MCP servers to Kiro" | `memorix_workspace_sync` — Migrates configs, merges (never overwrites) |
-| "Check my agent rules" | `memorix_rules_sync` — Scans 8 agents, deduplicates, detects conflicts |
-| "Generate rules for Cursor" | `memorix_rules_sync` — Cross-format conversion (`.mdc` ↔ `CLAUDE.md` ↔ `.kiro/steering/`) |
-| "Generate project skills" | `memorix_skills` — Creates SKILL.md from observation patterns |
-| "Inject the auth skill" | `memorix_skills` — Returns skill content directly into agent context |
-
-### Knowledge Graph (MCP Official Compatible)
-
-| Tool | What It Does |
-|------|-------------|
-| `create_entities` | Build your project's knowledge graph |
-| `create_relations` | Connect entities with typed edges (causes, fixes, depends_on) |
-| `add_observations` | Attach observations to entities |
-| `search_nodes` / `open_nodes` | Query the graph |
-| `read_graph` | Export full graph for visualization |
-
-> **Drop-in compatible** with [MCP Official Memory Server](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) — same API, more features.
+### 25 MCP Tools
 
-### 9 Observation Types
-
-Every memory is classified for intelligent retrieval:
-
-| Icon | Type | When To Use |
-|------|------|-------------|
-| 🎯 | `session-request` | Original task/goal for this session |
-| 🔴 | `gotcha` | Critical pitfall — "Never do X because Y" |
-| 🟡 | `problem-solution` | Bug fix with root cause and solution |
-| 🔵 | `how-it-works` | Technical explanation of a system |
-| 🟢 | `what-changed` | Code/config change record |
-| 🟣 | `discovery` | New insight or finding |
-| 🟠 | `why-it-exists` | Rationale behind a design choice |
-| 🟤 | `decision` | Architecture/design decision |
-| ⚖️ | `trade-off` | Compromise with pros/cons |
+| Category | Tools | What They Do |
+|----------|-------|-------------|
+| **Store & Classify** | `memorix_store`, `memorix_suggest_topic_key` | Store memories with 9 types (🔴gotcha 🟤decision 🟡fix ...), dedup via topic keys |
+| **Search & Retrieve** | `memorix_search`, `memorix_detail`, `memorix_timeline` | 3-layer progressive disclosure (~10x token savings), temporal queries, chronological context |
+| **Sessions** | `memorix_session_start/end/context` | Auto-inject previous session context, save structured summaries |
+| **Maintenance** | `memorix_retention`, `memorix_consolidate`, `memorix_export/import` | Decay scoring, merge duplicates, backup & share |
+| **Dashboard** | `memorix_dashboard` | Interactive web UI — D3.js knowledge graph, observation browser, retention panel |
+| **Workspace Sync** | `memorix_workspace_sync`, `memorix_rules_sync`, `memorix_skills` | Migrate MCP configs across 8 agents, sync rules (`.mdc` ↔ `CLAUDE.md` ↔ `.kiro/steering/`), auto-generate project skills |
+| **Knowledge Graph** | `create_entities`, `create_relations`, `add_observations`, `delete_entities`, `delete_observations`, `delete_relations`, `search_nodes`, `open_nodes`, `read_graph` | [MCP Official Memory Server](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) compatible — same API, more features |
 
-### Visual Dashboard
-
-Run `memorix_dashboard` to open a web UI at `http://localhost:3210`:
+### 9 Observation Types
 
-- **Interactive Knowledge Graph** — D3.js force-directed visualization of entities and relations
-- **Observation Browser** — Filter by type, search with highlighting, expand/collapse details
-- **Retention Panel** — See which memories are active, stale, or candidates for archival
-- **Project Switcher** — View any project's data without switching IDEs
-- **Batch Cleanup** — Auto-detect and bulk-delete low-quality observations
-- **Light/Dark Theme** — Premium glassmorphism design, bilingual (EN/中文)
+Every memory is classified: 🎯 session-request · 🔴 gotcha · 🟡 problem-solution · 🔵 how-it-works · 🟢 what-changed · 🟣 discovery · 🟠 why-it-exists · 🟤 decision · ⚖️ trade-off
 
 ### Auto-Memory Hooks
 
-Memorix can **automatically capture** decisions, errors, and gotchas from your coding sessions:
-
 ```bash
 memorix hooks install    # One-command setup
 ```
 
-- **Implicit Memory** — Detects patterns like "I decided to...", "The bug was caused by...", "Never use X"
-- **Session Start Injection** — Loads recent high-value memories into agent context automatically
-- **Multi-Language** — English + Chinese keyword matching
-- **Smart Filtering** — 30s cooldown, skips trivial commands (ls, cat, pwd)
+Automatically captures decisions, errors, and gotchas from your coding sessions. Detects patterns in English + Chinese, injects high-value memories at session start, with smart filtering (30s cooldown, skips trivial commands).
 
 ---
 
@@ -375,7 +322,7 @@ memorix hooks install    # One-command setup
 
 | | [Mem0](https://github.com/mem0ai/mem0) | [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service) | [claude-mem](https://github.com/anthropics/claude-code) | **Memorix** |
 |---|---|---|---|---|
-| **Agents supported** | SDK-based | 13+ (MCP) | Claude Code only | **7 IDEs (MCP)** |
+| **Agents supported** | SDK-based | 13+ (MCP) | Claude Code only | **8 agents (MCP)** |
 | **Cross-agent sync** | No | No | No | **Yes (configs, rules, skills, workflows)** |
 | **Rules sync** | No | No | No | **Yes (7 formats)** |
 | **Skills engine** | No | No | No | **Yes (auto-generated from memory)** |
@@ -387,7 +334,7 @@ memorix hooks install    # One-command setup
 | **Visual dashboard** | Cloud UI | Yes | No | **Yes (web UI + D3.js graph)** |
 | **Privacy** | Cloud | Local | Local | **100% Local** |
 | **Cost** | Per-call API | $0 | $0 | **$0** |
-| **Install** | `pip install` | `pip install` | Built into Claude | **`npx memorix serve`** |
+| **Install** | `pip install` | `pip install` | Built into Claude | **`npm i -g memorix`** |
 
 **Memorix is the only tool that bridges memory AND workspace across agents.**
 
@@ -413,9 +360,9 @@ With vector search, queries like "authentication" also match memories about "log
 
 - **Auto-detected** — Project identity from `git remote` URL, zero config needed
 - **MCP roots fallback** — If `cwd` is not a project (e.g., Antigravity), Memorix tries the [MCP roots protocol](https://modelcontextprotocol.io/docs/concepts/roots) to get your workspace path from the IDE
-- **Per-project storage** — `~/.memorix/data/<owner--repo>/` per project
+- **Shared storage, metadata isolation** — All data lives in `~/.memorix/data/`, with `projectId` embedded in each observation. This ensures cross-IDE sharing works even when different IDEs detect different project IDs for the same repo
 - **Scoped search** — Defaults to current project; `scope: "global"` to search all
-- **Zero cross-contamination** — Project A's decisions never leak into project B
+- **Zero cross-contamination** — Search results are filtered by project ID; project A's decisions never appear in project B's searches
 
 **Detection priority:** `--cwd` → `MEMORIX_PROJECT_ROOT` → `INIT_CWD` → `process.cwd()` → MCP roots → error
 
@@ -436,7 +383,7 @@ Run `memorix_workspace_sync` with action `"migrate"` and your target IDE. It sca
 Memorix workspace sync migrates MCP configs, agent rules (`.mdc` ↔ `CLAUDE.md` ↔ `.kiro/steering/`), skills, and workflows. One command, seconds to complete.
 
 **Is there an MCP server for persistent AI coding memory?**
-Yes — Memorix is a cross-agent memory MCP server supporting 7 IDEs with knowledge graph, 3-layer progressive disclosure search, workspace sync, and auto-generated project skills.
+Yes — Memorix is a cross-agent memory MCP server supporting 8 agents with knowledge graph, 3-layer progressive disclosure search, workspace sync, and auto-generated project skills.
 
 **How is this different from mcp-memory-service?**
 Both are great memory servers. Memorix adds: cross-agent workspace sync (MCP configs, rules, skills), auto-generated project skills from memory patterns, 3-layer token-efficient search, and session-start memory injection hooks.
@@ -456,7 +403,7 @@ cd memorix
 npm install
 
 npm run dev          # tsup watch mode
-npm test             # vitest (422 tests)
+npm test             # vitest (509 tests)
 npm run lint         # TypeScript type check
 npm run build        # Production build
 ```