1. 项目定位与设计目标

Moryn 是一个面向多 Agent、多设备 AI 工作场景的 本地优先（local-first）、用户拥有、可审计的上下文存储与交接层。它既不是 Agent 平台，也不是向量记忆 SDK，更不是托管云服务，而是 Agent 之间的「记忆总线」：默认路径简洁，在用户或 Agent 需要审查、溯源、同步或交接历史时完全可追溯。

核心定位来源于 README.md:1-13：

*"Moryn is a local-first, user-owned, auditable context store and handoff layer for multi-agent, multi-device AI work."*

当前版本为 v0.1.1（首个 npm 发布后的补丁版本），主要交付物包括：本地记忆操作、Git 同步、生命周期交接、包级冒烟测试与 stdio MCP 服务。npm 包名为 @richardyu114/moryn，安装方式为 npm install -g @richardyu114/moryn (package.json:1-3)。

2. 技术栈与运行时约束

模块组织上，源码位于 src/，CLI 与公开库入口分别为 src/cli.ts 与 src/index.ts，核心领域逻辑集中在 src/core/ 下（包括 agent-lifecycle.ts、agent-identity.ts、autocapture-policy.ts、action-safety.ts 等）。

3. 五态记忆模型与敏感数据护栏

Moryn 将所有记录划分为五个生命周期状态，状态转换关系如下：

stateDiagram-v2
    [*] --> raw
    raw --> candidate: 初步入库
    candidate --> canonical: 升级为持久上下文
    candidate --> archived: 归档
    candidate --> quarantined: 隔离
    canonical --> archived: 归档
    canonical --> quarantined: 隔离

• raw：源材料，默认隐藏。
• candidate：可能有用但尚未信任。
• canonical：默认召回返回的持久上下文。
• archived：保留的历史，默认隐藏。
• quarantined：敏感或不安全内容，默认隐藏 (README.md:18-30)。

带 private、secret、sensitive 标签的记录在 boot、recall、refresh、list-recent、timeline、memory doctor、memory lifecycle、capture policy、dogfood report 以及 Dashboard 等读路径上默认排除；仅当显式传入 --include-private 或 MCP 参数 include_private: true 时才返回。高风险 canonical 写入需要用户显式确认 (README.md:32-38)。

4. Agent 生命周期与自动化捕获

Agent 操作走「引导—启动—状态—结束—刷新」五阶段生命周期，模块入口为 src/core/agent-lifecycle.ts，对应 CLI/MCP 工具为 agent_enter、agent_start、agent_status、agent_finish 以及带 refresh_since 的 agent_start 刷新动作。每一步都返回结构化的 next.actions 列表（含 safe_to_run、required_fields、command 模板），驱动 Agent 按机器可读的契约执行 (src/core/agent-lifecycle.ts:148-160、src/core/agent-lifecycle.ts:317-419)。

身份归一化在 src/core/agent-identity.ts:18-23 中预定义四类已知 Agent 家族：codex、claude、kimi、gemini；其它客户端落入 generic 或 unknown 等级，便于在多 Agent 场景下追溯来源。

自动捕获策略（src/core/autocapture-policy.ts）按风险分级路由：

• 低风险 handoff：自动写入 candidate 态，标签 auto-captured，出现在 Dashboard handoff 面板，不进入 canonical (src/core/autocapture-policy.ts:60-78)。
• 带审查风险标记：路由到 capture_inbox，等待用户批/拒决策 (review_required: true、user_action_required: true) (src/core/autocapture-policy.ts:40-58)。

动作安全层 src/core/action-safety.ts 为每个候选动作计算 safe_to_run、缺失字段与 runbook，区分 run / collect_required_fields / confirm_with_user / do_not_auto_run 四类后续步骤，防止 Agent 误触发本地配置写入或高风险升级 (src/core/action-safety.ts:1-60)。

5. 架构总览

下图描绘了用户、Agent、CLI/MCP 与本地 Git 存储之间的关系：

