memorix 0.9.1 → 0.9.3

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.9.3] — 2026-02-25
+
+### Fixed
+- **`memorix_timeline` "not found" bug** — Timeline was using unreliable Orama empty-term search. Now uses in-memory observations (same fix pattern as `memorix_detail`).
+- **`memorix_retention` "no observations found" bug** — Same root cause as timeline. Now uses in-memory observations for reliable document retrieval.
+- **`memorix_search` cross-IDE projectId mismatch** — Removed redundant projectId filter from search. Data isolation is already handled at the directory level. Different IDEs resolving different projectIds for the same directory no longer causes empty search results.
+- **Claude Code hooks format** — Updated `generateClaudeConfig` to use the new `{matcher: {}, hooks: [...]}` structure required by Claude Code 2025+. Fixes "Expected array, but received undefined" error on `memorix hooks install --agent claude --global`.
+- **EPERM `process.cwd()` crash** — All CLI commands (`serve`, `hooks install/uninstall/status`) now safely handle `process.cwd()` failures (e.g., deleted CWD on macOS) with fallback to home directory.
+
+## [0.9.2] — 2026-02-25
+
+### Fixed
+- **Empty directory support** — Memorix now starts successfully in any directory, even without `.git` or `package.json`. No more `__invalid__` project errors for brand new folders. Only truly dangerous directories (home dir, drive root, system dirs) are rejected.
+- **`findPackageRoot` safety** — Walking up from temp/nested directories no longer accidentally selects the home directory as project root.
+
+### Changed
+- **README rewrite** — Complete rewrite of Quick Start section for both EN and 中文 READMEs:
+  - Two-step install (global install + MCP config) instead of error-prone `npx`
+  - Per-agent config examples (Claude Code, Cursor, Windsurf, etc.)
+  - Troubleshooting table for common errors
+  - AI-friendly: agents reading the README will now configure correctly on first try
+
 ## [0.9.1] — 2026-02-25
 
 ### Fixed

package/README.md

@@ -49,35 +49,90 @@ Your AI assistant forgets everything when you start a new chat. You spend 10 min
 
 ## ⚡ Get Started in 30 Seconds
 
-Add this to your agent's MCP config file, restart — done:
+### Step 1: Install globally (one-time)
 
+```bash
+npm install -g memorix
+```
+
+> ⚠️ **Do NOT use `npx`** — npx downloads the package every time, which causes MCP server initialization timeout (60s limit). Global install starts instantly.
+
+### Step 2: Add to your agent's MCP config
+
+<details open>
+<summary><strong>Claude Code</strong></summary>
+
+Run in terminal:
+```bash
+claude mcp add memorix -- memorix serve
+```
+Or manually add to `~/.claude.json`:
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "memorix",
+      "args": ["serve"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Add to `.cursor/mcp.json` in your project:
 ```json
 {
   "mcpServers": {
     "memorix": {
-      "command": "npx",
-      "args": ["-y", "memorix@latest", "serve"]
+      "command": "memorix",
+      "args": ["serve"]
     }
   }
 }
 ```
+</details>
 
-> 📖 **Where is my config file?** → [Full setup guide for all 7 agents](docs/SETUP.md)
-> Windsurf • Cursor • Claude Code • Codex • VS Code Copilot • Kiro • Antigravity
+<details>
+<summary><strong>Windsurf</strong></summary>
 
-That's it. No API keys. No cloud accounts. No dependencies. Just works.
+Add to Windsurf MCP settings (`~/.codeium/windsurf/mcp_config.json`):
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "memorix",
+      "args": ["serve"]
+    }
+  }
+}
+```
+</details>
 
 <details>
-<summary>⚠️ <strong>Antigravity users: extra config required</strong></summary>
+<summary><strong>VS Code Copilot / Codex / Kiro / Antigravity</strong></summary>
 
-Antigravity sets its working directory to its own install path (e.g., `G:\Antigravity`) instead of your project directory, and does not support the MCP roots protocol. You **must** add `MEMORIX_PROJECT_ROOT`:
+Same format — add to the agent's MCP config file:
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "memorix",
+      "args": ["serve"]
+    }
+  }
+}
+```
 
