memorix 1.1.7 → 1.1.8

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.1.8] - 2026-07-08
+
+### Added
+- **Agent integration doctor and repair** -- Added `memorix doctor agents` and `memorix repair agents` to inspect and repair Memorix-owned agent integration files. The doctor flags stale MCP command paths, missing Claude `alwaysLoad`, missing `memorix` MCP entries, and outdated Memory Autopilot guidance without printing environment secrets.
+
+### Changed
+- **Memory Autopilot adoption** -- Setup-generated agent guidance now makes `memorix_project_context` the default first step for non-trivial coding work before progress files, dev logs, broad file reads, or git archaeology.
+
+### Fixed
+- **Claude Code local MCP repair** -- `memorix doctor agents` and `memorix repair agents` now inspect and repair Claude Code 2.x project-private local MCP entries in `~/.claude.json`, replacing stale worktree commands with `memorix serve` and `alwaysLoad: true`.
+- **Cleaner CodeGraph Memory briefs** -- CodeGraph Lite and Memory Autopilot now ignore `.tmp`, nested `.worktrees`, and `.claude/worktrees` directories, so suggested reads point at the real project instead of local caches or agent scratch worktrees.
+- **All-scope doctor noise** -- Agent doctor now treats one healthy local, project, or global scope as sufficient in all-scope mode, while still flagging genuinely stale or repairable configs.
+
 ## [1.1.7] - 2026-07-07
 
 ### Added

package/CLAUDE.md

@@ -7,9 +7,14 @@ You have access to Memorix, an open-source cross-agent memory layer for coding a
 This project has Memorix MCP tools available for persistent cross-session memory.
 
 For broad continuation or a fresh handoff, start with Memory Autopilot before
-ad-hoc file reads:
+progress files, dev-log reads, ad-hoc file reads, or git archaeology:
 
 - MCP: `memorix_project_context` with the current task
+- Default first step for non-trivial coding work: call
+  `memorix_project_context` with the user's actual task. Memorix will choose a
+  task-lensed brief (bugfix, feature, release, onboarding, refactor, docs, test,
+  or general). Treat its "Start here" files as the first project files to
+  inspect.
 - Claude Code exposes MCP tools through dynamic tool loading. If the tool is not
   directly visible in the first tool list, search/select the Memorix project
   context tool before using shell fallback.

package/README.md

@@ -24,6 +24,7 @@
 <p align="center">
   <a href="README.zh-CN.md">Chinese</a> |
   <a href="#install">Install</a> |
+  <a href="#capabilities">Capabilities</a> |
   <a href="#works-with-your-agent">Agents</a> |
   <a href="#quick-start">Quick Start</a> |
   <a href="#memory-model">Memory Model</a> |
@@ -52,6 +53,25 @@ Use Claude Code today, Codex tomorrow, and Cursor in the afternoon. The agent ca
 
 Memorix is local-first. SQLite is the canonical store, Orama handles search, and LLM-backed formation/embedding is optional. Without model keys, Memorix still works with local full-text retrieval.
 