flowchart LR
    User[用户/多设备] -->|决策| Dashboard[moryn dashboard]
    Codex[Codex] -->|stdio MCP| McpServer[moryn mcp]
    Claude[Claude] -->|stdio MCP| McpServer
    Gemini[Gemini] -->|stdio MCP| McpServer
    Cursor[Cursor] -->|stdio MCP| McpServer
    Shell[Shell/脚本] -->|CLI| Cli[moryn CLI]
    McpServer --> Engine[core/engine.ts]
    Cli --> Engine
    Engine --> Store[(本地 Git 仓库<br/>Moryn Store)]
    Engine --> Lifecycle[agent-lifecycle]
    Engine --> Autocap[autocapture-policy]
    Engine --> Safety[action-safety]
    Store <-->|push/pull| GitRemote[(可选 Git Remote)]
    Dashboard --> Store

简而言之：Moryn = CLI + MCP stdio + 本地 Git 存储 + 生命周期/捕获/安全策略。Agent 不直接持有记忆，所有读写都经由 CLI 或 MCP 服务落到用户拥有的本地仓库；Dashboard 提供本地可观测性用于人工审查（v0.1.1 新增 moryn dashboard 命令）。

6. 安装与典型用法

最简启动路径（适配 Codex 等宿主） (README.md:35-44)：

moryn setup --host codex --project . --apply
moryn install --host codex --project . --apply
moryn context pack --project . --agent codex
moryn capture session --project . --agent codex --summary "Finished the task and left handoff notes."

需要诊断记忆质量或生命周期时，使用只读 doctor / lifecycle 报告；需要按时间线追溯时使用 moryn timeline --record-id ... --before 5 --after 5（README.md:70-105）。

See Also

• Contracts — 操作契约、选择源路径、动作模板与结构化恢复元数据
• Agent Workflow — Agent 端到端工作流
• Agent Install Prompt — 可复制给 Agent 的安装提示
• Dashboard — moryn dashboard 本地可观测面板
• Design Spec — 详细设计规范

概述

Moryn 的 Agent 生命周期层为多 Agent 协作提供了一套可审计、可回放的"会话剧本"。它以本地 store 为中心，把一次完整的代理任务拆成 agent_enter → agent_start → agent_status → agent_finish 几个阶段，并附带上下文包（context pack）、选择源路径（selection sources）以及安全护栏（guardrails），让 Codex、Claude、Cursor、Gemini、shell agent 等不同宿主能够遵循同一份语义完成启动、续接、状态发布和交接。所有写操作都要求 safe_to_run: false 直至显式确认，确保用户始终拥有最终决定权 资料来源：src/core/agent-lifecycle.ts:1-80。

@richardyu114/moryn 包以 ESM 模块形式发布，主入口为 dist/index.js，CLI 二进制名为 moryn，对应实现位于 src/core/agent-lifecycle.ts 中的 agentGuide、agentStart、agentStatus、agentFinish 等函数 资料来源：package.json:1-50。当前公开版本为 v0.1.1，已上线 moryn dashboard 等本地观测能力 资料来源：README.md:1-40。

生命周期阶段与上下文包

生命周期由若干步骤（step）组成，每个步骤都返回一份"动作模板 + 上下文包"。agentGuide 默认推荐的入口是 agent_enter，并在响应中给出 startup、lifecycle、lifecycle_by_step、rules、guardrails 五个字段，方便调用方按需选择 资料来源：src/core/agent-lifecycle.ts:120-200。常见步骤及触发条件如下：

agentStart 会先校验 agent 身份字段，再解析项目上下文（resolveLifecycleProjectContext），然后根据 sync_mode 决定是否自动 pull，并在 sync.before / pull / pull_error / after 中记录 Git 同步结果 资料来源：src/core/agent-lifecycle.ts:60-120。所有阶段都共用 lifecycleActionArguments 生成 CLI/MCP 调用的入参，从而保证在 startup 与 next.actions_by_id 中取出的命令行模板是等价的。

会话有效期通过常量 ACTIVE_SESSION_TTL_MINUTES = 120 控制，超过两小时的活动会话会被视为过期，需要重新 start_or_resume 资料来源：src/core/agent-lifecycle.ts:1-40。

flowchart LR
  A[agent_enter / agentGuide] --> B[agent_start\nstart_or_resume]
  B --> C{长任务?}
  C -- 是 --> D[agent_status\npublish_status]
  C -- 否 --> E[agent_finish\nfinish_handoff]
  D --> E
  E --> F[下一个 Agent\nstart_next_session]
  F --> G[agent_start\nrefresh_context]

Agent 身份识别与选择源