+**Antigravity only:** Antigravity uses its own install path as CWD. You **must** add:
 ```json
 {
   "mcpServers": {
     "memorix": {
-      "command": "npx",
-      "args": ["-y", "memorix@latest", "serve"],
+      "command": "memorix",
+      "args": ["serve"],
       "env": {
         "MEMORIX_PROJECT_ROOT": "E:/your/project/path"
       }
@@ -85,8 +140,23 @@ Antigravity sets its working directory to its own install path (e.g., `G:\Antigr
   }
 }
 ```
+</details>
+
+### Step 3: Restart your agent — done!
+
+No API keys. No cloud accounts. No dependencies. Works with any directory (git repo or not).
 
-You'll need to update `MEMORIX_PROJECT_ROOT` when switching projects. All other IDEs work without this.
+> 📖 **Full setup guide for all 7 agents** → [docs/SETUP.md](docs/SETUP.md)
+
+<details>
+<summary><strong>🔧 Troubleshooting</strong></summary>
+
+| 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` |
 
 </details>
 

package/README.zh-CN.md

@@ -49,35 +49,90 @@
 
 ## ⚡ 30 秒快速开始
 
-在你的 Agent 的 MCP 配置文件中添加以下内容，重启即可：
+### 第一步：全局安装（只需一次）
 
+```bash
+npm install -g memorix
+```
+
+> ⚠️ **不要用 `npx`** — npx 每次都会重新下载包，会导致 MCP 服务器初始化超时（60 秒限制）。全局安装后秒启动。
+
+### 第二步：添加到你的 Agent 的 MCP 配置
+
+<details open>
+<summary><strong>Claude Code</strong></summary>
+
+在终端执行：
+```bash
+claude mcp add memorix -- memorix serve
+```
+或手动添加到 `~/.claude.json`：
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "memorix",
+      "args": ["serve"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+添加到项目目录的 `.cursor/mcp.json`：
 ```json
 {
   "mcpServers": {
     "memorix": {
-      "command": "npx",
-      "args": ["-y", "memorix@latest", "serve"]
+      "command": "memorix",
+      "args": ["serve"]
     }
   }
 }
 ```
+</details>
 
-> 📖 **配置文件在哪里？** → [7 个 Agent 的完整配置指南](docs/SETUP.md)
-> Windsurf • Cursor • Claude Code • Codex • VS Code Copilot • Kiro • Antigravity
+<details>
+<summary><strong>Windsurf</strong></summary>
 
-就是这样。不需要 API Key，不需要云账号，不需要额外依赖。开箱即用。
+添加到 Windsurf MCP 配置（`~/.codeium/windsurf/mcp_config.json`）：
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "memorix",
+      "args": ["serve"]
+    }
+  }
+}
+```
+</details>
 
 <details>
-<summary>⚠️ <strong>Antigravity 用户：需要额外配置</strong></summary>
+<summary><strong>VS Code Copilot / Codex / Kiro / Antigravity</strong></summary>
 
-Antigravity 会将工作目录设为自身安装路径（如 `G:\Antigravity`），而不是你的项目目录，且不支持 MCP roots 协议。你**必须**添加 `MEMORIX_PROJECT_ROOT`：
+同样的格式 — 添加到对应 Agent 的 MCP 配置文件：
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "memorix",
+      "args": ["serve"]
+    }
+  }
+}
+```
 
+**仅 Antigravity：** Antigravity 使用自身安装路径作为工作目录，**必须**添加：
 ```json
 {
   "mcpServers": {
     "memorix": {
-      "command": "npx",
-      "args": ["-y", "memorix@latest", "serve"],
+      "command": "memorix",
+      "args": ["serve"],
       "env": {
         "MEMORIX_PROJECT_ROOT": "E:/your/project/path"
       }
@@ -85,8 +140,23 @@ Antigravity 会将工作目录设为自身安装路径（如 `G:\Antigravity`）
   }
 }
 ```
