memorix 1.0.7 → 1.0.8

package/docs/SETUP.md

@@ -0,0 +1,521 @@
+# Setup Guide
+
+Memorix is an open-source cross-agent memory layer for coding agents via MCP, with tiered support for Cursor, Claude Code, Windsurf (★ core), GitHub Copilot, Kiro, Codex (◆ extended), and Gemini CLI, OpenCode, Antigravity, Trae (○ community).
+
+Memorix has four common operator entry points:
+
+- `memorix` for the interactive local workbench in a TTY
+- `memorix serve` for the default stdio MCP path used by most IDE integrations
+- `memorix background start` for an optional long-lived HTTP control plane
+- `memorix serve-http --port 3211` for foreground HTTP MCP, debugging, and manual supervision
+
+The two server runtime modes are:
+
+- `memorix serve` for stdio MCP integrations
+- `memorix background start` or `memorix serve-http --port 3211` for HTTP MCP, shared access, and a live dashboard endpoint
+
+For most users, start with `memorix` or `memorix serve`. Move to HTTP only when you explicitly want one shared background control plane, multi-client MCP access, or a live dashboard endpoint.
+
+## Current Release Context
+
+This guide targets the **1.0.8** working release line.
+
+If you are setting up Memorix on a fresh machine or upgrading from an older install, the most visible operator-facing changes in 1.0.8 are:
+
+- provenance-aware memory fields and layered retrieval surfaces
+- stronger evidence semantics and citation-lite compact output
+- task-line scoping plus secret-safe storage/retrieval behavior
+- attribution auditing, retention explainability, and a cleaner remediation loop
+- OpenCode compaction using structured continuation context and `post_compact`
+- official Docker deployment for the HTTP control plane
+
+### Support Tiers
+
+| Tier | Clients | Meaning |
+|------|---------|---------|
+| ★ Core | Claude Code, Cursor, Windsurf | Full hook integration + tested MCP + rules sync |
+| ◆ Extended | GitHub Copilot, Kiro, Codex | Hook integration with platform caveats |
+| ○ Community | Gemini CLI, OpenCode, Antigravity, Trae | Best-effort hooks, community-reported compatibility |
+
+**Install ≠ runtime-ready.** `memorix hooks install` succeeds when config files are written to disk; whether the agent actually loads and executes those hooks at runtime depends on the agent's own behavior. Core-tier agents are verified end-to-end; extended/community may have gaps.
+
+---
+
+## 1. Install and Initialize
+
+Install Memorix globally:
+
+```bash
+npm install -g memorix
+```
+
+Initialize Memorix:
+
+```bash
+memorix init
+```
+
+The init wizard lets you choose between:
+
+- `Global defaults` for personal multi-project workflows
+- `Project config` for repo-specific overrides
+
+Memorix then creates the two-file setup it is built around:
+
+- `memorix.yml` for behavior and project settings
+- `.env` for secrets only
+
+See [CONFIGURATION.md](CONFIGURATION.md) for the full model.
+
+---
+
+## 2. Choose a Runtime Mode
+
+### Option A: stdio MCP
+
+```bash
+memorix serve
+```
+
+Use this when your IDE launches Memorix as a local stdio MCP server. This is the default MCP path for most single-IDE setups.
+
+Generic stdio MCP config:
+
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "memorix",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+### Option B: HTTP MCP + Dashboard
+
+```bash
+memorix background start
+```
+
+This mode gives you:
+
+- HTTP MCP endpoint at `http://localhost:3211/mcp`
+- dashboard at `http://localhost:3211`
+- live dashboard with autonomous Agent Team state
+- a single long-lived Memorix process shared by multiple agents
+
+Choose this mode when you intentionally want a shared control plane. It is not the default starting point for normal single-IDE memory use.
+
+Companion commands:
+
+```bash
+memorix background status
+memorix background logs
+memorix background stop
+```
+
+Startup note:
+
+- `serve-http` seeds its default project root from `--cwd` -> `MEMORIX_PROJECT_ROOT` -> `~/.memorix/last-project-root` -> `process.cwd()`
+- this helps the dashboard and control plane start in a sensible project even before any agent binds explicitly
+- in multi-session workflows, agents should still call `memorix_session_start(projectRoot=...)` to avoid cross-project drift
+- HTTP MCP sessions idle out after 30 minutes by default. For clients that do not transparently recover from stale HTTP session IDs, set `MEMORIX_SESSION_TIMEOUT_MS` before starting the control plane, for example `MEMORIX_SESSION_TIMEOUT_MS=86400000` for 24 hours.
+
+Use `memorix serve-http --port 3211` when you want the same HTTP control plane in the foreground for debugging, manual supervision, or a custom port.
+
+Important for multi-project usage:
+
+- In HTTP control-plane mode, agents should call `memorix_session_start` with `projectRoot` set to the **absolute path of the current workspace or repo root** when that path is available.
+- `projectRoot` is a detection anchor only; Git remains the source of truth for the final project identity.
+- If the client cannot provide a reliable workspace path, Memorix should fail closed rather than silently inventing an `untracked/*` project.
+
+Recommended when:
+
+- you want to use the dashboard regularly
+- you want Team tools to work
+- you want multiple IDEs or agents to talk to one Memorix instance
+
+Generic HTTP MCP config:
+
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "transport": "http",
+      "url": "http://localhost:3211/mcp"
+    }
+  }
+}
+```
+
+Some clients use a different key than `transport`. The per-client examples below show the exact shape where that differs.
+
+### Option C: Dockerized HTTP Control Plane
+
+If you want Memorix as a long-lived containerized control plane:
+
+```bash
+docker compose up --build -d
+```
+
+This repo now ships:
+
+- an official `Dockerfile`
+- an example `compose.yaml`
+- a healthchecked HTTP deployment on port `3211`
+
+Docker mode is for:
+
+- `memorix serve-http`
+- dashboard access
+- HTTP MCP clients pointing at `http://localhost:3211/mcp`
+
+It is not a containerized form of stdio MCP.
+
+Important path truth:
+
+- project-scoped Git/config behavior only works when the container can see the repo path it is asked to bind
+- if you run Memorix in Docker on a different machine than your IDE, you must mount the relevant repos into the container or accept reduced project-scoped semantics
+
+See [DOCKER.md](DOCKER.md) for the full deployment guide.
+
+---
+
+## 3. MCP Config by Client
+
+If you want Memorix to generate IDE-specific dot files, install them explicitly:
+
+```bash
+memorix integrate --agent cursor
+memorix integrate --agent windsurf
+memorix integrate --agent opencode
+```
+
+This keeps the default experience MCP-first and zero-write until you opt into a specific IDE integration.
+
+### Claude Code
+
+Recommended:
+
+```bash
+claude mcp add memorix -- memorix serve
+```
+
+Manual config example:
+
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "memorix",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+HTTP example:
+
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "transport": "http",
+      "url": "http://localhost:3211/mcp"
+    }
+  }
+}
+```
+
+If you use the HTTP control plane and your client supports workspace-aware prompts or rules, make sure it calls `memorix_session_start` with the current workspace absolute path as `projectRoot`.
+
+### Cursor
+
+Project config: `.cursor/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "memorix",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Config file: `~/.codeium/windsurf/mcp_config.json`
+
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "memorix",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+HTTP example:
+
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "serverUrl": "http://localhost:3211/mcp"
+    }
+  }
+}
+```
+
+For Windsurf-like HTTP clients, pair the MCP URL with agent instructions that pass the current workspace absolute path as `projectRoot` when starting a Memorix session.
+
+### Codex
+
+Config file: `~/.codex/config.toml`
+
+```toml
+[mcp_servers.memorix]
+command = "memorix"
+args = ["serve"]
+startup_timeout_sec = 30
+```
+
+HTTP example:
+
+```toml
+[mcp_servers.memorix]
+url = "http://localhost:3211/mcp"
+```
+
+For Codex-like HTTP clients, the transport URL alone is not enough for multi-project parallel work. The agent should also call `memorix_session_start` with the current workspace absolute path as `projectRoot`.
+
+### GitHub Copilot / VS Code
+
+Project config: `.vscode/mcp.json`
+
+```json
+{
+  "servers": {
+    "memorix": {
+      "command": "memorix",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+### Kiro
+
+Project config: `.kiro/settings/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "memorix",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+### OpenCode
+
+OpenCode integration is usually file-based and managed through Memorix hook installers or workspace sync. If you use stdio MCP directly, the same `memorix serve` command applies.
+
+### Gemini CLI and similar clients
+
+If the client supports stdio MCP:
+
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "memorix",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+If it supports HTTP MCP, prefer:
+
+- `http://localhost:3211/mcp`
+
+---
+
+## 4. Dashboard
+
+Recommended dashboard entry:
+
+- `http://localhost:3211`
+
+This is the dashboard served by the HTTP control plane. In normal use, start it with `memorix background start`; use `memorix serve-http` when you want the same service in the foreground.
+
+It includes:
+
+- Overview
+- Git Memory
+- Graph
+- Observations
+- Retention
+- Sessions
+- Team
+- Config
+- Identity Health
+
+There is also a standalone `memorix dashboard` command. It is a local read-mostly dashboard that includes memory, sessions, and autonomous Agent Team state from SQLite. HTTP is optional and only needed for shared MCP access or a live control-plane endpoint.
+
+---
+
+## 5. Agent Team Features
+
+Agent Team features are explicit autonomous-agent coordination surfaces. Use the CLI for the normal path:
+
+```bash
+memorix team status
+memorix orchestrate --goal "..."
+```
+
+These features include:
+
+- agent registry
+- direct messages
+- file locks
+- task board
+
+The standalone dashboard can show this state read-only. Start HTTP only when you also want a shared MCP control plane or a live dashboard endpoint.
+
+---
+
+## 6. Common Setup Flows
+
+### Minimal local setup
+
+```bash
+npm install -g memorix
+memorix init
+memorix serve
+```
+
+### Recommended full setup
+
+```bash
+npm install -g memorix
+memorix init
+memorix git-hook --force
+memorix background start
+```
+
+Then:
+
+- point your IDE MCP client to `memorix serve` or `http://localhost:3211/mcp`
+- open the dashboard at `http://localhost:3211`
+
+---
+
+## 7. Troubleshooting
+
+### Avoid `npx`
+
+Do not launch Memorix with `npx` in normal MCP configs. It adds startup cost and can cause handshake timeouts.
+
+Prefer:
+
+```bash
+memorix serve
+```
+
+Not:
+
+```bash
+npx memorix serve
+```
+
+### Windsurf says the MCP config file has invalid JSON
+
+On Windows, `~/.codeium/windsurf/mcp_config.json` must be valid JSON encoded as UTF-8 **without BOM**. A BOM at the start of the file can make Windsurf reject otherwise valid JSON.
+
+### Codex handshake timeout
+
+If Codex reports MCP startup timeouts, increase:
+
+```toml
+startup_timeout_sec = 30
+```
+
+or higher on slower Windows machines.
+
+### Codex stale HTTP session after idle time
+
+If Codex is connected to `http://localhost:3211/mcp` and fails after a long idle period with a transport/body decoding error, the HTTP session may have expired server-side. Memorix defaults to a 30-minute HTTP session idle timeout. Increase it before starting the background control plane:
+
+```powershell
+$env:MEMORIX_SESSION_TIMEOUT_MS = "86400000" # 24h
+memorix background restart
+```
+
+This keeps the default safe for normal users while giving long-running Codex HTTP sessions a practical recovery knob.
+
+### Project detection is wrong
+
+Memorix identifies projects from Git. If an IDE launches from a system directory or does not pass the workspace root correctly:
+
+- prefer opening the repository root in the IDE
+- if needed, set `MEMORIX_PROJECT_ROOT`
+- use `memorix status` to inspect the active project identity
+
+### Dashboard Agent Team page is empty
+
+That usually means no autonomous agent workflow has created tasks, locks, messages, or explicit agent identities for this project yet.
+
+Use:
+
+```bash
+memorix team status
+memorix task list
+```
+
+To create autonomous work, use:
+
+```bash
+memorix orchestrate --goal "..."
+```
+
+If you specifically want shared HTTP MCP or a live dashboard endpoint, then start:
+
+```bash
+memorix background start
+```
+
+### Git hook installed but commits are not appearing as memory
+
+Check:
+
+- the repository has Git initialized
+- the hook file exists
+- the commit was not filtered as noise
+- the active project identity is correct
+
+Use:
+
+```bash
+memorix status
+```
+
+and see [GIT_MEMORY.md](GIT_MEMORY.md).
+
+---
+
+## 8. Related Docs
+
+- [Configuration Guide](CONFIGURATION.md)
+- [Git Memory Guide](GIT_MEMORY.md)
+- [Architecture](ARCHITECTURE.md)
+- [API Reference](API_REFERENCE.md)
+- [Development Guide](DEVELOPMENT.md)

package/docs/hooks-architecture.md

@@ -0,0 +1,108 @@
+# Memorix Hooks Architecture — 无感知自动记忆
+
+## 核心目标
+
+用户安装 Memorix 后，所有 Agent 的对话、决策、bug 修复、配置变更都**自动记录**，
+切换 Agent/窗口/对话时**自动注入**相关上下文，零操作、无感知。
+
+## 各 Agent Hooks 格式对照
+
+### 事件映射表
+
+| 语义 | VS Code Copilot | Claude Code | Windsurf | Cursor (Beta) | Kiro |
+|------|----------------|-------------|----------|---------------|------|
+| 会话开始 | SessionStart | SessionStart | — | — | — |
+| 用户输入 | UserPromptSubmit | UserPromptSubmit | pre_user_prompt | beforeSubmitPrompt | user prompt |
+| 工具调用前 | PreToolUse | PreToolUse | pre_mcp_tool_use | beforeMCPExecution | — |
+| 工具调用后 | PostToolUse | PostToolUse | post_mcp_tool_use | — | — |
+| 文件编辑后 | PostToolUse(write) | PostToolUse(write) | post_write_code | afterFileEdit | file save |
+| 命令执行后 | PostToolUse(cmd) | PostToolUse(cmd) | post_run_command | — | — |
+| AI 回复后 | — | — | post_cascade_response | — | agent turn |
+| 上下文压缩前 | PreCompact | PreCompact | — | — | — |
+| 会话结束 | Stop | Stop | — | stop | — |
+
+### 配置文件位置
+
+| Agent | 配置路径 | 格式 |
+|-------|---------|------|
+| VS Code Copilot | `.github/hooks/*.json` | Claude Code 兼容 |
+| Claude Code | `.claude/settings.json` | 原生 |
+| Windsurf | `.windsurf/cascade.json` | Windsurf 格式 |
+| Cursor | `.cursor/hooks.json` | Cursor 格式 |
+| Kiro | `.kiro/hooks/*.hook.md` | Markdown + YAML |
+
+### stdin/stdout 通信协议
+
+所有 Agent 都用 **stdin JSON → stdout JSON** 通信，但字段名不同：
+
+```
+// VS Code / Claude Code
+{ "hookEventName": "PostToolUse", "sessionId": "...", "cwd": "...", "tool_name": "write", ... }
+
+// Windsurf  
+{ "agent_action_name": "post_write_code", "trajectory_id": "...", "tool_info": { "file_path": "..." } }
+
+// Cursor
+{ "hook_event_name": "afterFileEdit", "conversation_id": "...", "generation_id": "...", ... }
+```
+
+## Memorix Hook Handler 设计
+
+### 统一入口
+
+```bash
+memorix hook <normalized_event> [--agent <agent_name>]
+```
+
+通过 stdin 接收 Agent 原始 JSON，内部做格式归一化。
+
+### 归一化事件
+
+| 归一化事件 | 自动记忆行为 |
+|-----------|------------|
+| `session_start` | 搜索相关记忆 → stdout 注入上下文 |
+| `post_edit` | 分析变更 → 记录 what-changed |
+| `post_command` | 分析命令结果 → 记录 problem-solution (如有错误) |
+| `post_tool` | 分析 MCP 工具调用 → 记录相关操作 |
+| `pre_compact` | 压缩前保存当前上下文摘要 |
+| `session_end` | 总结本次会话 → 记录决策和发现 |
+| `user_prompt` | 模式检测 → 判断是否需要注入记忆 |
+
+### 智能过滤 — 不是什么都记
+
+- **最小内容长度**: 300 字符（避免记录琐碎操作）
+- **去重**: 相似度 > 0.85 的内容不重复记录
+- **冷却时间**: 同类事件 30 秒内不重复触发
+- **模式检测**: 只记录有价值的内容（决策、错误、学习、配置变更）
+
+## 一键安装
+
+```bash
+memorix hooks install
+# 自动检测已安装的 Agent → 生成对应配置文件
+# 支持: --agent cursor|windsurf|claude|copilot|kiro|codex
+# 支持: --project (仅当前项目) | --global (全局)
+```
+
+## 文件结构
+
+```
+memorix/
+  src/
+    hooks/
+      handler.ts        # 统一 hook handler 入口
+      normalizer.ts     # 各 Agent stdin 格式归一化
+      analyzers/
+        edit-analyzer.ts    # 文件变更分析 → what-changed
+        command-analyzer.ts # 命令结果分析 → problem-solution  
+        session-analyzer.ts # 会话总结 → decision/discovery
+        pattern-detector.ts # 模式检测 (decision/error/learning)
+      installers/
+        base.ts             # 安装器基类
+        claude-installer.ts # Claude Code / VS Code Copilot
+        windsurf-installer.ts
+        cursor-installer.ts
+        kiro-installer.ts
+    cli/commands/
+      hooks.ts          # `memorix hooks install/uninstall/status` 命令
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Open-source cross-agent memory layer for coding agents across Cursor, Claude Code, Codex, Windsurf, Gemini CLI, Copilot, Kiro, OpenCode, Antigravity, and Trae via MCP.",
   "type": "module",
   "sideEffects": false,
@@ -17,30 +17,24 @@
     "./types": {
       "import": "./dist/types.js",
       "types": "./dist/types.d.ts"
+    },
+    "./sdk": {
+      "import": "./dist/sdk.js",
+      "types": "./dist/sdk.d.ts"
     }
   },
-  "files": [
-    "dist/index.js",
-    "dist/index.js.map",
-    "dist/index.d.ts",
-    "dist/types.js",
-    "dist/types.js.map",
-    "dist/types.d.ts",
-    "dist/cli/index.js",
-    "dist/cli/index.js.map",
-    "dist/cli/index.d.ts",
-    "dist/dashboard/static/app.js",
-    "dist/dashboard/static/index.html",
-    "dist/dashboard/static/style.css",
-    "dist/dashboard/static/logo.png",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md",
-    "CLAUDE.md",
-    "llms.txt",
-    "llms-full.txt",
-    "README.zh-CN.md"
-  ],
+  "files": [
+    "dist",
+    "README.md",
+    "README.zh-CN.md",
+    "docs",
+    "TEAM.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CLAUDE.md",
+    "llms.txt",
+    "llms-full.txt"
+  ],
   "scripts": {
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsup",
     "dev": "tsup --watch",
@@ -107,6 +101,10 @@
     "gpt-tokenizer": "^2.8.0",
     "gray-matter": "^4.0.3",
     "ink": "^6.8.0",
+    "ink-big-text": "^2.0.0",
+    "ink-gradient": "^4.0.0",
+    "ink-scroll-view": "^0.3.6",
+    "ink-spinner": "^5.0.0",
     "js-yaml": "^3.13.1",
     "react": "^19.2.4",
     "remark": "^15.0.1",
@@ -118,6 +116,9 @@
     "better-sqlite3": "^11.0.0",
     "fastembed": "^1.14.4"
   },
+  "overrides": {
+    "tar": "^7.0.0"
+  },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.0",
     "@types/diff": "^7.0.0",