Moryn 通过正则白名单识别常见 Agent：codex、claude、kimi、gemini 被归为"已知"（confidence: known），agent、cli、mcp、moryn 等本地通用客户端被归为"通用"（generic），其余原始字符串保留为 unknown 资料来源：src/core/agent-identity.ts:1-60。normalizeAgentIdentity 同时把原始 raw_client 一并返回，方便审计。

agent_enter 在 mode: "discover_projects" 时返回 projects.projects_by_id.<project_id> 等选择源路径，调用方必须先从中挑选一个 project_id 再调用 agent_start，否则会触发 choose_discovered_project_id 步骤并标记 safe_to_run: false 资料来源：src/core/agent-lifecycle.ts:200-320。DISCOVER_PROJECT_SELECTION_SOURCES 与 GUIDE_SELECTION_SOURCES 把这些路径集中导出，确保 CLI、MCP 和 dashboard 共用一套寻址规则。

安全护栏与自动捕获策略

护栏（guardrail）以"必须避免的行为 → 风险 → 替代动作"的形式呈现：

• choose_discovered_project：在项目上下文不明时，禁止猜测 project_id，必须走 agent_enter discovery 流程 资料来源：src/core/agent-lifecycle.ts:320-420。
• use_returned_actions_verbatim：禁止凭记忆重建命令，必须直接消费返回的 command 字符串或 arguments，仅填充 required_fields 列举的占位符 资料来源：src/core/agent-lifecycle.ts:320-420。
• publish_status_and_finish_handoff：要求在长中断前调用 agent_status，在任务结束时调用 agent_finish 留下 summary 资料来源：src/core/agent-lifecycle.ts:320-420。
• pass_sync_remote_for_cross_device_handoff：跨设备交接时必须显式传入 sync_remote 资料来源：src/core/agent-lifecycle.ts:320-420。

action-safety.ts 把这些约束翻译成机器可读的运行手册（runbook），步骤包含 collect_required_inputs、ask_user_confirmation、call_mcp、do_not_run 四种，并暴露 missing_required_fields、required_inputs、choice_options 等选择源供前端回显 资料来源：src/core/action-safety.ts:1-80。

autocapture-policy.ts 定义了自动捕获 handoff 的策略：当内容命中 review_risk_marker 等高风险标记时，决策为 decision: "capture"、route: "review"、target_state: "candidate"、并在 dashboard 的 capture_inbox 面板暴露 user_action_required: true；低风险 handoff 则走 route: "auto_capture"，但仍以 candidate 状态进入存储，不会自动晋升为 canonical 资料来源：src/core/autocapture-policy.ts:1-80。

失败模式与排错

常见失败点与对应错误契约均集中定义：

• 身份字段缺失或类型错误会抛 AgentIdentityError，并附带 recovery_hint 指明 operations_by_id.agent_start 中应补齐的字段 资料来源：src/core/agent-lifecycle.ts:120-200。
• status / summary 为空字符串会抛 AgentLifecycleTextArgumentError，错误对象内嵌 retry_with.value_placeholder: "<status>" 等占位符，便于客户端提示用户重新输入 资料来源：src/core/agent-lifecycle.ts:420-520。
• Git 同步冲突时，assertSyncNotConflicted 会写入 sync.before.conflict 字段，调用方应先解决冲突再继续 agent_start 资料来源：src/core/agent-lifecycle.ts:60-120。
• 自动捕获命中敏感标记时，记录会被写入 quarantined 状态，在 boot、recall、timeline 等读取路径中被默认隐藏，需要显式 --include-private 才会出现 资料来源：README.md:40-120。

参见

• Agent Install Prompt
• Agent Workflow
• Contracts
• Dashboard
• Design Spec

1. 概述

Moryn 的核心是本地优先、用户拥有的上下文存储与交接层。它在多 Agent、多设备的 AI 协作中扮演"记忆总线"的角色：Agent 通过 CLI 或 MCP stdio 服务读取、写入、修订、晋升并交接上下文，而所有记忆的所有权始终属于用户。围绕这一目标，Moryn 在源码层面提供了一套完整的内存状态机、敏感度分级机制、自动捕获策略以及诊断工具链，分别由 schema.ts、sensitive.ts、autocapture-policy.ts、derived.ts、capture-review.ts、capture-policy-report.ts 等模块实现 README.md:1-40。

本主题聚焦于：