+</details>
+
+### 第三步：重启你的 Agent — 完成！
+
+不需要 API Key，不需要云账号，不需要额外依赖。**任何目录都能用**（有没有 git 都行）。
 
-切换项目时需要更新 `MEMORIX_PROJECT_ROOT`。其他所有 IDE 都不需要这个配置。
+> 📖 **7 个 Agent 的完整配置指南** → [docs/SETUP.md](docs/SETUP.md)
+
+<details>
+<summary><strong>🔧 常见问题</strong></summary>
+
+| 问题 | 解决方案 |
+|------|----------|
+| `MCP server initialization timed out after 60 seconds` | 你在用 `npx`。执行 `npm install -g memorix`，然后把配置改成 `"command": "memorix"` |
+| `Cannot start Memorix: no valid project detected` | 你的工作目录是系统目录（主目录、桌面等）。打开一个真正的项目文件夹，或设置 `MEMORIX_PROJECT_ROOT` |
+| `memorix: command not found` | 先执行 `npm install -g memorix`，用 `memorix --version` 验证 |
+| 参数类型错误（GLM/非 Anthropic 模型） | 更新到 v0.9.1+：`npm install -g memorix@latest` |
 
 </details>
 

package/dist/cli/index.js

@@ -959,37 +959,30 @@ async function getObservationsByIds(ids, projectId) {
   }
   return results;
 }
