memorix 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -2,7 +2,36 @@
 
 All notable changes to this project will be documented in this file.
 
-## [Unreleased]
+## [1.2.2] - 2026-07-25
+
+### Added
+- **Direct CLI control plane** -- Added a consistent terminal surface for memory, context, Code State, knowledge, coordination, audit, and transfer work. `--cwd` selects the Git project from any shell, `memorix workbench` explicitly opens the interactive terminal UI, and every action group now has task-oriented help.
+- **Explicit local CLI identity** -- Added `memorix identity status|join|use|clear`. A user can deliberately activate one project coordination identity for personal/team memory and task, message, lock, handoff, and poll commands without needing an MCP connection.
+- **Automation-friendly transfer** -- Memory exports can write directly to a file, and imports accept `--file` or `--stdin` as well as existing inline JSON.
+
+### Changed
+- **One visibility reader across terminal surfaces** -- CLI commands, Workbench search, recents, health, graph, knowledge, and chat now resolve the same project/actor reader. An unbound terminal remains project-scoped by default.
+- **CLI ergonomics** -- Root `search`, `remember`, and `recent` aliases now use the canonical memory commands; kebab-case flags are accepted alongside the existing camelCase forms.
+
+### Fixed
+- **Private evidence cannot become public indirectly** -- Personal and team observations are rejected when promoting shared skills or generating project skills.
+- **TUI visibility mismatch** -- The interactive terminal UI no longer falls back to an unbound reader after an explicit local identity has been activated.
+- **Transfer visibility bypass** -- CLI and MCP exports now include only observations readable by the current caller, rather than exporting personal/team records from the same project by default.
+
+## [1.2.1] - 2026-07-19
+
+### Added
+- **Review-gated Knowledge claims** -- Explicit agent observations now become source-backed candidates first. They can be inspected and deliberately approved or rejected through `memorix knowledge claims` / `memorix knowledge review` or the advanced `memorix_knowledge` MCP action before they enter knowledge compilation.
+- **Versioned Memorix release workflow** -- Added `docs/knowledge/workflows/memorix-release.md`, a canonical release playbook with verification gates and an explicit maintainer approval boundary.
+
+### Fixed
+- **Claude setup respects `--noHooks`** -- Project setup now keeps generated `CLAUDE.md` guidance without also creating Claude lifecycle-hook configuration when hook capture was explicitly disabled.
+- **Claude Code manual MCP readiness** -- Manual setup examples now include Claude Code's `alwaysLoad: true` entry and point to Doctor/Repair for detecting and restoring the eager-load contract.
+- **Workflow import fidelity** -- Canonical Windsurf workflows preserve their source ID, title, agents, phases, and verification gates instead of being reduced to a generated `workflow:<hash>` entry. Release workflows no longer match a non-release task merely because it says “verify” or “test”.
+- **Graph surface consistency** -- Explicit `relatedEntities` now persist as graph edges, and MCP graph tools, standalone Dashboard, HTTP control plane, and exports share one project-scoping rule.
+- **Intent-aware task and workflow routing** -- A safety constraint such as “do not publish” no longer routes an incident or debugging task into a release lens or release workflow. Explicit release requests still retain release verification while publication is deferred for approval.
+- **Git fact consistency** -- Project Context, Context Pack, and CodeGraph CLI now report `Git: unavailable` for an invalid or unreadable repository instead of presenting it as a clean worktree.
+- **Windows verification-gate timeout** -- A timed-out orchestration gate now resolves promptly while its shell process tree is terminated in the background, instead of waiting indefinitely for a descendant process to close.
 
 ## [1.2.0] - 2026-07-18
 

package/README.md

@@ -64,7 +64,7 @@ Memorix is more than a memory store. It also installs agent integrations, keeps
 | Code State and Code Memory | Versioned local code snapshots, file/symbol links, and freshness checks. The built-in Lite index is always honest about its limits; an already-indexed local CodeGraph can add a bounded semantic outline | `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 |
-| Knowledge Workspace | Reviewable Markdown pages and project playbooks compiled from source-backed claims; proposals never overwrite reviewed pages silently | `memorix knowledge`, `memorix knowledge workflow` |
+| Knowledge Workspace | Review-gated source-backed claims, Markdown pages, and canonical project workflows; proposals never overwrite reviewed pages silently | `memorix knowledge`, `memorix knowledge workflow` |
 | 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` |