+### Capabilities
+
+Memorix is more than a memory store. It also installs agent integrations, keeps useful work events, turns commits into project facts, exposes a local control plane, and can coordinate multi-agent work when a task needs it.
+
+| Capability | What it does | Entry point |
+| --- | --- | --- |
+| Memory Autopilot | A task-shaped project brief for a new agent session, with start files, trusted memories, cautions, and verification hints | `memorix context --task "..."`, `memorix_project_context` |
+| Observation Memory | Searchable facts, fixes, gotchas, session summaries, and implementation notes scoped to the current Git project | `memorix memory`, MCP memory tools |
+| Code Memory | File/symbol links and freshness checks so old memories point to current code or show up as suspect/stale | `memorix codegraph`, automatic context refresh |
+| Git Memory | Commit-derived engineering facts that answer what changed, where, and why it matters | `memorix ingest commit`, git hook |
+| Reasoning Memory | Design rationale, alternatives, trade-offs, and risks that should survive beyond one chat | `memorix reasoning`, memory formation |
+| Agent setup | One setup path for MCP, rules, hooks, skills, plugins, bundles, or extensions depending on the agent | `memorix setup --agent <agent>` |
+| Agent doctor | Checks whether agent MCP config and guidance are current, then repairs Memorix-owned entries when needed | `memorix doctor agents`, `memorix repair agents` |
+| Hooks and skills | Optional capture from supported agents, plus reusable project skills promoted from durable knowledge | `memorix hooks`, `memorix skills` |
+| Dashboard and HTTP | A local web UI and shared MCP endpoint for browsing memory, project state, teams, and diagnostics | `memorix dashboard`, `memorix background start` |
+| Orchestration and team work | Task planning, worker handoffs, file locks, messages, verification gates, and review loops | `memorix orchestrate`, `memorix team`, `memorix lock` |
+| memcode | A bundled terminal coding agent that already reads and writes the same project memory | `memorix`, `memcode` |
+| CLI and SDK | Scriptable access for automation, imports/exports, diagnostics, and custom integrations | `memorix ...`, `createMemoryClient()` |
+
 <h2 id="works-with-your-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-agents.svg"><img src="assets/tags/section-agents.svg" alt="Works with every agent" height="32" /></picture></h2>
 
 Memorix connects through the interfaces each agent already supports: plugin packages, MCP, project rules, hooks, skills, or the bundled terminal agent. `memorix setup` chooses the right setup for each agent and keeps stdio MCP as the default transport.
@@ -330,6 +350,7 @@ Search is project-scoped by default. `scope="global"` searches across projects.
 | You want | Run |
 | --- | --- |
 | Install an agent integration package | `memorix setup --agent <agent> --global` |
+| Check or repair an agent integration | `memorix doctor agents --agent <agent>`, `memorix repair agents --agent <agent>` |
 | Manually expose stdio MCP | `memorix serve` |
 | Run shared HTTP MCP plus dashboard | `memorix background start` |
 | Debug HTTP MCP in the foreground | `memorix serve-http --port 3211` |

package/README.zh-CN.md

@@ -24,6 +24,7 @@
 <p align="center">
   <a href="README.md">English</a> |
   <a href="#安装">安装</a> |
+  <a href="#能力矩阵">能力矩阵</a> |
   <a href="#支持你的-agent">Agents</a> |
   <a href="#快速开始">快速开始</a> |
   <a href="#记忆模型">记忆模型</a> |
@@ -52,6 +53,25 @@ Memorix 给你已经在用的 AI 编程 Agent 加上一套共享、可检索的
 
 Memorix 是本地优先的。SQLite 是权威存储，Orama 负责搜索，LLM 记忆整理和 embedding 是可选能力。没有模型 key 时，Memorix 仍然可以用本地全文检索工作。
 
+### 能力矩阵
+
+Memorix 不只是一个记忆库。它还负责安装 Agent 接入、保留有用的工作事件、把 commit 转成工程事实、提供本地控制面，并在需要时协调多 Agent 工作。
+
+| 能力 | 作用 | 入口 |
+| --- | --- | --- |
+| Memory Autopilot | 给新 Agent session 一份按当前任务整理的项目 brief，包含起步文件、可信记忆、风险提示和验证建议 | `memorix context --task "..."`、`memorix_project_context` |
+| Observation Memory | 当前 Git 项目内可检索的事实、修复、坑点、session 摘要和实现记录 | `memorix memory`、MCP memory tools |
+| Code Memory | 文件 / symbol 关联和 freshness 检查；旧记忆会指向当前代码，或标记为 suspect/stale | `memorix codegraph`、自动 context refresh |
+| Git Memory | 从 commit 中提取工程事实，回答改了什么、在哪里改、为什么重要 | `memorix ingest commit`、git hook |
+| Reasoning Memory | 保存设计原因、备选方案、trade-off 和风险，不让决策只留在一次聊天里 | `memorix reasoning`、memory formation |
+| Agent setup | 按目标 Agent 写入 MCP、rules、hooks、skills、plugin、bundle 或 extension | `memorix setup --agent <agent>` |
+| Agent doctor | 检查 Agent 的 MCP 配置和规则是否是当前版本，并修复 Memorix 自己管理的条目 | `memorix doctor agents`、`memorix repair agents` |
+| Hooks 和 skills | 在支持的 Agent 中可选捕获工作事件，并把稳定知识提升成可复用项目技能 | `memorix hooks`、`memorix skills` |
+| Dashboard 和 HTTP | 本地 Web UI 与共享 MCP endpoint，用于浏览记忆、项目状态、团队和诊断信息 | `memorix dashboard`、`memorix background start` |
+| Orchestration 和团队协作 | 任务规划、worker 交接、文件锁、消息、验证门和 review loop | `memorix orchestrate`、`memorix team`、`memorix lock` |
+| memcode | 内置终端 Coding Agent，默认读写同一套项目记忆 | `memorix`、`memcode` |
+| CLI 和 SDK | 给自动化、导入导出、诊断和自定义集成使用的本地接口 | `memorix ...`、`createMemoryClient()` |
+
 <h2 id="支持你的-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-agents.svg"><img src="assets/tags/section-agents.svg" alt="Works with every agent" height="32" /></picture></h2>
 
 Memorix 通过目标 Agent 已有的接口接入：插件包、MCP、项目规则、hooks、skills，或者内置终端 Agent。`memorix setup` 会为每个 Agent 选择合适的接入方式，默认使用 stdio MCP。