-async function getTimeline(anchorId, projectId, depthBefore = 3, depthAfter = 3) {
-  const database = await getDb();
-  const searchParams = {
-    term: "",
-    limit: 1e3
-  };
-  if (projectId) {
-    searchParams.where = { projectId };
-  }
-  const allResults = await search(database, searchParams);
-  const docs = allResults.hits.map((h) => h.document).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-  const anchorIndex = docs.findIndex((d) => d.observationId === anchorId);
+async function getTimeline(anchorId, _projectId, depthBefore = 3, depthAfter = 3) {
+  const { getAllObservations: getAllObservations2 } = await Promise.resolve().then(() => (init_observations(), observations_exports));
+  const allObs = getAllObservations2();
+  const sorted = allObs.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+  const anchorIndex = sorted.findIndex((o) => o.id === anchorId);
   if (anchorIndex === -1) {
     return { before: [], anchor: null, after: [] };
   }
-  const toIndexEntry = (doc) => {
-    const obsType = doc.type;
+  const toIndexEntry = (obs) => {
+    const obsType = obs.type;
     return {
-      id: doc.observationId,
-      time: formatTime(doc.createdAt),
+      id: obs.id,
+      time: formatTime(obs.createdAt),
       type: obsType,
       icon: OBSERVATION_ICONS[obsType] ?? "\u2753",
-      title: doc.title,
-      tokens: doc.tokens
+      title: obs.title,
+      tokens: obs.tokens
     };
   };
-  const before = docs.slice(Math.max(0, anchorIndex - depthBefore), anchorIndex).map(toIndexEntry);
-  const after = docs.slice(anchorIndex + 1, anchorIndex + 1 + depthAfter).map(toIndexEntry);
+  const before = sorted.slice(Math.max(0, anchorIndex - depthBefore), anchorIndex).map(toIndexEntry);
+  const after = sorted.slice(anchorIndex + 1, anchorIndex + 1 + depthAfter).map(toIndexEntry);
   return {
     before,
-    anchor: toIndexEntry(docs[anchorIndex]),
+    anchor: toIndexEntry(sorted[anchorIndex]),
     after
   };
 }
@@ -1169,6 +1162,7 @@ var init_entity_extractor = __esm({
 // src/memory/observations.ts
 var observations_exports = {};
 __export(observations_exports, {
+  getAllObservations: () => getAllObservations,
   getObservation: () => getObservation,
   getObservationCount: () => getObservationCount2,
   getProjectObservations: () => getProjectObservations,
@@ -1336,6 +1330,9 @@ function getObservation(id) {
 function getProjectObservations(projectId) {
   return observations.filter((o) => o.projectId === projectId);
 }
+function getAllObservations() {
+  return [...observations];
+}
 function getObservationCount2() {
   return observations.length;
 }
@@ -1678,20 +1675,19 @@ function detectProject(cwd) {
     const name2 = id2.split("/").pop() ?? path4.basename(rootPath);
     return { id: id2, name: name2, gitRemote, rootPath };
   }
-  if (!isValidProjectRoot(rootPath)) {
+  if (isDangerousRoot(rootPath)) {
     console.error(`[memorix] Skipped invalid project root: ${rootPath}`);
     return { id: "__invalid__", name: "unknown", rootPath };
   }
   const name = path4.basename(rootPath);
   const id = `local/${name}`;
-  console.error(`[memorix] Warning: no git remote found at ${rootPath}, using fallback projectId: ${id}`);
   return { id, name, rootPath };
 }
-function isValidProjectRoot(dirPath) {
+function isDangerousRoot(dirPath) {
   const resolved = path4.resolve(dirPath);
   const home = path4.resolve(os2.homedir());
-  if (resolved === home) return false;
-  if (resolved === path4.parse(resolved).root) return false;
+  if (resolved === home) return true;
+  if (resolved === path4.parse(resolved).root) return true;
   const basename2 = path4.basename(resolved).toLowerCase();
   const knownNonProjectDirs = /* @__PURE__ */ new Set([
     // IDE / editor config dirs
@@ -1728,31 +1724,16 @@ function isValidProjectRoot(dirPath) {
   if (knownNonProjectDirs.has(basename2)) {
     const parent = path4.resolve(path4.dirname(resolved));
     if (parent === home || parent === path4.parse(parent).root) {
-      return false;
+      return true;
     }
   }
-  const projectIndicators = [
-    "package.json",
-    "Cargo.toml",
-    "go.mod",
-    "pyproject.toml",
-    "setup.py",
-    "pom.xml",
-    "build.gradle",
-    "Makefile",
-    "CMakeLists.txt",
-    "composer.json",
-    "Gemfile",
-    ".git",
-    "README.md",
-    "README"
-  ];
-  return projectIndicators.some((f) => existsSync(path4.join(resolved, f)));
+  return false;
 }
 function findPackageRoot(cwd) {
   let dir = path4.resolve(cwd);
   const root = path4.parse(dir).root;
   while (dir !== root) {
+    if (isDangerousRoot(dir)) return null;
     if (existsSync(path4.join(dir, "package.json"))) {
       return dir;
     }
@@ -3719,18 +3700,23 @@ function resolveHookCommand() {
 }
 function generateClaudeConfig() {
   const cmd = `${resolveHookCommand()} hook`;
-  const hookEntry = {
-    type: "command",
-    command: cmd,
-    timeout: 10
+  const hookGroup = {
+    matcher: {},
+    hooks: [
+      {
+        type: "command",
+        command: cmd,
+        timeout: 10
+      }
+    ]
   };
   return {
     hooks: {
-      SessionStart: [hookEntry],
-      PostToolUse: [hookEntry],
-      UserPromptSubmit: [hookEntry],
-      PreCompact: [hookEntry],
-      Stop: [hookEntry]
+      SessionStart: [hookGroup],
+      PostToolUse: [hookGroup],
+      UserPromptSubmit: [hookGroup],
+      PreCompact: [hookGroup],
+      Stop: [hookGroup]
     }
   };
 }
@@ -5629,8 +5615,10 @@ Use this as the \`topicKey\` parameter in \`memorix_store\` to enable upsert beh
         maxTokens: safeMaxTokens,
         since,
         until,
-        // Default to current project scope; 'global' removes the project filter
-        projectId: scope === "global" ? void 0 : project.id
+        // Data isolation is handled at the directory level (each project has its own data dir).
+        // No projectId filter needed — avoids cross-IDE search failures when different IDEs
+        // resolve different projectIds for the same directory.
+        projectId: void 0
       });
       let text = result.formatted;
       if (!syncAdvisoryShown && syncAdvisory) {
@@ -5727,13 +5715,24 @@ ${result.remaining} active observations remaining.
 Archived memories can be restored manually if needed.` }]
         };
       }
-      const database = await (await Promise.resolve().then(() => (init_orama_store(), orama_store_exports))).getDb();
-      const allResults = await search2(database, {
-        term: "",
-        where: {},
-        limit: 1e4
-      });
-      const docs = allResults.hits.map((h) => h.document);
+      const { getAllObservations: getAllObservations2 } = await Promise.resolve().then(() => (init_observations(), observations_exports));
+      const allObs = getAllObservations2();
+      const docs = allObs.map((obs) => ({
+        id: `obs-${obs.id}`,
+        observationId: obs.id,
+        entityName: obs.entityName,
+        type: obs.type,
+        title: obs.title,
+        narrative: obs.narrative,
+        facts: obs.facts.join("\n"),
+        filesModified: obs.filesModified.join("\n"),
+        concepts: obs.concepts.join(", "),
+        tokens: obs.tokens,
+        createdAt: obs.createdAt,
+        projectId: obs.projectId,
+        accessCount: 0,
+        lastAccessedAt: ""
+      }));
       if (docs.length === 0) {
         return {
           content: [{ type: "text", text: "No observations found for this project." }]
@@ -6603,7 +6602,13 @@ var init_serve = __esm({
         const { McpServer: McpServer2 } = await import("@modelcontextprotocol/sdk/server/mcp.js");
         const { createMemorixServer: createMemorixServer2 } = await Promise.resolve().then(() => (init_server2(), server_exports2));
         const { detectProject: detectProject2 } = await Promise.resolve().then(() => (init_detector(), detector_exports));
-        let projectRoot = args.cwd || process.env.MEMORIX_PROJECT_ROOT || process.env.INIT_CWD || process.cwd();
+        let safeCwd;
+        try {
+          safeCwd = process.cwd();
+        } catch {
+          safeCwd = (await import("os")).homedir();
+        }
+        let projectRoot = args.cwd || process.env.MEMORIX_PROJECT_ROOT || process.env.INIT_CWD || safeCwd;
         console.error(`[memorix] Starting with cwd: ${projectRoot}`);
         const earlyDetect = detectProject2(projectRoot);
         const needsRoots = earlyDetect.id === "__invalid__" || earlyDetect.id.startsWith("local/");
@@ -7502,7 +7507,14 @@ var init_hooks_install = __esm({
       },
       run: async ({ args }) => {
         const { detectInstalledAgents: detectInstalledAgents2, installHooks: installHooks2 } = await Promise.resolve().then(() => (init_installers(), installers_exports));
-        const cwd = process.cwd();
+        const os4 = await import("os");
+        let cwd;
+        try {
+          cwd = process.cwd();
+        } catch {
+          cwd = os4.homedir();
+          console.log(`\u26A0\uFE0F Could not access current directory, using home: ${cwd}`);
+        }
         let agents;
         if (args.agent) {
           agents = [args.agent];
@@ -7563,7 +7575,13 @@ var init_hooks_uninstall = __esm({
       },
       run: async ({ args }) => {
         const { detectInstalledAgents: detectInstalledAgents2, uninstallHooks: uninstallHooks2 } = await Promise.resolve().then(() => (init_installers(), installers_exports));
-        const cwd = process.cwd();
+        const os4 = await import("os");
+        let cwd;
+        try {
+          cwd = process.cwd();
+        } catch {
+          cwd = os4.homedir();
+        }
         let agents;
         if (args.agent) {
           agents = [args.agent];
@@ -7605,7 +7623,13 @@ var init_hooks_status = __esm({
       },
       run: async () => {
         const { getHookStatus: getHookStatus2 } = await Promise.resolve().then(() => (init_installers(), installers_exports));
-        const cwd = process.cwd();
+        const os4 = await import("os");
+        let cwd;
+        try {
+          cwd = process.cwd();
+        } catch {
+          cwd = os4.homedir();
+        }
         const statuses = await getHookStatus2(cwd);
         console.log("\nMemorix Hooks Status");
         console.log("\u2550".repeat(50));