• 内存记录的有限状态模型与生命周期转换
• 敏感度标签（private、secret、sensitive）的读写隔离
• 自动捕获策略的路由规则
• 诊断与策略报告工具的输出形态

2. 内存状态模型

Moryn 把任意一条上下文记录视为有限状态机中的一个节点，并定义了五种状态 README.md:1-20：

stateDiagram-v2
    [*] --> raw
    raw --> candidate: 自动捕获
    candidate --> canonical: 用户/Agent 确认
    candidate --> archived: 判定为非关键
    candidate --> quarantined: 命中敏感或风险标记
    canonical --> archived: 降级保留
    canonical --> quarantined: 风险升级
    archived --> [*]
    quarantined --> [*]

各状态语义如下：

• raw：原始素材，默认隐藏，不参与常规召回。
• candidate：可能有用但尚未被信任的中间状态。
• canonical：默认召回的稳定上下文，是用户视角下的"长期记忆"。
• archived：仅作为历史保留，默认隐藏，便于审计与回溯。
• quarantined：隔离区，存放含敏感或风险标记的内容，默认隐藏。

转换由 capture-review.ts 与 autocapture-policy.ts 共同驱动，规则全部以只读策略报告的形式呈现，不会自动改写记录本身 README.md:1-15。

3. 安全分级与隔离

Moryn 把 private、secret、sensitive 视为主动记录的标签，但它们在常规操作中被显式排除。被排除的接口包括 boot、recall、refresh、list-recent、timeline、memory doctor、memory lifecycle、capture policy、dogfood report 以及 Dashboard 的常规视图 README.md:1-25。

要访问这些记录，必须显式声明意图：

src/core/sensitive.ts 负责标签的归一化与匹配，src/core/derived.ts 在派生视图（timeline、dogfood report 等）中对带标签记录做脱敏或剔除，而 agent-identity.ts 则确保每次写入都附带 client、session_id、model、device_id 等可追溯身份字段 src/core/agent-identity.ts:1-30src/core/agent-lifecycle.ts:1-50。

4. 自动捕获与诊断工具

4.1 自动捕获策略

src/core/autocapture-policy.ts 是路由中枢。它评估传入的捕获请求并返回 policy_id、version、decision、route、target_state、review_required、user_action_required 等字段。命中 review_risk_marker 的请求会进入 Dashboard 的 capture_inbox 表面，等待批量审批；低风险交接则自动落入 candidate 状态，附带 auto-captured 标签 src/core/autocapture-policy.ts:1-60。

4.2 诊断与策略报告

诊断链路由 memory doctor、memory lifecycle 与只读的 capture_policy 报告组成。后者解释自动捕获、审核、归档的路由逻辑，但不会修改存储——这是 Moryn 区别于"黑盒记忆 SDK"的关键约束 README.md:1-25。action-safety.ts 为每条返回的命令计算 ready_to_run、blocked_by、runbook，并在写操作前给出 requires_user_confirmation 标记，保证高风险动作只能由显式意图触发 src/core/action-safety.ts:1-80。

4.3 常见失败模式

• 在未知项目上下文下写入：会触发 AgentIdentityError，推荐先调用 agent_enter 完成发现并选择 project_id src/core/agent-lifecycle.ts:1-50。
• 凭记忆拼装命令：可能改写字段名、丢失占位符，应直接使用响应中 next.actions_by_id 返回的命令串 src/core/agent-lifecycle.ts:1-50。
• 跨设备交接未传 sync_remote：状态与摘要可能仅停留在本机 src/core/agent-lifecycle.ts:1-50。

5. 开发与发布检查

package.json 定义了构建、类型检查、单测与发布前自检脚本。建议在发布前运行 npm run release:check，必要时设置 MORYN_PRIVATE_GIT_REMOTE 指向专用测试仓库，以完成真实远程写入验证 package.json:1-50README.md:1-50。

See Also

• Agent 安装与协作流程：Agent Workflow
• 命令与数据结构契约：Contracts
• Dashboard 使用说明：Dashboard
• 总体设计规范：Design Spec

概述

Moryn 是一个本地优先、用户拥有、可审计的上下文存储与交接层（README.md:1-10）。v0.1.1 重点新增了 moryn dashboard 本地可观测性仪表板，使代理在工作中能够直接检查 Moryn 存储状态。可观测性主要由三块组成：本地 Dashboard 视图、Git 同步状态结构化探针，以及通过 stdio MCP 服务器暴露的只读工具。本页围绕这三块说明其作用面、安全边界与典型失败模式。