@@ -258,7 +258,7 @@ What it installs depends on the target agent, but the goal is the same: make Mem
 - Hermes Agent: installs into Hermes home (`%LOCALAPPDATA%\hermes` on native Windows, `~/.hermes` elsewhere, or `HERMES_HOME`), enables the plugin in `config.yaml`, registers plugin hooks, slash/CLI commands, skills, and writes MCP config.
 - Oh-my-Pi: installs an `omp.extensions` package with extension hook events, a `memorix` command, official skills, and writes MCP config.
 
-Need a quieter install? Add `--noHooks` for targets where setup can control hook capture separately from the host's official package entry.
+Need a quieter install? Add `--noHooks` for targets where setup can control hook capture separately from the host's official package entry. It keeps MCP and guidance, but skips Memorix hook capture.
 
 If you intentionally want repo-local guidance or hooks, run the same command inside that repository without `--global`.
 
@@ -275,6 +275,8 @@ If your agent only needs a manual MCP entry, use stdio:
 }
 ```
 
+For a manually managed Claude Code entry, add `"alwaysLoad": true` inside the `memorix` server object. This lets Claude Code expose Memorix tools during print-mode startup; `memorix doctor agents --agent claude` can detect and repair a missing setting.
+
 HTTP is not required for normal setup. Use it only when you intentionally want a shared background service, dashboard, Docker, or multiple clients using the same endpoint:
 
 ```bash
@@ -315,14 +317,25 @@ npm uninstall -g memorix
 ### Work from the CLI
 
 ```bash
-memorix context --task "continue release blocker"
+memorix --cwd /path/to/repo context --task "continue release blocker"
 memorix memory search --query "release blocker"
+memorix memory --help
+
+# Optional: activate one local agent identity for personal/team records and coordination.
+memorix identity join --agent-type codex --name codex-main
+memorix memory store --text "private investigation note" --visibility personal
+memorix task create --description "verify the release package"
+
+memorix transfer export --format json --out ./.memorix-export.json
+memorix transfer import --file ./.memorix-export.json
 memorix reasoning search --query "why sqlite"
 memorix git-hook --force
 memorix ingest log --count 20
-memorix dashboard
+memorix workbench
 ```
 
+The CLI is direct and does not depend on an MCP session. It binds to the current Git project, or to the project supplied with `--cwd`. Without an active identity it reads, writes, and exports project-visible memory only. Use `memorix identity join` or `memorix identity use --agent-id <id>` only when you intentionally need personal/team memory or coordinated task actions; `memorix identity clear` returns the terminal to project scope. `--as <active-agent-id>` is the one-command alternative for scripts. Both camelCase and kebab-case flags are accepted.
+
 ### Use the bundled terminal agent
 
 ```bash
@@ -356,6 +369,7 @@ Search is project-scoped by default. `scope="global"` searches across projects.
 | Run shared HTTP MCP plus dashboard | `memorix background start` |
 | Debug HTTP MCP in the foreground | `memorix serve-http --port 3211` |
 | Inspect or manage memory directly | `memorix memory`, `memorix reasoning`, `memorix session`, `memorix ingest` |
+| Use the interactive terminal memory control plane | `memorix workbench` |
 | Use the bundled terminal agent | `memorix` or `memcode` |
 | Run orchestrated subagent work | `memorix orchestrate --goal "..."` |
 

package/README.zh-CN.md

@@ -64,7 +64,7 @@ Memorix 不只是一个记忆库。它还负责安装 Agent 接入、保留有
 | Code State 和 Code Memory | 可版本化的本地代码快照、文件 / symbol 关联和 freshness 检查。内置 Lite 会如实说明边界；已有本地索引的 CodeGraph 可额外给出有预算的语义关系 | `memorix codegraph`、自动 context refresh |
 | Git Memory | 从 commit 中提取工程事实，回答改了什么、在哪里改、为什么重要 | `memorix ingest commit`、git hook |
 | Reasoning Memory | 保存设计原因、备选方案、trade-off 和风险，不让决策只留在一次聊天里 | `memorix reasoning`、memory formation |
-| Knowledge Workspace | 基于来源证据的可审阅 Markdown 知识页和项目工作流；提案不会悄悄覆盖已审阅页面 | `memorix knowledge`、`memorix knowledge workflow` |
+| Knowledge Workspace | 有审核门槛的来源证据 Claim、Markdown 知识页和规范化项目工作流；提案不会悄悄覆盖已审阅页面 | `memorix knowledge`、`memorix knowledge workflow` |
 | 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` |