@@ -330,6 +350,7 @@ memcode
 | 你想做什么 | 运行 |
 | --- | --- |
 | 安装某个 Agent 的接入包 | `memorix setup --agent <agent> --global` |
+| 检查或修复某个 Agent 接入 | `memorix doctor agents --agent <agent>`、`memorix repair agents --agent <agent>` |
 | 手动暴露 stdio MCP | `memorix serve` |
 | 启动共享 HTTP MCP 和 Dashboard | `memorix background start` |
 | 前台调试 HTTP MCP | `memorix serve-http --port 3211` |

package/TEAM.md

@@ -1,18 +1,18 @@
-# Memorix Team Protocol
-
+# Memorix Team Protocol
+
 Rules for project-scoped autonomous-agent coordination via Memorix team tools. The Team page is an **Agent Team status surface** — it shows explicitly joined autonomous agents, open tasks, locks, messages, handoffs, and what needs attention. It is NOT an organization backend, staffing admin tool, or automatic chat room between separate IDE windows.
 
 Only agents that are intentionally participating in team/task/message/lock workflows need this protocol. Memory-only sessions should stay lightweight and do not need a team identity.
 
 For real autonomous multi-agent development, prefer `memorix orchestrate`: it launches and supervises CLI agent workers through Memorix tasks, context, verification, and fix loops. The team tools support that workflow; they should not be interpreted as proof that unrelated IDE conversation windows can autonomously contact each other.
-
-There are 4 team tools, each with an `action` parameter:
-
-- `team_manage` — action: join / leave / status
-- `team_file_lock` — action: lock / unlock / status
-- `team_task` — action: create / claim / complete / list
-- `team_message` — action: send / broadcast / inbox
-
+
+There are 4 team tools, each with an `action` parameter:
+
+- `team_manage` — action: join / leave / status
+- `team_file_lock` — action: lock / unlock / status
+- `team_task` — action: create / claim / complete / list
+- `team_message` — action: send / broadcast / inbox
+
 ## RULE 1: Start Lightweight, Join Team Explicitly
 
 At the **beginning of every memory session**, before project-scoped memory work:
@@ -25,82 +25,82 @@ At the **beginning of every memory session**, before project-scoped memory work:
 4. Store the returned **agent ID** only after an explicit join — you will need it for subsequent team operations.
 5. Call `memorix_poll` with your agent ID to see current autonomous agents, check available tasks, and read unread messages.
 6. If you need a custom role or capabilities, use explicit `team_manage(join)` so the role overrides the default mapping cleanly.