Dashboard 本地仪表板

moryn dashboard 是面向用户与代理的本地检查入口。其核心只读视图如下表所示：

资料来源：README.md。所有这些视图在默认情况下都隐藏 private、secret、sensitive 标签的记录，调用方必须显式传入 --include-private 才可读取（README.md:41-47）。

自动捕获策略与仪表板路由

自动捕获策略决定每条 handoff 走哪条仪表板路径，其状态机为：

stateDiagram-v2
    [*] --> raw
    raw --> candidate: low_risk_handoff_auto_capture
    raw --> review: needs_user_decision
    raw --> archive: smoke_test_marker / duplicate_text
    candidate --> canonical: 用户确认
    review --> capture_inbox: user_action_required
    archive --> archived

raw、candidate、archived、quarantined 四种状态默认在仪表板中隐藏（README.md:35-40）。capture_inbox 是仅对需要用户决策的自动捕获 handoff 起作用的人工审查路径；低风险 handoff 仍为本地自动证据，不会自动晋升为 canonical（README.md:37-39）。策略规则定义在 src/core/autocapture-policy.ts 的 DEFAULT_AUTOCAPTURE_POLICY.rules 中，包括 smoke_test_marker、duplicate_text 等归档规则（src/core/autocapture-policy.ts:17-31）。

Git 同步可观测性

Moryn 的 Git 同步由本地存储驱动，远程仓库由用户决定。在 agentStart 中同步状态被显式探测：

• assertSyncNotConflicted(input.storePath) 在拉取前先行调用以检测冲突（src/core/agent-lifecycle.ts:5-25）。
• shouldPull 默认为 true，但当 projectInfo.sync_mode === "manual" 时跳过拉取（src/core/agent-lifecycle.ts:5-30）。
• 拉取失败会结构化捕获为 pull_error 与 pull_error_details（类型为 MorynErrorEnvelope["error"]），便于上层重试与上报（src/core/agent-lifecycle.ts:5-35）。
• 发布验证脚本通过 MORYN_PRIVATE_GIT_REMOTE 写入一次性测试事件（README.md:67-72）。

跨设备交接必须显式传 sync_remote；护栏规则 pass_sync_remote_for_cross_device_handoff 明确指出缺失该参数时状态与摘要将停留在本机（src/core/agent-lifecycle.ts:16-20）。

MCP stdio 可观测性

Moryn 通过真实 stdio MCP 服务器暴露工具，依赖 @modelcontextprotocol/sdk ^1.29.0（package.json:11-15）。下列 MCP 工具与 CLI 命令一一对应，且全部保持只读：

资料来源：README.md。ActionSafety 中定义的 safe_to_auto_run、requires_user_confirmation、requires_authored_input 字段（src/core/action-safety.ts:1-12）保证了这些建议在用户确认前不会被自动执行；ActionExecution.runbook 同时枚举 collect_required_inputs、ask_user_confirmation、call_mcp、do_not_run 四类步骤，使代理在阻塞时具有可追溯的恢复路径（src/core/action-safety.ts:14-32）。

常见失败模式

• 误以为可见即全部：仪表板默认隐藏 private/secret/sensitive 记录，若代理据此下结论会遗漏敏感上下文（README.md:41-47）。
• 跨设备误以为已同步：未传 sync_remote 时 handoff 仅落本机，状态摘要不会到达远端（src/core/agent-lifecycle.ts:16-20）。
• 把只读工具当作写入工具：recall_eval、capture_policy、memory_doctor、memory_lifecycle 均不修改存储；调用方若把它们当作执行入口会得到非预期结果（README.md）。
• 跳过显式确认直接晋升 canonical：高风险 canonical 写入要求用户显式确认，自动跳过将违反 requires_user_confirmation 边界（src/core/action-safety.ts:1-12）。

参见

• Agent Workflow
• Contracts
• Agent Install Prompt

Pitfall Log / 踩坑日志

项目：Richardyu114/Moryn

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/Richardyu114/Moryn | host_targets=mcp_host, claude, cursor

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/Richardyu114/Moryn | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/Richardyu114/Moryn | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/Richardyu114/Moryn | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/Richardyu114/Moryn | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/Richardyu114/Moryn | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/Richardyu114/Moryn | release_recency=unknown