@@ -258,7 +258,7 @@ memorix setup --agent omp --global
 - Hermes Agent：安装到 Hermes home（Windows native 默认为 `%LOCALAPPDATA%\hermes`，其他平台默认为 `~/.hermes`，也支持 `HERMES_HOME`），在 `config.yaml` 启用插件，注册 plugin hooks、slash/CLI commands、skills，并写入 MCP 配置。
 - Oh-my-Pi：安装 `omp.extensions` package，包含 extension hook 事件、`memorix` command、官方 skills，并写入 MCP 配置。
 
-如果你想要更安静一点的安装，可以对那些 setup 能独立控制 hook capture 的 target 加 `--noHooks`。
+如果你想要更安静一点的安装，可以对那些 setup 能独立控制 hook capture 的 target 加 `--noHooks`。它会保留 MCP 和使用规范，只跳过 Memorix 的 hook 自动捕获。
 
 如果你明确想要项目级指导或 hooks，就在那个仓库目录里再跑一次不带 `--global` 的 `memorix setup --agent <agent>`。
 
@@ -275,6 +275,8 @@ memorix setup --agent omp --global
 }
 ```
 
+如果是手动维护 Claude Code 的 MCP 配置，需要在 `memorix` server 对象里加上 `"alwaysLoad": true`。这样 Claude Code 在 print-mode 启动时就会暴露 Memorix tools；`memorix doctor agents --agent claude` 可以检查并修复缺失的设置。
+
 普通安装不需要 HTTP。只有在你明确需要共享后台服务、Dashboard、Docker，或多个客户端共用一个端点时才使用：
 
 ```bash
@@ -315,14 +317,25 @@ npm uninstall -g memorix
 ### 从 CLI 管理记忆
 
 ```bash
-memorix context --task "continue release blocker"
+memorix --cwd /path/to/repo context --task "继续处理发布阻塞问题"
 memorix memory search --query "release blocker"
+memorix memory --help
+
+# 可选：只在需要个人/团队记忆或协同时激活本地身份。
+memorix identity join --agent-type codex --name codex-main
+memorix memory store --text "个人排查笔记" --visibility personal
+memorix task create --description "验证发布包"
+
+memorix transfer export --format json --out ./.memorix-export.json
+memorix transfer import --file ./.memorix-export.json
 memorix reasoning search --query "why sqlite"
 memorix git-hook --force
 memorix ingest log --count 20
-memorix dashboard
+memorix workbench
 ```
 
+CLI 是直接入口，不依赖 MCP 会话。它默认绑定当前 Git 项目，也可以用 `--cwd` 指定项目。没有激活身份时，只会读写和导出项目公开记忆；只有明确需要个人/团队记忆或协同任务时，才运行 `memorix identity join` 或 `memorix identity use --agent-id <id>`。`memorix identity clear` 会回到项目公开范围；脚本可用一次性的 `--as <active-agent-id>`。已有 camelCase 参数仍兼容，kebab-case 也可直接使用。
+
 ### 使用内置终端 Agent
 
 ```bash
@@ -356,6 +369,7 @@ memcode
 | 启动共享 HTTP MCP 和 Dashboard | `memorix background start` |
 | 前台调试 HTTP MCP | `memorix serve-http --port 3211` |
 | 直接检查或管理记忆 | `memorix memory`、`memorix reasoning`、`memorix session`、`memorix ingest` |
+| 使用交互式终端记忆控制台 | `memorix workbench` |
 | 使用内置终端 Agent | `memorix` 或 `memcode` |
 | 运行编排式 subagent 工作 | `memorix orchestrate --goal "..."` |
 

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)` |