-
-## RULE 2: Lock Before Edit
-
-Before modifying any file that another agent might also be working on:
-
-1. Call `team_file_lock` with `action: "status"` and the file path to check if it is already locked.
-2. If unlocked, call `team_file_lock` with `action: "lock"`, the file path, and your agent ID.
-3. If locked by another agent, **do not edit that file**. Either:
-   - Work on a different file.
-   - Send a `request` message to the lock owner asking them to release it.
-   - Wait and re-check later.
-4. When you are done editing, call `team_file_lock` with `action: "unlock"` to release the lock.
-
-**Never edit a file locked by another agent.** Lock violations cause merge conflicts and data loss.
-
-Locks auto-expire after 10 minutes. If you hold a lock for extended work, re-lock periodically to refresh the TTL.
-
-## RULE 3: Use Tasks for Work Coordination
-
-When the user assigns work that involves multiple agents or multiple steps:
-
-1. Call `team_task` with `action: "create"` to break the work into discrete tasks with clear descriptions.
-2. Use `deps` to declare dependencies between tasks (a task cannot be claimed until its dependencies are completed).
-3. Call `team_task` with `action: "claim"` to assign a task to yourself before starting work on it.
-4. Call `team_task` with `action: "complete"` and a `result` summary when the task is done.
-5. Call `team_task` with `action: "list"` to see overall progress and find available work.
-
-Rules:
-- Only claim tasks whose dependencies are all completed.
-- Only one agent may claim a given task.
-- If you cannot complete a claimed task, leave the team so the task returns to pending and another agent can pick it up.
-
-## RULE 4: Communication Protocol
-
-Use `team_message` with `action: "send"` for direct messages and `action: "broadcast"` for announcements. Message types and their intended use:
-
-| Type | Use |
-|------|-----|
-| `request` | Ask another agent to do something, release a lock, or provide information. |
-| `response` | Reply to a prior request. |
-| `info` | Share context: discoveries, status updates, warnings about tricky code. |
-| `announcement` | Broadcast to all agents: major state changes, deployment events, breaking changes. |
-| `contract` | Propose or agree on a division of work. Both agents should acknowledge. |
-| `error` | Report a blocking issue that requires another agent's attention. |
-
-Rules:
-- `action: "send"` requires the full UUID of the target agent. Get it from `team_manage` with `action: "status"`.
-- Check your inbox (`action: "inbox"`) at least once before starting new work and once before ending a session.
-- Keep message content under 10KB. Be concise and actionable.
-
-## RULE 5: Leave on Session End
-
-When the session is ending:
-
-1. Call `team_file_lock` with `action: "unlock"` for every file you have locked, or they will remain locked until TTL expiry (10 min).
-2. If you have in-progress tasks you cannot finish, leave them — leaving releases your tasks back to pending.
-3. Call `team_manage` with `action: "leave"` and your agent ID. This marks you inactive, releases all your locks, and clears your inbox.
-
-## RULE 6: Conflict Prevention
-
-- **Check before acting.** Always check team status and file lock status before starting work to understand the current state.
-- **Communicate before diverging.** If you plan to refactor shared code, broadcast an `announcement` first so other agents can save their work.
-- **Respect lock ownership.** The lock holder has exclusive write access. No exceptions.
-- **Prefer small, scoped changes.** Large cross-cutting changes increase conflict risk. Coordinate via tasks and messages if a change touches files other agents are working on.
-- **Do not duplicate work.** Check the task list before creating new tasks. If a similar task exists, claim it instead of creating a duplicate.
-
-## Summary of Required Calls
-
-| When | Tool Call |
-|------|-----------|
+
+## RULE 2: Lock Before Edit
+
+Before modifying any file that another agent might also be working on:
+
+1. Call `team_file_lock` with `action: "status"` and the file path to check if it is already locked.
+2. If unlocked, call `team_file_lock` with `action: "lock"`, the file path, and your agent ID.
+3. If locked by another agent, **do not edit that file**. Either:
+   - Work on a different file.
+   - Send a `request` message to the lock owner asking them to release it.
+   - Wait and re-check later.
+4. When you are done editing, call `team_file_lock` with `action: "unlock"` to release the lock.
+
+**Never edit a file locked by another agent.** Lock violations cause merge conflicts and data loss.
+
+Locks auto-expire after 10 minutes. If you hold a lock for extended work, re-lock periodically to refresh the TTL.
+
+## RULE 3: Use Tasks for Work Coordination
+
+When the user assigns work that involves multiple agents or multiple steps:
+
+1. Call `team_task` with `action: "create"` to break the work into discrete tasks with clear descriptions.
+2. Use `deps` to declare dependencies between tasks (a task cannot be claimed until its dependencies are completed).
+3. Call `team_task` with `action: "claim"` to assign a task to yourself before starting work on it.
+4. Call `team_task` with `action: "complete"` and a `result` summary when the task is done.
+5. Call `team_task` with `action: "list"` to see overall progress and find available work.
+
+Rules:
+- Only claim tasks whose dependencies are all completed.
+- Only one agent may claim a given task.
+- If you cannot complete a claimed task, leave the team so the task returns to pending and another agent can pick it up.
+
+## RULE 4: Communication Protocol
+
+Use `team_message` with `action: "send"` for direct messages and `action: "broadcast"` for announcements. Message types and their intended use:
+
+| Type | Use |
+|------|-----|
+| `request` | Ask another agent to do something, release a lock, or provide information. |
+| `response` | Reply to a prior request. |
+| `info` | Share context: discoveries, status updates, warnings about tricky code. |
+| `announcement` | Broadcast to all agents: major state changes, deployment events, breaking changes. |
+| `contract` | Propose or agree on a division of work. Both agents should acknowledge. |
+| `error` | Report a blocking issue that requires another agent's attention. |
+
+Rules:
+- `action: "send"` requires the full UUID of the target agent. Get it from `team_manage` with `action: "status"`.
+- Check your inbox (`action: "inbox"`) at least once before starting new work and once before ending a session.
+- Keep message content under 10KB. Be concise and actionable.
+
+## RULE 5: Leave on Session End
+
+When the session is ending:
+
+1. Call `team_file_lock` with `action: "unlock"` for every file you have locked, or they will remain locked until TTL expiry (10 min).
+2. If you have in-progress tasks you cannot finish, leave them — leaving releases your tasks back to pending.
+3. Call `team_manage` with `action: "leave"` and your agent ID. This marks you inactive, releases all your locks, and clears your inbox.
+
+## RULE 6: Conflict Prevention
+
+- **Check before acting.** Always check team status and file lock status before starting work to understand the current state.
+- **Communicate before diverging.** If you plan to refactor shared code, broadcast an `announcement` first so other agents can save their work.
+- **Respect lock ownership.** The lock holder has exclusive write access. No exceptions.
+- **Prefer small, scoped changes.** Large cross-cutting changes increase conflict risk. Coordinate via tasks and messages if a change touches files other agents are working on.
+- **Do not duplicate work.** Check the task list before creating new tasks. If a similar task exists, claim it instead of creating a duplicate.
+
+## Summary of Required Calls
+
+| When | Tool Call |
+|------|-----------|
 | Session start | `memorix_session_start` (lightweight) |
 | Join Agent Team | `memorix_session_start(joinTeam=true)` or `team_manage(join)` |
 | After joining | `memorix_poll` (check status + inbox) |
-| Before editing a shared file | `team_file_lock(status)`, `team_file_lock(lock)` |
-| After editing | `team_file_lock(unlock)` |
-| Starting a unit of work | `team_task(claim)` or `team_task(create)` + `team_task(claim)` |
-| Finishing a unit of work | `team_task(complete)` |
-| Need to coordinate | `team_message(send)` or `team_message(broadcast)` |
-| Session end | `team_file_lock(unlock)` (all), `team_manage(leave)` |
+| Before editing a shared file | `team_file_lock(status)`, `team_file_lock(lock)` |
+| After editing | `team_file_lock(unlock)` |
+| Starting a unit of work | `team_task(claim)` or `team_task(create)` + `team_task(claim)` |
+| Finishing a unit of work | `team_task(complete)` |
+| Need to coordinate | `team_message(send)` or `team_message(broadcast)` |
+| Session end | `team_file_lock(unlock)` (all), `team_manage(leave)` |