From 5fa42b68e6107d191e703edcb672b567dedfb2e4 Mon Sep 17 00:00:00 2001 From: Grivn Date: Tue, 19 May 2026 17:08:30 +0000 Subject: [PATCH 1/6] docs(harness): add lifecycle control plane site Document Mnemon's lifecycle control plane as a memory-driven orchestration model built around desired state, reconcile, host adapters, projections, and status. The page explains how current memory, skill, and eval loops enter that control path without making Mnemon a host agent runtime. Link the rendered site from the private docs index and both harness documentation indexes, fix the docs home navigation links, and connect the memory-loop and skill-loop pages and design docs back to the same lifecycle control path. Validation: parsed the updated HTML pages with Python's html.parser and checked embedded scripts with node --check. --- docs/harness/README.md | 1 + docs/harness/memory-loop/DESIGN.md | 23 + docs/harness/skill-loop/DESIGN.md | 23 + docs/site/index.html | 14 +- docs/site/lifecycle-control-plane/index.html | 1312 ++++++++++++++++++ docs/site/memory-loop/index.html | 152 +- docs/site/skill-loop/index.html | 152 +- docs/zh/harness/README.md | 1 + docs/zh/harness/memory-loop/DESIGN.md | 23 + docs/zh/harness/skill-loop/DESIGN.md | 23 + 10 files changed, 1719 insertions(+), 5 deletions(-) create mode 100644 docs/site/lifecycle-control-plane/index.html diff --git a/docs/harness/README.md b/docs/harness/README.md index 623de78..a7d3aa0 100644 --- a/docs/harness/README.md +++ b/docs/harness/README.md @@ -28,6 +28,7 @@ projection into host surfaces, and optional daemon scheduling. | Loop Module Standard | [EN](LOOP_MODULE_STANDARD.md) / [中文](../zh/harness/LOOP_MODULE_STANDARD.md) | | Host Projection | [EN](HOST_PROJECTION.md) / [中文](../zh/harness/HOST_PROJECTION.md) | | Harness Roadmap | [EN](ROADMAP.md) / [中文](../zh/harness/ROADMAP.md) | +| Lifecycle Control Plane | [site](../site/lifecycle-control-plane/index.html) | | Memory Loop | [EN](memory-loop/DESIGN.md) / [中文](../zh/harness/memory-loop/DESIGN.md) / [site](../site/memory-loop/index.html) | | Skill Loop | [EN](skill-loop/DESIGN.md) / [中文](../zh/harness/skill-loop/DESIGN.md) / [site](../site/skill-loop/index.html) | | Eval Loop | [EN](eval-loop/DESIGN.md) / [中文](../zh/harness/eval-loop/DESIGN.md) | diff --git a/docs/harness/memory-loop/DESIGN.md b/docs/harness/memory-loop/DESIGN.md index 8354fda..99777f7 100644 --- a/docs/harness/memory-loop/DESIGN.md +++ b/docs/harness/memory-loop/DESIGN.md @@ -8,6 +8,29 @@ Installable MVP assets: [harness/modules/memory-loop](../../../harness/modules/m The memory loop is the first practical slice of the self-evolution harness. It gives a host agent a prompt-facing working memory while using Mnemon as durable long-term memory. The harness stays small: it installs Markdown policy, hook prompts, protocol skills, and one maintenance subagent around an existing host agent. +## Lifecycle Control Plane Position + +In the lifecycle control plane, `memory-loop` is a `LoopModule`. It declares the +portable memory policy, lifecycle prompts, protocol skills, dreaming subagent, +and runtime state contract. + +The loop becomes active through a host binding: + +```text +LoopModule(memory-loop) + -> HostBinding(host + lifecycle surfaces) + -> Reconcile + -> HostAdapter + -> Projection(.codex / .claude / other host surface) + -> Status + -> next Reconcile +``` + +The HostAgent consumes the projection and still owns execution. `.mnemon` keeps +the canonical memory-loop state, including `MEMORY.md`, manifests, and durable +Mnemon stores. Host directories are generated views that can be repaired when +projection status drifts from the declared binding. + ## Design Goal The MVP should answer one question: how can a host agent remember useful information across work without becoming a custom agent runtime? diff --git a/docs/harness/skill-loop/DESIGN.md b/docs/harness/skill-loop/DESIGN.md index 9bc6acd..3bb321d 100644 --- a/docs/harness/skill-loop/DESIGN.md +++ b/docs/harness/skill-loop/DESIGN.md @@ -8,6 +8,29 @@ The skill loop gives a host agent a self-evolving skill library without replacin The MVP is intentionally a visibility and lifecycle harness. It decides which skills should be discoverable now, which should be kept for maintenance, and which should remain as history. It does not inject all skills into the prompt, and it does not require the host agent to reload newly-created or patched skills in the current session. +## Lifecycle Control Plane Position + +In the lifecycle control plane, `skill-loop` is a `LoopModule`. It declares +skill visibility policy, observation and management protocols, curator +maintenance, and the canonical skill lifecycle state contract. + +The loop becomes active through a host binding: + +```text +LoopModule(skill-loop) + -> HostBinding(host + skill surface) + -> Reconcile + -> HostAdapter + -> Projection(.codex/skills, .claude/skills, or another host surface) + -> Status + -> next Reconcile +``` + +The HostAgent consumes the projected active skill surface and still owns native +skill discovery and execution. `.mnemon` keeps the canonical skill library and +evidence. Host skill directories are generated views that can be repaired when +projection status drifts from the declared binding. + ## Goals - Keep the host agent in control of execution, native skill discovery, subagent calls, and tool routing. diff --git a/docs/site/index.html b/docs/site/index.html index 21f07a5..5c5587a 100644 --- a/docs/site/index.html +++ b/docs/site/index.html @@ -151,7 +151,7 @@

Mnemon documentation

- +

Memory Loop MVP

Architecture, assets, hooks, and runtime data flow for the memory loop.

@@ -159,7 +159,7 @@

Memory Loop MVP

Open site - +

Skill Loop MVP

Entities, skill state surfaces, curator flow, and runtime data flow for the skill loop.

@@ -167,7 +167,15 @@

Skill Loop MVP

Open site - + + +

Lifecycle Control Plane

+

Design note for Mnemon as a memory-driven lifecycle orchestration layer, with loop objects, projection, status, and reconcile.

+ + Open site + + +

Documentation Tree

Read rendered Markdown and static assets from the docs directory, including diagrams, localized docs, and harness notes.

diff --git a/docs/site/lifecycle-control-plane/index.html b/docs/site/lifecycle-control-plane/index.html new file mode 100644 index 0000000..1fcfde1 --- /dev/null +++ b/docs/site/lifecycle-control-plane/index.html @@ -0,0 +1,1312 @@ + + + + + + + Mnemon Lifecycle Control Plane + + + +
+
+
+
+ Docs Home +
Mnemon Harness Design Note
+
+
+ + +
+
+ +
+
+
+

生命周期控制平面

+

+ Mnemon 的核心不是另一个 memory store，也不是新的 agent runtime，而是一个由 durable memory 驱动的 agent 生命周期编排层。它通过宿主已有的 hooks、skills、plugins、subagents 或 app-server surface，把 memory、skill、eval、goal、audit 等 loop 编排到 HostAgent 的执行平面之外。 +

+
+ memory-driven + lifecycle loops + control plane + host-native projection +
+
+ +
+
+ +
+
+
+

Lifecycle Control Plane

+

+ Mnemon is not just another memory store and not a new agent runtime. It is an agent lifecycle orchestration layer driven by durable memory. It projects memory, skill, eval, goal, and audit loops onto host-native surfaces such as hooks, skills, plugins, subagents, and app-server endpoints. +

+
+ memory-driven + lifecycle loops + control plane + host-native projection +
+
+ +
+
+
+
+ +
+
+
+
+

核心定义

+

把 memory 从存取能力提升为 agent 生命周期中的持续循环机制。

+
+
+
+

Mnemon 是什么

+
+

+ Mnemon 是面向 agent 的生命周期控制平面。 它不替换 HostAgent 的执行模型，也不只控制 memory 本身，而是管理由 durable state 驱动的一组生命周期 loop：经验如何变成长期状态、这些状态如何被召回、写回、沉淀、评估和审计。 +

+
+
+
+

Mnemon 不是什么

+
+

+ Mnemon 不定义 ReAct loop、tool runtime、plugin 格式、skill runtime、subagent 执行模型或 UI。宿主继续拥有执行平面；Mnemon 只拥有围绕执行平面挂载的治理循环。 +

+
+
+
+
+ +
+
+

控制编排主轴

+

Mnemon 的主轴不是“执行任务”，而是让声明的 loop projection 持续接近现实。

+
+
+
+
+ + + + + +
+ +
+ + +
+
+
Desired State 由 LoopModule 加 HostBinding 构成：声明哪个 loop 应该出现在什么 host 上。
+
+
+ +
+
+

控制对象

+

六个对象不是并列概念；它们分别服务于同一个 desired-state reconcile 闭环。

+
+
+
+ LoopModule + Desired state 的能力定义：policy、lifecycle prompts、protocol skills、state contract。 +
+
+ HostAdapter + Reconcile 调用的宿主实现：把 loop 渲染成 Claude Code、Codex、OpenClaw 的原生 surface。 +
+
+ HostBinding + Desired state 的绑定定义：哪个 loop 应该安装到哪个 host，启用哪些 lifecycle 能力。 +
+
+ Projection + Actual state 的宿主视图：生成的 host-native 文件，不是 source of truth。 +
+
+ Status + Actual state 的观测结果：Installed、Ready、Drifted、MissingCapability、Stale。 +
+
+ Reconcile + 控制动作：比较 desired 和 actual，执行 create、repair、update、remove 或 no-op。 +
+
+
+ +
+
+

现有 loops 如何进入闭环

+

memory、skill、eval 不是散落模块；它们先变成 desired state，再由 host adapter 投影到宿主。

+
+
+
+
+ + + + + + +
+
+
LoopModules 是可携带能力包：memory-loop、skill-loop、eval-loop 都先保持 host-agnostic。
+
+
+ +
+
+

现有 loops 的组织

+

memory-loop 是连续性起点；skill-loop 和 eval-loop 是围绕记忆治理自然展开的控制循环。

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Loop控制目标主要动作状态位置
memory-loop让经验变成未来可用的 durable memory。prime、recall、writeback、compact preservation、dreaming consolidation。.mnemon/harness/memory-loop
skill-loop从重复有效行为中沉淀、治理和迁移 skills。observe、curate、author、manage active/stale/archived lifecycle。.mnemon/harness/skill-loop
eval-loop验证 loop 是否真的改善 HostAgent 行为。plan scenarios、run evals、analyze reports、propose improvements。.mnemon/harness/eval-loop
+
+
+ +
+
+

外部 memory 的位置

+

外部 memory 项目不必被替代；它们可以成为 Mnemon memory-loop 编排的 backend、source 或 surface。

+
+
+
+
+ + + + +
+
+
外部 memory 系统可以作为 backend、source 或 surface 接入，而不是被 Mnemon 替代。
+
+
+ +
+
+

现实落地

+

这个划分现实，因为它抽象的是已经存在的复杂度，而不是发明一个新 agent runtime。

+
+
+
+

现在已有

+
+
+
LoopModule
+

harness/modules/*

+
+
+
HostAdapter
+

harness/hosts/*

+
+
+
Projection
+

.claude、.codex generated files

+
+
+
+
+

下一步

+
+
+
HostBinding
+

把“哪个 loop 绑定到哪个 host”从命令参数提升为声明对象。

+
+
+
Status
+

从目录存在检查升级为 projection drift 和 capability 检查。

+
+
+
Reconcile
+

让 install 成为幂等 reconcile 的入口，而不是一次性复制脚本。

+
+
+
+
+

保持克制

+
+

+ 不急于做 API server、daemon、distributed scheduler、CRD 系统或全模块依赖求解。先用文件、CLI、manifest 和 adapter 把 desired state 与 actual projection 对齐。 +

+
+ 最小成功标准：mnemon harness reconcile 可以修复缺失或过期的 host projection。 +
+
+
+
+
+
+ +
+
+
+

Core Definition

+

Mnemon turns memory from a storage capability into a lifecycle mechanism for agents.

+
+
+
+

What Mnemon Is

+
+

+ Mnemon is a memory-driven lifecycle control plane for agents. It does not replace the HostAgent execution model, and it does not only control memory itself. It governs a set of lifecycle loops driven by durable state: how experience becomes long-term state, and how that state is recalled, written back, consolidated, evaluated, and audited. +

+
+
+
+

What Mnemon Is Not

+
+

+ Mnemon does not define the ReAct loop, tool runtime, plugin format, skill runtime, subagent execution model, or UI. The host owns execution; Mnemon owns attachable governance loops around execution. +

+
+
+
+
+ +
+
+

Control Loop Blueprint

+

Mnemon's main axis is not task execution. It keeps declared loop projections close to reality.

+
+
+
+
+ + + + + +
+ +
+ + +
+
+
Desired State is LoopModule plus HostBinding: which loop should appear on which host.
+
+
+ +
+
+

Control Objects

+

These six objects are not parallel ideas. They each occupy one position in the same desired-state reconcile loop.

+
+
+
+ LoopModule + Desired-state capability definition: policy, lifecycle prompts, protocol skills, and state contract. +
+
+ HostAdapter + Host implementation called by reconcile to render Claude Code, Codex, or OpenClaw surfaces. +
+
+ HostBinding + Desired-state binding: which loop goes to which host, and which lifecycle capabilities are enabled. +
+
+ Projection + Actual host view: generated host-native files, not the source of truth. +
+
+ Status + Observed actual state: Installed, Ready, Drifted, MissingCapability, Stale. +
+
+ Reconcile + Control action: compare desired with actual, then create, repair, update, remove, or no-op. +
+
+
+ +
+
+

How Current Loops Enter The Control Loop

+

memory, skill, and eval are not scattered modules. They become desired state, then host adapters project them.

+
+
+
+
+ + + + + + +
+
+
LoopModules are portable capability packages: memory-loop, skill-loop, and eval-loop stay host-agnostic first.
+
+
+ +
+
+

Current Loops

+

memory-loop is the continuity point. skill-loop and eval-loop naturally extend memory-centered governance.

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LoopControl GoalMain ActionsState Location
memory-loopTurn experience into durable memory usable by future work.prime, recall, writeback, compact preservation, dreaming consolidation..mnemon/harness/memory-loop
skill-loopPromote repeated useful behavior into governed skills.observe, curate, author, manage active/stale/archived lifecycle..mnemon/harness/skill-loop
eval-loopVerify whether loops improve HostAgent behavior.plan scenarios, run evals, analyze reports, propose improvements..mnemon/harness/eval-loop
+
+
+ +
+
+

External Memory

+

External memory systems do not need to be replaced. They can become backends, sources, or surfaces orchestrated by Mnemon memory-loop.

+
+
+
+
+ + + + +
+
+
External memory systems can plug in as backends, sources, or surfaces instead of being replaced by Mnemon.
+
+
+ +
+
+

Practical Path

+

This split is practical because it abstracts complexity already present in the system instead of inventing a new agent runtime.

+
+
+
+

Already Present

+
+
+
LoopModule
+

harness/modules/*

+
+
+
HostAdapter
+

harness/hosts/*

+
+
+
Projection
+

.claude and .codex generated files

+
+
+
+
+

Next Step

+
+
+
HostBinding
+

Promote “which loop goes to which host” from command arguments into a declared object.

+
+
+
Status
+

Move beyond directory checks into projection drift and capability checks.

+
+
+
Reconcile
+

Make install an idempotent reconcile entrypoint instead of a one-time copy script.

+
+
+
+
+

Keep It Small

+
+

+ Do not start with an API server, daemon, distributed scheduler, CRD system, or dependency solver. Use files, CLI commands, manifests, and adapters to align desired state with actual projection. +

+
+ Minimal success: mnemon harness reconcile can repair missing or stale host projections. +
+
+
+
+
+
+
+ + + + diff --git a/docs/site/memory-loop/index.html b/docs/site/memory-loop/index.html index 468b9f5..88c22d8 100644 --- a/docs/site/memory-loop/index.html +++ b/docs/site/memory-loop/index.html @@ -69,6 +69,36 @@ text-transform: uppercase; } + .nav-left { + display: flex; + flex-wrap: wrap; + gap: 10px; + align-items: center; + } + + .home-link { + display: inline-flex; + align-items: center; + min-height: 30px; + padding: 5px 10px; + border: 1px solid var(--line); + border-radius: 999px; + background: var(--panel); + color: var(--muted); + font-size: 12px; + font-weight: 800; + letter-spacing: 0.04em; + text-decoration: none; + text-transform: uppercase; + } + + .home-link:hover, + .home-link:focus-visible { + border-color: var(--host); + color: var(--host); + outline: 0; + } + .language-switch { display: inline-flex; gap: 2px; @@ -270,6 +300,74 @@ font-size: 14px; } + .control-path { + margin-bottom: 18px; + border: 1px solid var(--line); + border-radius: var(--radius); + background: var(--panel); + box-shadow: var(--shadow); + overflow: hidden; + } + + .control-path-grid { + display: grid; + grid-template-columns: repeat(6, minmax(0, 1fr)); + gap: 1px; + background: var(--line); + } + + .control-step { + position: relative; + min-height: 118px; + padding: 13px; + background: #ffffff; + border-top: 4px solid var(--color); + } + + .control-step:not(:last-child)::after { + content: ""; + position: absolute; + top: 50%; + right: -14px; + z-index: 2; + width: 24px; + height: 2px; + background: var(--color); + } + + .control-step:not(:last-child)::before { + content: ""; + position: absolute; + top: calc(50% - 4px); + right: -17px; + z-index: 3; + border-top: 5px solid transparent; + border-bottom: 5px solid transparent; + border-left: 8px solid var(--color); + } + + .control-step b { + display: block; + margin-bottom: 5px; + color: var(--color); + font-size: 13px; + line-height: 1.2; + } + + .control-step p { + margin: 0; + color: var(--muted); + font-size: 12px; + } + + .control-feedback { + padding: 10px 14px; + border-top: 1px solid var(--line); + background: #fbfcfe; + color: var(--muted); + font-size: 13px; + } + .flow-layout { display: grid; grid-template-columns: 260px minmax(0, 1fr); @@ -513,11 +611,17 @@ @media (max-width: 1080px) { .hero, .inventory-layout, + .control-path-grid, .flow-layout, .rules { grid-template-columns: 1fr; } + .control-step:not(:last-child)::before, + .control-step:not(:last-child)::after { + display: none; + } + .section-title { display: block; } @@ -565,7 +669,10 @@
-
+
+ Docs Home +
+
@@ -582,6 +689,17 @@

+
+
+

+

+
+
+
+ +
+
+

@@ -646,6 +764,17 @@

"再看五类支撑概念：GUIDE、setup、hook、protocol、subagent。", "最后切换阶段，看每个 hook 如何把判断交给 skill 或 subagent。" ], + controlTitle: "生命周期控制位置", + controlIntro: "memory-loop 在整体控制平面里是一个 LoopModule。它先被声明和绑定，再由 HostAdapter 投影到宿主；运行结果和状态回到 .mnemon，供下一次 reconcile 使用。", + controlFeedback: "Status 反馈到下一次 Reconcile；记忆真实状态保留在 .mnemon，而不是宿主 projection 目录。", + controlSteps: [ + { name: "LoopModule", color: "var(--working)", text: "memory-loop 声明 GUIDE、hooks、memory_get、memory_set、dreaming 和 MEMORY.md 状态契约。" }, + { name: "HostBinding", color: "var(--guide)", text: "声明 memory-loop 应绑定到 Codex、Claude Code 或其他 host，并启用对应 lifecycle surface。" }, + { name: "Reconcile", color: "var(--capability)", text: "检查 projection 是否存在、过期或漂移，并决定是否重新生成宿主可见资产。" }, + { name: "HostAdapter", color: "var(--host)", text: "把同一 memory-loop 渲染成 host-native skills、hooks、env 和 runtime 指针。" }, + { name: "Projection", color: "var(--hook)", text: "HostAgent 消费 .codex 或 .claude 中生成的 skill、hook、instruction 和 env 文件。" }, + { name: "Status", color: "var(--longterm)", text: "记录 projection 状态、manifest 和 .mnemon/harness/memory-loop 的 canonical runtime state。" } + ], componentsTitle: "系统组成", componentsIntro: "这里先固定三大核心主体，再用统一的五类 harness 概念描述安装、触发、协议和后台维护。", coreHeading: "三大核心主体", @@ -801,6 +930,17 @@

"Then read the five harness concepts: GUIDE, setup, hook, protocol, and subagent.", "Finally switch phases to see how each hook delegates to a skill or subagent." ], + controlTitle: "Lifecycle Control Position", + controlIntro: "memory-loop is one LoopModule in the lifecycle control plane. It is declared, bound to a host, projected by a HostAdapter, and observed through status so the next reconcile can repair drift.", + controlFeedback: "Status feeds the next Reconcile; durable memory state remains in .mnemon, not in the host projection directory.", + controlSteps: [ + { name: "LoopModule", color: "var(--working)", text: "memory-loop declares GUIDE, hooks, memory_get, memory_set, dreaming, and the MEMORY.md state contract." }, + { name: "HostBinding", color: "var(--guide)", text: "Declares that memory-loop should bind to Codex, Claude Code, or another host with specific lifecycle surfaces." }, + { name: "Reconcile", color: "var(--capability)", text: "Checks whether projection is missing, stale, or drifted, then decides whether host-visible assets need repair." }, + { name: "HostAdapter", color: "var(--host)", text: "Renders the same memory-loop into host-native skills, hooks, env files, and runtime pointers." }, + { name: "Projection", color: "var(--hook)", text: "The HostAgent consumes generated skills, hooks, instructions, and env files under .codex or .claude." }, + { name: "Status", color: "var(--longterm)", text: "Records projection condition, manifests, and canonical runtime state under .mnemon/harness/memory-loop." } + ], componentsTitle: "System Components", componentsIntro: "This keeps the three core runtime parts stable, then describes installation, timing, protocol execution, and background maintenance through one shared harness vocabulary.", coreHeading: "Three Core Parts", @@ -1100,6 +1240,9 @@

document.getElementById("page-title").textContent = t.title; document.getElementById("page-summary").textContent = t.summary; document.getElementById("reading-card").innerHTML = `

${t.readingTitle}

    ${t.reading.map((item) => `
  1. ${item}
    2. `).join("")}
`; + document.getElementById("control-title").textContent = t.controlTitle; + document.getElementById("control-intro").textContent = t.controlIntro; + document.getElementById("control-feedback").textContent = t.controlFeedback; document.getElementById("components-title").textContent = t.componentsTitle; document.getElementById("components-intro").textContent = t.componentsIntro; document.getElementById("core-heading").textContent = t.coreHeading; @@ -1117,6 +1260,13 @@

`).join(""); + document.getElementById("control-path").innerHTML = t.controlSteps.map((item) => ` +
+ ${item.name} +

${item.text}

+
+ `).join(""); + document.getElementById("asset-list").innerHTML = t.assets.map((item) => `
${item.name} diff --git a/docs/site/skill-loop/index.html b/docs/site/skill-loop/index.html index 536b679..ee42d19 100644 --- a/docs/site/skill-loop/index.html +++ b/docs/site/skill-loop/index.html @@ -107,6 +107,36 @@ text-transform: uppercase; } + .nav-left { + display: flex; + flex-wrap: wrap; + gap: 10px; + align-items: center; + } + + .home-link { + display: inline-flex; + align-items: center; + min-height: 30px; + padding: 5px 10px; + border: 1px solid var(--line); + border-radius: 999px; + background: var(--panel); + color: var(--muted); + font-size: 12px; + font-weight: 800; + letter-spacing: 0.04em; + text-decoration: none; + text-transform: uppercase; + } + + .home-link:hover, + .home-link:focus-visible { + border-color: var(--active); + color: var(--active); + outline: 0; + } + h1 { margin: 0; font-size: 44px; @@ -275,6 +305,74 @@ font-size: 14px; } + .control-path { + margin-bottom: 18px; + border: 1px solid var(--line); + border-radius: var(--radius); + background: var(--panel); + box-shadow: var(--shadow); + overflow: hidden; + } + + .control-path-grid { + display: grid; + grid-template-columns: repeat(6, minmax(0, 1fr)); + gap: 1px; + background: var(--line); + } + + .control-step { + position: relative; + min-height: 118px; + padding: 13px; + background: #ffffff; + border-top: 4px solid var(--color); + } + + .control-step:not(:last-child)::after { + content: ""; + position: absolute; + top: 50%; + right: -14px; + z-index: 2; + width: 24px; + height: 2px; + background: var(--color); + } + + .control-step:not(:last-child)::before { + content: ""; + position: absolute; + top: calc(50% - 4px); + right: -17px; + z-index: 3; + border-top: 5px solid transparent; + border-bottom: 5px solid transparent; + border-left: 8px solid var(--color); + } + + .control-step b { + display: block; + margin-bottom: 5px; + color: var(--color); + font-size: 13px; + line-height: 1.2; + } + + .control-step p { + margin: 0; + color: var(--muted); + font-size: 12px; + } + + .control-feedback { + padding: 10px 14px; + border-top: 1px solid var(--line); + background: #fbfcfe; + color: var(--muted); + font-size: 13px; + } + .flow-layout { display: grid; grid-template-columns: 260px minmax(0, 1fr); @@ -530,11 +628,17 @@ @media (max-width: 1080px) { .hero, .inventory-layout, + .control-path-grid, .flow-layout, .rules { grid-template-columns: 1fr; } + .control-step:not(:last-child)::before, + .control-step:not(:last-child)::after { + display: none; + } + .section-title { display: block; } @@ -585,7 +689,10 @@
-
+
+ Docs Home +
+
@@ -602,6 +709,17 @@

+
+
+

+

+
+
+
+ +
+
+

@@ -662,6 +780,17 @@

"再看五类支撑概念：GUIDE、setup、hook、protocol、subagent。", "最后切换阶段，看 Prime、Nudge、Observe、Curator、Manage 如何闭合成 loop。" ], + controlTitle: "生命周期控制位置", + controlIntro: "skill-loop 在整体控制平面里是一个 LoopModule。它声明 skill lifecycle policy，并通过 host adapter 把 active skill 集合投影到宿主原生 skill surface。", + controlFeedback: "Status 反馈到下一次 Reconcile；canonical skill state 保留在 .mnemon，宿主 skill surface 只是 projection。", + controlSteps: [ + { name: "LoopModule", color: "var(--library)", text: "skill-loop 声明 GUIDE、hooks、skill_observe、skill_curate、skill_manage 和 curator。" }, + { name: "HostBinding", color: "var(--guide)", text: "声明 skill-loop 绑定到哪个 host，以及 active skills 应投影到哪个 host skill surface。" }, + { name: "Reconcile", color: "var(--protocol)", text: "检查 active skill projection 是否缺失、过期、漂移，或与 host capability 不兼容。" }, + { name: "HostAdapter", color: "var(--host)", text: "把 .mnemon/skills/active 渲染、同步或挂载到 .codex、.claude 或其他 host surface。" }, + { name: "Projection", color: "var(--active)", text: "HostAgent 使用生成的 host-native skill files；stale 和 archived 默认不进入这个 surface。" }, + { name: "Status", color: "var(--curator)", text: "记录 projection 状态、usage evidence、proposal/report，并反馈给下一次维护和 reconcile。" } + ], componentsTitle: "System Components", componentsIntro: "Skill loop 的核心不是冷热存储，而是可见性治理：哪些 skill 当前可被发现，哪些进入维护，哪些仅保留历史。", coreHeading: "Three Core Parts", @@ -821,6 +950,17 @@

"Then read the five harness concepts: GUIDE, setup, hook, protocol, and subagent.", "Finally switch phases to see how Prime, Nudge, Observe, Curator, and Manage close the loop." ], + controlTitle: "Lifecycle Control Position", + controlIntro: "skill-loop is one LoopModule in the lifecycle control plane. It declares skill lifecycle policy and uses host adapters to project the active skill set into the host-native skill surface.", + controlFeedback: "Status feeds the next Reconcile; canonical skill state remains in .mnemon, while the host skill surface is only a projection.", + controlSteps: [ + { name: "LoopModule", color: "var(--library)", text: "skill-loop declares GUIDE, hooks, skill_observe, skill_curate, skill_manage, and the curator." }, + { name: "HostBinding", color: "var(--guide)", text: "Declares which host receives skill-loop and which host skill surface should receive active skills." }, + { name: "Reconcile", color: "var(--protocol)", text: "Checks whether active skill projection is missing, stale, drifted, or incompatible with host capabilities." }, + { name: "HostAdapter", color: "var(--host)", text: "Renders, syncs, or mounts .mnemon/skills/active into .codex, .claude, or another host surface." }, + { name: "Projection", color: "var(--active)", text: "The HostAgent uses generated host-native skill files; stale and archived skills stay out by default." }, + { name: "Status", color: "var(--curator)", text: "Records projection status, usage evidence, proposals, and reports for maintenance and the next reconcile." } + ], componentsTitle: "System Components", componentsIntro: "The skill loop is not a hot/cold storage split. It governs visibility: which skills are discoverable now, which need maintenance, and which remain historical.", coreHeading: "Three Core Parts", @@ -1218,6 +1358,9 @@

${phase.title}

document.getElementById("page-title").textContent = t.title; document.getElementById("page-summary").textContent = t.summary; document.getElementById("reading-card").innerHTML = `

${t.readingTitle}

    ${t.reading.map((item) => `
  1. ${item}
    2. `).join("")}
`; + document.getElementById("control-title").textContent = t.controlTitle; + document.getElementById("control-intro").textContent = t.controlIntro; + document.getElementById("control-feedback").textContent = t.controlFeedback; document.getElementById("components-title").textContent = t.componentsTitle; document.getElementById("components-intro").textContent = t.componentsIntro; document.getElementById("core-heading").textContent = t.coreHeading; @@ -1236,6 +1379,13 @@

${phase.title}

`).join(""); + document.getElementById("control-path").innerHTML = t.controlSteps.map((item) => ` +
+ ${item.name} +

${item.text}

+
+ `).join(""); + document.getElementById("asset-list").innerHTML = t.assets.map((item) => `
${item.name} diff --git a/docs/zh/harness/README.md b/docs/zh/harness/README.md index e32e454..e5bba4b 100644 --- a/docs/zh/harness/README.md +++ b/docs/zh/harness/README.md @@ -23,6 +23,7 @@ host surface projection，以及可选的 daemon scheduling。 | Loop Module Standard | [中文](LOOP_MODULE_STANDARD.md) / [EN](../../harness/LOOP_MODULE_STANDARD.md) | | Host Projection | [中文](HOST_PROJECTION.md) / [EN](../../harness/HOST_PROJECTION.md) | | Harness Roadmap | [中文](ROADMAP.md) / [EN](../../harness/ROADMAP.md) | +| Lifecycle Control Plane | [site](../../site/lifecycle-control-plane/index.html) | | Memory Loop | [中文](memory-loop/DESIGN.md) / [EN](../../harness/memory-loop/DESIGN.md) / [site](../../site/memory-loop/index.html) | | Skill Loop | [中文](skill-loop/DESIGN.md) / [EN](../../harness/skill-loop/DESIGN.md) / [site](../../site/skill-loop/index.html) | | Eval Loop | [中文](eval-loop/DESIGN.md) / [EN](../../harness/eval-loop/DESIGN.md) | diff --git a/docs/zh/harness/memory-loop/DESIGN.md b/docs/zh/harness/memory-loop/DESIGN.md index fdf3455..0c0afc5 100644 --- a/docs/zh/harness/memory-loop/DESIGN.md +++ b/docs/zh/harness/memory-loop/DESIGN.md @@ -8,6 +8,29 @@ Memory loop 是 self-evolution harness 的第一个可落地切片。它给 HostAgent 提供一份面向 prompt 的工作记忆，同时使用 Mnemon 作为持久长期记忆。Harness 本身保持很小：围绕已有 HostAgent 安装 Markdown policy、hook prompt、protocol skills 和一个维护型 subagent。 +## 生命周期控制平面位置 + +在生命周期控制平面里，`memory-loop` 是一个 `LoopModule`。它声明可迁移的记忆 +policy、lifecycle prompts、protocol skills、dreaming subagent 和 runtime state +contract。 + +这个 loop 通过 host binding 进入宿主： + +```text +LoopModule(memory-loop) + -> HostBinding(host + lifecycle surfaces) + -> Reconcile + -> HostAdapter + -> Projection(.codex / .claude / other host surface) + -> Status + -> next Reconcile +``` + +HostAgent 消费 projection，并继续拥有执行。`.mnemon` 保存 memory-loop 的 +canonical state，包括 `MEMORY.md`、manifests 和持久 Mnemon stores。宿主目录是 +可重新生成的视图；当 projection status 与声明的 binding 漂移时，可以由 +reconcile 修复。 + ## 设计目标 MVP 要回答一个问题：如何让 HostAgent 在不变成自定义 agent runtime 的前提下，跨任务记住有用信息？ diff --git a/docs/zh/harness/skill-loop/DESIGN.md b/docs/zh/harness/skill-loop/DESIGN.md index a55a23b..6fa50e4 100644 --- a/docs/zh/harness/skill-loop/DESIGN.md +++ b/docs/zh/harness/skill-loop/DESIGN.md @@ -10,6 +10,29 @@ Skill loop 的目标是让宿主 Agent 拥有一套可自我演进的 skill libr MVP 的边界是“可见性治理”和“生命周期治理”：哪些 skill 当前应该可被发现，哪些进入维护，哪些仅保留为历史。它不把所有 skill 注入 prompt，也不要求新建或 patch 后的 skill 在当前 session 立即 reload。 +## 生命周期控制平面位置 + +在生命周期控制平面里，`skill-loop` 是一个 `LoopModule`。它声明 skill visibility +policy、observation 和 management protocols、curator maintenance，以及 +canonical skill lifecycle state contract。 + +这个 loop 通过 host binding 进入宿主： + +```text +LoopModule(skill-loop) + -> HostBinding(host + skill surface) + -> Reconcile + -> HostAdapter + -> Projection(.codex/skills, .claude/skills, or another host surface) + -> Status + -> next Reconcile +``` + +HostAgent 消费被投影的 active skill surface，并继续拥有原生 skill discovery 和 +执行。`.mnemon` 保存 canonical skill library 和 evidence。宿主 skill 目录是 +可重新生成的视图；当 projection status 与声明的 binding 漂移时，可以由 +reconcile 修复。 + ## 目标 - 让 HostAgent 继续拥有执行、原生 skill discovery、subagent 调用和 tool routing。 From 2b17fcce27c5f54ac85d848027a24a1cea6e48aa Mon Sep 17 00:00:00 2001 From: Grivn Date: Wed, 20 May 2026 08:11:18 +0000 Subject: [PATCH 2/6] docs(harness): add YC evolving design philosophy Capture the YC self-improving company framing as a harness design reference in both English and Chinese. The note translates the article into Mnemon concepts such as canonical context, lifecycle loops, host capability surfaces, quality gates, and human review boundaries. Link the new philosophy note from the English and Chinese harness README entries. Validation: checked markdown links and staged diff whitespace. --- docs/harness/README.md | 1 + docs/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md | 207 ++++++++++++++++++ docs/zh/harness/README.md | 1 + .../harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md | 190 ++++++++++++++++ 4 files changed, 399 insertions(+) create mode 100644 docs/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md create mode 100644 docs/zh/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md diff --git a/docs/harness/README.md b/docs/harness/README.md index a7d3aa0..43b8c97 100644 --- a/docs/harness/README.md +++ b/docs/harness/README.md @@ -28,6 +28,7 @@ projection into host surfaces, and optional daemon scheduling. | Loop Module Standard | [EN](LOOP_MODULE_STANDARD.md) / [中文](../zh/harness/LOOP_MODULE_STANDARD.md) | | Host Projection | [EN](HOST_PROJECTION.md) / [中文](../zh/harness/HOST_PROJECTION.md) | | Harness Roadmap | [EN](ROADMAP.md) / [中文](../zh/harness/ROADMAP.md) | +| YC Evolving Design Philosophy | [EN](YC_EVOLVING_DESIGN_PHILOSOPHY.md) / [中文](../zh/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md) | | Lifecycle Control Plane | [site](../site/lifecycle-control-plane/index.html) | | Memory Loop | [EN](memory-loop/DESIGN.md) / [中文](../zh/harness/memory-loop/DESIGN.md) / [site](../site/memory-loop/index.html) | | Skill Loop | [EN](skill-loop/DESIGN.md) / [中文](../zh/harness/skill-loop/DESIGN.md) / [site](../site/skill-loop/index.html) | diff --git a/docs/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md b/docs/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md new file mode 100644 index 0000000..0c8b7e0 --- /dev/null +++ b/docs/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md @@ -0,0 +1,207 @@ +# YC Evolving Design Philosophy + +Chinese version: [YC_EVOLVING_DESIGN_PHILOSOPHY.md](../zh/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md) + +This note captures a design philosophy inspired by the YC Root Access talk +"How to Build a Self-Improving Company with AI" and the Chinese article +"YC合伙人：如何打造一家自我进化的AI原生公司". It is not an article archive. +It records the parts that should guide Mnemon's harness and lifecycle control +plane design. + +## Core Thesis + +An AI-native organization should not be understood as a traditional hierarchy +with AI tools attached to each employee. It can be understood as a set of +recursive, self-improving loops: + +```text +signals -> policy -> tools -> quality gates -> learning + ^ | + |---------------------------------------------| +``` + +For Mnemon, this strengthens the core harness thesis: + +Mnemon should not become an agent runtime, a workflow engine, or a memory store +alone. Mnemon should provide the lifecycle control layer that lets host agents +turn durable context, skills, policy, feedback, and execution results into +governed self-improvement loops. + +## From Copilot To Self-Improving System + +The article draws a useful distinction: + +| Mode | Shape | Limit | +| --- | --- | --- | +| Copilot | AI helps a human perform an existing task faster. | The organization still depends on human coordination and manual improvement. | +| Self-improving loop | AI observes outcomes, identifies failures, proposes or applies fixes, and feeds results back into the system. | Requires readable context, deterministic tools, quality gates, and durable feedback. | + +Mnemon should be designed for the second mode. A host agent may execute the +work, but Mnemon should help the surrounding system remember what happened, +detect drift, improve skills, update lifecycle state, and preserve reviewable +evidence. + +## Company Brain And Canonical Context + +The article's "company brain" maps directly to Mnemon's canonical state idea. +The valuable asset is not a transient dashboard, generated script, chat thread, +or host-specific plugin file. The valuable asset is readable, durable, +structured context: + +- goals, decisions, policies, and constraints +- memory and summarized operating knowledge +- skills and their usage evidence +- reports, proposals, audit records, and review status +- host bindings and capability manifests +- validation outcomes and observed drift + +In Mnemon terms, this state should live under `.mnemon` or another canonical +state root. Host-specific directories such as `.codex`, `.claude`, or future +plugin surfaces should be treated as projections that can be regenerated. + +```text +canonical context + durable memory, skills, policy, reports, proposals, audit + | + v +lifecycle control + reconcile, validate, project, learn + | + v +host surfaces + skills, hooks, app servers, tools, generated files +``` + +## Disposable Software, Durable Context + +The article argues that generated internal software can become temporary while +business context and skills become the durable asset. This is a strong fit for +Mnemon's host projection model. + +Mnemon should treat host-native assets as useful but replaceable: + +- generated dashboards +- host skill files +- hook glue +- app-server configuration +- eval runners +- temporary workflow code + +The durable layer is the lifecycle state that explains what these assets are +for, when they are stale, how they were validated, and whether they should be +regenerated. + +## Loop Structure + +The article's loop structure can be translated into Mnemon's lifecycle model: + +```text +Observed Signals + user intent, repo diffs, host status, eval results, customer feedback + | + v +Desired State + goals, policies, skills, memory, bindings, expected projections + | + v +Reconcile + compare desired state with actual host surfaces and outcomes + | + v +Projection And Execution + host adapters expose skills, hooks, app servers, tools, evals + | + v +Status And Learning + record success, failure, drift, missing tools, stale skills, review needs + | + v +Updated Canonical Context +``` + +This is the minimum trunk Mnemon should keep clear: + +```text +LoopModule + HostBinding + | + v +Desired State + | + v +Reconcile + | + v +HostAdapter -> Projection -> HostAgent + | + v +Status -> Learning -> next Reconcile +``` + +## Host Capability Surfaces + +The article emphasizes deterministic tools, generated software, and quality +gates. In Mnemon, these should be represented as host capability surfaces rather +than Mnemon-owned execution runtimes. + +Examples: + +- Codex skills and project files +- Claude Code skills, hooks, and subagents +- Codex app-server endpoints +- eval runners and test commands +- repository files and generated dashboards +- databases, search indexes, and external APIs exposed through host tools + +The host owns execution. Mnemon owns lifecycle coordination around that +execution: what should exist, how it is projected, how it is validated, what +failed, and what should change next. + +## Quality Gates And Human Boundaries + +The article does not imply full autonomy everywhere. It explicitly leaves +humans at the edge of the system for high-risk, novel, ethical, or emotionally +complex situations. + +Mnemon should make this boundary explicit: + +- low-risk observation and reporting can be automated +- projection validation can be automated +- skill and memory proposals can be generated automatically +- destructive changes require explicit review +- high-risk policy, security, data, or production changes require human gates +- audit records should preserve what happened and why + +This keeps self-improvement reviewable instead of invisible. + +## Design Implications For Mnemon + +This philosophy supports several concrete Mnemon design choices: + +1. Keep `.mnemon` as canonical lifecycle state. +2. Treat `.codex`, `.claude`, and similar directories as projections. +3. Model each improvement path as a loop with signals, policy, tools, gates, + and feedback. +4. Keep host execution outside Mnemon core. +5. Make Reconcile explicit: compare desired lifecycle state with actual host + surfaces and observed outcomes. +6. Record status, failures, stale projections, and missing capabilities as + first-class state. +7. Prefer generated or projected host assets over hand-maintained duplicated + truth. +8. Preserve human review boundaries for risky changes. + +## Strategic Position + +This article describes the organizational shape Mnemon should serve: +self-improving agentic systems that operate through durable context and +recursive loops. + +Mnemon's differentiation is not "memory for agents" by itself. The stronger +position is: + +```text +Mnemon turns durable context into lifecycle-controlled agent improvement loops. +``` + +Memory is the continuity point. The loop is the differentiator. The control +plane is the product shape. diff --git a/docs/zh/harness/README.md b/docs/zh/harness/README.md index e5bba4b..773c162 100644 --- a/docs/zh/harness/README.md +++ b/docs/zh/harness/README.md @@ -23,6 +23,7 @@ host surface projection，以及可选的 daemon scheduling。 | Loop Module Standard | [中文](LOOP_MODULE_STANDARD.md) / [EN](../../harness/LOOP_MODULE_STANDARD.md) | | Host Projection | [中文](HOST_PROJECTION.md) / [EN](../../harness/HOST_PROJECTION.md) | | Harness Roadmap | [中文](ROADMAP.md) / [EN](../../harness/ROADMAP.md) | +| YC Evolving 设计哲学 | [中文](YC_EVOLVING_DESIGN_PHILOSOPHY.md) / [EN](../../harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md) | | Lifecycle Control Plane | [site](../../site/lifecycle-control-plane/index.html) | | Memory Loop | [中文](memory-loop/DESIGN.md) / [EN](../../harness/memory-loop/DESIGN.md) / [site](../../site/memory-loop/index.html) | | Skill Loop | [中文](skill-loop/DESIGN.md) / [EN](../../harness/skill-loop/DESIGN.md) / [site](../../site/skill-loop/index.html) | diff --git a/docs/zh/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md b/docs/zh/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md new file mode 100644 index 0000000..d9db886 --- /dev/null +++ b/docs/zh/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md @@ -0,0 +1,190 @@ +# YC Evolving 设计哲学 + +English version: [YC_EVOLVING_DESIGN_PHILOSOPHY.md](../../harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md) + +这份文档基于 YC Root Access 的演讲 "How to Build a Self-Improving Company +with AI" 以及中文文章《YC合伙人：如何打造一家自我进化的AI原生公司》整理。它不是 +文章归档，而是把其中对 Mnemon harness 和 lifecycle control plane 有价值的判断， +沉淀成后续设计参考。 + +## 核心判断 + +AI 原生组织不应该只被理解为“传统层级组织 + AI 工具”。它更像一组递归、自我改进 +的 loop： + +```text +信号 -> 策略 -> 工具 -> 质量关卡 -> 学习 + ^ | + |----------------------------------| +``` + +对 Mnemon 来说，这强化了 harness 的核心判断： + +Mnemon 不应该变成 agent runtime、workflow engine，或者单纯的 memory store。 +Mnemon 应该提供一层生命周期控制能力，让宿主 agent 能够把持久上下文、skill、 +policy、反馈和执行结果，转化为可治理的自我改进 loop。 + +## 从 Copilot 到自我改进系统 + +文章中最有价值的区分是： + +| 模式 | 形态 | 局限 | +| --- | --- | --- | +| Copilot | AI 帮助人更快完成已有任务。 | 组织仍然依赖人类协调和手工改进。 | +| 自我改进 loop | AI 观察结果、识别失败、提出或执行修正，并把结果反馈回系统。 | 需要可读取上下文、确定性工具、质量关卡和持久反馈。 | + +Mnemon 应该服务第二种模式。宿主 agent 可以负责实际执行，但 Mnemon 应该帮助外层 +系统记住发生了什么、检测漂移、改进 skill、更新生命周期状态，并保存可 review 的 +证据。 + +## 公司大脑与 canonical context + +文章里的“公司大脑”，可以直接映射到 Mnemon 的 canonical state。真正有价值的资产 +不是临时 dashboard、生成脚本、聊天线程或宿主特定插件文件，而是可读取、持久、 +结构化的上下文： + +- goals、decisions、policies 和 constraints +- memory 和压缩后的运营知识 +- skills 及其 usage evidence +- reports、proposals、audit records 和 review status +- host bindings 和 capability manifests +- validation outcomes 和 observed drift + +在 Mnemon 中，这些状态应该位于 `.mnemon` 或其他 canonical state root 下。 +`.codex`、`.claude` 或未来插件目录，应该被视为可再生成的 projection。 + +```text +canonical context + durable memory, skills, policy, reports, proposals, audit + | + v +lifecycle control + reconcile, validate, project, learn + | + v +host surfaces + skills, hooks, app servers, tools, generated files +``` + +## 临时软件，持久上下文 + +文章提出，生成出来的内部软件可以是临时的，而业务上下文和 skills 才是长期资产。 +这与 Mnemon 的 host projection 模型高度一致。 + +Mnemon 应该把宿主原生资产视为有用但可替换： + +- generated dashboards +- host skill files +- hook glue +- app-server configuration +- eval runners +- temporary workflow code + +真正持久的，是解释这些资产为何存在、何时过期、如何验证、是否应该重新生成的 +lifecycle state。 + +## Loop 结构 + +文章中的 loop 可以转化为 Mnemon 的生命周期模型： + +```text +Observed Signals + user intent, repo diffs, host status, eval results, customer feedback + | + v +Desired State + goals, policies, skills, memory, bindings, expected projections + | + v +Reconcile + compare desired state with actual host surfaces and outcomes + | + v +Projection And Execution + host adapters expose skills, hooks, app servers, tools, evals + | + v +Status And Learning + record success, failure, drift, missing tools, stale skills, review needs + | + v +Updated Canonical Context +``` + +Mnemon 应该保持清晰的最小主干： + +```text +LoopModule + HostBinding + | + v +Desired State + | + v +Reconcile + | + v +HostAdapter -> Projection -> HostAgent + | + v +Status -> Learning -> next Reconcile +``` + +## Host Capability Surfaces + +文章强调确定性工具、生成软件和质量关卡。在 Mnemon 中，这些不应该变成 Mnemon +自己的 execution runtime，而应该被表达为 host capability surfaces。 + +示例包括： + +- Codex skills 和 project files +- Claude Code skills、hooks 和 subagents +- Codex app-server endpoints +- eval runners 和 test commands +- repository files 和 generated dashboards +- 通过宿主工具暴露的 databases、search indexes 和 external APIs + +宿主拥有执行。Mnemon 拥有围绕执行展开的生命周期协调：什么应该存在、如何投影、 +如何验证、哪里失败了、下一步应该改变什么。 + +## 质量关卡与人类边界 + +文章并不意味着所有事情都应该完全自治。它明确把人类放在系统边缘，用来处理高风险、 +新颖、伦理复杂或情绪浓度很高的现实场景。 + +Mnemon 应该把这个边界显式化： + +- 低风险 observation 和 reporting 可以自动化 +- projection validation 可以自动化 +- skill 和 memory proposal 可以自动生成 +- 破坏性变更需要显式 review +- 高风险 policy、security、data 或 production 变更需要 human gate +- audit records 应该保存发生了什么以及为什么发生 + +这样，自我改进是可 review 的，而不是隐形发生的。 + +## 对 Mnemon 的设计含义 + +这个设计哲学支持以下 Mnemon 设计选择： + +1. 把 `.mnemon` 作为 canonical lifecycle state。 +2. 把 `.codex`、`.claude` 和类似目录视为 projection。 +3. 每条改进路径都建模为包含 signals、policy、tools、gates 和 feedback 的 loop。 +4. 宿主执行保持在 Mnemon core 之外。 +5. 显式建模 Reconcile：比较 desired lifecycle state、actual host surfaces 和 + observed outcomes。 +6. 把 status、failures、stale projections 和 missing capabilities 作为一等状态。 +7. 优先生成或投影宿主资产，而不是维护重复真相。 +8. 对高风险变更保留 human review boundary。 + +## 战略定位 + +这篇文章描述的是 Mnemon 应该服务的组织形态：通过持久上下文和递归 loop 运转的 +self-improving agentic systems。 + +Mnemon 的差异化不只是“agent memory”。更强的定位是： + +```text +Mnemon turns durable context into lifecycle-controlled agent improvement loops. +``` + +Memory 是连续性支点。Loop 是差异化。Control plane 是产品形态。 From 6aa07511a62ad7c90b3c49b458ea05aad3ad4d01 Mon Sep 17 00:00:00 2001 From: Grivn Date: Wed, 20 May 2026 15:59:45 +0000 Subject: [PATCH 3/6] docs(site): simplify lifecycle control plane model Rewrite the lifecycle control plane material around a lighter three-layer model: State/Intent/Reality/Reconcile as the core loop, entity profiles as lightweight classifications, and execution surfaces for projection and observation. Add English and Chinese markdown design notes that mirror the site model and link them from the harness README entries. The model keeps LoopModule, LoopBinding, HostCapability, Projection, Observation, and governance records in a consistent profile framework while positioning Codex appserver as a dynamic observation surface. Validation: checked HTML parsing, script syntax, markdown links, and staged diff whitespace. --- docs/harness/LIFECYCLE_CONTROL_PLANE.md | 158 ++ docs/harness/README.md | 2 +- docs/site/lifecycle-control-plane/index.html | 1388 ++++++++---------- docs/zh/harness/LIFECYCLE_CONTROL_PLANE.md | 147 ++ docs/zh/harness/README.md | 2 +- 5 files changed, 945 insertions(+), 752 deletions(-) create mode 100644 docs/harness/LIFECYCLE_CONTROL_PLANE.md create mode 100644 docs/zh/harness/LIFECYCLE_CONTROL_PLANE.md diff --git a/docs/harness/LIFECYCLE_CONTROL_PLANE.md b/docs/harness/LIFECYCLE_CONTROL_PLANE.md new file mode 100644 index 0000000..9e68f7a --- /dev/null +++ b/docs/harness/LIFECYCLE_CONTROL_PLANE.md @@ -0,0 +1,158 @@ +# Lifecycle Control Plane + +Chinese version: [LIFECYCLE_CONTROL_PLANE.md](../zh/harness/LIFECYCLE_CONTROL_PLANE.md) + +This document defines the lightweight control model behind Mnemon Harness. The +visual site version is available at [Lifecycle Control Plane](../site/lifecycle-control-plane/index.html). + +Mnemon does not need a heavy distributed control system. It needs a consistent +model for making agent lifecycle capabilities durable, observable, portable, and +governable. + +## Minimal Definition + +Mnemon keeps `State`, declares `Intent`, observes `Reality`, and uses +`Reconcile` to pull Reality back toward Intent. The result is written back into +State. + +```text +State -> Intent -> Reality -> Reconcile -> State +``` + +This is the stable kernel. Concrete files, skills, hooks, host adapters, evals, +and proposals enter the kernel through profiles. + +## Core Model + +| Concept | Meaning | +| --- | --- | +| State | Durable truth owned by Mnemon, such as memory, skills, reports, proposals, audit, and status under `.mnemon`. | +| Intent | The lifecycle shape Mnemon wants the system to present. | +| Reality | The current real state of the host, project, tools, evals, and runtime. | +| Reconcile | The alignment mechanism that compares Intent with Reality and writes outcomes back into State. | + +Execution surfaces are not part of the core model. They belong to the execution +layer: they are how Mnemon reaches host reality. + +## Entity Profiles + +Entities are not the model itself. Each entity declares a profile inside the +model. + +| Profile | Meaning | Examples | +| --- | --- | --- | +| Template | Reusable definition, not necessarily reconciled. | `LoopModule` | +| Controlled | Needs ongoing alignment of Intent and Reality. | `LoopBinding`, `EvalRun`, future `Goal` | +| Surface | Expresses or reaches host capability. | `HostCapability`, `Projection` | +| Evidence | Observed fact from Reality, not a declarative object. | `Observation`, runtime status | +| Governance | Review, risk, and audit boundary. | `Proposal`, `Review`, `Audit` | + +Only controlled entities need the full `spec/status/reconcile` shape. Other +profiles participate in reconcile differently. + +## Current Entities + +| Entity | Profile | Role | +| --- | --- | --- | +| `LoopModule` | Template | Reusable lifecycle capability package such as memory-loop, skill-loop, or eval-loop. | +| `LoopBinding` | Controlled | Binds one `LoopModule` to one host; suitable as the first full controlled object sample. | +| `HostCapability` | Surface | Describes static or dynamic capabilities a host can expose. | +| `Projection` | Surface | Lets the HostAgent see Mnemon's Intent. | +| `Observation` | Evidence | Lets Mnemon see the HostAgent's Reality. | +| `Proposal` / `Review` / `Audit` | Governance | Stores proposals, decisions, and immutable records when Reconcile cannot safely complete automatically. | + +## Execution Surfaces + +Execution surfaces explain how Mnemon reaches the host without mixing that +mechanism into the core model. + +### Projection + +Projection is the static direction: render Intent into a host-readable view. + +Examples: + +- `.codex/skills` +- `.claude/hooks` +- host config +- generated docs +- manifests + +Projection lets the HostAgent see Mnemon's Intent. + +### Observation + +Observation is the dynamic direction: turn Reality into status, evidence, or +proposal input. + +Examples: + +- Codex appserver +- session APIs +- eval endpoints +- tool status +- runtime errors + +Observation lets Mnemon see HostAgent Reality. + +## What Memory-loop Proved + +Mnemon's method is to take capabilities that are often built as heavy external +systems and reintroduce them into the host lifecycle through hooks, skills, +daemon work, canonical state, and reconcile. + +`memory-loop` validated this pattern for memory: + +```text +external memory service + -> hook + skill + .mnemon state + -> prime / remind / nudge / compact lifecycle + -> lifecycle-native memory capability +``` + +The lifecycle control plane generalizes the same pattern for self-improving +loops: + +```text +standalone self-improvement loop + -> hook + skill + daemon + HostCapability + -> projection / observation / reconcile + -> governable project evolution +``` + +## Relation To Autoresearch + +Autoresearch is a useful reference because it demonstrates a constrained +self-improving loop: + +```text +edit -> run -> evaluate -> keep/discard -> repeat +``` + +Mnemon does not clone an experiment platform. Mnemon borrows the discipline of +self-improving loops and makes them lifecycle-native, host-portable, and +governable. + +In Mnemon, the decision space expands beyond keep or discard: + +- repair +- validate +- propose +- review +- audit +- no-op + +## Evolution Levels + +Mnemon should grow through lightweight capability levels: + +| Level | Shape | +| --- | --- | +| Profiles | Every entity declares a profile before becoming a full resource object. | +| Projection | Project Intent into the HostAgent. | +| Observation | Observe Reality through appserver, eval, tool status, and runtime evidence. | +| Governance | Let AI produce patches, reports, and proposals while review gates control risk. | + +The goal is not to copy a large control system. The goal is a small, consistent +lifecycle model that can scale from memory-loop to self-evolving agentic +projects. diff --git a/docs/harness/README.md b/docs/harness/README.md index 43b8c97..17fb18a 100644 --- a/docs/harness/README.md +++ b/docs/harness/README.md @@ -29,7 +29,7 @@ projection into host surfaces, and optional daemon scheduling. | Host Projection | [EN](HOST_PROJECTION.md) / [中文](../zh/harness/HOST_PROJECTION.md) | | Harness Roadmap | [EN](ROADMAP.md) / [中文](../zh/harness/ROADMAP.md) | | YC Evolving Design Philosophy | [EN](YC_EVOLVING_DESIGN_PHILOSOPHY.md) / [中文](../zh/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md) | -| Lifecycle Control Plane | [site](../site/lifecycle-control-plane/index.html) | +| Lifecycle Control Plane | [EN](LIFECYCLE_CONTROL_PLANE.md) / [中文](../zh/harness/LIFECYCLE_CONTROL_PLANE.md) / [site](../site/lifecycle-control-plane/index.html) | | Memory Loop | [EN](memory-loop/DESIGN.md) / [中文](../zh/harness/memory-loop/DESIGN.md) / [site](../site/memory-loop/index.html) | | Skill Loop | [EN](skill-loop/DESIGN.md) / [中文](../zh/harness/skill-loop/DESIGN.md) / [site](../site/skill-loop/index.html) | | Eval Loop | [EN](eval-loop/DESIGN.md) / [中文](../zh/harness/eval-loop/DESIGN.md) | diff --git a/docs/site/lifecycle-control-plane/index.html b/docs/site/lifecycle-control-plane/index.html index 1fcfde1..e67a46a 100644 --- a/docs/site/lifecycle-control-plane/index.html +++ b/docs/site/lifecycle-control-plane/index.html @@ -3,7 +3,7 @@ - + Mnemon Lifecycle Control Plane @@ -692,21 +571,21 @@

生命周期控制平面

- Mnemon 的核心不是另一个 memory store，也不是新的 agent runtime，而是一个由 durable memory 驱动的 agent 生命周期编排层。它通过宿主已有的 hooks、skills、plugins、subagents 或 app-server surface，把 memory、skill、eval、goal、audit 等 loop 编排到 HostAgent 的执行平面之外。 + Mnemon 保存 State，声明 Intent，观察 Reality，并通过 Reconcile 对齐差距。实体不是模型本身；实体只是模型中的 profile。Execution Surfaces 负责把 Mnemon 的意图投影给宿主，并把宿主现实观察回来。

- memory-driven - lifecycle loops - control plane - host-native projection + state + intent + reality + reconcile
@@ -717,21 +596,21 @@

阅读顺序

Lifecycle Control Plane

- Mnemon is not just another memory store and not a new agent runtime. It is an agent lifecycle orchestration layer driven by durable memory. It projects memory, skill, eval, goal, and audit loops onto host-native surfaces such as hooks, skills, plugins, subagents, and app-server endpoints. + Mnemon keeps State, declares Intent, observes Reality, and Reconciles the gap. Entities are not the model itself; they are profiles inside the model. Execution Surfaces project Mnemon intent into the host and observe host reality back into Mnemon.

- memory-driven - lifecycle loops - control plane - host-native projection + state + intent + reality + reconcile
@@ -743,178 +622,157 @@

Reading Path

-

核心定义

-

把 memory 从存取能力提升为 agent 生命周期中的持续循环机制。

+

最小定义

+

不强行对齐外部系统概念，只保留 Mnemon 自己的一致结构。

-
-
-

Mnemon 是什么

-
-

- Mnemon 是面向 agent 的生命周期控制平面。 它不替换 HostAgent 的执行模型，也不只控制 memory 本身，而是管理由 durable state 驱动的一组生命周期 loop：经验如何变成长期状态、这些状态如何被召回、写回、沉淀、评估和审计。 -

-
-
-
-

Mnemon 不是什么

-
-

- Mnemon 不定义 ReAct loop、tool runtime、plugin 格式、skill runtime、subagent 执行模型或 UI。宿主继续拥有执行平面；Mnemon 只拥有围绕执行平面挂载的治理循环。 -

-
-
+
+

+ Mnemon 保存 State，声明 Intent，观察 Reality，并通过 Reconcile 把 Reality 拉回 Intent，结果重新写入 State。 +

-

控制编排主轴

-

Mnemon 的主轴不是“执行任务”，而是让声明的 loop projection 持续接近现实。

+

Core Model

+

这是 Mnemon 如何理解世界；Surface 不在这一层，而在执行层。

-
-
-
- - - - - -
- -
- - -
+
+
+ State + durable truth + .mnemon 中的 memory、skills、reports、proposals、audit、status。 +
+
+ Intent + desired lifecycle + Mnemon 声明希望系统呈现的生命周期形态。 +
+
+ Reality + observed world + 宿主、项目、工具、eval 和运行时当前真实发生的状态。 +
+
+ Reconcile + alignment + 比较 Intent 与 Reality，并把结果写回 State。
-
Desired State 由 LoopModule 加 HostBinding 构成：声明哪个 loop 应该出现在什么 host 上。
-

控制对象

-

六个对象不是并列概念；它们分别服务于同一个 desired-state reconcile 闭环。

+

控制闭环

+

这个闭环是稳定内核；具体实体只是进入闭环的不同 profile。

-
-
- LoopModule - Desired state 的能力定义：policy、lifecycle prompts、protocol skills、state contract。 -
-
- HostAdapter - Reconcile 调用的宿主实现：把 loop 渲染成 Claude Code、Codex、OpenClaw 的原生 surface。 -
-
- HostBinding - Desired state 的绑定定义：哪个 loop 应该安装到哪个 host，启用哪些 lifecycle 能力。 -
-
- Projection - Actual state 的宿主视图：生成的 host-native 文件，不是 source of truth。 -
-
- Status - Actual state 的观测结果：Installed、Ready、Drifted、MissingCapability、Stale。 -
-
- Reconcile - 控制动作：比较 desired 和 actual，执行 create、repair、update、remove 或 no-op。 +
+
+
+
+ State + 持久上下文、控制状态、证据和治理记录。 +
+
+ Intent + 期望的 lifecycle shape、policy、binding 或 proposal。 +
+
+ Reality + 通过宿主 surface 观察到的文件、运行时、eval、工具状态。 +
+
+ Reconcile + repair、validate、propose、review 或 no-op。 +
+
+ State + status、report、proposal、audit 成为下一轮输入。 +
+
+
-

现有 loops 如何进入闭环

-

memory、skill、eval 不是散落模块；它们先变成 desired state，再由 host adapter 投影到宿主。

+

Entity Profiles

+

实体不是模型本身。实体只需要声明自己在 Core Model 中扮演什么 profile。

-
-
-
- - - - - - -
+
+
+ Template + reusable definition + 定义可复用能力，不一定被持续 reconcile。例：LoopModule。 +
+
+ Controlled + spec / status + 需要持续对齐 Intent 与 Reality。例：LoopBinding、EvalRun、未来 Goal。 +
+
+ Surface + reach reality + 表达或触达宿主能力。例：HostCapability、Projection。 +
+
+ Evidence + observed fact + 来自 Reality 的证据，不是声明对象。例：Observation、runtime status。 +
+
+ Governance + risk boundary + 处理人审和审计。例：Proposal、Review、Audit。
-
LoopModules 是可携带能力包：memory-loop、skill-loop、eval-loop 都先保持 host-agnostic。
-

现有 loops 的组织

-

memory-loop 是连续性起点；skill-loop 和 eval-loop 是围绕记忆治理自然展开的控制循环。

+

当前实体映射

+

只列当前最需要理解的实体，保持页面轻量。

-
- +
+
- - - - + + + - - - - + + + + + + + + + + + + + - - - - + + + - - - - + + + + + + + +
Loop控制目标主要动作状态位置EntityProfileRole
memory-loop让经验变成未来可用的 durable memory。prime、recall、writeback、compact preservation、dreaming consolidation。.mnemon/harness/memory-loopLoopModuleTemplate可复用生命周期能力包，例如 memory-loop、skill-loop、eval-loop。
LoopBindingControlled把某个 LoopModule 绑定到某个 host；适合作为第一个完整 controlled object 样本。
HostCapabilitySurface描述宿主可暴露的静态或动态能力。
skill-loop从重复有效行为中沉淀、治理和迁移 skills。observe、curate、author、manage active/stale/archived lifecycle。.mnemon/harness/skill-loopProjectionSurface让 HostAgent 看见 Mnemon 的 Intent。
eval-loop验证 loop 是否真的改善 HostAgent 行为。plan scenarios、run evals、analyze reports、propose improvements。.mnemon/harness/eval-loopObservationEvidence让 Mnemon 看见 HostAgent 的 Reality。
Proposal / Review / AuditGovernance当 Reconcile 无法安全自动完成时，保存提议、决策和不可变记录。
@@ -923,264 +781,277 @@

现有 loops 的组织

-

外部 memory 的位置

-

外部 memory 项目不必被替代；它们可以成为 Mnemon memory-loop 编排的 backend、source 或 surface。

+

Execution Surfaces

+

这一层解释 Mnemon 如何触达宿主，不再和 Core Model 混在一起。

-
-
-
- - - - +
+
+

Projection

+
+

静态方向：把 Intent 渲染成 host-readable view。

+
+ .codex/skills + .claude/hooks + config + generated docs + manifest +
-
-
外部 memory 系统可以作为 backend、source 或 surface 接入，而不是被 Mnemon 替代。
+ +
+

Observation

+
+

动态方向：把 Reality 转化为 status、evidence 或 proposal 的输入。

+
+ Codex appserver + session API + eval endpoint + tool status + runtime errors +
+
+
-

现实落地

-

这个划分现实，因为它抽象的是已经存在的复杂度，而不是发明一个新 agent runtime。

+

Memory-loop 给出的证据

+

memory-loop 不是全部答案，但它验证了 Mnemon 的方法论。

-
-
-

现在已有

-
-
-
LoopModule
-

harness/modules/*

-
-
-
HostAdapter
-

harness/hosts/*

-
-
-
Projection
-

.claude、.codex generated files

-
-
-
-
-

下一步

-
-
-
HostBinding
-

把“哪个 loop 绑定到哪个 host”从命令参数提升为声明对象。

-
-
-
Status
-

从目录存在检查升级为 projection drift 和 capability 检查。

-
-
-
Reconcile
-

让 install 成为幂等 reconcile 的入口，而不是一次性复制脚本。

-
-
-
-
-

保持克制

-
-

- 不急于做 API server、daemon、distributed scheduler、CRD 系统或全模块依赖求解。先用文件、CLI、manifest 和 adapter 把 desired state 与 actual projection 对齐。 -

-
- 最小成功标准：mnemon harness reconcile 可以修复缺失或过期的 host projection。 -
-
-
+
+ + + + + + + + + + + + + + + + + + + + + + + +
模式常见做法Mnemon 做法抽象结果
Memory外部 memory service、vector DB、retrieval API。通过 hook + skill + .mnemon state 进入 prime、remind、nudge、compact。memory 从存储能力变成 lifecycle-native capability。
Self-improvement独立实验平台或单 repo overnight loop。通过 hook + skill + daemon + HostCapability 进入可治理 project evolution。autoresearch-like loop 变成可治理生命周期能力。
-
-
-

Core Definition

-

Mnemon turns memory from a storage capability into a lifecycle mechanism for agents.

+

与 autoresearch 的关系

+

参考的是自改进循环的纪律，不是复制一个实验平台。

-
-
-

What Mnemon Is

-
-

- Mnemon is a memory-driven lifecycle control plane for agents. It does not replace the HostAgent execution model, and it does not only control memory itself. It governs a set of lifecycle loops driven by durable state: how experience becomes long-term state, and how that state is recalled, written back, consolidated, evaluated, and audited. -

-
+
+
+

Autoresearch

+
    +
  • 极简自主实验循环。
    • +
  • 一个主要可变文件、一个固定时间预算、一个指标。
    • +
  • 核心决策是 keep 或 discard。
    • +
-
-

What Mnemon Is Not

-
-

- Mnemon does not define the ReAct loop, tool runtime, plugin format, skill runtime, subagent execution model, or UI. The host owns execution; Mnemon owns attachable governance loops around execution. -

-
+
+

Mnemon

+
    +
  • 面向持久自主改进循环的生命周期控制平面。
    • +
  • 用 Entity Profiles 让不同实体轻量进入同一个控制模型。
    • +
  • 把决策扩展为 repair、validate、propose、review、audit。
    • +
-

Control Loop Blueprint

-

Mnemon's main axis is not task execution. It keeps declared loop projections close to reality.

+

演进层级

+

保持轻量：先定义 profile，再扩展 surface，最后进入自演进治理。

-
-
-
- - - - - -
- -
- - -
+
+
+ Level 1: Profiles + 每个实体声明 profile，不急于变成完整资源对象。 +
+
+ Level 2: Projection + 把 Intent 投影给 HostAgent。 +
+
+ Level 3: Observation + 通过 appserver、eval、tool status 观察 Reality。 +
+
+ Level 4: Governance + 让 AI 产生 patch、report、proposal，由 review gate 控制风险。
-
Desired State is LoopModule plus HostBinding: which loop should appear on which host.
+
+
-

Control Objects

-

These six objects are not parallel ideas. They each occupy one position in the same desired-state reconcile loop.

+

Minimal Definition

+

Do not force-fit external concepts. Keep Mnemon's own structure consistent.

-
-
- LoopModule - Desired-state capability definition: policy, lifecycle prompts, protocol skills, and state contract. -
-
- HostAdapter - Host implementation called by reconcile to render Claude Code, Codex, or OpenClaw surfaces. -
-
- HostBinding - Desired-state binding: which loop goes to which host, and which lifecycle capabilities are enabled. +
+

+ Mnemon keeps State, declares Intent, observes Reality, and uses Reconcile to pull Reality back toward Intent, writing the result into State. +

+
+
+ +
+
+

Core Model

+

This is how Mnemon understands the world. Surface belongs to the execution layer, not this layer.

+
+
+
+ State + durable truth + Memory, skills, reports, proposals, audit, and status under .mnemon.
-
- Projection - Actual host view: generated host-native files, not the source of truth. +
+ Intent + desired lifecycle + The lifecycle shape Mnemon wants the system to present.
-
- Status - Observed actual state: Installed, Ready, Drifted, MissingCapability, Stale. +
+ Reality + observed world + The current real state of the host, project, tools, evals, and runtime.
-
+
Reconcile - Control action: compare desired with actual, then create, repair, update, remove, or no-op. + alignment + Compare Intent with Reality, then write outcomes back into State.
-

How Current Loops Enter The Control Loop

-

memory, skill, and eval are not scattered modules. They become desired state, then host adapters project them.

+

Control Loop

+

This loop is the stable kernel. Concrete entities enter it through different profiles.

-
-
-
- - - - - - + repair, validate, propose, review, or no-op. +
+
+ State + Status, reports, proposals, and audit become next input. +
+ +
+
+
+ +
+
+

Entity Profiles

+

Entities are not the model itself. Each entity only declares its profile inside the Core Model.

+
+
+
+ Template + reusable definition + Defines reusable capability and is not necessarily reconciled. Example: LoopModule. +
+
+ Controlled + spec / status + Needs ongoing alignment of Intent and Reality. Examples: LoopBinding, EvalRun, future Goal. +
+
+ Surface + reach reality + Expresses or reaches host capability. Examples: HostCapability, Projection. +
+
+ Evidence + observed fact + Evidence from Reality, not a declarative object. Examples: Observation, runtime status. +
+
+ Governance + risk boundary + Handles review and audit. Examples: Proposal, Review, Audit.
-
LoopModules are portable capability packages: memory-loop, skill-loop, and eval-loop stay host-agnostic first.
-

Current Loops

-

memory-loop is the continuity point. skill-loop and eval-loop naturally extend memory-centered governance.

+

Current Entities

+

Only list entities that must be understood now, keeping the page lightweight.

-
- +
+
- - - - + + + - - - - + + + - - - - + + + - - - - + + + + + + + + + + + + + + + + + +
LoopControl GoalMain ActionsState LocationEntityProfileRole
memory-loopTurn experience into durable memory usable by future work.prime, recall, writeback, compact preservation, dreaming consolidation..mnemon/harness/memory-loopLoopModuleTemplateReusable lifecycle capability package such as memory-loop, skill-loop, eval-loop.
skill-loopPromote repeated useful behavior into governed skills.observe, curate, author, manage active/stale/archived lifecycle..mnemon/harness/skill-loopLoopBindingControlledBinds one LoopModule to one host; suitable as the first full controlled object sample.
eval-loopVerify whether loops improve HostAgent behavior.plan scenarios, run evals, analyze reports, propose improvements..mnemon/harness/eval-loopHostCapabilitySurfaceDescribes static or dynamic capabilities a host can expose.
ProjectionSurfaceLets the HostAgent see Mnemon's Intent.
ObservationEvidenceLets Mnemon see the HostAgent's Reality.
Proposal / Review / AuditGovernanceStores proposals, decisions, and immutable records when Reconcile cannot safely complete automatically.
@@ -1189,87 +1060,121 @@

Current Loops

-

External Memory

-

External memory systems do not need to be replaced. They can become backends, sources, or surfaces orchestrated by Mnemon memory-loop.

+

Execution Surfaces

+

This layer explains how Mnemon reaches the host without mixing it into the Core Model.

-
-
-
- - - - +
+
+

Projection

+
+

Static direction: render Intent into a host-readable view.

+
+ .codex/skills + .claude/hooks + config + generated docs + manifest +
-
-
External memory systems can plug in as backends, sources, or surfaces instead of being replaced by Mnemon.
+ +
+

Observation

+
+

Dynamic direction: turn Reality into status, evidence, or proposal input.

+
+ Codex appserver + session API + eval endpoint + tool status + runtime errors +
+
+
-

Practical Path

-

This split is practical because it abstracts complexity already present in the system instead of inventing a new agent runtime.

+

What Memory-loop Proved

+

memory-loop is not the whole answer, but it validated Mnemon's method.

-
-
-

Already Present

-
-
-
LoopModule
-

harness/modules/*

-
-
-
HostAdapter
-

harness/hosts/*

-
-
-
Projection
-

.claude and .codex generated files

-
-
-
-
-

Next Step

-
-
-
HostBinding
-

Promote “which loop goes to which host” from command arguments into a declared object.

-
-
-
Status
-

Move beyond directory checks into projection drift and capability checks.

-
-
-
Reconcile
-

Make install an idempotent reconcile entrypoint instead of a one-time copy script.

-
-
+
+ + + + + + + + + + + + + + + + + + + + + + + +
PatternCommon PathMnemon PathAbstraction
MemoryExternal memory service, vector DB, retrieval API.hook + skill + .mnemon state across prime, remind, nudge, and compact.Memory becomes a lifecycle-native capability.
Self-improvementStandalone experiment platform or one-repo overnight loop.hook + skill + daemon + HostCapability for governable project evolution.Autoresearch-like loops become governable lifecycle capabilities.
+
+
+ +
+
+

Relation To Autoresearch

+

Borrow the discipline of self-improving loops, not the shape of an experiment platform.

+
+
+
+

Autoresearch

+
    +
  • A minimal autonomous experimentation loop.
    • +
  • One main mutable file, one fixed time budget, one metric.
    • +
  • The core decision is keep or discard.
    • +
-
-

Keep It Small

-
-

- Do not start with an API server, daemon, distributed scheduler, CRD system, or dependency solver. Use files, CLI commands, manifests, and adapters to align desired state with actual projection. -

-
- Minimal success: mnemon harness reconcile can repair missing or stale host projections. -
-
+
+

Mnemon

+
    +
  • A lifecycle control plane for durable autonomous improvement loops.
    • +
  • Uses Entity Profiles to keep different entities inside one lightweight model.
    • +
  • Extends decisions into repair, validate, propose, review, and audit.
    • +
+ +
+
+

Evolution Levels

+

Stay lightweight: define profiles, expand surfaces, then move toward self-evolution governance.

+
+
+
+ Level 1: Profiles + Every entity declares a profile before becoming a full resource object. +
+
+ Level 2: Projection + Project Intent into the HostAgent. +
+
+ Level 3: Observation + Observe Reality through appserver, eval, and tool status. +
+
+ Level 4: Governance + Let AI produce patches, reports, and proposals while review gates control risk. +
+
+
@@ -1290,23 +1195,6 @@

Keep It Small

buttons.forEach((button) => { button.addEventListener("click", () => setLanguage(button.dataset.lang)); }); - - document.querySelectorAll("[data-diagram]").forEach((diagram) => { - const caption = diagram.querySelector(".diagram-caption"); - const nodes = Array.from(diagram.querySelectorAll(".diagram-node")); - - function activate(node) { - nodes.forEach((item) => item.classList.toggle("active", item === node)); - if (caption && node.dataset.caption) { - caption.textContent = node.dataset.caption; - } - } - - nodes.forEach((node) => { - node.addEventListener("click", () => activate(node)); - node.addEventListener("focus", () => activate(node)); - }); - }); diff --git a/docs/zh/harness/LIFECYCLE_CONTROL_PLANE.md b/docs/zh/harness/LIFECYCLE_CONTROL_PLANE.md new file mode 100644 index 0000000..988c648 --- /dev/null +++ b/docs/zh/harness/LIFECYCLE_CONTROL_PLANE.md @@ -0,0 +1,147 @@ +# 生命周期控制平面 + +English version: [LIFECYCLE_CONTROL_PLANE.md](../../harness/LIFECYCLE_CONTROL_PLANE.md) + +本文定义 Mnemon Harness 背后的轻量控制模型。可视化版本见 +[Lifecycle Control Plane](../../site/lifecycle-control-plane/index.html)。 + +Mnemon 不需要一个重型分布式控制系统。Mnemon 需要的是一套一致的模型，用来让 +agent 生命周期能力变得持久、可观测、可迁移、可治理。 + +## 最小定义 + +Mnemon 保存 `State`，声明 `Intent`，观察 `Reality`，并通过 `Reconcile` 把 +Reality 拉回 Intent。结果重新写回 State。 + +```text +State -> Intent -> Reality -> Reconcile -> State +``` + +这是稳定内核。具体文件、skills、hooks、host adapters、evals 和 proposals，都通过 +profile 进入这个内核。 + +## 核心模型 + +| 概念 | 含义 | +| --- | --- | +| State | Mnemon 拥有的持久事实，例如 `.mnemon` 下的 memory、skills、reports、proposals、audit 和 status。 | +| Intent | Mnemon 希望系统呈现的生命周期形态。 | +| Reality | 宿主、项目、工具、eval 和运行时当前真实发生的状态。 | +| Reconcile | 比较 Intent 与 Reality，并把结果写回 State 的对齐机制。 | + +Execution surfaces 不属于核心模型。它们属于执行层：它们说明 Mnemon 如何触达宿主现实。 + +## Entity Profiles + +实体不是模型本身。每个实体只是在模型中声明自己的 profile。 + +| Profile | 含义 | 示例 | +| --- | --- | --- | +| Template | 可复用定义，不一定被持续 reconcile。 | `LoopModule` | +| Controlled | 需要持续对齐 Intent 与 Reality。 | `LoopBinding`、`EvalRun`、未来 `Goal` | +| Surface | 表达或触达宿主能力。 | `HostCapability`、`Projection` | +| Evidence | 来自 Reality 的观测事实，不是声明对象。 | `Observation`、runtime status | +| Governance | review、risk 和 audit 边界。 | `Proposal`、`Review`、`Audit` | + +只有 controlled entities 需要完整的 `spec/status/reconcile` 形态。其他 profile +以不同方式参与 reconcile。 + +## 当前实体 + +| Entity | Profile | 作用 | +| --- | --- | --- | +| `LoopModule` | Template | 可复用 lifecycle capability package，例如 memory-loop、skill-loop、eval-loop。 | +| `LoopBinding` | Controlled | 把某个 `LoopModule` 绑定到某个 host；适合作为第一个完整 controlled object 样本。 | +| `HostCapability` | Surface | 描述宿主可以暴露的静态或动态能力。 | +| `Projection` | Surface | 让 HostAgent 看见 Mnemon 的 Intent。 | +| `Observation` | Evidence | 让 Mnemon 看见 HostAgent 的 Reality。 | +| `Proposal` / `Review` / `Audit` | Governance | 当 Reconcile 无法安全自动完成时，保存 proposal、decision 和不可变记录。 | + +## Execution Surfaces + +Execution surfaces 说明 Mnemon 如何触达宿主，而不把这个机制混进核心模型。 + +### Projection + +Projection 是静态方向：把 Intent 渲染成 host-readable view。 + +示例： + +- `.codex/skills` +- `.claude/hooks` +- host config +- generated docs +- manifests + +Projection 让 HostAgent 看见 Mnemon 的 Intent。 + +### Observation + +Observation 是动态方向：把 Reality 转化为 status、evidence 或 proposal 的输入。 + +示例： + +- Codex appserver +- session APIs +- eval endpoints +- tool status +- runtime errors + +Observation 让 Mnemon 看见 HostAgent Reality。 + +## Memory-loop 给出的证据 + +Mnemon 的方法，是把通常被做成重外部系统的能力，通过 hooks、skills、daemon work、 +canonical state 和 reconcile，重新引入宿主生命周期。 + +`memory-loop` 已经用 memory 验证了这个模式： + +```text +external memory service + -> hook + skill + .mnemon state + -> prime / remind / nudge / compact lifecycle + -> lifecycle-native memory capability +``` + +lifecycle control plane 把同样模式推广到 self-improving loops： + +```text +standalone self-improvement loop + -> hook + skill + daemon + HostCapability + -> projection / observation / reconcile + -> governable project evolution +``` + +## 与 Autoresearch 的关系 + +Autoresearch 是有价值的参考，因为它展示了一个受约束的 self-improving loop： + +```text +edit -> run -> evaluate -> keep/discard -> repeat +``` + +Mnemon 不复制实验平台。Mnemon 借鉴的是 self-improving loop 的纪律，并让这类 loop +变得生命周期原生、宿主可迁移、可治理。 + +在 Mnemon 中，决策空间不止 keep 或 discard： + +- repair +- validate +- propose +- review +- audit +- no-op + +## 演进层级 + +Mnemon 应该沿着轻量能力层级增长： + +| Level | 形态 | +| --- | --- | +| Profiles | 每个实体先声明 profile，不急于成为完整 resource object。 | +| Projection | 把 Intent 投影给 HostAgent。 | +| Observation | 通过 appserver、eval、tool status 和 runtime evidence 观察 Reality。 | +| Governance | AI 可以产生 patch、report 和 proposal，由 review gate 控制风险。 | + +目标不是复制一个大型控制系统，而是形成一个小而一致的 lifecycle model，从 +memory-loop 延展到自演进的 agentic projects。 diff --git a/docs/zh/harness/README.md b/docs/zh/harness/README.md index 773c162..1c1c697 100644 --- a/docs/zh/harness/README.md +++ b/docs/zh/harness/README.md @@ -24,7 +24,7 @@ host surface projection，以及可选的 daemon scheduling。 | Host Projection | [中文](HOST_PROJECTION.md) / [EN](../../harness/HOST_PROJECTION.md) | | Harness Roadmap | [中文](ROADMAP.md) / [EN](../../harness/ROADMAP.md) | | YC Evolving 设计哲学 | [中文](YC_EVOLVING_DESIGN_PHILOSOPHY.md) / [EN](../../harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md) | -| Lifecycle Control Plane | [site](../../site/lifecycle-control-plane/index.html) | +| Lifecycle Control Plane | [中文](LIFECYCLE_CONTROL_PLANE.md) / [EN](../../harness/LIFECYCLE_CONTROL_PLANE.md) / [site](../../site/lifecycle-control-plane/index.html) | | Memory Loop | [中文](memory-loop/DESIGN.md) / [EN](../../harness/memory-loop/DESIGN.md) / [site](../../site/memory-loop/index.html) | | Skill Loop | [中文](skill-loop/DESIGN.md) / [EN](../../harness/skill-loop/DESIGN.md) / [site](../../site/skill-loop/index.html) | | Eval Loop | [中文](eval-loop/DESIGN.md) / [EN](../../harness/eval-loop/DESIGN.md) | From e55a5be93b3837257d1c01031fa67dcc8c07ae9b Mon Sep 17 00:00:00 2001 From: Grivn Date: Wed, 20 May 2026 16:24:02 +0000 Subject: [PATCH 4/6] docs(harness): align loop docs with lifecycle model Reframe the memory-loop and skill-loop docs around the shared State, Intent, Projection, Reality, and Reconcile model. The site pages keep their existing runtime phase flows while making each loop's lifecycle role clearer. Validation: git diff --check and embedded site script parsing for memory-loop and skill-loop. --- docs/harness/memory-loop/DESIGN.md | 53 +++++++++---- docs/harness/skill-loop/DESIGN.md | 46 ++++++++---- docs/site/memory-loop/index.html | 104 +++++++++++++------------- docs/site/skill-loop/index.html | 94 ++++++++++++----------- docs/zh/harness/memory-loop/DESIGN.md | 50 +++++++++---- docs/zh/harness/skill-loop/DESIGN.md | 45 +++++++---- 6 files changed, 233 insertions(+), 159 deletions(-) diff --git a/docs/harness/memory-loop/DESIGN.md b/docs/harness/memory-loop/DESIGN.md index 99777f7..0ce54c6 100644 --- a/docs/harness/memory-loop/DESIGN.md +++ b/docs/harness/memory-loop/DESIGN.md @@ -10,26 +10,49 @@ The memory loop is the first practical slice of the self-evolution harness. It g ## Lifecycle Control Plane Position -In the lifecycle control plane, `memory-loop` is a `LoopModule`. It declares the -portable memory policy, lifecycle prompts, protocol skills, dreaming subagent, -and runtime state contract. +In the lifecycle control plane, `memory-loop` is the first practical proof that +an external capability can become lifecycle-native without turning Mnemon into a +host agent runtime. -The loop becomes active through a host binding: +Using the shared control model: + +| Layer | Memory-loop shape | +| --- | --- | +| State | `MEMORY.md`, Mnemon long-term stores, reports, manifests, and memory-loop status under `.mnemon`. | +| Intent | Keep useful agent, user, and project continuity available across lifecycle boundaries. | +| Reality | The host prompt, current task, working-memory contents, recall results, context pressure, and consolidation state. | +| Reconcile | Decide whether to read, write, compact, consolidate, or leave memory unchanged, then write status or durable state. | + +The entity profiles are intentionally light: + +| Entity | Profile | Role | +| --- | --- | --- | +| `memory-loop` | Template | Reusable lifecycle capability package. | +| memory binding | Controlled | Binds memory behavior to a host lifecycle such as Prime, Remind, Nudge, Compact, and maintenance. | +| hot/cold memory surfaces | Surface | `MEMORY.md`, Mnemon recall/write, host hooks, and protocol skills. | +| recall/write/consolidation evidence | Evidence | Observed memory usefulness, context pressure, stale entries, and durable write results. | +| memory proposals or audits | Governance | Future reviewable records for risky memory changes or policy changes. | + +In this framing, `MEMORY.md` is not the model. It is the first hot-memory +surface. Mnemon long-term storage is not the model either. It is the first +cold-memory surface. The model is the lifecycle loop that keeps useful +continuity aligned with reality. + +The loop becomes active through projection and observation surfaces: ```text -LoopModule(memory-loop) - -> HostBinding(host + lifecycle surfaces) - -> Reconcile - -> HostAdapter - -> Projection(.codex / .claude / other host surface) - -> Status - -> next Reconcile +State(.mnemon memory state) + -> Intent(memory should help this lifecycle boundary) + -> Projection(hooks, GUIDE, memory_get, memory_set, dreaming) + -> Reality(host prompt, task, context pressure, recall/write outcomes) + -> Reconcile(read, write, compact, consolidate, no-op) + -> State(MEMORY.md, Mnemon store, reports, status) ``` -The HostAgent consumes the projection and still owns execution. `.mnemon` keeps -the canonical memory-loop state, including `MEMORY.md`, manifests, and durable -Mnemon stores. Host directories are generated views that can be repaired when -projection status drifts from the declared binding. +The HostAgent consumes the projection and still owns execution. Mnemon owns the +durable state, profile model, and reconcile boundary. Host directories remain +generated views that can be repaired when projected memory assets drift from the +declared lifecycle intent. ## Design Goal diff --git a/docs/harness/skill-loop/DESIGN.md b/docs/harness/skill-loop/DESIGN.md index 3bb321d..eac402f 100644 --- a/docs/harness/skill-loop/DESIGN.md +++ b/docs/harness/skill-loop/DESIGN.md @@ -10,26 +10,44 @@ The MVP is intentionally a visibility and lifecycle harness. It decides which sk ## Lifecycle Control Plane Position -In the lifecycle control plane, `skill-loop` is a `LoopModule`. It declares -skill visibility policy, observation and management protocols, curator -maintenance, and the canonical skill lifecycle state contract. +In the lifecycle control plane, `skill-loop` makes skill visibility and skill +lifecycle state a lifecycle-native capability without replacing the host's +native skill runtime. -The loop becomes active through a host binding: +Using the shared control model: + +| Layer | Skill-loop shape | +| --- | --- | +| State | `.mnemon` skill library, active/stale/archived state, evidence, proposals, reports, and skill-loop status. | +| Intent | Keep the right skills visible to the host while preserving stale and archived skills for review, recovery, and design memory. | +| Reality | Host skill surface, actual active projection, skill usage evidence, missing or misleading skills, curator findings, and review decisions. | +| Reconcile | Sync active skills, record evidence, propose lifecycle changes, apply approved changes, and refresh host visibility at Prime. | + +The entity profiles are intentionally light: + +| Entity | Profile | Role | +| --- | --- | --- | +| `skill-loop` | Template | Reusable lifecycle capability package. | +| skill binding | Controlled | Binds skill visibility and lifecycle policy to one host skill surface. | +| host skill surface | Surface | Host-native discovery surface such as `.codex/skills` or `.claude/skills`. | +| usage signals and curator findings | Evidence | Observed skill usefulness, missing skills, stale skills, or workflow repetition. | +| proposals, reviews, audits | Governance | Reviewable changes before canonical skill lifecycle mutation. | + +The loop becomes active through projection and observation surfaces: ```text -LoopModule(skill-loop) - -> HostBinding(host + skill surface) - -> Reconcile - -> HostAdapter - -> Projection(.codex/skills, .claude/skills, or another host surface) - -> Status - -> next Reconcile +State(.mnemon skill library) + -> Intent(the right skills should be visible) + -> Projection(active skills into host skill surface) + -> Reality(host usage, evidence, missing or stale skills) + -> Reconcile(observe, curate, propose, manage, no-op) + -> State(active/stale/archived, reports, proposals, status) ``` The HostAgent consumes the projected active skill surface and still owns native -skill discovery and execution. `.mnemon` keeps the canonical skill library and -evidence. Host skill directories are generated views that can be repaired when -projection status drifts from the declared binding. +skill discovery and execution. Mnemon owns canonical skill state, evidence, +proposal-first governance, and the reconcile boundary. Host skill directories +remain generated views that can be refreshed when Reality drifts from Intent. ## Goals diff --git a/docs/site/memory-loop/index.html b/docs/site/memory-loop/index.html index 88c22d8..94371c0 100644 --- a/docs/site/memory-loop/index.html +++ b/docs/site/memory-loop/index.html @@ -311,7 +311,7 @@ .control-path-grid { display: grid; - grid-template-columns: repeat(6, minmax(0, 1fr)); + grid-template-columns: repeat(5, minmax(0, 1fr)); gap: 1px; background: var(--line); } @@ -757,23 +757,22 @@

langAttr: "zh-CN", title: "Memory Loop MVP", eyebrow: "Mnemon Harness / Memory Loop", - summary: "第一版只实现一个清晰的记忆闭环：MEMORY.md 是模型友好的热记忆，Mnemon 是工程友好的冷记忆，GUIDE/hook/protocol/dreaming 负责二者之间的读取、积累和巩固。", + summary: "Memory-loop 是生命周期控制平面的第一个完整证明：Mnemon 保存记忆 State，声明跨生命周期可用的记忆 Intent，观察 HostAgent 的 Reality，并通过 Reconcile 决定 read、write、compact、consolidate 或 no-op。", readingTitle: "阅读顺序", reading: [ - "先看三大核心：HostAgent、MEMORY.md、Mnemon。", - "再看五类支撑概念：GUIDE、setup、hook、protocol、subagent。", - "最后切换阶段，看每个 hook 如何把判断交给 skill 或 subagent。" + "先看 memory-loop 如何落入 State / Intent / Reality / Reconcile。", + "再看热记忆、冷记忆和执行 surface 如何协作。", + "最后切换阶段，看每个 lifecycle boundary 如何触发 read、write 或 consolidation。" ], controlTitle: "生命周期控制位置", - controlIntro: "memory-loop 在整体控制平面里是一个 LoopModule。它先被声明和绑定，再由 HostAdapter 投影到宿主；运行结果和状态回到 .mnemon，供下一次 reconcile 使用。", - controlFeedback: "Status 反馈到下一次 Reconcile；记忆真实状态保留在 .mnemon，而不是宿主 projection 目录。", + controlIntro: "memory-loop 不是一个外部 memory service，而是一个 lifecycle-native capability。它把热记忆、冷记忆、hook、protocol 和 dreaming 放进同一个控制闭环。", + controlFeedback: "Memory status and durable state feed the next lifecycle pass.", controlSteps: [ - { name: "LoopModule", color: "var(--working)", text: "memory-loop 声明 GUIDE、hooks、memory_get、memory_set、dreaming 和 MEMORY.md 状态契约。" }, - { name: "HostBinding", color: "var(--guide)", text: "声明 memory-loop 应绑定到 Codex、Claude Code 或其他 host，并启用对应 lifecycle surface。" }, - { name: "Reconcile", color: "var(--capability)", text: "检查 projection 是否存在、过期或漂移，并决定是否重新生成宿主可见资产。" }, - { name: "HostAdapter", color: "var(--host)", text: "把同一 memory-loop 渲染成 host-native skills、hooks、env 和 runtime 指针。" }, - { name: "Projection", color: "var(--hook)", text: "HostAgent 消费 .codex 或 .claude 中生成的 skill、hook、instruction 和 env 文件。" }, - { name: "Status", color: "var(--longterm)", text: "记录 projection 状态、manifest 和 .mnemon/harness/memory-loop 的 canonical runtime state。" } + { name: "State", color: "var(--longterm)", text: ".mnemon 保存 MEMORY.md、Mnemon store、reports、manifests 和 memory-loop status。" }, + { name: "Intent", color: "var(--guide)", text: "记忆应该在 Prime、Remind、Nudge、Compact 和 maintenance 中帮助 HostAgent 保持连续性。" }, + { name: "Projection", color: "var(--hook)", text: "GUIDE、hooks、memory_get、memory_set、dreaming 和 env 被投影成 host-readable surface。" }, + { name: "Reality", color: "var(--host)", text: "Host prompt、当前任务、上下文压力、recall/write 结果和 stale working memory 构成现实状态。" }, + { name: "Reconcile", color: "var(--capability)", text: "根据现实决定 read、write、compact、consolidate 或 no-op，并把结果写回 State。" } ], componentsTitle: "系统组成", componentsIntro: "这里先固定三大核心主体，再用统一的五类 harness 概念描述安装、触发、协议和后台维护。", @@ -823,7 +822,7 @@

prime: { title: "Prime", tag: "hook", - summary: "Prime 是唯一的直接加载路径：把 MEMORY.md 和 GUIDE.md 加入 HostAgent 的 system prompt。", + summary: "Prime 是唯一的直接加载路径：把热 State（MEMORY.md）和 Intent policy（GUIDE.md）投影进 HostAgent 的 system prompt。", short: "MEMORY.md + GUIDE.md -> prompt", events: [ { kind: "arrow", from: "working", to: "host", y: 96, label: "MEMORY.md 内容" }, @@ -832,14 +831,14 @@

], details: [ ["input", "MEMORY.md + GUIDE.md"], - ["action", "直接加入 system prompt"], + ["action", "把 hot State 和 Intent policy 投影到 prompt"], ["boundary", "不调用 memory_get，不触发 Mnemon recall"] ] }, recall: { title: "Remind / Recall", tag: "hook + protocol", - summary: "Remind 只触发读记忆判断；如果需要读取，HostAgent 加载 memory_get.md protocol skill，并按其中协议调用 Mnemon。", + summary: "Remind 观察当前任务 Reality，并触发读记忆判断；如果需要读取，HostAgent 加载 memory_get.md，把 cold State page-in 到上下文。", short: "GUIDE -> memory_get.md -> Mnemon", events: [ { kind: "arrow", from: "guide", to: "host", y: 82, label: "是否读记忆？" }, @@ -849,14 +848,14 @@

], details: [ ["trigger", "Remind hook"], - ["action", "memory_get.md protocol skill 定义 recall 方法"], + ["action", "memory_get.md 将当前 Reality 映射成有界 recall"], ["boundary", "GUIDE.md 不需要知道长期记忆细节"] ] }, nudge: { title: "Nudge / Accumulate", tag: "hook + protocol", - summary: "Nudge 只触发写记忆判断；如果需要积累，HostAgent 加载 memory_set.md protocol skill，并按 MNEMON_MEMORY_LOOP_DIR 定位 MEMORY.md。", + summary: "Nudge 观察新产生的 Reality，并触发写记忆判断；如果值得保留，memory_set.md 把它 reconcile 进 hot State。", short: "GUIDE -> memory_set.md -> $DIR/MEMORY.md", events: [ { kind: "arrow", from: "guide", to: "host", y: 82, label: "是否写记忆？" }, @@ -866,14 +865,14 @@

], details: [ ["trigger", "Nudge hook"], - ["action", "memory_set.md protocol skill 定义 MEMORY.md 编辑规则"], + ["action", "memory_set.md 将有用 Reality 写入 MEMORY.md"], ["boundary", "在线积累不直接写 Mnemon"] ] }, compact: { title: "Compact", tag: "hook + protocol", - summary: "Compact 与 Nudge 共享 memory_set.md，只是触发点在上下文压缩边界前，用来保存即将丢失的重要信息。", + summary: "Compact 是上下文压缩前的 reconcile boundary：复用 memory_set.md，把即将丢失但仍有价值的 Reality 写入 hot State。", short: "pre-compact -> memory_set.md -> $DIR/MEMORY.md", events: [ { kind: "arrow", from: "guide", to: "host", y: 82, label: "压缩前是否保存？" }, @@ -890,7 +889,7 @@

dreaming: { title: "Dreaming", tag: "spawned subagent", - summary: "Dreaming 是专用维护 subagent。每次触发时通过 MNEMON_MEMORY_LOOP_DIR 读取完整 MEMORY.md，按规则写入 Mnemon，并整理工作记忆。", + summary: "Dreaming 是维护型 reconciler。它读取完整 hot State，筛选 durable Reality 写入 Mnemon cold State，并整理工作记忆。", short: "subagent -> Mnemon + MEMORY.md compact", events: [ { kind: "arrow", from: "host", to: "capability", y: 78, label: "启动 dreaming subagent" }, @@ -901,45 +900,44 @@

], details: [ ["trigger", "MEMORY.md 超长、compact 前、主动要求"], - ["action", "启动专用 dreaming subagent"], + ["action", "把 hot State 巩固到 cold State，并压缩 working memory"], ["boundary", "负责巩固和清理，不参与每次在线读写判断"] ] } }, matrixRows: [ ["Host runtime", "HostAgent", "运行任务，接收 hook，决定是否加载 protocol skill 或 subagent。", "不拥有记忆存储协议，只执行被安装的能力。", "var(--host)"], - ["Host-facing surface", "MEMORY.md", "作为 hot working memory 直接进入 system prompt。", "模型友好但昂贵；由 memory_set.md 和 dreaming subagent 维护。", "var(--working)"], - ["Canonical store", "Mnemon", "作为 cold long-term memory store 提供 recall 和 write。", "系统友好、容量更大；由 mnemon binary + store 承载。", "var(--longterm)"], + ["Hot State", "MEMORY.md", "作为 hot working memory 直接进入 system prompt。", "模型友好但昂贵；由 memory_set.md 和 dreaming subagent 维护。", "var(--working)"], + ["Cold State", "Mnemon", "作为 cold long-term memory store 提供 recall 和 write。", "系统友好、容量更大；由 mnemon binary + store 承载。", "var(--longterm)"], ["Memory pattern", "hot <-> cold contract", "协调 LLM-native 热记忆与 system-native 冷记忆。", "MEMORY.md 和 Mnemon 是第一组选择，不是唯一选择。", "var(--capability)"], ["Retrieval tools", "web/docs/code/RAG search", "查询外部知识源，补充当前任务资料。", "默认不是 memory；只有内化为持久状态后才写入记忆。", "var(--host)"], - ["GUIDE", "GUIDE.md", "说明何时读写记忆、什么值得保留。", "只定义 policy，不绑定存储目标。", "var(--guide)"], + ["Intent policy", "GUIDE.md", "说明何时读写记忆、什么值得保留。", "只定义 policy，不绑定存储目标。", "var(--guide)"], ["setup", "harness/setup + env.sh", "安装四个 hook、两个 protocol skills、dreaming subagent、memory 文件和环境变量。", "只负责挂载，并设置 MNEMON_MEMORY_LOOP_DIR。", "var(--guide)"], ["hook", "prime/remind/nudge/compact", "提供宿主生命周期触发点。", "只给时机和短提醒，不承载记忆协议。", "var(--hook)"], - ["protocol", "memory_get.md / memory_set.md", "提供读长期记忆和写工作记忆的在线方法。", "绑定 Mnemon recall 与 MEMORY.md 编辑规则。", "var(--capability)"], - ["subagent", "dreaming", "维护、巩固和清理工作记忆。", "绑定 Mnemon write 与 MEMORY.md compact / eviction。", "var(--capability)"] + ["reconcile protocol", "memory_get.md / memory_set.md", "提供读长期记忆和写工作记忆的在线方法。", "绑定 Mnemon recall 与 MEMORY.md 编辑规则。", "var(--capability)"], + ["maintenance reconciler", "dreaming", "维护、巩固和清理工作记忆。", "绑定 Mnemon write 与 MEMORY.md compact / eviction。", "var(--capability)"] ] }, en: { langAttr: "en", title: "Memory Loop MVP", eyebrow: "Mnemon Harness / Memory Loop", - summary: "The first version implements one focused memory loop: MEMORY.md is model-friendly hot memory, Mnemon is system-friendly cold memory, and GUIDE/hooks/protocols/dreaming manage read, accumulation, and consolidation between them.", + summary: "memory-loop is the first complete proof of the lifecycle control plane: Mnemon keeps memory State, declares continuity Intent across lifecycle boundaries, observes HostAgent Reality, and Reconciles by reading, writing, compacting, consolidating, or no-oping.", readingTitle: "Reading Order", reading: [ - "Start with the three core parts: HostAgent, MEMORY.md, and Mnemon.", - "Then read the five harness concepts: GUIDE, setup, hook, protocol, and subagent.", - "Finally switch phases to see how each hook delegates to a skill or subagent." + "Start with how memory-loop maps to State / Intent / Reality / Reconcile.", + "Then read how hot memory, cold memory, and execution surfaces cooperate.", + "Finally switch phases to see how each lifecycle boundary triggers read, write, or consolidation." ], controlTitle: "Lifecycle Control Position", - controlIntro: "memory-loop is one LoopModule in the lifecycle control plane. It is declared, bound to a host, projected by a HostAdapter, and observed through status so the next reconcile can repair drift.", - controlFeedback: "Status feeds the next Reconcile; durable memory state remains in .mnemon, not in the host projection directory.", + controlIntro: "memory-loop is not an external memory service. It is a lifecycle-native capability that puts hot memory, cold memory, hooks, protocols, and dreaming inside one control loop.", + controlFeedback: "Memory status and durable state feed the next lifecycle pass.", controlSteps: [ - { name: "LoopModule", color: "var(--working)", text: "memory-loop declares GUIDE, hooks, memory_get, memory_set, dreaming, and the MEMORY.md state contract." }, - { name: "HostBinding", color: "var(--guide)", text: "Declares that memory-loop should bind to Codex, Claude Code, or another host with specific lifecycle surfaces." }, - { name: "Reconcile", color: "var(--capability)", text: "Checks whether projection is missing, stale, or drifted, then decides whether host-visible assets need repair." }, - { name: "HostAdapter", color: "var(--host)", text: "Renders the same memory-loop into host-native skills, hooks, env files, and runtime pointers." }, - { name: "Projection", color: "var(--hook)", text: "The HostAgent consumes generated skills, hooks, instructions, and env files under .codex or .claude." }, - { name: "Status", color: "var(--longterm)", text: "Records projection condition, manifests, and canonical runtime state under .mnemon/harness/memory-loop." } + { name: "State", color: "var(--longterm)", text: ".mnemon keeps MEMORY.md, Mnemon stores, reports, manifests, and memory-loop status." }, + { name: "Intent", color: "var(--guide)", text: "Memory should help the HostAgent preserve continuity across Prime, Remind, Nudge, Compact, and maintenance." }, + { name: "Projection", color: "var(--hook)", text: "GUIDE, hooks, memory_get, memory_set, dreaming, and env are projected as host-readable surfaces." }, + { name: "Reality", color: "var(--host)", text: "The host prompt, current task, context pressure, recall/write outcomes, and stale working memory form observed reality." }, + { name: "Reconcile", color: "var(--capability)", text: "Decide whether to read, write, compact, consolidate, or no-op, then write outcomes back into State." } ], componentsTitle: "System Components", componentsIntro: "This keeps the three core runtime parts stable, then describes installation, timing, protocol execution, and background maintenance through one shared harness vocabulary.", @@ -989,7 +987,7 @@

prime: { title: "Prime", tag: "hook", - summary: "Prime is the only direct loading path: it injects MEMORY.md and GUIDE.md into the HostAgent system prompt.", + summary: "Prime is the only direct loading path: it projects hot State (MEMORY.md) and Intent policy (GUIDE.md) into the HostAgent system prompt.", short: "MEMORY.md + GUIDE.md -> prompt", events: [ { kind: "arrow", from: "working", to: "host", y: 96, label: "MEMORY.md content" }, @@ -998,14 +996,14 @@

], details: [ ["input", "MEMORY.md + GUIDE.md"], - ["action", "Inject both into the system prompt"], + ["action", "Project hot State and Intent policy into the prompt"], ["boundary", "Does not call memory_get or trigger Mnemon recall"] ] }, recall: { title: "Remind / Recall", tag: "hook + protocol", - summary: "Remind only prompts the read-memory decision. If recall is needed, the HostAgent loads the memory_get.md protocol skill and follows its Mnemon protocol.", + summary: "Remind observes current task Reality and prompts the read-memory decision. If recall is needed, memory_get.md pages cold State into context.", short: "GUIDE -> memory_get.md -> Mnemon", events: [ { kind: "arrow", from: "guide", to: "host", y: 82, label: "read memory?" }, @@ -1015,14 +1013,14 @@

], details: [ ["trigger", "Remind hook"], - ["action", "memory_get.md protocol skill defines the recall method"], + ["action", "memory_get.md maps current Reality into bounded recall"], ["boundary", "GUIDE.md does not need long-term storage details"] ] }, nudge: { title: "Nudge / Accumulate", tag: "hook + protocol", - summary: "Nudge only prompts the write-memory decision. If accumulation is needed, the HostAgent loads the memory_set.md protocol skill and locates MEMORY.md through MNEMON_MEMORY_LOOP_DIR.", + summary: "Nudge observes newly produced Reality and prompts the write-memory decision. If it is worth keeping, memory_set.md reconciles it into hot State.", short: "GUIDE -> memory_set.md -> $DIR/MEMORY.md", events: [ { kind: "arrow", from: "guide", to: "host", y: 82, label: "write memory?" }, @@ -1032,14 +1030,14 @@

], details: [ ["trigger", "Nudge hook"], - ["action", "memory_set.md protocol skill defines MEMORY.md editing rules"], + ["action", "memory_set.md writes useful Reality into MEMORY.md"], ["boundary", "Online accumulation does not write Mnemon directly"] ] }, compact: { title: "Compact", tag: "hook + protocol", - summary: "Compact shares memory_set.md with Nudge, but it runs before context compaction to preserve important information that may be lost.", + summary: "Compact is the pre-compaction reconcile boundary: it reuses memory_set.md to write valuable soon-to-be-lost Reality into hot State.", short: "pre-compact -> memory_set.md -> $DIR/MEMORY.md", events: [ { kind: "arrow", from: "guide", to: "host", y: 82, label: "save before compact?" }, @@ -1056,7 +1054,7 @@

dreaming: { title: "Dreaming", tag: "spawned subagent", - summary: "Dreaming is a dedicated maintenance subagent. On each trigger it reads the full MEMORY.md through MNEMON_MEMORY_LOOP_DIR, writes durable material to Mnemon, then compacts working memory.", + summary: "Dreaming is the maintenance reconciler. It reads full hot State, writes durable Reality into Mnemon cold State, then compacts working memory.", short: "subagent -> Mnemon + MEMORY.md compact", events: [ { kind: "arrow", from: "host", to: "capability", y: 78, label: "spawn dreaming subagent" }, @@ -1067,22 +1065,22 @@

], details: [ ["trigger", "MEMORY.md quota, pre-compact, or explicit request"], - ["action", "Spawn the dedicated dreaming subagent"], + ["action", "Consolidate hot State into cold State and compact working memory"], ["boundary", "Handles consolidation and cleanup, not online read/write decisions"] ] } }, matrixRows: [ ["Host runtime", "HostAgent", "Runs tasks, receives hooks, and decides whether to load a protocol skill or subagent.", "Does not own memory storage protocols.", "var(--host)"], - ["Host-facing surface", "MEMORY.md", "Enters the system prompt as hot working memory.", "Model-friendly but expensive; maintained by memory_set.md and dreaming.", "var(--working)"], - ["Canonical store", "Mnemon", "Provides recall and write for cold long-term memory.", "System-friendly with larger capacity; backed by the mnemon binary and store.", "var(--longterm)"], + ["Hot State", "MEMORY.md", "Enters the system prompt as hot working memory.", "Model-friendly but expensive; maintained by memory_set.md and dreaming.", "var(--working)"], + ["Cold State", "Mnemon", "Provides recall and write for cold long-term memory.", "System-friendly with larger capacity; backed by the mnemon binary and store.", "var(--longterm)"], ["Memory pattern", "hot <-> cold contract", "Coordinates LLM-native hot memory with system-native cold memory.", "MEMORY.md and Mnemon are first choices, not the only choices.", "var(--capability)"], ["Retrieval tools", "web/docs/code/RAG search", "Queries external knowledge sources for the current task.", "Not memory by default; write only internalized durable state into memory.", "var(--host)"], - ["GUIDE", "GUIDE.md", "Explains when to read or write memory and what is worth keeping.", "Defines policy only, not storage targets.", "var(--guide)"], + ["Intent policy", "GUIDE.md", "Explains when to read or write memory and what is worth keeping.", "Defines policy only, not storage targets.", "var(--guide)"], ["setup", "harness/setup + env.sh", "Installs four hooks, two protocol skills, the dreaming subagent, memory files, and environment variables.", "Mounts assets and sets MNEMON_MEMORY_LOOP_DIR.", "var(--guide)"], ["hook", "prime/remind/nudge/compact", "Provides host lifecycle trigger points.", "Provides timing and short reminders only, not memory protocols.", "var(--hook)"], - ["protocol", "memory_get.md / memory_set.md", "Provides the online methods for long-term recall and working-memory writes.", "Binds Mnemon recall and MEMORY.md editing rules.", "var(--capability)"], - ["subagent", "dreaming", "Maintains, consolidates, and cleans working memory.", "Binds Mnemon write with MEMORY.md compaction and eviction.", "var(--capability)"] + ["reconcile protocol", "memory_get.md / memory_set.md", "Provides the online methods for long-term recall and working-memory writes.", "Binds Mnemon recall and MEMORY.md editing rules.", "var(--capability)"], + ["maintenance reconciler", "dreaming", "Maintains, consolidates, and cleans working memory.", "Binds Mnemon write with MEMORY.md compaction and eviction.", "var(--capability)"] ] } }; diff --git a/docs/site/skill-loop/index.html b/docs/site/skill-loop/index.html index ee42d19..d16ea07 100644 --- a/docs/site/skill-loop/index.html +++ b/docs/site/skill-loop/index.html @@ -316,7 +316,7 @@ .control-path-grid { display: grid; - grid-template-columns: repeat(6, minmax(0, 1fr)); + grid-template-columns: repeat(5, minmax(0, 1fr)); gap: 1px; background: var(--line); } @@ -773,23 +773,22 @@

langAttr: "zh-CN", title: "Skill Loop MVP", eyebrow: "Mnemon Harness / Skill Loop", - summary: "第一版 skill loop 与 memory loop 使用同一套 harness 概念：GUIDE 写 policy，setup 负责安装和挂载，hook 仍按 Prime/Remind/Nudge/Compact 理解，protocol skills 记录和迁移 skill state，curator subagent 做后台审阅与提案。", + summary: "skill-loop 把 skill visibility 和 skill lifecycle state 做成 lifecycle-native capability：Mnemon 保存 skill State，声明可见性 Intent，观察 HostAgent 的 skill Reality，并通过 Reconcile 执行 observe、curate、propose、manage 或 no-op。", readingTitle: "阅读顺序", reading: [ - "先看三大核心：HostAgent、Host Skill Surface、Skill Library。", - "再看五类支撑概念：GUIDE、setup、hook、protocol、subagent。", - "最后切换阶段，看 Prime、Nudge、Observe、Curator、Manage 如何闭合成 loop。" + "先看 skill-loop 如何映射 State、Intent、Projection、Reality、Reconcile。", + "再看 host skill surface 与 `.mnemon` canonical library 如何分工。", + "最后切换阶段，看 Prime、Nudge、Observe、Curator、Manage 如何形成闭环。" ], controlTitle: "生命周期控制位置", - controlIntro: "skill-loop 在整体控制平面里是一个 LoopModule。它声明 skill lifecycle policy，并通过 host adapter 把 active skill 集合投影到宿主原生 skill surface。", - controlFeedback: "Status 反馈到下一次 Reconcile；canonical skill state 保留在 .mnemon，宿主 skill surface 只是 projection。", + controlIntro: "skill-loop 不替换宿主的 skill runtime。它把可见性、证据和迁移状态纳入同一条生命周期主干：保存状态，声明意图，投影给宿主，观察现实，再对齐差距。", + controlFeedback: "Reconcile 的结果写回 State；canonical skill state 保留在 .mnemon，宿主 skill surface 只是 active skill 的 projection。", controlSteps: [ - { name: "LoopModule", color: "var(--library)", text: "skill-loop 声明 GUIDE、hooks、skill_observe、skill_curate、skill_manage 和 curator。" }, - { name: "HostBinding", color: "var(--guide)", text: "声明 skill-loop 绑定到哪个 host，以及 active skills 应投影到哪个 host skill surface。" }, - { name: "Reconcile", color: "var(--protocol)", text: "检查 active skill projection 是否缺失、过期、漂移，或与 host capability 不兼容。" }, - { name: "HostAdapter", color: "var(--host)", text: "把 .mnemon/skills/active 渲染、同步或挂载到 .codex、.claude 或其他 host surface。" }, - { name: "Projection", color: "var(--active)", text: "HostAgent 使用生成的 host-native skill files；stale 和 archived 默认不进入这个 surface。" }, - { name: "Status", color: "var(--curator)", text: "记录 projection 状态、usage evidence、proposal/report，并反馈给下一次维护和 reconcile。" } + { name: "State", color: "var(--library)", text: "`.mnemon` skill library 保存 active/stale/archived、usage evidence、proposal、report 和 skill-loop status。" }, + { name: "Intent", color: "var(--guide)", text: "当前应该可见的 skill 集合，以及 stale/archived 应如何保留、审阅、恢复或隔离。" }, + { name: "Projection", color: "var(--active)", text: "Prime 把 active skills 同步、挂载或渲染到 `.codex/skills`、`.claude/skills` 等 host-native surface。" }, + { name: "Reality", color: "var(--host)", text: "HostAgent 实际发现和使用了哪些 skill，哪些缺失、误导、过期，哪些流程重复出现。" }, + { name: "Reconcile", color: "var(--protocol)", text: "根据 Reality 决定 observe、curate、propose、manage 或 no-op，并把结果写回 State。" } ], componentsTitle: "System Components", componentsIntro: "Skill loop 的核心不是冷热存储，而是可见性治理：哪些 skill 当前可被发现，哪些进入维护，哪些仅保留历史。", @@ -844,7 +843,7 @@

prime: { title: "Prime", tag: "hook", - summary: "Prime 不把所有 skill 内容注入 prompt。它负责把 `.mnemon/skills/active` 单向同步或挂载到 HostAgent 的原生 skill 发现面，让 HostAgent 自己完成 skill discovery。", + summary: "Prime 是 skill-loop 的 Projection 边界。它不把所有 skill 内容注入 prompt，而是把 canonical State 中的 active 集合投影到 HostAgent 原生 skill 发现面。", short: "active skills -> host surface", events: [ { kind: "arrow", from: "library", to: "surface", y: 94, label: "sync active skills" }, @@ -852,7 +851,7 @@

{ kind: "action", actor: "host", y: 210, label: "discover skills natively" } ], details: [ - ["input", "GUIDE + `.mnemon/skills/active` + setup bindings"], + ["input", "Intent policy + `.mnemon/skills/active` + setup bindings"], ["action", "Prime hook 同步、挂载或生成 host-native skill files"], ["boundary", "`.mnemon` 是 source of truth；host-native 目录是 generated view"] ] @@ -860,7 +859,7 @@

nudge: { title: "Nudge", tag: "hook", - summary: "Nudge 是 agent loop stop 阶段的一句 hook prompt。它不写规则，只提醒 LLM 按 GUIDE 判断本轮是否产生 skill usage evidence 或 reusable workflow signal；如果有，应加载 skill_observe。", + summary: "Nudge 是 Reality 观察边界。它不写规则，只提醒 HostAgent 按 Intent policy 判断本轮是否产生 skill usage evidence 或 reusable workflow signal；如果有，应加载 skill_observe。", short: "stop hook -> skill_observe", events: [ { kind: "arrow", from: "surface", to: "host", y: 74, label: "native skill use outside harness" }, @@ -870,14 +869,14 @@

], details: [ ["trigger", "agent loop stop 阶段的 Nudge hook"], - ["action", "只提醒 LLM 按 GUIDE 判断是否需要记录 skill signal"], + ["action", "只提醒 HostAgent 按 Intent policy 判断是否需要记录 skill signal"], ["boundary", "Nudge 不写 sidecar、不生成 skill、不做 review"] ] }, observe: { title: "skill_observe", tag: "protocol", - summary: "skill_observe 是在线轻量能力。它按照 GUIDE 和协议，把 skill view/use/patch evidence 或 reusable workflow signal 写入 usage sidecar 或 signal report。", + summary: "skill_observe 是在线轻量 Reconcile。它把本轮观察到的 skill view/use/patch evidence 或 reusable workflow signal 写入 State，但不决定生命周期迁移。", short: "write usage / signal", events: [ { kind: "arrow", from: "host", to: "protocol", y: 78, label: "load skill_observe.md" }, @@ -894,7 +893,7 @@

curate: { title: "Curator", tag: "subagent", - summary: "Curator 是后台或手动维护入口。它读取 usage sidecar、signal reports 和 skill library，拉起 curator subagent 检查是否应 patch、consolidate、create、stale 或 archive，并默认生成 proposal/report。", + summary: "Curator 是低频维护 reconciler。它读取 evidence 与 skill library，检查是否应 patch、consolidate、create、stale 或 archive，并默认生成 proposal/report。", short: "evidence -> proposal", events: [ { kind: "arrow", from: "host", to: "protocol", y: 78, label: "load skill_curate.md" }, @@ -912,7 +911,7 @@

manage: { title: "skill_manage", tag: "protocol", - summary: "被批准的迁移由 skill_manage 执行：patch、consolidate、active -> stale、stale -> archived、restore。它只改 `.mnemon` canonical state，不直接刷新 HostAgent；新的可见 skill 集合会在下一次 Prime 同步到 host skill surface。", + summary: "skill_manage 执行已批准的生命周期迁移：patch、consolidate、active -> stale、stale -> archived、restore。它只改 `.mnemon` State；新的可见集合由下一次 Prime 投影到 HostAgent。", short: "skill_manage -> next Prime", events: [ { kind: "arrow", from: "curator", to: "protocol", y: 76, label: "approved proposal" }, @@ -930,36 +929,35 @@

}, matrixRows: [ ["Host runtime", "HostAgent", "运行 ReAct loop，接收 hook，决定是否加载 protocol skill 或 curator subagent。", "不拥有 canonical skill state。", "var(--host)"], - ["Host-facing surface", "Host Skill Surface", "HostAgent 原生 skill discovery 读取的位置。", "由 Prime 从 `.mnemon/skills/active` 单向同步或挂载生成。", "var(--active)"], - ["Canonical store", ".mnemon Skill Library", "保存 active/stale/archived skills 和 `.usage.json`。", "canonical source of truth，host-native 目录只是 generated view。", "var(--library)"], - ["GUIDE", "GUIDE", "定义 skill evidence、review trigger、protected/pinned、proposal-first 等判断规则。", "只定义 policy，不执行迁移。", "var(--guide)"], + ["Projection surface", "Host Skill Surface", "HostAgent 原生 skill discovery 读取的位置。", "由 Prime 从 `.mnemon/skills/active` 单向同步或挂载生成。", "var(--active)"], + ["Skill State", ".mnemon Skill Library", "保存 active/stale/archived skills、usage evidence、proposal 和 report。", "canonical source of truth，host-native 目录只是 generated view。", "var(--library)"], + ["Intent policy", "GUIDE", "定义 skill evidence、review trigger、protected/pinned、proposal-first 等判断规则。", "只定义 policy，不执行迁移。", "var(--guide)"], ["setup", "setup + bindings", "安装 hooks、protocol skills、curator subagent，并配置 host-native skill surface binding。", "只负责挂载，不参与每次 runtime 判断。", "var(--setup)"], ["hook", "prime/remind/nudge/compact", "提供同步、观察提醒和低频 review 触发边界；Remind 通常 no-op。", "只给时机和短提醒，规则在 GUIDE 中。", "var(--hook)"], - ["protocol", "skill_observe / skill_manage / skill_curate", "定义 observe/manage/curate 的跨 HostAgent 操作方法。", "通过 `MNEMON_HARNESS_DIR` 定位 `.mnemon`。", "var(--protocol)"], - ["subagent", "curator", "低频审阅、合并、迁移和报告。", "默认 proposal-first；批准后由 skill_manage 修改状态。", "var(--curator)"] + ["Reconcile protocol", "skill_observe / skill_manage / skill_curate", "定义 observe/manage/curate 的跨 HostAgent 操作方法。", "通过 `MNEMON_HARNESS_DIR` 定位 `.mnemon`。", "var(--protocol)"], + ["Maintenance reconciler", "curator", "低频审阅、合并、迁移和报告。", "默认 proposal-first；批准后由 skill_manage 修改状态。", "var(--curator)"] ] }, en: { langAttr: "en", title: "Skill Loop MVP", eyebrow: "Mnemon Harness / Skill Loop", - summary: "The first skill loop uses the same harness vocabulary as the memory loop: GUIDE holds policy, setup installs and mounts assets, hooks provide Prime/Remind/Nudge/Compact timing, protocol skills record and migrate skill state, and the curator subagent performs background review and proposals.", + summary: "skill-loop turns skill visibility and skill lifecycle state into a lifecycle-native capability: Mnemon keeps skill State, declares visibility Intent, observes HostAgent skill Reality, and Reconciles by observing, curating, proposing, managing, or no-oping.", readingTitle: "Reading Order", reading: [ - "Start with the three core parts: HostAgent, Host Skill Surface, and Skill Library.", - "Then read the five harness concepts: GUIDE, setup, hook, protocol, and subagent.", + "Start with how skill-loop maps to State, Intent, Projection, Reality, and Reconcile.", + "Then read how the host skill surface and `.mnemon` canonical library divide responsibility.", "Finally switch phases to see how Prime, Nudge, Observe, Curator, and Manage close the loop." ], controlTitle: "Lifecycle Control Position", - controlIntro: "skill-loop is one LoopModule in the lifecycle control plane. It declares skill lifecycle policy and uses host adapters to project the active skill set into the host-native skill surface.", - controlFeedback: "Status feeds the next Reconcile; canonical skill state remains in .mnemon, while the host skill surface is only a projection.", + controlIntro: "skill-loop does not replace the host skill runtime. It puts visibility, evidence, and migration state on one lifecycle path: keep state, declare intent, project into the host, observe reality, and reconcile the gap.", + controlFeedback: "Reconcile writes results back into State; canonical skill state remains in .mnemon, while the host skill surface is only the active-skill projection.", controlSteps: [ - { name: "LoopModule", color: "var(--library)", text: "skill-loop declares GUIDE, hooks, skill_observe, skill_curate, skill_manage, and the curator." }, - { name: "HostBinding", color: "var(--guide)", text: "Declares which host receives skill-loop and which host skill surface should receive active skills." }, - { name: "Reconcile", color: "var(--protocol)", text: "Checks whether active skill projection is missing, stale, drifted, or incompatible with host capabilities." }, - { name: "HostAdapter", color: "var(--host)", text: "Renders, syncs, or mounts .mnemon/skills/active into .codex, .claude, or another host surface." }, - { name: "Projection", color: "var(--active)", text: "The HostAgent uses generated host-native skill files; stale and archived skills stay out by default." }, - { name: "Status", color: "var(--curator)", text: "Records projection status, usage evidence, proposals, and reports for maintenance and the next reconcile." } + { name: "State", color: "var(--library)", text: "The `.mnemon` skill library stores active/stale/archived skills, usage evidence, proposals, reports, and skill-loop status." }, + { name: "Intent", color: "var(--guide)", text: "The skills that should be visible now, plus how stale and archived skills should be preserved, reviewed, restored, or isolated." }, + { name: "Projection", color: "var(--active)", text: "Prime syncs, mounts, or renders active skills into host-native surfaces such as `.codex/skills` or `.claude/skills`." }, + { name: "Reality", color: "var(--host)", text: "What the HostAgent actually discovered and used, what was missing or misleading, and which workflows repeated." }, + { name: "Reconcile", color: "var(--protocol)", text: "Decides observe, curate, propose, manage, or no-op from Reality, then writes the result back into State." } ], componentsTitle: "System Components", componentsIntro: "The skill loop is not a hot/cold storage split. It governs visibility: which skills are discoverable now, which need maintenance, and which remain historical.", @@ -1014,7 +1012,7 @@

prime: { title: "Prime", tag: "hook", - summary: "Prime does not inject every skill body into the prompt. It syncs or mounts `.mnemon/skills/active` into the host-native discovery surface so the HostAgent can discover skills natively.", + summary: "Prime is the skill-loop Projection boundary. It does not inject every skill body into the prompt; it projects the active set from canonical State into the host-native discovery surface.", short: "active skills -> host surface", events: [ { kind: "arrow", from: "library", to: "surface", y: 94, label: "sync active skills" }, @@ -1022,7 +1020,7 @@

{ kind: "action", actor: "host", y: 210, label: "discover skills natively" } ], details: [ - ["input", "GUIDE + `.mnemon/skills/active` + setup bindings"], + ["input", "Intent policy + `.mnemon/skills/active` + setup bindings"], ["action", "Prime hook syncs, mounts, or generates host-native skill files"], ["boundary", "`.mnemon` is the source of truth; host-native directories are generated views"] ] @@ -1030,7 +1028,7 @@

nudge: { title: "Nudge", tag: "hook", - summary: "Nudge is a one-line hook prompt at the agent-loop stop boundary. It does not carry rules; it asks the model to follow GUIDE and decide whether this turn produced skill evidence or a reusable workflow signal.", + summary: "Nudge is a Reality observation boundary. It does not carry rules; it asks the HostAgent to follow Intent policy and decide whether this turn produced skill evidence or a reusable workflow signal.", short: "stop hook -> skill_observe", events: [ { kind: "arrow", from: "surface", to: "host", y: 74, label: "native skill use outside harness" }, @@ -1040,14 +1038,14 @@

], details: [ ["trigger", "Nudge hook at the agent-loop stop boundary"], - ["action", "Only reminds the model to follow GUIDE and decide whether to record a skill signal"], + ["action", "Only reminds the HostAgent to follow Intent policy and decide whether to record a skill signal"], ["boundary", "Nudge does not write sidecars, generate skills, or run review"] ] }, observe: { title: "skill_observe", tag: "protocol", - summary: "skill_observe is the lightweight online protocol. It writes skill view/use/patch evidence or reusable workflow signals into the usage sidecar or signal report.", + summary: "skill_observe is the lightweight online Reconcile path. It writes observed skill view/use/patch evidence or reusable workflow signals into State, without deciding lifecycle migration.", short: "write usage / signal", events: [ { kind: "arrow", from: "host", to: "protocol", y: 78, label: "load skill_observe.md" }, @@ -1064,7 +1062,7 @@

curate: { title: "Curator", tag: "subagent", - summary: "Curator is the background or manual maintenance entry point. It reads usage sidecars, signal reports, and the skill library, then reviews whether to patch, consolidate, create, stale, or archive.", + summary: "Curator is the low-frequency maintenance reconciler. It reads evidence and the skill library, then reviews whether to patch, consolidate, create, stale, or archive.", short: "evidence -> proposal", events: [ { kind: "arrow", from: "host", to: "protocol", y: 78, label: "load skill_curate.md" }, @@ -1082,7 +1080,7 @@

manage: { title: "skill_manage", tag: "protocol", - summary: "Approved migrations are applied by skill_manage: patch, consolidate, active -> stale, stale -> archived, or restore. It changes only `.mnemon` canonical state; new visibility appears after the next Prime sync.", + summary: "skill_manage applies approved lifecycle migrations: patch, consolidate, active -> stale, stale -> archived, or restore. It changes only `.mnemon` State; new visibility appears after the next Prime projection.", short: "skill_manage -> next Prime", events: [ { kind: "arrow", from: "curator", to: "protocol", y: 76, label: "approved proposal" }, @@ -1100,13 +1098,13 @@

}, matrixRows: [ ["Host runtime", "HostAgent", "Runs the ReAct loop, receives hooks, and decides whether to load protocol skills or the curator subagent.", "Does not own canonical skill state.", "var(--host)"], - ["Host-facing surface", "Host Skill Surface", "The location read by host-native skill discovery.", "Generated or mounted by Prime from `.mnemon/skills/active`.", "var(--active)"], - ["Canonical store", ".mnemon Skill Library", "Stores active/stale/archived skills and `.usage.json`.", "Canonical source of truth; host-native directories are generated views.", "var(--library)"], - ["GUIDE", "GUIDE", "Defines skill evidence, review triggers, protected/pinned rules, and proposal-first policy.", "Defines policy only; it does not migrate state.", "var(--guide)"], + ["Projection surface", "Host Skill Surface", "The location read by host-native skill discovery.", "Generated or mounted by Prime from `.mnemon/skills/active`.", "var(--active)"], + ["Skill State", ".mnemon Skill Library", "Stores active/stale/archived skills, usage evidence, proposals, and reports.", "Canonical source of truth; host-native directories are generated views.", "var(--library)"], + ["Intent policy", "GUIDE", "Defines skill evidence, review triggers, protected/pinned rules, and proposal-first policy.", "Defines policy only; it does not migrate state.", "var(--guide)"], ["setup", "setup + bindings", "Installs hooks, protocol skills, curator subagent, and host-native skill surface bindings.", "Mounts assets only; it does not participate in each runtime decision.", "var(--setup)"], ["hook", "prime/remind/nudge/compact", "Provides sync, observation reminders, and low-frequency review trigger boundaries; Remind is usually a no-op.", "Provides timing and short reminders only; rules live in GUIDE.", "var(--hook)"], - ["protocol", "skill_observe / skill_manage / skill_curate", "Defines cross-HostAgent methods for observe, manage, and curate.", "Locates `.mnemon` through `MNEMON_HARNESS_DIR`.", "var(--protocol)"], - ["subagent", "curator", "Performs low-frequency review, consolidation, migration, and reports.", "Proposal-first by default; approved changes are applied by skill_manage.", "var(--curator)"] + ["Reconcile protocol", "skill_observe / skill_manage / skill_curate", "Defines cross-HostAgent methods for observe, manage, and curate.", "Locates `.mnemon` through `MNEMON_HARNESS_DIR`.", "var(--protocol)"], + ["Maintenance reconciler", "curator", "Performs low-frequency review, consolidation, migration, and reports.", "Proposal-first by default; approved changes are applied by skill_manage.", "var(--curator)"] ] } }; diff --git a/docs/zh/harness/memory-loop/DESIGN.md b/docs/zh/harness/memory-loop/DESIGN.md index 0c0afc5..eb9fcb6 100644 --- a/docs/zh/harness/memory-loop/DESIGN.md +++ b/docs/zh/harness/memory-loop/DESIGN.md @@ -10,26 +10,46 @@ Memory loop 是 self-evolution harness 的第一个可落地切片。它给 Host ## 生命周期控制平面位置 -在生命周期控制平面里，`memory-loop` 是一个 `LoopModule`。它声明可迁移的记忆 -policy、lifecycle prompts、protocol skills、dreaming subagent 和 runtime state -contract。 +在生命周期控制平面里，`memory-loop` 是第一个实际证明：外部能力可以变成 +lifecycle-native capability，而不需要让 Mnemon 变成宿主 agent runtime。 -这个 loop 通过 host binding 进入宿主： +按照统一控制模型： + +| Layer | Memory-loop 形态 | +| --- | --- | +| State | `.mnemon` 下的 `MEMORY.md`、Mnemon long-term stores、reports、manifests 和 memory-loop status。 | +| Intent | 让有用的 agent、user、project continuity 能跨 lifecycle boundaries 保持可用。 | +| Reality | host prompt、当前任务、working-memory 内容、recall 结果、context pressure 和 consolidation 状态。 | +| Reconcile | 判断是否 read、write、compact、consolidate 或 no-op，并写回 status 或 durable state。 | + +实体 profile 保持轻量： + +| Entity | Profile | 作用 | +| --- | --- | --- | +| `memory-loop` | Template | 可复用 lifecycle capability package。 | +| memory binding | Controlled | 将 memory 行为绑定到 Prime、Remind、Nudge、Compact 和 maintenance 等宿主生命周期。 | +| hot/cold memory surfaces | Surface | `MEMORY.md`、Mnemon recall/write、host hooks 和 protocol skills。 | +| recall/write/consolidation evidence | Evidence | memory usefulness、context pressure、stale entries 和 durable write results。 | +| memory proposals or audits | Governance | 未来用于高风险 memory change 或 policy change 的可 review 记录。 | + +在这个 framing 里，`MEMORY.md` 不是模型本身，而是第一个 hot-memory surface。 +Mnemon long-term storage 也不是模型本身，而是第一个 cold-memory surface。模型是 +让有用 continuity 与 reality 持续对齐的 lifecycle loop。 + +这个 loop 通过 projection 和 observation surfaces 进入宿主： ```text -LoopModule(memory-loop) - -> HostBinding(host + lifecycle surfaces) - -> Reconcile - -> HostAdapter - -> Projection(.codex / .claude / other host surface) - -> Status - -> next Reconcile +State(.mnemon memory state) + -> Intent(memory should help this lifecycle boundary) + -> Projection(hooks, GUIDE, memory_get, memory_set, dreaming) + -> Reality(host prompt, task, context pressure, recall/write outcomes) + -> Reconcile(read, write, compact, consolidate, no-op) + -> State(MEMORY.md, Mnemon store, reports, status) ``` -HostAgent 消费 projection，并继续拥有执行。`.mnemon` 保存 memory-loop 的 -canonical state，包括 `MEMORY.md`、manifests 和持久 Mnemon stores。宿主目录是 -可重新生成的视图；当 projection status 与声明的 binding 漂移时，可以由 -reconcile 修复。 +HostAgent 消费 projection，并继续拥有执行。Mnemon 拥有 durable state、profile +model 和 reconcile boundary。宿主目录仍然是可重新生成的视图；当 projected memory +assets 与声明的 lifecycle intent 漂移时，可以由 reconcile 修复。 ## 设计目标 diff --git a/docs/zh/harness/skill-loop/DESIGN.md b/docs/zh/harness/skill-loop/DESIGN.md index 6fa50e4..b0eddf2 100644 --- a/docs/zh/harness/skill-loop/DESIGN.md +++ b/docs/zh/harness/skill-loop/DESIGN.md @@ -12,26 +12,43 @@ MVP 的边界是“可见性治理”和“生命周期治理”：哪些 skill ## 生命周期控制平面位置 -在生命周期控制平面里，`skill-loop` 是一个 `LoopModule`。它声明 skill visibility -policy、observation 和 management protocols、curator maintenance，以及 -canonical skill lifecycle state contract。 +在生命周期控制平面里，`skill-loop` 把 skill visibility 和 skill lifecycle state +变成 lifecycle-native capability，同时不替换宿主原生 skill runtime。 -这个 loop 通过 host binding 进入宿主： +按照统一控制模型： + +| Layer | Skill-loop 形态 | +| --- | --- | +| State | `.mnemon` skill library、active/stale/archived state、evidence、proposals、reports 和 skill-loop status。 | +| Intent | 让正确的 skills 对宿主可见，同时保留 stale 和 archived skills 用于 review、recovery 和 design memory。 | +| Reality | Host skill surface、实际 active projection、skill usage evidence、missing 或 misleading skills、curator findings 和 review decisions。 | +| Reconcile | 同步 active skills、记录 evidence、提出 lifecycle changes、执行已批准变更，并在 Prime 刷新宿主可见性。 | + +实体 profile 保持轻量： + +| Entity | Profile | 作用 | +| --- | --- | --- | +| `skill-loop` | Template | 可复用 lifecycle capability package。 | +| skill binding | Controlled | 将 skill visibility 和 lifecycle policy 绑定到某个 host skill surface。 | +| host skill surface | Surface | 宿主原生 discovery surface，例如 `.codex/skills` 或 `.claude/skills`。 | +| usage signals and curator findings | Evidence | skill usefulness、missing skills、stale skills 或 workflow repetition 等观测证据。 | +| proposals, reviews, audits | Governance | canonical skill lifecycle mutation 之前的可 review 变更记录。 | + +这个 loop 通过 projection 和 observation surfaces 进入宿主： ```text -LoopModule(skill-loop) - -> HostBinding(host + skill surface) - -> Reconcile - -> HostAdapter - -> Projection(.codex/skills, .claude/skills, or another host surface) - -> Status - -> next Reconcile +State(.mnemon skill library) + -> Intent(the right skills should be visible) + -> Projection(active skills into host skill surface) + -> Reality(host usage, evidence, missing or stale skills) + -> Reconcile(observe, curate, propose, manage, no-op) + -> State(active/stale/archived, reports, proposals, status) ``` HostAgent 消费被投影的 active skill surface，并继续拥有原生 skill discovery 和 -执行。`.mnemon` 保存 canonical skill library 和 evidence。宿主 skill 目录是 -可重新生成的视图；当 projection status 与声明的 binding 漂移时，可以由 -reconcile 修复。 +执行。Mnemon 拥有 canonical skill state、evidence、proposal-first governance 和 +reconcile boundary。宿主 skill 目录仍然是可重新生成的视图；当 Reality 与 Intent +漂移时，可以刷新。 ## 目标 From 22b45b521917a4dae4f5ebf99c1bac031a234d68 Mon Sep 17 00:00:00 2001 From: Grivn Date: Wed, 20 May 2026 16:55:00 +0000 Subject: [PATCH 5/6] refactor(harness): reshape lifecycle control layout Restructure the experimental harness around the lifecycle control model: loops, hosts, bindings, control contracts, and ops. This replaces module/setup naming with loop/ops naming, moves loop manifests to loop.json, and updates host projectors, validation, and Codex app-server eval wiring to use the new layout. The change is intentionally breaking because the harness layer is not yet a stable release-path API. Validation covered harness manifest checks, script syntax, site script parsing, temporary Codex and Claude Code installs, markdown link checks, and go test ./.... --- Makefile | 10 +- README.md | 6 +- docs/harness/HOST_PROJECTION.md | 66 ++-- docs/harness/LIFECYCLE_CONTROL_PLANE.md | 10 +- ...OP_MODULE_STANDARD.md => LOOP_STANDARD.md} | 95 +++-- docs/harness/README.md | 39 +- docs/harness/ROADMAP.md | 18 +- docs/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md | 36 +- docs/harness/eval/CODEX_APP_SERVER.md | 6 +- docs/harness/{eval-loop => eval}/DESIGN.md | 22 +- .../harness/{memory-loop => memory}/DESIGN.md | 16 +- docs/harness/modular-agent/DESIGN.md | 76 ++-- docs/harness/{skill-loop => skill}/DESIGN.md | 14 +- docs/site/index.html | 4 +- docs/site/lifecycle-control-plane/index.html | 28 +- docs/site/{memory-loop => memory}/index.html | 20 +- docs/site/{skill-loop => skill}/index.html | 26 +- docs/zh/README.md | 6 +- docs/zh/harness/HOST_PROJECTION.md | 65 ++-- docs/zh/harness/LIFECYCLE_CONTROL_PLANE.md | 10 +- ...OP_MODULE_STANDARD.md => LOOP_STANDARD.md} | 93 +++-- docs/zh/harness/README.md | 41 ++- docs/zh/harness/ROADMAP.md | 18 +- .../harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md | 36 +- docs/zh/harness/eval/CODEX_APP_SERVER.md | 2 +- docs/zh/harness/{eval-loop => eval}/DESIGN.md | 24 +- .../harness/{memory-loop => memory}/DESIGN.md | 16 +- docs/zh/harness/modular-agent/DESIGN.md | 68 ++-- .../harness/{skill-loop => skill}/DESIGN.md | 16 +- harness/bindings/claude-code.memory.json | 16 + harness/bindings/claude-code.skill.json | 16 + harness/bindings/codex.eval.json | 17 + harness/bindings/codex.memory.json | 16 + harness/bindings/codex.skill.json | 16 + harness/control/README.md | 24 ++ harness/control/contracts/intent.md | 12 + harness/control/contracts/observation.md | 8 + harness/control/contracts/projection.md | 8 + harness/control/contracts/reconcile.md | 13 + harness/control/contracts/state.md | 14 + harness/control/schemas/README.md | 6 + harness/eval/README.md | 16 +- harness/hosts/README.md | 8 +- harness/hosts/claude-code/host.json | 24 +- .../claude-code/memory-loop/hooks/remind.sh | 4 - .../{memory-loop => memory}/hooks/compact.sh | 8 +- .../{memory-loop => memory}/hooks/nudge.sh | 6 +- .../{memory-loop => memory}/hooks/prime.sh | 6 +- .../hosts/claude-code/memory/hooks/remind.sh | 4 + .../scripts/update_settings.py | 4 +- harness/hosts/claude-code/projector.sh | 266 +++++++------ .../claude-code/skill-loop/hooks/nudge.sh | 8 - .../claude-code/skill-loop/hooks/remind.sh | 4 - .../{skill-loop => skill}/hooks/compact.sh | 8 +- .../hosts/claude-code/skill/hooks/nudge.sh | 8 + .../{skill-loop => skill}/hooks/prime.sh | 14 +- .../hosts/claude-code/skill/hooks/remind.sh | 4 + .../scripts/update_settings.py | 4 +- harness/hosts/codex/host.json | 31 +- harness/hosts/codex/projector.sh | 348 ++++++++++-------- harness/loops/README.md | 13 + .../eval-loop => loops/eval}/GUIDE.md | 0 .../eval-loop => loops/eval}/README.md | 18 +- .../{modules/eval-loop => loops/eval}/env.sh | 0 .../eval-loop => loops/eval}/hooks/compact.md | 0 .../eval-loop => loops/eval}/hooks/nudge.md | 0 .../eval-loop => loops/eval}/hooks/prime.md | 0 .../eval-loop => loops/eval}/hooks/remind.md | 0 .../module.json => loops/eval/loop.json} | 76 +++- .../eval}/rubrics/eval-asset-quality.md | 0 .../eval}/rubrics/interface-loop-behavior.md | 0 .../scenarios/docs/bilingual-doc-sync.md | 2 +- .../memory/project-preference-recall.md | 4 +- .../scenarios/ops}/host-projection-smoke.md | 10 +- .../scenarios/skill/skill-creation-reuse.md | 4 +- .../eval}/skills/eval_analyze.md | 6 +- .../eval}/skills/eval_improve.md | 0 .../eval}/skills/eval_plan.md | 2 +- .../eval}/skills/eval_run.md | 2 +- .../eval}/subagents/evaluator.md | 2 +- .../eval}/suites/regression.json | 2 +- .../eval}/suites/smoke.json | 4 +- .../memory-loop => loops/memory}/GUIDE.md | 0 .../memory-loop => loops/memory}/MEMORY.md | 0 .../memory-loop => loops/memory}/README.md | 20 +- .../memory-loop => loops/memory}/env.sh | 0 .../memory}/hooks/compact.md | 0 .../memory}/hooks/nudge.md | 0 .../memory}/hooks/prime.md | 0 .../memory}/hooks/remind.md | 0 harness/loops/memory/loop.json | 111 ++++++ .../memory}/skills/memory_get.md | 0 .../memory}/skills/memory_set.md | 0 .../memory}/subagents/dreaming.md | 0 .../skill-loop => loops/skill}/GUIDE.md | 0 .../skill-loop => loops/skill}/README.md | 22 +- .../skill-loop => loops/skill}/env.sh | 0 .../skill}/hooks/compact.md | 0 .../skill-loop => loops/skill}/hooks/nudge.md | 0 .../skill-loop => loops/skill}/hooks/prime.md | 0 .../skill}/hooks/remind.md | 0 harness/loops/skill/loop.json | 118 ++++++ .../skill}/skills/skill_author.md | 2 +- .../skill}/skills/skill_curate.md | 0 .../skill}/skills/skill_manage.md | 0 .../skill}/skills/skill_observe.md | 0 .../skill}/subagents/curator.md | 0 harness/modules/README.md | 13 - harness/modules/memory-loop/module.json | 47 --- harness/modules/skill-loop/module.json | 50 --- harness/ops/README.md | 25 ++ harness/{setup => ops}/install.sh | 22 +- harness/{setup => ops}/lib/paths.sh | 8 +- harness/{setup => ops}/status.sh | 20 +- harness/{setup => ops}/uninstall.sh | 22 +- harness/setup/README.md | 26 -- scripts/codex_app_server_eval.py | 94 ++--- scripts/validate_harness_loops.sh | 154 ++++++++ scripts/validate_harness_modules.sh | 60 --- 119 files changed, 1712 insertions(+), 1075 deletions(-) rename docs/harness/{LOOP_MODULE_STANDARD.md => LOOP_STANDARD.md} (66%) rename docs/harness/{eval-loop => eval}/DESIGN.md (77%) rename docs/harness/{memory-loop => memory}/DESIGN.md (95%) rename docs/harness/{skill-loop => skill}/DESIGN.md (95%) rename docs/site/{memory-loop => memory}/index.html (97%) rename docs/site/{skill-loop => skill}/index.html (96%) rename docs/zh/harness/{LOOP_MODULE_STANDARD.md => LOOP_STANDARD.md} (64%) rename docs/zh/harness/{eval-loop => eval}/DESIGN.md (72%) rename docs/zh/harness/{memory-loop => memory}/DESIGN.md (94%) rename docs/zh/harness/{skill-loop => skill}/DESIGN.md (94%) create mode 100644 harness/bindings/claude-code.memory.json create mode 100644 harness/bindings/claude-code.skill.json create mode 100644 harness/bindings/codex.eval.json create mode 100644 harness/bindings/codex.memory.json create mode 100644 harness/bindings/codex.skill.json create mode 100644 harness/control/README.md create mode 100644 harness/control/contracts/intent.md create mode 100644 harness/control/contracts/observation.md create mode 100644 harness/control/contracts/projection.md create mode 100644 harness/control/contracts/reconcile.md create mode 100644 harness/control/contracts/state.md create mode 100644 harness/control/schemas/README.md delete mode 100644 harness/hosts/claude-code/memory-loop/hooks/remind.sh rename harness/hosts/claude-code/{memory-loop => memory}/hooks/compact.sh (62%) rename harness/hosts/claude-code/{memory-loop => memory}/hooks/nudge.sh (73%) rename harness/hosts/claude-code/{memory-loop => memory}/hooks/prime.sh (89%) create mode 100644 harness/hosts/claude-code/memory/hooks/remind.sh rename harness/hosts/claude-code/{memory-loop => memory}/scripts/update_settings.py (97%) delete mode 100644 harness/hosts/claude-code/skill-loop/hooks/nudge.sh delete mode 100644 harness/hosts/claude-code/skill-loop/hooks/remind.sh rename harness/hosts/claude-code/{skill-loop => skill}/hooks/compact.sh (58%) create mode 100644 harness/hosts/claude-code/skill/hooks/nudge.sh rename harness/hosts/claude-code/{skill-loop => skill}/hooks/prime.sh (85%) create mode 100644 harness/hosts/claude-code/skill/hooks/remind.sh rename harness/hosts/claude-code/{skill-loop => skill}/scripts/update_settings.py (97%) create mode 100644 harness/loops/README.md rename harness/{modules/eval-loop => loops/eval}/GUIDE.md (100%) rename harness/{modules/eval-loop => loops/eval}/README.md (83%) rename harness/{modules/eval-loop => loops/eval}/env.sh (100%) rename harness/{modules/eval-loop => loops/eval}/hooks/compact.md (100%) rename harness/{modules/eval-loop => loops/eval}/hooks/nudge.md (100%) rename harness/{modules/eval-loop => loops/eval}/hooks/prime.md (100%) rename harness/{modules/eval-loop => loops/eval}/hooks/remind.md (100%) rename harness/{modules/eval-loop/module.json => loops/eval/loop.json} (51%) rename harness/{modules/eval-loop => loops/eval}/rubrics/eval-asset-quality.md (100%) rename harness/{modules/eval-loop => loops/eval}/rubrics/interface-loop-behavior.md (100%) rename harness/{modules/eval-loop => loops/eval}/scenarios/docs/bilingual-doc-sync.md (95%) rename harness/{modules/eval-loop => loops/eval}/scenarios/memory/project-preference-recall.md (95%) rename harness/{modules/eval-loop/scenarios/setup => loops/eval/scenarios/ops}/host-projection-smoke.md (56%) rename harness/{modules/eval-loop => loops/eval}/scenarios/skill/skill-creation-reuse.md (95%) rename harness/{modules/eval-loop => loops/eval}/skills/eval_analyze.md (95%) rename harness/{modules/eval-loop => loops/eval}/skills/eval_improve.md (100%) rename harness/{modules/eval-loop => loops/eval}/skills/eval_plan.md (98%) rename harness/{modules/eval-loop => loops/eval}/skills/eval_run.md (94%) rename harness/{modules/eval-loop => loops/eval}/subagents/evaluator.md (89%) rename harness/{modules/eval-loop => loops/eval}/suites/regression.json (91%) rename harness/{modules/eval-loop => loops/eval}/suites/smoke.json (66%) rename harness/{modules/memory-loop => loops/memory}/GUIDE.md (100%) rename harness/{modules/memory-loop => loops/memory}/MEMORY.md (100%) rename harness/{modules/memory-loop => loops/memory}/README.md (80%) rename harness/{modules/memory-loop => loops/memory}/env.sh (100%) rename harness/{modules/memory-loop => loops/memory}/hooks/compact.md (100%) rename harness/{modules/memory-loop => loops/memory}/hooks/nudge.md (100%) rename harness/{modules/memory-loop => loops/memory}/hooks/prime.md (100%) rename harness/{modules/memory-loop => loops/memory}/hooks/remind.md (100%) create mode 100644 harness/loops/memory/loop.json rename harness/{modules/memory-loop => loops/memory}/skills/memory_get.md (100%) rename harness/{modules/memory-loop => loops/memory}/skills/memory_set.md (100%) rename harness/{modules/memory-loop => loops/memory}/subagents/dreaming.md (100%) rename harness/{modules/skill-loop => loops/skill}/GUIDE.md (100%) rename harness/{modules/skill-loop => loops/skill}/README.md (82%) rename harness/{modules/skill-loop => loops/skill}/env.sh (100%) rename harness/{modules/skill-loop => loops/skill}/hooks/compact.md (100%) rename harness/{modules/skill-loop => loops/skill}/hooks/nudge.md (100%) rename harness/{modules/skill-loop => loops/skill}/hooks/prime.md (100%) rename harness/{modules/skill-loop => loops/skill}/hooks/remind.md (100%) create mode 100644 harness/loops/skill/loop.json rename harness/{modules/skill-loop => loops/skill}/skills/skill_author.md (97%) rename harness/{modules/skill-loop => loops/skill}/skills/skill_curate.md (100%) rename harness/{modules/skill-loop => loops/skill}/skills/skill_manage.md (100%) rename harness/{modules/skill-loop => loops/skill}/skills/skill_observe.md (100%) rename harness/{modules/skill-loop => loops/skill}/subagents/curator.md (100%) delete mode 100644 harness/modules/README.md delete mode 100644 harness/modules/memory-loop/module.json delete mode 100644 harness/modules/skill-loop/module.json create mode 100644 harness/ops/README.md rename harness/{setup => ops}/install.sh (56%) rename harness/{setup => ops}/lib/paths.sh (81%) rename harness/{setup => ops}/status.sh (63%) rename harness/{setup => ops}/uninstall.sh (55%) delete mode 100644 harness/setup/README.md create mode 100755 scripts/validate_harness_loops.sh delete mode 100755 scripts/validate_harness_modules.sh diff --git a/Makefile b/Makefile index b352950..739b193 100644 --- a/Makefile +++ b/Makefile @@ -10,7 +10,7 @@ ifeq ($(GOBIN),) GOBIN := $(shell go env GOPATH)/bin endif -.PHONY: deps build install uninstall test unit vet harness-validate codex-app-eval codex-app-eval-suite codex-memory-deep-eval codex-skill-deep-eval codex-eval-loop-smoke docker-build docker-run compose-up compose-down compose-dev release-snapshot clean help +.PHONY: deps build install uninstall test unit vet harness-validate codex-app-eval codex-app-eval-suite codex-memory-deep-eval codex-skill-deep-eval codex-eval-smoke docker-build docker-run compose-up compose-down compose-dev release-snapshot clean help .DEFAULT_GOAL := help @@ -45,8 +45,8 @@ unit: ## Run Go unit tests vet: ## Run go vet static analysis go vet ./... -harness-validate: ## Validate harness module manifests and declared asset paths - bash scripts/validate_harness_modules.sh +harness-validate: ## Validate harness loop manifests and declared asset paths + bash scripts/validate_harness_loops.sh codex-app-eval: ## Run real Codex app-server harness smoke eval python3 scripts/codex_app_server_eval.py @@ -60,8 +60,8 @@ codex-memory-deep-eval: ## Run deep real Codex app-server memory regression suit codex-skill-deep-eval: ## Run deep real Codex app-server skill regression suite python3 scripts/codex_app_server_eval.py --suite --suite-name skill-deep -codex-eval-loop-smoke: ## Run real Codex app-server eval-loop projection smoke check - python3 scripts/codex_app_server_eval.py --module eval-loop +codex-eval-smoke: ## Run real Codex app-server eval projection smoke check + python3 scripts/codex_app_server_eval.py --loop eval # ── Containers / Deployment ────────────────────────────────────────── diff --git a/README.md b/README.md index 0032648..6348c67 100644 --- a/README.md +++ b/README.md @@ -229,7 +229,7 @@ Different agents/processes can use different stores via the `MNEMON_STORE` envir **How do I customize the behavior?** Edit the generated guideline (`~/.mnemon/prompt/guide.md` in current setup -flows) or use the installable [memory loop GUIDE](harness/modules/memory-loop/GUIDE.md) +flows) or use the installable [memory loop GUIDE](harness/loops/memory/GUIDE.md) as the source. The skill file should stay focused on command syntax. **What is sub-agent delegation?** @@ -270,8 +270,8 @@ See [Development and Deployment](docs/DEPLOYMENT.md) for Docker, Compose, Ollama ## Documentation - [Modular Self-Evolution Harness](docs/harness/README.md) — formal harness docs for modular agent, memory loop, and skill loop design -- [Memory Loop Harness](harness/modules/memory-loop/README.md) — installable memory loop assets -- [Skill Loop Harness](harness/modules/skill-loop/README.md) — installable skill loop assets +- [Memory Loop Harness](harness/loops/memory/README.md) — installable memory loop assets +- [Skill Loop Harness](harness/loops/skill/README.md) — installable skill loop assets - [Design & Architecture](docs/DESIGN.md) — current engine architecture, algorithms, integration design - [Usage & Reference](docs/USAGE.md) — CLI commands, embedding support, architecture overview - [Architecture Diagrams](docs/diagrams/) — system architecture, pipelines, lifecycle management diff --git a/docs/harness/HOST_PROJECTION.md b/docs/harness/HOST_PROJECTION.md index 4805c57..2add73d 100644 --- a/docs/harness/HOST_PROJECTION.md +++ b/docs/harness/HOST_PROJECTION.md @@ -2,11 +2,11 @@ Chinese version: [HOST_PROJECTION.md](../zh/harness/HOST_PROJECTION.md) -This document defines how a Mnemon loop module is projected into a concrete +This document defines how a Mnemon loop template is projected into a concrete host runtime such as Claude Code, Codex, OpenClaw, or a future app-server eval host. -The loop module standard defines the canonical package shape. Host projection +The loop standard defines the canonical package shape. Host projection defines how that package becomes visible and executable inside a host runtime. ## Principle @@ -16,9 +16,9 @@ projections that can be regenerated. ```text .mnemon/ - canonical state, loop modules, reports, proposals, audit + canonical state, loop templates, reports, proposals, audit | - | projected by setup/ + | projected by harness/hosts/ through harness/ops v .claude/ or .codex/ host-readable skills, hooks, config, and pointers back to .mnemon @@ -31,17 +31,22 @@ The projection adapter should not create an independent copy of truth. It should render enough host-native files for the host to discover and use the loop while keeping durable state under `.mnemon`. +Projection and observation are separate surfaces. Projection lets the host see +Mnemon's Intent. Observation lets Mnemon see enough Reality to write status, +collect evidence, and run future reconcile actions. + ## Responsibilities A host projection adapter owns these responsibilities: | Responsibility | Description | | --- | --- | -| Path resolution | Resolve project root, host config directory, canonical `.mnemon`, active store, and loop module path. | +| Path resolution | Resolve project root, host config directory, canonical `.mnemon`, active store, and loop template path. | | Asset projection | Render or copy host-readable GUIDE, hooks, protocol skills, and subagents. | | Hook registration | Register host lifecycle hooks when the host supports them. | | Environment injection | Make `MNEMON_DATA_DIR`, `MNEMON_STORE`, `MNEMON_HARNESS_DIR`, and loop-specific env visible to hooks and skills. | | Manifest writing | Record what was projected and where under `.mnemon/hosts//manifest.json`. | +| Status writing | Record the installed loop control model under `.mnemon/harness//status.json`. | | Validation | Detect missing assets, stale projections, incompatible host capabilities, and path conflicts. | | Uninstall | Remove host projection files while preserving canonical `.mnemon` state by default. | @@ -51,7 +56,7 @@ A host projection adapter should not: - Reimplement Mnemon memory storage or retrieval. - Move canonical state into `.claude`, `.codex`, or another host directory. -- Hide host-specific behavior inside loop module root files. +- Hide host-specific behavior inside loop template root files. - Mutate user-owned host config outside declared projection sections. - Delete memory, reports, proposals, or audit records unless the user explicitly requests destructive cleanup. @@ -65,8 +70,10 @@ The target canonical layout is: ├── data/ │ └── /mnemon.db ├── harness/ -│ ├── memory-loop/ -│ └── skill-loop/ +│ ├── memory/ +│ │ └── status.json +│ └── skill/ +│ └── status.json ├── reports/ ├── proposals/ ├── audit/ @@ -166,21 +173,28 @@ Recommended shape: ```json { - "schema_version": 1, + "schema_version": 2, "host": "codex", - "installed_at": "2026-05-14T00:00:00Z", + "updated_at": "2026-05-20T00:00:00Z", "project_root": "/path/to/project", "mnemon_dir": "/path/to/project/.mnemon", "store": "default", "loops": { - "memory-loop": { - "module_path": ".mnemon/harness/memory-loop", - "module_version": "0.1.0", - "projection_path": ".codex", - "projected_assets": { - "skills": [".codex/skills/memory_get.md"], - "hooks": [".codex/hooks/prime.sh"], - "subagents": [] + "memory": { + "loop_path": ".mnemon/harness/memory", + "loop_version": "0.1.0", + "state_path": ".mnemon/harness/memory", + "intent_policy": ".mnemon/harness/memory/GUIDE.md", + "status_path": ".mnemon/harness/memory/status.json", + "projection": { + "path": ".codex", + "surfaces": ["GUIDE.md", "hooks", "memory_get", "memory_set", "runtime env"] + }, + "reality": { + "surfaces": ["hook output", "MEMORY.md length", "recall results", "write outcomes"] + }, + "reconcile": { + "actions": ["read", "write", "compact", "consolidate", "no-op"] }, "lifecycle_mapping": { "prime": "session-init", @@ -193,7 +207,10 @@ Recommended shape: } ``` -The manifest is the bridge between setup, status, uninstall, and eval tooling. +The manifest is the bridge between ops, status, uninstall, eval tooling, and +future reconcile tooling. Each installed loop also writes `status.json` in its +canonical state directory so loop-local state can be inspected without reading +host-specific configuration. ## Setup Contract @@ -201,15 +218,17 @@ All host adapters should support the same high-level operations: ```text install - validate loop module manifests + validate loop manifests resolve canonical .mnemon install canonical loop assets if needed render host projection register hooks/config write host manifest + write loop status status read host manifest + read loop status validate projected files exist validate registered hooks/config report stale or missing projections @@ -233,7 +252,7 @@ behavior. It should use the same projection contract as real hosts: eval orchestrator | | create isolated workspace and .mnemon - | run setup//install + | run harness/ops/install.sh | start host app server v host app server @@ -250,7 +269,7 @@ Eval should test host behavior under harness influence, not only Mnemon CLI CRUD. Useful assertions include: - The app server uses the isolated `.mnemon`. -- The expected loop module versions are installed. +- The expected loop template versions are installed. - Lifecycle events are invoked through the declared mapping. - Recall decisions affect later task behavior. - Writeback decisions create durable memory only when justified. @@ -259,10 +278,9 @@ CRUD. Useful assertions include: ## Quality Rules - Projection files should be small and generated from canonical assets. -- Host-specific behavior belongs in `setup//` or generated adapter files. +- Host-specific behavior belongs in `harness/hosts//` or generated adapter files. - Setup should be repeatable and idempotent where practical. - Uninstall should be conservative and preserve canonical state. - Manifest paths should be relative when possible and absolute when required for runtime execution. - Public projection behavior must be documented in both English and Chinese. - diff --git a/docs/harness/LIFECYCLE_CONTROL_PLANE.md b/docs/harness/LIFECYCLE_CONTROL_PLANE.md index 9e68f7a..4c3a4ae 100644 --- a/docs/harness/LIFECYCLE_CONTROL_PLANE.md +++ b/docs/harness/LIFECYCLE_CONTROL_PLANE.md @@ -41,7 +41,7 @@ model. | Profile | Meaning | Examples | | --- | --- | --- | -| Template | Reusable definition, not necessarily reconciled. | `LoopModule` | +| Template | Reusable definition, not necessarily reconciled. | `Loop` | | Controlled | Needs ongoing alignment of Intent and Reality. | `LoopBinding`, `EvalRun`, future `Goal` | | Surface | Expresses or reaches host capability. | `HostCapability`, `Projection` | | Evidence | Observed fact from Reality, not a declarative object. | `Observation`, runtime status | @@ -54,8 +54,8 @@ profiles participate in reconcile differently. | Entity | Profile | Role | | --- | --- | --- | -| `LoopModule` | Template | Reusable lifecycle capability package such as memory-loop, skill-loop, or eval-loop. | -| `LoopBinding` | Controlled | Binds one `LoopModule` to one host; suitable as the first full controlled object sample. | +| `Loop` | Template | Reusable lifecycle capability package such as memory, skill, or eval. | +| `Binding` | Controlled | Binds one `Loop` to one host; suitable as the first full controlled object sample. | | `HostCapability` | Surface | Describes static or dynamic capabilities a host can expose. | | `Projection` | Surface | Lets the HostAgent see Mnemon's Intent. | | `Observation` | Evidence | Lets Mnemon see the HostAgent's Reality. | @@ -101,7 +101,7 @@ Mnemon's method is to take capabilities that are often built as heavy external systems and reintroduce them into the host lifecycle through hooks, skills, daemon work, canonical state, and reconcile. -`memory-loop` validated this pattern for memory: +`memory` validated this pattern for memory: ```text external memory service @@ -154,5 +154,5 @@ Mnemon should grow through lightweight capability levels: | Governance | Let AI produce patches, reports, and proposals while review gates control risk. | The goal is not to copy a large control system. The goal is a small, consistent -lifecycle model that can scale from memory-loop to self-evolving agentic +lifecycle model that can scale from memory to self-evolving agentic projects. diff --git a/docs/harness/LOOP_MODULE_STANDARD.md b/docs/harness/LOOP_STANDARD.md similarity index 66% rename from docs/harness/LOOP_MODULE_STANDARD.md rename to docs/harness/LOOP_STANDARD.md index e358a9e..d78d458 100644 --- a/docs/harness/LOOP_MODULE_STANDARD.md +++ b/docs/harness/LOOP_STANDARD.md @@ -1,40 +1,38 @@ -# Loop Module Standard +# Loop Standard -Chinese version: [LOOP_MODULE_STANDARD.md](../zh/harness/LOOP_MODULE_STANDARD.md) +Chinese version: [LOOP_STANDARD.md](../zh/harness/LOOP_STANDARD.md) -This document defines the standard structure for Mnemon harness loop modules. +This document defines the standard structure for Mnemon harness loop templates. The standard is host-agnostic. Concrete hosts such as Claude Code, Codex, -OpenClaw, or future runtimes consume the same loop module through host-specific +OpenClaw, or future runtimes consume the same loop template through host-specific projection adapters. ## Core Model -Mnemon separates canonical harness state from host runtime projection: +Mnemon uses the lifecycle control model for every installable loop: ```text -.mnemon canonical state - | - | projected by a host adapter - v -.claude / .codex / other host config - | - v -host runtime +State(.mnemon loop state) + -> Intent(loop policy and desired visibility) + -> Projection(host-readable skills, hooks, env, config) + -> Reality(host behavior, evidence, drift, reports) + -> Reconcile(loop action or no-op) + -> State(updated status and durable state) ``` -The loop module owns policy, lifecycle reminders, protocol skills, maintenance -agents, environment contracts, and setup adapters. The host runtime owns the -conversation loop, prompt assembly, tool routing, native skill discovery, -permission model, and UI. +The loop template owns its State contract, Intent policy, host-facing projection +assets, observation surfaces, reconcile actions, environment contracts, and +maintenance roles. The host runtime owns the conversation loop, prompt assembly, +tool routing, native skill discovery, permission model, and UI. ## Standard Directory -Every installable loop module should follow this shape: +Every installable loop template should follow this shape: ```text -harness/modules// +harness/loops// ├── README.md -├── module.json +├── loop.json ├── env.sh ├── GUIDE.md ├── hooks/ @@ -48,7 +46,7 @@ harness/modules// │ └── .md ``` -Host-specific projection logic lives outside modules: +Host-specific projection logic lives outside loops: ```text harness/hosts// @@ -57,10 +55,10 @@ harness/hosts// └── scripts/ ``` -Shared setup entrypoints compose modules and hosts: +Shared ops entrypoints compose loops and hosts: ```text -harness/setup/ +harness/ops/ ├── install.sh ├── status.sh └── uninstall.sh @@ -73,13 +71,13 @@ contract, such as `MEMORY.md` for the Memory Loop. | Concept | Required | Role | | --- | --- | --- | -| `module.json` | Yes | Machine-readable loop identity, declared assets, state directories, lifecycle events, and supported host adapters. | +| `loop.json` | Yes | Machine-readable loop identity, control model, entity profiles, projection and observation surfaces, assets, state directories, lifecycle events, and supported host adapters. | | `GUIDE.md` | Yes | Policy for when the loop should act, what the host agent should consider, and what remains out of scope. | | `env.sh` | Yes | Runtime path contract for scripts, hooks, protocol skills, and maintenance agents. | | `hooks/*.md` | Yes | Host-agnostic lifecycle reminders. They describe what the agent should consider at a lifecycle boundary. | | `skills/*.md` | Usually | Protocol skills for reusable online operations. These define procedures, not host-specific installation. | | `subagents/*.md` | Optional | Maintenance roles for heavier review, consolidation, or proposal generation. Hosts without native subagents may run them as manual or scheduled jobs. | -| `harness/hosts//` | At least one host overall | Host-specific projection adapter that installs or removes modules from a host runtime. | +| `harness/hosts//` | At least one host overall | Host-specific projection adapter that installs or removes loops from a host runtime. | ## Lifecycle Events @@ -100,11 +98,11 @@ API. ## Host Projection -A host projection adapter renders the canonical loop module into a host-native +A host projection adapter renders the canonical loop template into a host-native surface. Projection must not create a second source of truth. ```text -canonical loop module +canonical loop template | | install / project v @@ -132,8 +130,10 @@ Recommended layout: ├── data/ │ └── /mnemon.db ├── harness/ -│ ├── memory-loop/ -│ └── skill-loop/ +│ ├── memory/ +│ │ └── status.json +│ └── skill/ +│ └── status.json ├── reports/ ├── proposals/ ├── audit/ @@ -145,20 +145,37 @@ Recommended layout: └── manifest.json ``` -Current MVP setup scripts may still place runtime files inside host config +Current MVP ops scripts may still place runtime files inside host config directories. New adapters should move toward the canonical `.mnemon` layout and use host directories only as projection surfaces. ## Manifest Schema -Each loop module should include a `module.json` file with this stable shape: +Each loop template should include a `loop.json` file with this stable shape: ```json { - "schema_version": 1, - "name": "memory-loop", + "schema_version": 2, + "name": "memory", "version": "0.1.0", "description": "Connects prompt-facing working memory with Mnemon long-term memory.", + "control_model": { + "state": ["MEMORY.md", ".mnemon stores", "reports", "memory status"], + "intent": "Keep useful continuity available across lifecycle boundaries.", + "reality": ["host prompt", "current task", "recall results", "context pressure"], + "reconcile": ["read", "write", "compact", "consolidate", "no-op"] + }, + "entity_profiles": { + "template": "memory", + "controlled": ["memory binding"], + "surface": ["MEMORY.md", "Mnemon recall/write", "host hooks", "protocol skills"], + "evidence": ["recall usefulness", "write results", "context pressure"], + "governance": ["memory proposals", "memory audits"] + }, + "surfaces": { + "projection": ["GUIDE.md", "hooks", "memory_get", "memory_set", "dreaming", "runtime env"], + "observation": ["hook output", "MEMORY.md length", "recall results", "write outcomes"] + }, "lifecycle_events": ["prime", "remind", "nudge", "compact"], "assets": { "guide": "GUIDE.md", @@ -182,8 +199,10 @@ Each loop module should include a `module.json` file with this stable shape: } ``` -The manifest is descriptive in the MVP. Later setup tooling can validate loop -modules, generate projections, and drive app-server evals from this metadata. +The manifest is now part of the executable harness contract. Setup tooling +validates it, projectors copy it into canonical loop state, and host manifests +carry its control model so status, eval, and future reconcile tooling can reason +about the installed loop. ## Adapter Mapping @@ -202,11 +221,11 @@ The same standard concepts map differently across hosts: ## Quality Rules -- Keep loop modules host-agnostic by default. -- Keep host-specific code under `setup//`. +- Keep loop templates host-agnostic by default. +- Keep host-specific code under `harness/hosts//`. - Do not duplicate canonical state into host directories. - Treat host directories as projections that can be regenerated. -- Keep setup, status, and uninstall behavior explicit and auditable. +- Keep ops, status, and uninstall behavior explicit and auditable. - Preserve user state on uninstall unless a destructive flag is explicit. - Document English and Chinese behavior together when adding or changing public harness concepts. diff --git a/docs/harness/README.md b/docs/harness/README.md index 17fb18a..71b1d95 100644 --- a/docs/harness/README.md +++ b/docs/harness/README.md @@ -13,11 +13,11 @@ skills, subagents, filesystem assets, and environment configuration. The key assumption is that many behavior-level agent capabilities can be externalized when the host already has a ReAct loop and readable extension -surfaces. Mnemon packages those capabilities as harness modules instead of +surfaces. Mnemon packages those capabilities as harness loops instead of building another runtime. Mnemon is also not only a set of skills. It owns a harness runtime substrate: -module layout, setup, environment, state, reports, proposals, locks, queues, +loop layout, ops, environment, state, reports, proposals, locks, queues, projection into host surfaces, and optional daemon scheduling. ## Core Positioning @@ -25,51 +25,52 @@ projection into host surfaces, and optional daemon scheduling. | Topic | Design | | --- | --- | | Modular Agent Harness | [EN](modular-agent/DESIGN.md) / [中文](../zh/harness/modular-agent/DESIGN.md) | -| Loop Module Standard | [EN](LOOP_MODULE_STANDARD.md) / [中文](../zh/harness/LOOP_MODULE_STANDARD.md) | +| Loop Standard | [EN](LOOP_STANDARD.md) / [中文](../zh/harness/LOOP_STANDARD.md) | | Host Projection | [EN](HOST_PROJECTION.md) / [中文](../zh/harness/HOST_PROJECTION.md) | | Harness Roadmap | [EN](ROADMAP.md) / [中文](../zh/harness/ROADMAP.md) | | YC Evolving Design Philosophy | [EN](YC_EVOLVING_DESIGN_PHILOSOPHY.md) / [中文](../zh/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md) | | Lifecycle Control Plane | [EN](LIFECYCLE_CONTROL_PLANE.md) / [中文](../zh/harness/LIFECYCLE_CONTROL_PLANE.md) / [site](../site/lifecycle-control-plane/index.html) | -| Memory Loop | [EN](memory-loop/DESIGN.md) / [中文](../zh/harness/memory-loop/DESIGN.md) / [site](../site/memory-loop/index.html) | -| Skill Loop | [EN](skill-loop/DESIGN.md) / [中文](../zh/harness/skill-loop/DESIGN.md) / [site](../site/skill-loop/index.html) | -| Eval Loop | [EN](eval-loop/DESIGN.md) / [中文](../zh/harness/eval-loop/DESIGN.md) | +| Memory Loop | [EN](memory/DESIGN.md) / [中文](../zh/harness/memory/DESIGN.md) / [site](../site/memory/index.html) | +| Skill Loop | [EN](skill/DESIGN.md) / [中文](../zh/harness/skill/DESIGN.md) / [site](../site/skill/index.html) | +| Eval Loop | [EN](eval/DESIGN.md) / [中文](../zh/harness/eval/DESIGN.md) | ## Installable Assets -| Harness Module | Implementation | +| Harness Loop | Implementation | | --- | --- | -| Memory Loop | [harness/modules/memory-loop](../../harness/modules/memory-loop/README.md) | -| Skill Loop | [harness/modules/skill-loop](../../harness/modules/skill-loop/README.md) | -| Eval Loop | [harness/modules/eval-loop](../../harness/modules/eval-loop/README.md) | +| Memory Loop | [harness/loops/memory](../../harness/loops/memory/README.md) | +| Skill Loop | [harness/loops/skill](../../harness/loops/skill/README.md) | +| Eval Loop | [harness/loops/eval](../../harness/loops/eval/README.md) | ## Repository Layout | Directory | Role | | --- | --- | -| `harness/modules/` | Canonical host-agnostic loop modules. | +| `harness/loops/` | Canonical host-agnostic loop templates. | | `harness/hosts/` | Host projection adapters such as Claude Code and future Codex support. | -| `harness/setup/` | Shared install, status, and uninstall entrypoints that compose modules with hosts. | -| `harness//` | Compatibility wrappers for older install paths. | +| `harness/bindings/` | Loop x host binding definitions. | +| `harness/control/` | Shared control-plane contracts. | +| `harness/ops/` | Shared install, status, and uninstall entrypoints that compose loops with hosts. | ## Vocabulary | Concept | Meaning | | --- | --- | -| loop module | Standard package shape for one attachable harness loop. | +| loop template | Standard package shape for one attachable harness loop. | | GUIDE | Markdown policy for deciding when a loop should act. | -| setup | Installation and mounting into a host agent. | +| ops | Installation, status, validation, and uninstall operations. | | hook | Host lifecycle timing such as Prime, Remind, Nudge, and Compact. | | protocol | Markdown skills that define reusable operations. | | subagent | Background maintenance agent for heavier review or consolidation. | | projection | Host-specific rendering of canonical loop assets into `.claude`, `.codex`, or another runtime surface. | | host manifest | Machine-readable record of projected loops, paths, lifecycle mappings, and host capabilities. | -| daemon | Optional harness maintenance runner for scheduled module work. | -| substrate | Mnemon-owned runtime base for module state, setup, projection, scheduling, and cross-module protocols. | +| daemon | Optional harness maintenance runner for scheduled loop work. | +| substrate | Mnemon-owned runtime base for loop state, ops, projection, scheduling, and cross-loop protocols. | ## Boundary The host agent keeps the ReAct loop, prompt assembly, tool routing, native skill -runtime, permission model, and UI. Mnemon provides attachable harness modules +runtime, permission model, and UI. Mnemon provides attachable harness loops that make the host agent more durable and self-improving. In short: the host agent is the execution runtime; Mnemon is the harness runtime @@ -79,4 +80,4 @@ Claude Code is the first reference host because it exposes hooks, skills, and subagents. The architecture is intentionally broader than Claude Code. `mnemon-daemon` may later provide a background maintenance runner for harness -modules. It is part of the harness layer, not a host agent runtime. +loops. It is part of the harness layer, not a host agent runtime. diff --git a/docs/harness/ROADMAP.md b/docs/harness/ROADMAP.md index 9513e94..e478c1d 100644 --- a/docs/harness/ROADMAP.md +++ b/docs/harness/ROADMAP.md @@ -6,10 +6,10 @@ This roadmap describes how Mnemon Harness should grow from the current MVP loops into a broader modular-agent governance layer. It is directional, not a fixed release schedule. -The principle is simple: build one loop at a time, keep each module useful on +The principle is simple: build one loop at a time, keep each loop useful on its own, and avoid turning Mnemon into a replacement agent runtime. -The roadmap is memory-driven rather than module-driven. Memory is the continuity +The roadmap is memory-driven rather than loop-driven. Memory is the continuity point that lets agent experience become durable state. Other loops should strengthen, govern, or operate around that state instead of becoming isolated features. @@ -26,11 +26,11 @@ Mnemon already has two installable MVP harness loops. Both MVP loops use the same harness vocabulary: - GUIDE files define loop policy. -- setup scripts mount the loop into a host agent. +- ops scripts mount the loop into a host agent. - hooks inject lifecycle prompts at host-defined moments. - protocol skills expose reusable operations. - subagents run heavier maintenance work. -- Mnemon-owned state keeps module data outside the host runtime. +- Mnemon-owned state keeps loop data outside the host runtime. Claude Code is the first reference host because it exposes hooks, skills, subagents, and project/user configuration. The architecture should remain @@ -54,9 +54,9 @@ understand what changed. Focus: make multiple loops easier to operate together. -This phase should introduce the minimum shared substrate needed by modules: +This phase should introduce the minimum shared substrate needed by loops: -- module registry and version metadata +- loop registry and version metadata - canonical filesystem layout - shared state, reports, proposals, and audit records - locks, leases, queues, and background job status @@ -65,13 +65,13 @@ This phase should introduce the minimum shared substrate needed by modules: `mnemon-daemon` should be a harness maintenance runner, not an agent runtime. It can run dreaming, curator review, eval jobs, risk scans, audit writing, and -other offline module work. +other offline loop work. ## Phase 3: Goal Loop Focus: support long-horizon work without replacing the host agent. -A future `mnemon-goal` module should maintain durable goal state: +A future `mnemon-goal` loop should maintain durable goal state: - objectives - milestones @@ -89,7 +89,7 @@ risk review, human review, audit, and policy reminders. Focus: add control, quality, and accountability around self-evolution. -Likely modules: +Likely loops: - Eval Loop: tests, benchmarks, checklists, and outcome feedback. - Risk Loop: scan proposed memory, skill, policy, or setup changes. diff --git a/docs/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md b/docs/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md index 0c8b7e0..e38788d 100644 --- a/docs/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md +++ b/docs/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md @@ -96,45 +96,33 @@ regenerated. The article's loop structure can be translated into Mnemon's lifecycle model: ```text -Observed Signals - user intent, repo diffs, host status, eval results, customer feedback +State + durable context, skill lifecycle state, reports, proposals, status | v -Desired State - goals, policies, skills, memory, bindings, expected projections +Intent + goals, policies, desired visibility, review boundaries | v -Reconcile - compare desired state with actual host surfaces and outcomes +Projection + host-readable skills, hooks, app servers, tools, eval surfaces | v -Projection And Execution - host adapters expose skills, hooks, app servers, tools, evals +Reality + user intent, repo diffs, host behavior, eval results, customer feedback | v -Status And Learning - record success, failure, drift, missing tools, stale skills, review needs +Reconcile + compare Intent with Reality, then record action, no-op, or proposal | v -Updated Canonical Context +Updated State ``` This is the minimum trunk Mnemon should keep clear: ```text -LoopModule + HostBinding - | - v -Desired State - | - v -Reconcile - | - v -HostAdapter -> Projection -> HostAgent - | - v -Status -> Learning -> next Reconcile +State -> Intent -> Projection -> Reality -> Reconcile -> State ``` ## Host Capability Surfaces diff --git a/docs/harness/eval/CODEX_APP_SERVER.md b/docs/harness/eval/CODEX_APP_SERVER.md index e9d6a52..4514149 100644 --- a/docs/harness/eval/CODEX_APP_SERVER.md +++ b/docs/harness/eval/CODEX_APP_SERVER.md @@ -2,7 +2,7 @@ This eval mode uses the real Codex app-server rather than a mock server. It creates an isolated run directory under `.testdata`, projects Mnemon loop -modules into a generated workspace, then starts: +loops into a generated workspace, then starts: ```bash codex app-server --listen stdio:// @@ -27,7 +27,7 @@ The suite currently covers local-context memory skip, focused long-term recall, durable `MEMORY.md` writes, transient no-pollution behavior, and skill evidence logging. -For longer memory-loop regression, run: +For longer memory regression, run: ```bash make codex-memory-deep-eval @@ -37,7 +37,7 @@ The deep memory suite adds noisy recall filtering, stale-memory supersession, uncertain-preference rejection, secret-like value rejection, and multi-turn continuity through persisted `MEMORY.md`. -For longer skill-loop regression, run: +For longer skill regression, run: ```bash make codex-skill-deep-eval diff --git a/docs/harness/eval-loop/DESIGN.md b/docs/harness/eval/DESIGN.md similarity index 77% rename from docs/harness/eval-loop/DESIGN.md rename to docs/harness/eval/DESIGN.md index 2943835..eedd333 100644 --- a/docs/harness/eval-loop/DESIGN.md +++ b/docs/harness/eval/DESIGN.md @@ -1,26 +1,26 @@ # Eval Loop MVP Design -Chinese version: [DESIGN.md](../../zh/harness/eval-loop/DESIGN.md) +Chinese version: [DESIGN.md](../../zh/harness/eval/DESIGN.md) -Installable MVP assets: [harness/modules/eval-loop](../../../harness/modules/eval-loop/README.md) +Installable MVP assets: [harness/loops/eval](../../../harness/loops/eval/README.md) -The eval loop is Mnemon's feedback-facing harness module. It defines how a +The eval loop is Mnemon's feedback-facing harness loop. It defines how a HostAgent is tested through realistic scenarios, how evidence is collected, and how stable failures become curated improvement candidates. ## Positioning -The eval loop is a peer of memory-loop and skill-loop. It is not their parent -module. Memory-loop and skill-loop directly affect the HostAgent interface by +The eval loop is a peer of memory and skill. It is not their parent +loop. Memory-loop and skill directly affect the HostAgent interface by changing remembered context and reusable working methods. Eval-loop observes those effects through scenario execution and feeds findings back into the project. ```text -harness/modules/ -├── memory-loop -├── skill-loop -└── eval-loop +harness/loops/ +├── memory +├── skill +└── eval ``` ## Core Model @@ -85,6 +85,6 @@ The first scenarios focus on Mnemon's current self-evolution work: - bilingual documentation synchronization - host projection smoke checks -These scenarios evaluate memory-loop and skill-loop today, but the eval-loop +These scenarios evaluate memory and skill today, but the eval framework is intentionally broader. It can also evaluate setup, host adapters, -docs workflow, commit discipline, and eval-loop itself. +docs workflow, commit discipline, and eval itself. diff --git a/docs/harness/memory-loop/DESIGN.md b/docs/harness/memory/DESIGN.md similarity index 95% rename from docs/harness/memory-loop/DESIGN.md rename to docs/harness/memory/DESIGN.md index 0ce54c6..1b2bc8c 100644 --- a/docs/harness/memory-loop/DESIGN.md +++ b/docs/harness/memory/DESIGN.md @@ -1,16 +1,16 @@ # Memory Loop MVP Design -Related visualization: [memory-loop](../../site/memory-loop/index.html) +Related visualization: [memory](../../site/memory/index.html) -Chinese version: [DESIGN.md](../../zh/harness/memory-loop/DESIGN.md) +Chinese version: [DESIGN.md](../../zh/harness/memory/DESIGN.md) -Installable MVP assets: [harness/modules/memory-loop](../../../harness/modules/memory-loop/README.md) +Installable MVP assets: [harness/loops/memory](../../../harness/loops/memory/README.md) The memory loop is the first practical slice of the self-evolution harness. It gives a host agent a prompt-facing working memory while using Mnemon as durable long-term memory. The harness stays small: it installs Markdown policy, hook prompts, protocol skills, and one maintenance subagent around an existing host agent. ## Lifecycle Control Plane Position -In the lifecycle control plane, `memory-loop` is the first practical proof that +In the lifecycle control plane, `memory` is the first practical proof that an external capability can become lifecycle-native without turning Mnemon into a host agent runtime. @@ -18,7 +18,7 @@ Using the shared control model: | Layer | Memory-loop shape | | --- | --- | -| State | `MEMORY.md`, Mnemon long-term stores, reports, manifests, and memory-loop status under `.mnemon`. | +| State | `MEMORY.md`, Mnemon long-term stores, reports, manifests, and memory status under `.mnemon`. | | Intent | Keep useful agent, user, and project continuity available across lifecycle boundaries. | | Reality | The host prompt, current task, working-memory contents, recall results, context pressure, and consolidation state. | | Reconcile | Decide whether to read, write, compact, consolidate, or leave memory unchanged, then write status or durable state. | @@ -27,7 +27,7 @@ The entity profiles are intentionally light: | Entity | Profile | Role | | --- | --- | --- | -| `memory-loop` | Template | Reusable lifecycle capability package. | +| `memory` | Template | Reusable lifecycle capability package. | | memory binding | Controlled | Binds memory behavior to a host lifecycle such as Prime, Remind, Nudge, Compact, and maintenance. | | hot/cold memory surfaces | Surface | `MEMORY.md`, Mnemon recall/write, host hooks, and protocol skills. | | recall/write/consolidation evidence | Evidence | Observed memory usefulness, context pressure, stale entries, and durable write results. | @@ -106,7 +106,7 @@ cold memory implementation. Future work can improve either side: - better dreaming, promotion, demotion, compaction, and eviction improve the exchange protocol between the two. -The memory-loop contract is therefore: +The memory contract is therefore: ```text LLM-native hot memory @@ -157,7 +157,7 @@ Everything else is a harness asset around these three parts. | Concept | Memory Loop Asset | Responsibility | Boundary | | --- | --- | --- | --- | | GUIDE | `GUIDE.md` | Defines when to read, write, compact, and consolidate memory. | Policy only; it does not bind storage targets. | -| setup | `harness/setup` + host projection | Installs hooks, protocol skills, dreaming subagent, memory files, and environment variables. | Installation only; not a runtime decision maker. | +| ops | `harness/ops` + host projection | Installs hooks, protocol skills, dreaming subagent, memory files, and environment variables. | Installation only; not a runtime decision maker. | | hook | `prime/remind/nudge/compact` | Provides host lifecycle timing and short reminders. | No heavy reasoning or storage protocol. | | protocol | `memory_get.md` / `memory_set.md` | Defines online recall from Mnemon and online edits to `MEMORY.md`. | Called by the host only when GUIDE says memory work is useful. | | subagent | `dreaming` | Consolidates `MEMORY.md` into Mnemon and rewrites working memory. | Background or explicit maintenance, not every-turn online behavior. | diff --git a/docs/harness/modular-agent/DESIGN.md b/docs/harness/modular-agent/DESIGN.md index 5fa7d1f..f03c4ed 100644 --- a/docs/harness/modular-agent/DESIGN.md +++ b/docs/harness/modular-agent/DESIGN.md @@ -8,13 +8,13 @@ that replaces them. Mnemon does not own the agent runtime, but it does own a harness runtime substrate. That substrate is the system layer that makes independent harness -modules installable, composable, scheduled, auditable, and safe to combine with a +loops installable, composable, scheduled, auditable, and safe to combine with a host agent. ## Thesis Any host agent that supports standard extension points can gain self-evolution -capabilities by installing Mnemon harness modules. +capabilities by installing Mnemon harness loops. The host agent owns the ReAct loop: @@ -60,14 +60,14 @@ The host runtime still owns low-level execution: UI, permissions, tool routing, sandboxing, model calls, and session management. Mnemon focuses on the attachable behavioral layer that can be installed around that runtime. -This is why the architecture emphasizes harness modules instead of a new agent +This is why the architecture emphasizes harness loops instead of a new agent framework. The goal is to turn advanced agent behavior into portable, -inspectable, installable modules. +inspectable, installable loops. However, skill, hook, and Markdown assets are not sufficient by themselves once -multiple modules need to cooperate. Mnemon needs its own substrate for: +multiple loops need to cooperate. Mnemon needs its own substrate for: -- module registry and versioning +- loop registry and versioning - canonical filesystem layout - environment and configuration resolution - hook binding and prompt injection boundaries @@ -75,7 +75,7 @@ multiple modules need to cooperate. Mnemon needs its own substrate for: - proposal, report, audit, and state schemas - locks, leases, queues, and background job status - setup, uninstall, upgrade, and recovery paths -- cross-module protocols +- cross-loop protocols This substrate is still not an agent runtime. It does not own the ReAct loop, talk to users, or replace host tool routing. @@ -95,7 +95,7 @@ experience -> memory -> skills -> goals -> eval / risk / review / audit ``` Memory is the continuity point. Skill evolution depends on remembered evidence -and repeated workflows. Goal modules depend on durable objective state. Eval, +and repeated workflows. Goal loops depend on durable objective state. Eval, risk, review, and audit loops depend on records of decisions, changes, and outcomes. Backup and replication protect that memory-centered harness state. @@ -113,16 +113,16 @@ state. | Prompt assembly | Host agent | Decides which context enters the model. | | Tool routing | Host agent | Chooses and executes tools under the host permission model. | | Native skills | Host agent | Discovers and invokes skills using the host's own runtime. | -| Evolution modules | Mnemon harness | Adds memory, skill evolution, evaluation, and review loops through attachable assets. | +| Evolution loops | Mnemon harness | Adds memory, skill evolution, evaluation, and review loops through attachable assets. | | Canonical state | Mnemon harness | Stores durable memory, skill lifecycle state, evidence, proposals, and reports. | -| Harness substrate | Mnemon harness | Provides module registry, filesystem layout, environment, setup, projection, reports, proposals, locks, queues, and cross-module protocols. | -| Maintenance runner | Mnemon harness | Optionally schedules background module jobs without becoming an agent runtime. | +| Harness substrate | Mnemon harness | Provides loop registry, filesystem layout, environment, setup, projection, reports, proposals, locks, queues, and cross-loop protocols. | +| Maintenance runner | Mnemon harness | Optionally schedules background loop jobs without becoming an agent runtime. | -This split keeps Mnemon portable. A host can adopt one module without adopting a +This split keeps Mnemon portable. A host can adopt one loop without adopting a new runtime. It also prevents the opposite mistake: Mnemon should not be treated as only a -pile of Markdown skills. The harness substrate is what lets modules coordinate +pile of Markdown skills. The harness substrate is what lets loops coordinate without becoming a monolithic agent framework. ## Execution Plane And Governance Loops @@ -152,8 +152,8 @@ without mixing all of those concerns into one agent framework. | Hooks | Install lifecycle nudges at Prime, Remind, Nudge, Compact, or equivalent host events. | | Skills | Expose reusable protocol operations such as `memory_get`, `memory_set`, `skill_observe`, and `skill_manage`. | | Subagents | Run heavier maintenance jobs such as dreaming and curator review outside the online task path. | -| Daemon | Optionally schedule background maintenance for installed modules. | -| Filesystem | Store canonical module state in predictable directories and project/user scopes. | +| Daemon | Optionally schedule background maintenance for installed loops. | +| Filesystem | Store canonical loop state in predictable directories and project/user scopes. | | Environment | Let protocol skills resolve paths without hard-coding a specific host agent. | The minimal requirement is a hook-like lifecycle mechanism. Skills and subagents @@ -163,9 +163,9 @@ protocols directly. ## Harness Daemon `mnemon-daemon` is the proposed harness daemon: a background maintenance runner -for installed Mnemon modules. +for installed Mnemon loops. -It is useful because some module work should not run inside the online ReAct +It is useful because some loop work should not run inside the online ReAct loop: - dreaming for memory consolidation @@ -173,7 +173,7 @@ loop: - evaluation jobs - risk scans - audit and report writing -- leases, locks, queues, and module status +- leases, locks, queues, and loop status The daemon is not a host agent and not a second runtime. It must not converse with users, take over task execution, route tools for the host, or bypass @@ -183,20 +183,20 @@ The intended boundary is: ```text Host Agent -> online task execution and user interaction -mnemon-daemon -> offline harness maintenance and scheduled module jobs -Harness Modules -> memory, skills, eval, risk, review, audit, policy +mnemon-daemon -> offline harness maintenance and scheduled loop jobs +Harness Loops -> memory, skills, eval, risk, review, audit, policy ``` -For the MVP, modules can still run manually or through host hooks. The daemon -becomes important when multiple modules need shared scheduling, logs, reports, +For the MVP, loops can still run manually or through host hooks. The daemon +becomes important when multiple loops need shared scheduling, logs, reports, locks, and status. ## Current Modules | Module | Purpose | Current Reference Host | | --- | --- | --- | -| Memory Loop | Adds working memory, long-term memory, and dreaming consolidation. | Claude Code setup under `harness/setup/install.sh --host claude-code --module memory-loop`. | -| Skill Loop | Adds active/stale/archived skill lifecycle, evidence capture, curator proposals, and approved lifecycle mutation. | Claude Code setup under `harness/setup/install.sh --host claude-code --module skill-loop`. | +| Memory Loop | Adds working memory, long-term memory, and dreaming consolidation. | Claude Code setup under `harness/ops/install.sh --host claude-code --loop memory`. | +| Skill Loop | Adds active/stale/archived skill lifecycle, evidence capture, curator proposals, and approved lifecycle mutation. | Claude Code setup under `harness/ops/install.sh --host claude-code --loop skill`. | ## Relationship To Skill Packs @@ -211,10 +211,10 @@ Mnemon sits at a different layer: ```text Host Agent -> task/workflow skill packs - -> Mnemon harness modules + -> Mnemon harness loops ``` -Task skills help the agent do work. Mnemon harness modules help the agent manage +Task skills help the agent do work. Mnemon harness loops help the agent manage memory, skill lifecycle, evaluation, risk, audit, review, and policy around that work. @@ -224,7 +224,7 @@ only another skill pack. ## Memory Differentiator -The memory module uses a hot/cold memory model: +The memory loop uses a hot/cold memory model: - Working memory is model-friendly. It is small Markdown context loaded into the prompt and maintained by the agent. @@ -243,12 +243,12 @@ The same harness pattern can support more loops: - Eval loop: collect outcomes, run benchmarks, and feed failures into proposals. - Risk loop: scan proposed skill or memory changes before they become active. - Review loop: coordinate human approval, checkpoints, and release gates. -- Audit loop: record which module acted, why it acted, and what changed. +- Audit loop: record which loop acted, why it acted, and what changed. - Policy loop: maintain host-specific safety and permission guidance. - Backup / replication loop: preserve and restore harness state across machines, nodes, or host-agent environments. -Each module should remain independently installable. Modules may optionally use +Each loop should remain independently installable. Modules may optionally use `mnemon-daemon` for background scheduling, but should not require it for the basic install path. @@ -259,7 +259,7 @@ coordination can remain a later design. ## Composable Module Flow -Harness modules should compose through explicit state and proposal boundaries, +Harness loops should compose through explicit state and proposal boundaries, not by silently calling each other. Example: @@ -273,18 +273,18 @@ Skill Loop produces a skill proposal ``` The same pattern can apply to memory consolidation, policy updates, benchmark -failures, or host setup changes. A module may create evidence or a proposal; -another module may review, scan, approve, or record it. The host agent remains +failures, or host setup changes. A loop may create evidence or a proposal; +another loop may review, scan, approve, or record it. The host agent remains the runtime that decides when to invoke these capabilities. ## Long-Horizon Goal Modules -A future `mnemon-goal` module can use this architecture to support long-horizon +A future `mnemon-goal` loop can use this architecture to support long-horizon agent work without becoming a task runtime itself. `mnemon-goal` would maintain objective state, milestones, blockers, decisions, handoffs, and progress reports. Around a long-running goal, it can repeatedly -coordinate other harness modules: +coordinate other harness loops: - Memory Loop recalls context at the start and preserves durable decisions after milestones. @@ -297,7 +297,7 @@ coordinate other harness modules: - `mnemon-daemon` can detect stale, blocked, or due goals and schedule maintenance jobs. -This makes `mnemon-goal` an orchestrating harness module: it coordinates +This makes `mnemon-goal` an orchestrating harness loop: it coordinates memory, skills, evaluation, risk, review, audit, and policy around a durable objective while the host agent continues to execute the actual work. @@ -317,13 +317,13 @@ the most complete combinations of hooks, skills, subagents, filesystem configuration, and project/user scopes. That makes Claude Code a strong experimental mount point for Mnemon harness -modules: +loops: -- hooks can carry Prime, Remind, Nudge, Compact, and future module triggers +- hooks can carry Prime, Remind, Nudge, Compact, and future loop triggers - skills can expose portable protocol operations - subagents can run dreaming, curator review, and other maintenance work - project and user config can validate local and global install scopes -- settings files can make setup and uninstall repeatable +- settings files can make ops and uninstall repeatable Claude Code is a reference host, not the only supported runtime. Its role is to validate the harness attachment model. The architecture should remain portable diff --git a/docs/harness/skill-loop/DESIGN.md b/docs/harness/skill/DESIGN.md similarity index 95% rename from docs/harness/skill-loop/DESIGN.md rename to docs/harness/skill/DESIGN.md index eac402f..be046d6 100644 --- a/docs/harness/skill-loop/DESIGN.md +++ b/docs/harness/skill/DESIGN.md @@ -1,8 +1,8 @@ # Skill Loop MVP Design -Related visualization: [skill-loop](../../site/skill-loop/index.html) +Related visualization: [skill](../../site/skill/index.html) -Installable MVP assets: [harness/modules/skill-loop](../../../harness/modules/skill-loop/README.md) +Installable MVP assets: [harness/loops/skill](../../../harness/loops/skill/README.md) The skill loop gives a host agent a self-evolving skill library without replacing the host's native skill runtime. It treats skills as host-native assets, while `.mnemon` owns the canonical lifecycle state and the evidence used to evolve that state. @@ -10,7 +10,7 @@ The MVP is intentionally a visibility and lifecycle harness. It decides which sk ## Lifecycle Control Plane Position -In the lifecycle control plane, `skill-loop` makes skill visibility and skill +In the lifecycle control plane, `skill` makes skill visibility and skill lifecycle state a lifecycle-native capability without replacing the host's native skill runtime. @@ -18,7 +18,7 @@ Using the shared control model: | Layer | Skill-loop shape | | --- | --- | -| State | `.mnemon` skill library, active/stale/archived state, evidence, proposals, reports, and skill-loop status. | +| State | `.mnemon` skill library, active/stale/archived state, evidence, proposals, reports, and skill status. | | Intent | Keep the right skills visible to the host while preserving stale and archived skills for review, recovery, and design memory. | | Reality | Host skill surface, actual active projection, skill usage evidence, missing or misleading skills, curator findings, and review decisions. | | Reconcile | Sync active skills, record evidence, propose lifecycle changes, apply approved changes, and refresh host visibility at Prime. | @@ -27,7 +27,7 @@ The entity profiles are intentionally light: | Entity | Profile | Role | | --- | --- | --- | -| `skill-loop` | Template | Reusable lifecycle capability package. | +| `skill` | Template | Reusable lifecycle capability package. | | skill binding | Controlled | Binds skill visibility and lifecycle policy to one host skill surface. | | host skill surface | Surface | Host-native discovery surface such as `.codex/skills` or `.claude/skills`. | | usage signals and curator findings | Evidence | Observed skill usefulness, missing skills, stale skills, or workflow repetition. | @@ -72,7 +72,7 @@ The important distinction is that HostAgent owns behavior, while `.mnemon` owns | Concept | Skill Loop Asset | Role | Boundary | | --- | --- | --- | --- | | GUIDE | `GUIDE.md` | Defines what counts as skill evidence, reusable workflow signal, review trigger, protected or pinned skill, and proposal-first policy. | Policy only. It does not generate, patch, move, or archive skills. | -| setup | setup scripts and bindings | Installs hooks, protocol skills, the curator subagent, and host-native skill-surface bindings. | Installation only. It does not participate in every runtime decision. | +| ops | ops scripts and bindings | Installs hooks, protocol skills, the curator subagent, and host-native skill-surface bindings. | Installation only. It does not participate in every runtime decision. | | hook | `prime`, `remind`, `nudge`, `compact` | Provides timing: Prime syncs active skills, Nudge reminds the model to observe evidence, Compact can mark a low-frequency review boundary, and Remind is usually a no-op. | Hooks should stay short. The rules live in GUIDE and the actions live in protocol skills. | | protocol | `skill_observe.md`, `skill_curate.md`, `skill_manage.md` | Defines portable procedures the HostAgent can load for observation, review startup, and lifecycle mutation. | Protocol skills locate `.mnemon` through the harness environment, such as `MNEMON_HARNESS_DIR`. | | subagent | `curator` | Performs low-frequency review over evidence and the skill library, then proposes create, patch, consolidate, stale, archive, or restore actions. | Proposal-first by default. Approved changes are applied through `skill_manage`. | @@ -280,7 +280,7 @@ Out of scope for MVP: | Host-facing surface | Host Skill Surface | Location read by host-native skill discovery. | Generated or mounted by Prime from `.mnemon/skills/active`. | | Canonical store | `.mnemon` Skill Library | Stores active, stale, archived skills and usage evidence. | Source of truth; host-native directories are views. | | GUIDE | `GUIDE.md` | Defines evidence, review triggers, protected/pinned rules, and proposal-first policy. | Policy only; no migration. | -| setup | setup + bindings | Installs hooks, protocol skills, curator subagent, and host-native skill-surface binding. | Installation and mounting only. | +| ops | ops + bindings | Installs hooks, protocol skills, curator subagent, and host-native skill-surface binding. | Installation and mounting only. | | hook | `prime/remind/nudge/compact` | Provides sync, observation reminders, and low-frequency review boundaries. | Timing only; rules stay in GUIDE. | | protocol | `skill_observe` / `skill_curate` / `skill_manage` | Defines observe, curate, and manage procedures. | Uses harness environment to locate `.mnemon`. | | subagent | curator | Performs low-frequency review, consolidation, proposals, and reports. | Proposal-first; approved changes flow through `skill_manage`. | diff --git a/docs/site/index.html b/docs/site/index.html index 5c5587a..c9c0009 100644 --- a/docs/site/index.html +++ b/docs/site/index.html @@ -151,7 +151,7 @@

Mnemon documentation

- +

Memory Loop MVP

Architecture, assets, hooks, and runtime data flow for the memory loop.

@@ -159,7 +159,7 @@

Memory Loop MVP

Open site - +

Skill Loop MVP

Entities, skill state surfaces, curator flow, and runtime data flow for the skill loop.

diff --git a/docs/site/lifecycle-control-plane/index.html b/docs/site/lifecycle-control-plane/index.html index e67a46a..75c2fde 100644 --- a/docs/site/lifecycle-control-plane/index.html +++ b/docs/site/lifecycle-control-plane/index.html @@ -704,12 +704,12 @@

Entity Profiles

Template reusable definition - 定义可复用能力，不一定被持续 reconcile。例：LoopModule。 + 定义可复用能力，不一定被持续 reconcile。例：Loop。
Controlled spec / status - 需要持续对齐 Intent 与 Reality。例：LoopBinding、EvalRun、未来 Goal。 + 需要持续对齐 Intent 与 Reality。例：Binding、EvalRun、未来 Goal。
Surface @@ -745,14 +745,14 @@

当前实体映射

- LoopModule + Loop Template - 可复用生命周期能力包，例如 memory-loop、skill-loop、eval-loop。 + 可复用生命周期能力包，例如 memory、skill、eval。 - LoopBinding + Binding Controlled - 把某个 LoopModule 绑定到某个 host；适合作为第一个完整 controlled object 样本。 + 把某个 Loop 绑定到某个 host；适合作为第一个完整 controlled object 样本。 HostCapability @@ -817,7 +817,7 @@

Observation

Memory-loop 给出的证据

-

memory-loop 不是全部答案，但它验证了 Mnemon 的方法论。

+

memory 不是全部答案，但它验证了 Mnemon 的方法论。

@@ -983,12 +983,12 @@

Entity Profiles

Template reusable definition - Defines reusable capability and is not necessarily reconciled. Example: LoopModule. + Defines reusable capability and is not necessarily reconciled. Example: Loop.
Controlled spec / status - Needs ongoing alignment of Intent and Reality. Examples: LoopBinding, EvalRun, future Goal. + Needs ongoing alignment of Intent and Reality. Examples: Binding, EvalRun, future Goal.
Surface @@ -1024,14 +1024,14 @@

Current Entities

- + - + - + - + @@ -1096,7 +1096,7 @@

Observation

What Memory-loop Proved

-

memory-loop is not the whole answer, but it validated Mnemon's method.

+

memory is not the whole answer, but it validated Mnemon's method.

LoopModuleLoop TemplateReusable lifecycle capability package such as memory-loop, skill-loop, eval-loop.Reusable lifecycle capability package such as memory, skill, eval.
LoopBindingBinding ControlledBinds one LoopModule to one host; suitable as the first full controlled object sample.Binds one Loop to one host; suitable as the first full controlled object sample.
HostCapability
diff --git a/docs/site/memory-loop/index.html b/docs/site/memory/index.html similarity index 97% rename from docs/site/memory-loop/index.html rename to docs/site/memory/index.html index 94371c0..c534b94 100644 --- a/docs/site/memory-loop/index.html +++ b/docs/site/memory/index.html @@ -760,15 +760,15 @@

summary: "Memory-loop 是生命周期控制平面的第一个完整证明：Mnemon 保存记忆 State，声明跨生命周期可用的记忆 Intent，观察 HostAgent 的 Reality，并通过 Reconcile 决定 read、write、compact、consolidate 或 no-op。", readingTitle: "阅读顺序", reading: [ - "先看 memory-loop 如何落入 State / Intent / Reality / Reconcile。", + "先看 memory 如何落入 State / Intent / Reality / Reconcile。", "再看热记忆、冷记忆和执行 surface 如何协作。", "最后切换阶段，看每个 lifecycle boundary 如何触发 read、write 或 consolidation。" ], controlTitle: "生命周期控制位置", - controlIntro: "memory-loop 不是一个外部 memory service，而是一个 lifecycle-native capability。它把热记忆、冷记忆、hook、protocol 和 dreaming 放进同一个控制闭环。", + controlIntro: "memory 不是一个外部 memory service，而是一个 lifecycle-native capability。它把热记忆、冷记忆、hook、protocol 和 dreaming 放进同一个控制闭环。", controlFeedback: "Memory status and durable state feed the next lifecycle pass.", controlSteps: [ - { name: "State", color: "var(--longterm)", text: ".mnemon 保存 MEMORY.md、Mnemon store、reports、manifests 和 memory-loop status。" }, + { name: "State", color: "var(--longterm)", text: ".mnemon 保存 MEMORY.md、Mnemon store、reports、manifests 和 memory status。" }, { name: "Intent", color: "var(--guide)", text: "记忆应该在 Prime、Remind、Nudge、Compact 和 maintenance 中帮助 HostAgent 保持连续性。" }, { name: "Projection", color: "var(--hook)", text: "GUIDE、hooks、memory_get、memory_set、dreaming 和 env 被投影成 host-readable surface。" }, { name: "Reality", color: "var(--host)", text: "Host prompt、当前任务、上下文压力、recall/write 结果和 stale working memory 构成现实状态。" }, @@ -912,7 +912,7 @@

["Memory pattern", "hot <-> cold contract", "协调 LLM-native 热记忆与 system-native 冷记忆。", "MEMORY.md 和 Mnemon 是第一组选择，不是唯一选择。", "var(--capability)"], ["Retrieval tools", "web/docs/code/RAG search", "查询外部知识源，补充当前任务资料。", "默认不是 memory；只有内化为持久状态后才写入记忆。", "var(--host)"], ["Intent policy", "GUIDE.md", "说明何时读写记忆、什么值得保留。", "只定义 policy，不绑定存储目标。", "var(--guide)"], - ["setup", "harness/setup + env.sh", "安装四个 hook、两个 protocol skills、dreaming subagent、memory 文件和环境变量。", "只负责挂载，并设置 MNEMON_MEMORY_LOOP_DIR。", "var(--guide)"], + ["ops", "harness/ops + env.sh", "安装四个 hook、两个 protocol skills、dreaming subagent、memory 文件和环境变量。", "只负责挂载，并设置 MNEMON_MEMORY_LOOP_DIR。", "var(--guide)"], ["hook", "prime/remind/nudge/compact", "提供宿主生命周期触发点。", "只给时机和短提醒，不承载记忆协议。", "var(--hook)"], ["reconcile protocol", "memory_get.md / memory_set.md", "提供读长期记忆和写工作记忆的在线方法。", "绑定 Mnemon recall 与 MEMORY.md 编辑规则。", "var(--capability)"], ["maintenance reconciler", "dreaming", "维护、巩固和清理工作记忆。", "绑定 Mnemon write 与 MEMORY.md compact / eviction。", "var(--capability)"] @@ -922,18 +922,18 @@

langAttr: "en", title: "Memory Loop MVP", eyebrow: "Mnemon Harness / Memory Loop", - summary: "memory-loop is the first complete proof of the lifecycle control plane: Mnemon keeps memory State, declares continuity Intent across lifecycle boundaries, observes HostAgent Reality, and Reconciles by reading, writing, compacting, consolidating, or no-oping.", + summary: "memory is the first complete proof of the lifecycle control plane: Mnemon keeps memory State, declares continuity Intent across lifecycle boundaries, observes HostAgent Reality, and Reconciles by reading, writing, compacting, consolidating, or no-oping.", readingTitle: "Reading Order", reading: [ - "Start with how memory-loop maps to State / Intent / Reality / Reconcile.", + "Start with how memory maps to State / Intent / Reality / Reconcile.", "Then read how hot memory, cold memory, and execution surfaces cooperate.", "Finally switch phases to see how each lifecycle boundary triggers read, write, or consolidation." ], controlTitle: "Lifecycle Control Position", - controlIntro: "memory-loop is not an external memory service. It is a lifecycle-native capability that puts hot memory, cold memory, hooks, protocols, and dreaming inside one control loop.", + controlIntro: "memory is not an external memory service. It is a lifecycle-native capability that puts hot memory, cold memory, hooks, protocols, and dreaming inside one control loop.", controlFeedback: "Memory status and durable state feed the next lifecycle pass.", controlSteps: [ - { name: "State", color: "var(--longterm)", text: ".mnemon keeps MEMORY.md, Mnemon stores, reports, manifests, and memory-loop status." }, + { name: "State", color: "var(--longterm)", text: ".mnemon keeps MEMORY.md, Mnemon stores, reports, manifests, and memory status." }, { name: "Intent", color: "var(--guide)", text: "Memory should help the HostAgent preserve continuity across Prime, Remind, Nudge, Compact, and maintenance." }, { name: "Projection", color: "var(--hook)", text: "GUIDE, hooks, memory_get, memory_set, dreaming, and env are projected as host-readable surfaces." }, { name: "Reality", color: "var(--host)", text: "The host prompt, current task, context pressure, recall/write outcomes, and stale working memory form observed reality." }, @@ -1077,7 +1077,7 @@

["Memory pattern", "hot <-> cold contract", "Coordinates LLM-native hot memory with system-native cold memory.", "MEMORY.md and Mnemon are first choices, not the only choices.", "var(--capability)"], ["Retrieval tools", "web/docs/code/RAG search", "Queries external knowledge sources for the current task.", "Not memory by default; write only internalized durable state into memory.", "var(--host)"], ["Intent policy", "GUIDE.md", "Explains when to read or write memory and what is worth keeping.", "Defines policy only, not storage targets.", "var(--guide)"], - ["setup", "harness/setup + env.sh", "Installs four hooks, two protocol skills, the dreaming subagent, memory files, and environment variables.", "Mounts assets and sets MNEMON_MEMORY_LOOP_DIR.", "var(--guide)"], + ["ops", "harness/ops + env.sh", "Installs four hooks, two protocol skills, the dreaming subagent, memory files, and environment variables.", "Mounts assets and sets MNEMON_MEMORY_LOOP_DIR.", "var(--guide)"], ["hook", "prime/remind/nudge/compact", "Provides host lifecycle trigger points.", "Provides timing and short reminders only, not memory protocols.", "var(--hook)"], ["reconcile protocol", "memory_get.md / memory_set.md", "Provides the online methods for long-term recall and working-memory writes.", "Binds Mnemon recall and MEMORY.md editing rules.", "var(--capability)"], ["maintenance reconciler", "dreaming", "Maintains, consolidates, and cleans working memory.", "Binds Mnemon write with MEMORY.md compaction and eviction.", "var(--capability)"] @@ -1086,7 +1086,7 @@

}; const PHASE_ORDER = ["prime", "recall", "nudge", "compact", "dreaming"]; - const LANGUAGE_STORAGE_KEY = "mnemon-memory-loop-lang"; + const LANGUAGE_STORAGE_KEY = "mnemon-memory-lang"; const savedLang = readStoredLanguage(); let lang = COPY[savedLang] ? savedLang : ((navigator.language || "").toLowerCase().startsWith("zh") ? "zh" : "en"); let activeId = "prime"; diff --git a/docs/site/skill-loop/index.html b/docs/site/skill/index.html similarity index 96% rename from docs/site/skill-loop/index.html rename to docs/site/skill/index.html index d16ea07..9aa5776 100644 --- a/docs/site/skill-loop/index.html +++ b/docs/site/skill/index.html @@ -773,18 +773,18 @@

langAttr: "zh-CN", title: "Skill Loop MVP", eyebrow: "Mnemon Harness / Skill Loop", - summary: "skill-loop 把 skill visibility 和 skill lifecycle state 做成 lifecycle-native capability：Mnemon 保存 skill State，声明可见性 Intent，观察 HostAgent 的 skill Reality，并通过 Reconcile 执行 observe、curate、propose、manage 或 no-op。", + summary: "skill 把 skill visibility 和 skill lifecycle state 做成 lifecycle-native capability：Mnemon 保存 skill State，声明可见性 Intent，观察 HostAgent 的 skill Reality，并通过 Reconcile 执行 observe、curate、propose、manage 或 no-op。", readingTitle: "阅读顺序", reading: [ - "先看 skill-loop 如何映射 State、Intent、Projection、Reality、Reconcile。", + "先看 skill 如何映射 State、Intent、Projection、Reality、Reconcile。", "再看 host skill surface 与 `.mnemon` canonical library 如何分工。", "最后切换阶段，看 Prime、Nudge、Observe、Curator、Manage 如何形成闭环。" ], controlTitle: "生命周期控制位置", - controlIntro: "skill-loop 不替换宿主的 skill runtime。它把可见性、证据和迁移状态纳入同一条生命周期主干：保存状态，声明意图，投影给宿主，观察现实，再对齐差距。", + controlIntro: "skill 不替换宿主的 skill runtime。它把可见性、证据和迁移状态纳入同一条生命周期主干：保存状态，声明意图，投影给宿主，观察现实，再对齐差距。", controlFeedback: "Reconcile 的结果写回 State；canonical skill state 保留在 .mnemon，宿主 skill surface 只是 active skill 的 projection。", controlSteps: [ - { name: "State", color: "var(--library)", text: "`.mnemon` skill library 保存 active/stale/archived、usage evidence、proposal、report 和 skill-loop status。" }, + { name: "State", color: "var(--library)", text: "`.mnemon` skill library 保存 active/stale/archived、usage evidence、proposal、report 和 skill status。" }, { name: "Intent", color: "var(--guide)", text: "当前应该可见的 skill 集合，以及 stale/archived 应如何保留、审阅、恢复或隔离。" }, { name: "Projection", color: "var(--active)", text: "Prime 把 active skills 同步、挂载或渲染到 `.codex/skills`、`.claude/skills` 等 host-native surface。" }, { name: "Reality", color: "var(--host)", text: "HostAgent 实际发现和使用了哪些 skill，哪些缺失、误导、过期，哪些流程重复出现。" }, @@ -843,7 +843,7 @@

prime: { title: "Prime", tag: "hook", - summary: "Prime 是 skill-loop 的 Projection 边界。它不把所有 skill 内容注入 prompt，而是把 canonical State 中的 active 集合投影到 HostAgent 原生 skill 发现面。", + summary: "Prime 是 skill 的 Projection 边界。它不把所有 skill 内容注入 prompt，而是把 canonical State 中的 active 集合投影到 HostAgent 原生 skill 发现面。", short: "active skills -> host surface", events: [ { kind: "arrow", from: "library", to: "surface", y: 94, label: "sync active skills" }, @@ -932,7 +932,7 @@

["Projection surface", "Host Skill Surface", "HostAgent 原生 skill discovery 读取的位置。", "由 Prime 从 `.mnemon/skills/active` 单向同步或挂载生成。", "var(--active)"], ["Skill State", ".mnemon Skill Library", "保存 active/stale/archived skills、usage evidence、proposal 和 report。", "canonical source of truth，host-native 目录只是 generated view。", "var(--library)"], ["Intent policy", "GUIDE", "定义 skill evidence、review trigger、protected/pinned、proposal-first 等判断规则。", "只定义 policy，不执行迁移。", "var(--guide)"], - ["setup", "setup + bindings", "安装 hooks、protocol skills、curator subagent，并配置 host-native skill surface binding。", "只负责挂载，不参与每次 runtime 判断。", "var(--setup)"], + ["ops", "ops + bindings", "安装 hooks、protocol skills、curator subagent，并配置 host-native skill surface binding。", "只负责挂载，不参与每次 runtime 判断。", "var(--setup)"], ["hook", "prime/remind/nudge/compact", "提供同步、观察提醒和低频 review 触发边界；Remind 通常 no-op。", "只给时机和短提醒，规则在 GUIDE 中。", "var(--hook)"], ["Reconcile protocol", "skill_observe / skill_manage / skill_curate", "定义 observe/manage/curate 的跨 HostAgent 操作方法。", "通过 `MNEMON_HARNESS_DIR` 定位 `.mnemon`。", "var(--protocol)"], ["Maintenance reconciler", "curator", "低频审阅、合并、迁移和报告。", "默认 proposal-first；批准后由 skill_manage 修改状态。", "var(--curator)"] @@ -942,18 +942,18 @@

langAttr: "en", title: "Skill Loop MVP", eyebrow: "Mnemon Harness / Skill Loop", - summary: "skill-loop turns skill visibility and skill lifecycle state into a lifecycle-native capability: Mnemon keeps skill State, declares visibility Intent, observes HostAgent skill Reality, and Reconciles by observing, curating, proposing, managing, or no-oping.", + summary: "skill turns skill visibility and skill lifecycle state into a lifecycle-native capability: Mnemon keeps skill State, declares visibility Intent, observes HostAgent skill Reality, and Reconciles by observing, curating, proposing, managing, or no-oping.", readingTitle: "Reading Order", reading: [ - "Start with how skill-loop maps to State, Intent, Projection, Reality, and Reconcile.", + "Start with how skill maps to State, Intent, Projection, Reality, and Reconcile.", "Then read how the host skill surface and `.mnemon` canonical library divide responsibility.", "Finally switch phases to see how Prime, Nudge, Observe, Curator, and Manage close the loop." ], controlTitle: "Lifecycle Control Position", - controlIntro: "skill-loop does not replace the host skill runtime. It puts visibility, evidence, and migration state on one lifecycle path: keep state, declare intent, project into the host, observe reality, and reconcile the gap.", + controlIntro: "skill does not replace the host skill runtime. It puts visibility, evidence, and migration state on one lifecycle path: keep state, declare intent, project into the host, observe reality, and reconcile the gap.", controlFeedback: "Reconcile writes results back into State; canonical skill state remains in .mnemon, while the host skill surface is only the active-skill projection.", controlSteps: [ - { name: "State", color: "var(--library)", text: "The `.mnemon` skill library stores active/stale/archived skills, usage evidence, proposals, reports, and skill-loop status." }, + { name: "State", color: "var(--library)", text: "The `.mnemon` skill library stores active/stale/archived skills, usage evidence, proposals, reports, and skill status." }, { name: "Intent", color: "var(--guide)", text: "The skills that should be visible now, plus how stale and archived skills should be preserved, reviewed, restored, or isolated." }, { name: "Projection", color: "var(--active)", text: "Prime syncs, mounts, or renders active skills into host-native surfaces such as `.codex/skills` or `.claude/skills`." }, { name: "Reality", color: "var(--host)", text: "What the HostAgent actually discovered and used, what was missing or misleading, and which workflows repeated." }, @@ -1012,7 +1012,7 @@

prime: { title: "Prime", tag: "hook", - summary: "Prime is the skill-loop Projection boundary. It does not inject every skill body into the prompt; it projects the active set from canonical State into the host-native discovery surface.", + summary: "Prime is the skill Projection boundary. It does not inject every skill body into the prompt; it projects the active set from canonical State into the host-native discovery surface.", short: "active skills -> host surface", events: [ { kind: "arrow", from: "library", to: "surface", y: 94, label: "sync active skills" }, @@ -1101,7 +1101,7 @@

["Projection surface", "Host Skill Surface", "The location read by host-native skill discovery.", "Generated or mounted by Prime from `.mnemon/skills/active`.", "var(--active)"], ["Skill State", ".mnemon Skill Library", "Stores active/stale/archived skills, usage evidence, proposals, and reports.", "Canonical source of truth; host-native directories are generated views.", "var(--library)"], ["Intent policy", "GUIDE", "Defines skill evidence, review triggers, protected/pinned rules, and proposal-first policy.", "Defines policy only; it does not migrate state.", "var(--guide)"], - ["setup", "setup + bindings", "Installs hooks, protocol skills, curator subagent, and host-native skill surface bindings.", "Mounts assets only; it does not participate in each runtime decision.", "var(--setup)"], + ["ops", "ops + bindings", "Installs hooks, protocol skills, curator subagent, and host-native skill surface bindings.", "Mounts assets only; it does not participate in each runtime decision.", "var(--setup)"], ["hook", "prime/remind/nudge/compact", "Provides sync, observation reminders, and low-frequency review trigger boundaries; Remind is usually a no-op.", "Provides timing and short reminders only; rules live in GUIDE.", "var(--hook)"], ["Reconcile protocol", "skill_observe / skill_manage / skill_curate", "Defines cross-HostAgent methods for observe, manage, and curate.", "Locates `.mnemon` through `MNEMON_HARNESS_DIR`.", "var(--protocol)"], ["Maintenance reconciler", "curator", "Performs low-frequency review, consolidation, migration, and reports.", "Proposal-first by default; approved changes are applied by skill_manage.", "var(--curator)"] @@ -1117,7 +1117,7 @@

curate: "var(--curator)", manage: "var(--protocol)" }; - const LANGUAGE_STORAGE_KEY = "mnemon-skill-loop-lang"; + const LANGUAGE_STORAGE_KEY = "mnemon-skill-lang"; const savedLang = readStoredLanguage(); let lang = COPY[savedLang] ? savedLang : ((navigator.language || "").toLowerCase().startsWith("zh") ? "zh" : "en"); let activeId = "prime"; diff --git a/docs/zh/README.md b/docs/zh/README.md index afdcdbf..d563858 100644 --- a/docs/zh/README.md +++ b/docs/zh/README.md @@ -196,7 +196,7 @@ MNEMON_STORE=work mnemon recall "query" # 或按进程使用环境变量 `mnemon setup` 默认**本地**（项目级 `.claude/`），适合大多数用户。**全局**（`mnemon setup --global`，安装到 `~/.claude/`）在所有项目中激活 mnemon — 如果想让其他框架（如 OpenClaw）通过 Claude Code CLI 共享记忆很方便，但可能增加维护开销。 **如何自定义行为？** -编辑当前 setup 流程生成的 guideline（`~/.mnemon/prompt/guide.md`），或以可安装的 [memory loop GUIDE](../../harness/modules/memory-loop/GUIDE.md) 作为来源。Skill 文件应专注于命令语法。 +编辑当前 setup 流程生成的 guideline（`~/.mnemon/prompt/guide.md`），或以可安装的 [memory loop GUIDE](../../harness/loops/memory/GUIDE.md) 作为来源。Skill 文件应专注于命令语法。 **什么是 Sub-agent 委派？** Sub-agent 委派是可选执行策略。当 runtime 支持时，主 agent 可以决定*记什么*，再让更便宜或隔离的 worker 执行 `mnemon remember`。它有用，但不是 Mnemon 架构必需品。 @@ -230,8 +230,8 @@ make help # 显示所有目标 ## 文档 - [Modular Self-Evolution Harness](harness/README.md) — modular agent、memory loop 与 skill loop 的正式 harness 文档 -- [Memory Loop Harness](../../harness/modules/memory-loop/README.md) — 可安装 memory loop 资产 -- [Skill Loop Harness](../../harness/modules/skill-loop/README.md) — 可安装 skill loop 资产 +- [Memory Loop Harness](../../harness/loops/memory/README.md) — 可安装 memory loop 资产 +- [Skill Loop Harness](../../harness/loops/skill/README.md) — 可安装 skill loop 资产 - [设计与架构](DESIGN.md) — 当前 engine architecture、核心概念、算法、集成设计 - [用法与参考](USAGE.md) — CLI 命令、嵌入向量支持、架构概览 - [架构图](../diagrams/) — 系统架构、记忆/召回流程、四图模型、生命周期管理 diff --git a/docs/zh/harness/HOST_PROJECTION.md b/docs/zh/harness/HOST_PROJECTION.md index 0926d63..9a3beca 100644 --- a/docs/zh/harness/HOST_PROJECTION.md +++ b/docs/zh/harness/HOST_PROJECTION.md @@ -2,10 +2,10 @@ 英文版本：[HOST_PROJECTION.md](../../harness/HOST_PROJECTION.md) -本文定义 Mnemon loop module 如何投影到具体宿主 runtime，例如 Claude Code、 +本文定义 Mnemon loop template 如何投影到具体宿主 runtime，例如 Claude Code、 Codex、OpenClaw，或未来的 app-server eval host。 -Loop Module Standard 定义 canonical package shape。Host Projection 定义这套 +Loop Standard 定义 canonical package shape。Host Projection 定义这套 package 如何在某个宿主 runtime 中变得可见、可执行。 ## 原则 @@ -14,9 +14,9 @@ Mnemon 把 canonical harness state 保存在 `.mnemon`。宿主目录只保存 ```text .mnemon/ - canonical state, loop modules, reports, proposals, audit + canonical state, loop templates, reports, proposals, audit | - | 由 setup/ 投影 + | 由 harness/hosts/ 通过 harness/ops 投影 v .claude/ or .codex/ 宿主可读的 skills、hooks、config，以及指回 .mnemon 的路径 @@ -28,17 +28,22 @@ host runtime Projection adapter 不应该制造另一份真实状态。它只渲染足够的宿主原生文件， 让宿主能够发现和使用 loop，同时把持久状态保留在 `.mnemon` 下。 +Projection 和 observation 是两个方向。Projection 让宿主看见 Mnemon 的 +Intent；observation 让 Mnemon 看见足够的 Reality，用于写 status、收集 evidence， +并支撑未来 reconcile。 + ## 职责 Host projection adapter 负责： | 职责 | 说明 | | --- | --- | -| Path resolution | 解析 project root、host config directory、canonical `.mnemon`、active store 和 loop module path。 | +| Path resolution | 解析 project root、host config directory、canonical `.mnemon`、active store 和 loop template path。 | | Asset projection | 渲染或复制宿主可读的 GUIDE、hooks、protocol skills 和 subagents。 | | Hook registration | 当宿主支持时，注册宿主生命周期 hooks。 | | Environment injection | 让 `MNEMON_DATA_DIR`、`MNEMON_STORE`、`MNEMON_HARNESS_DIR` 和 loop-specific env 对 hooks 和 skills 可见。 | | Manifest writing | 在 `.mnemon/hosts//manifest.json` 记录投影了什么、投影到哪里。 | +| Status writing | 在 `.mnemon/harness//status.json` 记录已安装 loop 的 control model。 | | Validation | 检测缺失资产、过期 projection、不兼容宿主能力和路径冲突。 | | Uninstall | 删除宿主 projection 文件，默认保留 canonical `.mnemon` 状态。 | @@ -48,7 +53,7 @@ Host projection adapter 不应该： - 重新实现 Mnemon memory storage 或 retrieval。 - 把 canonical state 移动到 `.claude`、`.codex` 或其他宿主目录。 -- 把宿主特定行为隐藏在 loop module 根目录文件里。 +- 把宿主特定行为隐藏在 loop template 根目录文件里。 - 修改声明区域之外的用户宿主配置。 - 删除 memory、reports、proposals 或 audit records，除非用户显式要求破坏性清理。 @@ -61,8 +66,10 @@ Host projection adapter 不应该： ├── data/ │ └── /mnemon.db ├── harness/ -│ ├── memory-loop/ -│ └── skill-loop/ +│ ├── memory/ +│ │ └── status.json +│ └── skill/ +│ └── status.json ├── reports/ ├── proposals/ ├── audit/ @@ -155,21 +162,28 @@ event，adapter 应选择最接近且安全的边界，并在 host manifest 中 ```json { - "schema_version": 1, + "schema_version": 2, "host": "codex", - "installed_at": "2026-05-14T00:00:00Z", + "updated_at": "2026-05-20T00:00:00Z", "project_root": "/path/to/project", "mnemon_dir": "/path/to/project/.mnemon", "store": "default", "loops": { - "memory-loop": { - "module_path": ".mnemon/harness/memory-loop", - "module_version": "0.1.0", - "projection_path": ".codex", - "projected_assets": { - "skills": [".codex/skills/memory_get.md"], - "hooks": [".codex/hooks/prime.sh"], - "subagents": [] + "memory": { + "loop_path": ".mnemon/harness/memory", + "loop_version": "0.1.0", + "state_path": ".mnemon/harness/memory", + "intent_policy": ".mnemon/harness/memory/GUIDE.md", + "status_path": ".mnemon/harness/memory/status.json", + "projection": { + "path": ".codex", + "surfaces": ["GUIDE.md", "hooks", "memory_get", "memory_set", "runtime env"] + }, + "reality": { + "surfaces": ["hook output", "MEMORY.md length", "recall results", "write outcomes"] + }, + "reconcile": { + "actions": ["read", "write", "compact", "consolidate", "no-op"] }, "lifecycle_mapping": { "prime": "session-init", @@ -182,7 +196,9 @@ event，adapter 应选择最接近且安全的边界，并在 host manifest 中 } ``` -Manifest 是 setup、status、uninstall 和 eval tooling 之间的桥。 +Manifest 是 ops、status、uninstall、eval tooling 和未来 reconcile tooling 之间的桥。 +每个已安装 loop 也会在 canonical state 目录写入 `status.json`，这样不读取宿主配置 +也能检查 loop-local state。 ## Setup Contract @@ -190,15 +206,17 @@ Manifest 是 setup、status、uninstall 和 eval tooling 之间的桥。 ```text install - validate loop module manifests + validate loop manifests resolve canonical .mnemon install canonical loop assets if needed render host projection register hooks/config write host manifest + write loop status status read host manifest + read loop status validate projected files exist validate registered hooks/config report stale or missing projections @@ -221,7 +239,7 @@ App-server eval host 是用于测试 loop 行为的一次性宿主 runtime。它 eval orchestrator | | create isolated workspace and .mnemon - | run setup//install + | run harness/ops/install.sh | start host app server v host app server @@ -238,7 +256,7 @@ Eval 应测试 harness influence 下的 host behavior，而不是只测试 Mnemo 有价值的断言包括： - App server 使用隔离的 `.mnemon`。 -- 安装了预期版本的 loop modules。 +- 安装了预期版本的 loop templates。 - Lifecycle events 通过 manifest 声明的 mapping 被调用。 - Recall decisions 影响后续任务行为。 - Writeback decisions 只在合理时写入 durable memory。 @@ -247,9 +265,8 @@ Eval 应测试 harness influence 下的 host behavior，而不是只测试 Mnemo ## 质量规则 - Projection files 应保持小而明确，并从 canonical assets 生成。 -- Host-specific behavior 放在 `setup//` 或生成的 adapter files。 +- Host-specific behavior 放在 `harness/hosts//` 或生成的 adapter files。 - Setup 应尽可能可重复、幂等。 - Uninstall 应保守，默认保留 canonical state。 - Manifest paths 尽可能使用相对路径；只有 runtime execution 需要时才使用绝对路径。 - 公开 projection 行为必须同时维护英文和中文文档。 - diff --git a/docs/zh/harness/LIFECYCLE_CONTROL_PLANE.md b/docs/zh/harness/LIFECYCLE_CONTROL_PLANE.md index 988c648..13f4d6d 100644 --- a/docs/zh/harness/LIFECYCLE_CONTROL_PLANE.md +++ b/docs/zh/harness/LIFECYCLE_CONTROL_PLANE.md @@ -37,7 +37,7 @@ Execution surfaces 不属于核心模型。它们属于执行层：它们说明 | Profile | 含义 | 示例 | | --- | --- | --- | -| Template | 可复用定义，不一定被持续 reconcile。 | `LoopModule` | +| Template | 可复用定义，不一定被持续 reconcile。 | `Loop` | | Controlled | 需要持续对齐 Intent 与 Reality。 | `LoopBinding`、`EvalRun`、未来 `Goal` | | Surface | 表达或触达宿主能力。 | `HostCapability`、`Projection` | | Evidence | 来自 Reality 的观测事实，不是声明对象。 | `Observation`、runtime status | @@ -50,8 +50,8 @@ Execution surfaces 不属于核心模型。它们属于执行层：它们说明 | Entity | Profile | 作用 | | --- | --- | --- | -| `LoopModule` | Template | 可复用 lifecycle capability package，例如 memory-loop、skill-loop、eval-loop。 | -| `LoopBinding` | Controlled | 把某个 `LoopModule` 绑定到某个 host；适合作为第一个完整 controlled object 样本。 | +| `Loop` | Template | 可复用 lifecycle capability package，例如 memory、skill、eval。 | +| `Binding` | Controlled | 把某个 `Loop` 绑定到某个 host；适合作为第一个完整 controlled object 样本。 | | `HostCapability` | Surface | 描述宿主可以暴露的静态或动态能力。 | | `Projection` | Surface | 让 HostAgent 看见 Mnemon 的 Intent。 | | `Observation` | Evidence | 让 Mnemon 看见 HostAgent 的 Reality。 | @@ -94,7 +94,7 @@ Observation 让 Mnemon 看见 HostAgent Reality。 Mnemon 的方法，是把通常被做成重外部系统的能力，通过 hooks、skills、daemon work、 canonical state 和 reconcile，重新引入宿主生命周期。 -`memory-loop` 已经用 memory 验证了这个模式： +`memory` 已经用 memory 验证了这个模式： ```text external memory service @@ -144,4 +144,4 @@ Mnemon 应该沿着轻量能力层级增长： | Governance | AI 可以产生 patch、report 和 proposal，由 review gate 控制风险。 | 目标不是复制一个大型控制系统，而是形成一个小而一致的 lifecycle model，从 -memory-loop 延展到自演进的 agentic projects。 +memory 延展到自演进的 agentic projects。 diff --git a/docs/zh/harness/LOOP_MODULE_STANDARD.md b/docs/zh/harness/LOOP_STANDARD.md similarity index 64% rename from docs/zh/harness/LOOP_MODULE_STANDARD.md rename to docs/zh/harness/LOOP_STANDARD.md index 7dbecfa..0ad02ae 100644 --- a/docs/zh/harness/LOOP_MODULE_STANDARD.md +++ b/docs/zh/harness/LOOP_STANDARD.md @@ -1,38 +1,37 @@ -# Loop Module Standard +# Loop Standard -英文版本：[LOOP_MODULE_STANDARD.md](../../harness/LOOP_MODULE_STANDARD.md) +英文版本：[LOOP_STANDARD.md](../../harness/LOOP_STANDARD.md) -本文定义 Mnemon harness loop module 的标准结构。这个标准与宿主无关。 +本文定义 Mnemon harness loop template 的标准结构。这个标准与宿主无关。 Claude Code、Codex、OpenClaw 或未来 runtime 都应该通过各自的 host projection -adapter 使用同一套 loop module。 +adapter 使用同一套 loop template。 ## 核心模型 -Mnemon 把 canonical harness state 和 host runtime projection 分开： +Mnemon 对每个可安装 loop 使用 lifecycle control model： ```text -.mnemon canonical state - | - | 由 host adapter 投影 - v -.claude / .codex / 其他宿主配置 - | - v -host runtime +State(.mnemon loop state) + -> Intent(loop policy and desired visibility) + -> Projection(host-readable skills, hooks, env, config) + -> Reality(host behavior, evidence, drift, reports) + -> Reconcile(loop action or no-op) + -> State(updated status and durable state) ``` -Loop module 拥有 policy、lifecycle reminders、protocol skills、maintenance -agents、environment contract 和 setup adapters。宿主 runtime 拥有 conversation -loop、prompt assembly、tool routing、native skill discovery、权限模型和 UI。 +Loop template 拥有 State contract、Intent policy、host-facing projection assets、 +observation surfaces、reconcile actions、environment contracts 和 maintenance +roles。宿主 runtime 拥有 conversation loop、prompt assembly、tool routing、native +skill discovery、权限模型和 UI。 ## 标准目录 -每个可安装 loop module 应该遵循这个结构： +每个可安装 loop template 应该遵循这个结构： ```text -harness/modules// +harness/loops// ├── README.md -├── module.json +├── loop.json ├── env.sh ├── GUIDE.md ├── hooks/ @@ -46,7 +45,7 @@ harness/modules// │ └── .md ``` -Host-specific projection logic 位于 modules 之外： +Host-specific projection logic 位于 loops 之外： ```text harness/hosts// @@ -55,10 +54,10 @@ harness/hosts// └── scripts/ ``` -Shared setup entrypoints 负责组合 modules 和 hosts： +Shared ops entrypoints 负责组合 loops 和 hosts： ```text -harness/setup/ +harness/ops/ ├── install.sh ├── status.sh └── uninstall.sh @@ -71,13 +70,13 @@ harness/setup/ | 概念 | 是否必需 | 作用 | | --- | --- | --- | -| `module.json` | 是 | 机器可读的 loop identity、资产声明、state 目录、lifecycle events 和已支持 host adapters。 | +| `loop.json` | 是 | 机器可读的 loop identity、control model、entity profiles、projection/observation surfaces、资产声明、state 目录、lifecycle events 和已支持 host adapters。 | | `GUIDE.md` | 是 | 定义 loop 何时应该行动、宿主 agent 应该如何判断，以及哪些内容不属于该 loop。 | | `env.sh` | 是 | scripts、hooks、protocol skills 和 maintenance agents 使用的运行时路径契约。 | | `hooks/*.md` | 是 | 与宿主无关的 lifecycle reminders。描述 agent 在生命周期边界应考虑什么。 | | `skills/*.md` | 通常是 | 用于在线可复用操作的 protocol skills。它们定义流程，不定义宿主安装方式。 | | `subagents/*.md` | 可选 | 用于较重 review、consolidation 或 proposal generation 的维护角色。没有 native subagent 的宿主可以降级为人工或定时 job。 | -| `harness/hosts//` | 整体至少一个 host | Host-specific projection adapter，把 modules 安装或移除到某个宿主 runtime。 | +| `harness/hosts//` | 整体至少一个 host | Host-specific projection adapter，把 loops 安装或移除到某个宿主 runtime。 | ## 生命周期事件 @@ -97,10 +96,10 @@ lifecycle boundary，或通过 app-server eval API 显式触发。 ## Host Projection -Host projection adapter 把 canonical loop module 渲染到宿主原生 surface。投影不能制造第二份真实状态。 +Host projection adapter 把 canonical loop template 渲染到宿主原生 surface。投影不能制造第二份真实状态。 ```text -canonical loop module +canonical loop template | | install / project v @@ -128,8 +127,10 @@ Canonical state 属于 `.mnemon`，不属于某个宿主目录。`.claude` 或 ` ├── data/ │ └── /mnemon.db ├── harness/ -│ ├── memory-loop/ -│ └── skill-loop/ +│ ├── memory/ +│ │ └── status.json +│ └── skill/ +│ └── status.json ├── reports/ ├── proposals/ ├── audit/ @@ -141,20 +142,37 @@ Canonical state 属于 `.mnemon`，不属于某个宿主目录。`.claude` 或 ` └── manifest.json ``` -当前 MVP setup scripts 仍可能把 runtime files 放在 host config 目录下。新的 +当前 MVP ops scripts 仍可能把 runtime files 放在 host config 目录下。新的 adapters 应逐步转向 canonical `.mnemon` 布局，并把 host directories 只作为 projection surfaces。 ## Manifest Schema -每个 loop module 应该包含一个 `module.json` 文件，使用这个稳定结构： +每个 loop template 应该包含一个 `loop.json` 文件，使用这个稳定结构： ```json { - "schema_version": 1, - "name": "memory-loop", + "schema_version": 2, + "name": "memory", "version": "0.1.0", "description": "Connects prompt-facing working memory with Mnemon long-term memory.", + "control_model": { + "state": ["MEMORY.md", ".mnemon stores", "reports", "memory status"], + "intent": "Keep useful continuity available across lifecycle boundaries.", + "reality": ["host prompt", "current task", "recall results", "context pressure"], + "reconcile": ["read", "write", "compact", "consolidate", "no-op"] + }, + "entity_profiles": { + "template": "memory", + "controlled": ["memory binding"], + "surface": ["MEMORY.md", "Mnemon recall/write", "host hooks", "protocol skills"], + "evidence": ["recall usefulness", "write results", "context pressure"], + "governance": ["memory proposals", "memory audits"] + }, + "surfaces": { + "projection": ["GUIDE.md", "hooks", "memory_get", "memory_set", "dreaming", "runtime env"], + "observation": ["hook output", "MEMORY.md length", "recall results", "write outcomes"] + }, "lifecycle_events": ["prime", "remind", "nudge", "compact"], "assets": { "guide": "GUIDE.md", @@ -178,8 +196,9 @@ projection surfaces。 } ``` -在 MVP 阶段，manifest 是描述性的。后续 setup tooling 可以基于这些 metadata -验证 loop modules、生成 projections，并驱动 app-server eval。 +Manifest 现在是可执行 harness contract 的一部分。Setup tooling 会校验它， +projector 会把它复制到 canonical loop state，host manifest 会携带其中的 control +model，让 status、eval 和未来 reconcile tooling 能理解已安装 loop。 ## Adapter Mapping @@ -198,10 +217,10 @@ projection surfaces。 ## 质量规则 -- Loop modules 默认保持 host-agnostic。 -- Host-specific code 只放在 `setup//`。 +- Loop templates 默认保持 host-agnostic。 +- Host-specific code 只放在 `harness/hosts//`。 - 不要把 canonical state 复制成宿主目录下的第二份真实状态。 - 把 host directories 视为可重新生成的 projection。 -- setup、status 和 uninstall 行为必须明确、可审计。 +- ops、status 和 uninstall 行为必须明确、可审计。 - 卸载时保留用户状态，除非用户显式传入破坏性选项。 - 新增或修改公开 harness 概念时，同步维护英文和中文文档。 diff --git a/docs/zh/harness/README.md b/docs/zh/harness/README.md index 1c1c697..5acb137 100644 --- a/docs/zh/harness/README.md +++ b/docs/zh/harness/README.md @@ -8,11 +8,11 @@ Mnemon 建立在 memory-driven 原则之上：持久 agent 应该把经验转化 Mnemon 不替换宿主 agent runtime，而是通过 hooks、skills、subagents、文件系统资产和环境配置，把外置 evolution loop 挂载到已有 agent 上。 这里的核心判断是：当宿主已经拥有 ReAct loop 和可读扩展面时，大量行为层面的 -agent 能力都可以外置实现。Mnemon 把这些能力包装成 harness modules，而不是 +agent 能力都可以外置实现。Mnemon 把这些能力包装成 harness loops，而不是 重新实现一个 runtime。 -Mnemon 也不只是 skill 集合。它拥有自己的 harness runtime substrate：module -layout、setup、environment、state、reports、proposals、locks、queues、 +Mnemon 也不只是 skill 集合。它拥有自己的 harness runtime substrate：loop +layout、ops、environment、state、reports、proposals、locks、queues、 host surface projection，以及可选的 daemon scheduling。 ## 核心定位 @@ -20,54 +20,55 @@ host surface projection，以及可选的 daemon scheduling。 | 主题 | 设计 | | --- | --- | | Modular Agent Harness | [中文](modular-agent/DESIGN.md) / [EN](../../harness/modular-agent/DESIGN.md) | -| Loop Module Standard | [中文](LOOP_MODULE_STANDARD.md) / [EN](../../harness/LOOP_MODULE_STANDARD.md) | +| Loop Standard | [中文](LOOP_STANDARD.md) / [EN](../../harness/LOOP_STANDARD.md) | | Host Projection | [中文](HOST_PROJECTION.md) / [EN](../../harness/HOST_PROJECTION.md) | | Harness Roadmap | [中文](ROADMAP.md) / [EN](../../harness/ROADMAP.md) | | YC Evolving 设计哲学 | [中文](YC_EVOLVING_DESIGN_PHILOSOPHY.md) / [EN](../../harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md) | | Lifecycle Control Plane | [中文](LIFECYCLE_CONTROL_PLANE.md) / [EN](../../harness/LIFECYCLE_CONTROL_PLANE.md) / [site](../../site/lifecycle-control-plane/index.html) | -| Memory Loop | [中文](memory-loop/DESIGN.md) / [EN](../../harness/memory-loop/DESIGN.md) / [site](../../site/memory-loop/index.html) | -| Skill Loop | [中文](skill-loop/DESIGN.md) / [EN](../../harness/skill-loop/DESIGN.md) / [site](../../site/skill-loop/index.html) | -| Eval Loop | [中文](eval-loop/DESIGN.md) / [EN](../../harness/eval-loop/DESIGN.md) | +| Memory Loop | [中文](memory/DESIGN.md) / [EN](../../harness/memory/DESIGN.md) / [site](../../site/memory/index.html) | +| Skill Loop | [中文](skill/DESIGN.md) / [EN](../../harness/skill/DESIGN.md) / [site](../../site/skill/index.html) | +| Eval Loop | [中文](eval/DESIGN.md) / [EN](../../harness/eval/DESIGN.md) | ## 可安装资产 -| Harness Module | 实现 | +| Harness Loop | 实现 | | --- | --- | -| Memory Loop | [harness/modules/memory-loop](../../../harness/modules/memory-loop/README.md) | -| Skill Loop | [harness/modules/skill-loop](../../../harness/modules/skill-loop/README.md) | -| Eval Loop | [harness/modules/eval-loop](../../../harness/modules/eval-loop/README.md) | +| Memory Loop | [harness/loops/memory](../../../harness/loops/memory/README.md) | +| Skill Loop | [harness/loops/skill](../../../harness/loops/skill/README.md) | +| Eval Loop | [harness/loops/eval](../../../harness/loops/eval/README.md) | ## 仓库布局 | 目录 | 作用 | | --- | --- | -| `harness/modules/` | Canonical、host-agnostic loop modules。 | +| `harness/loops/` | Canonical、host-agnostic loop templates。 | | `harness/hosts/` | Host projection adapters，例如 Claude Code，以及后续 Codex 支持。 | -| `harness/setup/` | 统一 install、status 和 uninstall 入口，用来组合 modules 与 hosts。 | -| `harness//` | 为旧安装路径保留的兼容 wrapper。 | +| `harness/bindings/` | Loop x host binding definitions。 | +| `harness/control/` | Shared control-plane contracts。 | +| `harness/ops/` | 统一 install、status 和 uninstall 入口，用来组合 loops 与 hosts。 | ## 词汇 | 概念 | 含义 | | --- | --- | -| loop module | 一个可挂载 harness loop 的标准包结构。 | +| loop template | 一个可挂载 harness loop 的标准包结构。 | | GUIDE | Markdown policy，用来判断某个 loop 何时应该行动。 | -| setup | 安装并挂载到宿主 agent。 | +| ops | 安装、status、validate 和 uninstall 操作。 | | hook | Prime、Remind、Nudge、Compact 等宿主生命周期时机。 | | protocol | 定义可复用操作的 Markdown skill。 | | subagent | 用于较重 review 或 consolidation 的后台维护 agent。 | | projection | 把 canonical loop assets 渲染到 `.claude`、`.codex` 或其他 runtime surface 的宿主特定过程。 | | host manifest | 机器可读记录，描述已投影 loops、paths、lifecycle mappings 和 host capabilities。 | -| daemon | 可选的 harness maintenance runner，用于调度模块后台工作。 | -| substrate | Mnemon 拥有的运行时基座，用于 module state、setup、projection、scheduling 和跨模块协议。 | +| daemon | 可选的 harness maintenance runner，用于调度 loop 后台工作。 | +| substrate | Mnemon 拥有的运行时基座，用于 loop state、ops、projection、scheduling 和跨 loop 协议。 | ## 边界 -宿主 agent 保留 ReAct loop、prompt assembly、tool routing、native skill runtime、权限模型和 UI。Mnemon 提供可挂载的 harness module，让宿主 agent 获得更持久、更可自进化的能力。 +宿主 agent 保留 ReAct loop、prompt assembly、tool routing、native skill runtime、权限模型和 UI。Mnemon 提供可挂载的 harness loop，让宿主 agent 获得更持久、更可自进化的能力。 简言之：宿主 agent 是 execution runtime；Mnemon 是 harness runtime substrate。 Claude Code 是第一个 reference host，因为它提供 hooks、skills 和 subagents。这个架构的目标不局限于 Claude Code。 -`mnemon-daemon` 后续可以作为 harness module 的后台维护 runner。它属于 +`mnemon-daemon` 后续可以作为 harness loop 的后台维护 runner。它属于 harness layer，不是宿主 agent runtime。 diff --git a/docs/zh/harness/ROADMAP.md b/docs/zh/harness/ROADMAP.md index e03ce5d..6bfb1cc 100644 --- a/docs/zh/harness/ROADMAP.md +++ b/docs/zh/harness/ROADMAP.md @@ -5,10 +5,10 @@ 这份 roadmap 描述 Mnemon Harness 如何从当前 MVP loops，逐步成长为更完整的 modular-agent governance layer。它是方向性路线图，不是固定 release schedule。 -核心原则很简单：一次做好一个 loop，让每个 module 都能独立产生价值，同时不把 +核心原则很简单：一次做好一个 loop，让每个 loop 都能独立产生价值，同时不把 Mnemon 做成替代宿主的 agent runtime。 -这份路线图是 memory-driven 的，而不是 module-driven 的。Memory 是让 agent +这份路线图是 memory-driven 的，而不是 loop-driven 的。Memory 是让 agent 经验变成持久状态的连续性中心。其他 loop 应该围绕这些状态进行增强、治理或 运行，而不是变成彼此割裂的功能。 @@ -24,11 +24,11 @@ Mnemon 已经有两个可安装的 MVP harness loops。 这两个 MVP loops 使用同一套 harness 词汇： - GUIDE 文件定义 loop policy。 -- setup scripts 将 loop 挂载到宿主 agent。 +- ops scripts 将 loop 挂载到宿主 agent。 - hooks 在宿主定义的生命周期时机注入提示。 - protocol skills 暴露可复用操作。 - subagents 执行较重的维护工作。 -- Mnemon-owned state 把 module 数据保存在宿主 runtime 之外。 +- Mnemon-owned state 把 loop 数据保存在宿主 runtime 之外。 Claude Code 是第一个 reference host，因为它提供 hooks、skills、subagents 和 project/user configuration。架构仍应保持可移植，面向其他具备类似扩展点的 @@ -52,9 +52,9 @@ project/user configuration。架构仍应保持可移植，面向其他具备类 重点：让多个 loops 更容易协同运行。 -这一阶段应该引入 modules 所需的最小共享 substrate： +这一阶段应该引入 loops 所需的最小共享 substrate： -- module registry 和 version metadata +- loop registry 和 version metadata - canonical filesystem layout - shared state、reports、proposals 和 audit records - locks、leases、queues 和 background job status @@ -63,13 +63,13 @@ project/user configuration。架构仍应保持可移植，面向其他具备类 `mnemon-daemon` 应该是 harness maintenance runner，而不是 agent runtime。它可以 运行 dreaming、curator review、eval jobs、risk scans、audit writing，以及其他 -离线 module 工作。 +离线 loop 工作。 ## Phase 3：Goal Loop 重点：支持长程任务，但不替代宿主 agent。 -未来的 `mnemon-goal` module 应维护 durable goal state： +未来的 `mnemon-goal` loop 应维护 durable goal state： - objectives - milestones @@ -87,7 +87,7 @@ review、audit 和 policy reminders。 重点：为自进化增加控制、质量和问责能力。 -可能的 modules： +可能的 loops： - Eval Loop：tests、benchmarks、checklists 和 outcome feedback。 - Risk Loop：扫描 proposed memory、skill、policy 或 setup changes。 diff --git a/docs/zh/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md b/docs/zh/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md index d9db886..f8c9190 100644 --- a/docs/zh/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md +++ b/docs/zh/harness/YC_EVOLVING_DESIGN_PHILOSOPHY.md @@ -88,45 +88,33 @@ lifecycle state。 文章中的 loop 可以转化为 Mnemon 的生命周期模型： ```text -Observed Signals - user intent, repo diffs, host status, eval results, customer feedback +State + durable context, skill lifecycle state, reports, proposals, status | v -Desired State - goals, policies, skills, memory, bindings, expected projections +Intent + goals, policies, desired visibility, review boundaries | v -Reconcile - compare desired state with actual host surfaces and outcomes +Projection + host-readable skills, hooks, app servers, tools, eval surfaces | v -Projection And Execution - host adapters expose skills, hooks, app servers, tools, evals +Reality + user intent, repo diffs, host behavior, eval results, customer feedback | v -Status And Learning - record success, failure, drift, missing tools, stale skills, review needs +Reconcile + compare Intent with Reality, then record action, no-op, or proposal | v -Updated Canonical Context +Updated State ``` Mnemon 应该保持清晰的最小主干： ```text -LoopModule + HostBinding - | - v -Desired State - | - v -Reconcile - | - v -HostAdapter -> Projection -> HostAgent - | - v -Status -> Learning -> next Reconcile +State -> Intent -> Projection -> Reality -> Reconcile -> State ``` ## Host Capability Surfaces diff --git a/docs/zh/harness/eval/CODEX_APP_SERVER.md b/docs/zh/harness/eval/CODEX_APP_SERVER.md index 57290b2..57d1d2b 100644 --- a/docs/zh/harness/eval/CODEX_APP_SERVER.md +++ b/docs/zh/harness/eval/CODEX_APP_SERVER.md @@ -1,7 +1,7 @@ # Codex App-Server Eval 这个 eval 模式使用真实的 Codex app-server，而不是 mock server。它会在 -`.testdata` 下创建一次性的隔离运行目录，把 Mnemon loop module 投影到生成的 +`.testdata` 下创建一次性的隔离运行目录，把 Mnemon loop template 投影到生成的 workspace 中，然后启动： ```bash diff --git a/docs/zh/harness/eval-loop/DESIGN.md b/docs/zh/harness/eval/DESIGN.md similarity index 72% rename from docs/zh/harness/eval-loop/DESIGN.md rename to docs/zh/harness/eval/DESIGN.md index de338ea..f63638e 100644 --- a/docs/zh/harness/eval-loop/DESIGN.md +++ b/docs/zh/harness/eval/DESIGN.md @@ -1,25 +1,25 @@ # Eval Loop MVP Design -英文版本：[DESIGN.md](../../../harness/eval-loop/DESIGN.md) +英文版本：[DESIGN.md](../../../harness/eval/DESIGN.md) -可安装 MVP 资产：[harness/modules/eval-loop](../../../../harness/modules/eval-loop/README.md) +可安装 MVP 资产：[harness/loops/eval](../../../../harness/loops/eval/README.md) -Eval loop 是 Mnemon 的 feedback-facing harness module。它定义如何通过真实 +Eval loop 是 Mnemon 的 feedback-facing harness loop。它定义如何通过真实 scenario 测试 HostAgent，如何收集证据，以及如何把稳定失败转化为经过治理的 改进候选。 ## 定位 -Eval loop 与 memory-loop、skill-loop 是平级模块，不是它们的父模块。 -memory-loop 和 skill-loop 直接影响 HostAgent interface：前者影响记忆上下文， -后者影响可复用工作方法。eval-loop 通过 scenario 执行观察这些影响，并把发现 +Eval loop 与 memory、skill 是平级模块，不是它们的父模块。 +memory 和 skill 直接影响 HostAgent interface：前者影响记忆上下文， +后者影响可复用工作方法。eval 通过 scenario 执行观察这些影响，并把发现 反馈回项目。 ```text -harness/modules/ -├── memory-loop -├── skill-loop -└── eval-loop +harness/loops/ +├── memory +├── skill +└── eval ``` ## 核心模型 @@ -83,6 +83,6 @@ promotion 审阅。 - bilingual documentation synchronization - host projection smoke checks -这些场景当前主要评估 memory-loop 和 skill-loop，但 eval-loop 框架本身更通用。 +这些场景当前主要评估 memory 和 skill，但 eval 框架本身更通用。 它也可以评估 setup、host adapter、docs workflow、commit discipline，以及 -eval-loop 自身。 +eval 自身。 diff --git a/docs/zh/harness/memory-loop/DESIGN.md b/docs/zh/harness/memory/DESIGN.md similarity index 94% rename from docs/zh/harness/memory-loop/DESIGN.md rename to docs/zh/harness/memory/DESIGN.md index eb9fcb6..8e584e4 100644 --- a/docs/zh/harness/memory-loop/DESIGN.md +++ b/docs/zh/harness/memory/DESIGN.md @@ -1,23 +1,23 @@ # Memory Loop MVP 设计 -相关可视化页面：[memory-loop](../../../site/memory-loop/index.html) +相关可视化页面：[memory](../../../site/memory/index.html) -英文版本：[DESIGN.md](../../../harness/memory-loop/DESIGN.md) +英文版本：[DESIGN.md](../../../harness/memory/DESIGN.md) -可安装 MVP 资产：[harness/modules/memory-loop](../../../../harness/modules/memory-loop/README.md) +可安装 MVP 资产：[harness/loops/memory](../../../../harness/loops/memory/README.md) Memory loop 是 self-evolution harness 的第一个可落地切片。它给 HostAgent 提供一份面向 prompt 的工作记忆，同时使用 Mnemon 作为持久长期记忆。Harness 本身保持很小：围绕已有 HostAgent 安装 Markdown policy、hook prompt、protocol skills 和一个维护型 subagent。 ## 生命周期控制平面位置 -在生命周期控制平面里，`memory-loop` 是第一个实际证明：外部能力可以变成 +在生命周期控制平面里，`memory` 是第一个实际证明：外部能力可以变成 lifecycle-native capability，而不需要让 Mnemon 变成宿主 agent runtime。 按照统一控制模型： | Layer | Memory-loop 形态 | | --- | --- | -| State | `.mnemon` 下的 `MEMORY.md`、Mnemon long-term stores、reports、manifests 和 memory-loop status。 | +| State | `.mnemon` 下的 `MEMORY.md`、Mnemon long-term stores、reports、manifests 和 memory status。 | | Intent | 让有用的 agent、user、project continuity 能跨 lifecycle boundaries 保持可用。 | | Reality | host prompt、当前任务、working-memory 内容、recall 结果、context pressure 和 consolidation 状态。 | | Reconcile | 判断是否 read、write、compact、consolidate 或 no-op，并写回 status 或 durable state。 | @@ -26,7 +26,7 @@ lifecycle-native capability，而不需要让 Mnemon 变成宿主 agent runtime | Entity | Profile | 作用 | | --- | --- | --- | -| `memory-loop` | Template | 可复用 lifecycle capability package。 | +| `memory` | Template | 可复用 lifecycle capability package。 | | memory binding | Controlled | 将 memory 行为绑定到 Prime、Remind、Nudge、Compact 和 maintenance 等宿主生命周期。 | | hot/cold memory surfaces | Surface | `MEMORY.md`、Mnemon recall/write、host hooks 和 protocol skills。 | | recall/write/consolidation evidence | Evidence | memory usefulness、context pressure、stale entries 和 durable write results。 | @@ -98,7 +98,7 @@ Recall -> page-in / retrieval into context - 更好的 dreaming、promotion、demotion、compaction 和 eviction，则是在增强二者 之间的交换协议。 -因此，memory-loop 的 contract 是： +因此，memory 的 contract 是： ```text LLM-native hot memory @@ -145,7 +145,7 @@ Search result 只有在被 agent 内化为耐久的 user、project 或 task stat | 概念 | Memory Loop 资产 | 职责 | 边界 | | --- | --- | --- | --- | | GUIDE | `GUIDE.md` | 定义何时读、何时写、何时压缩、何时巩固。 | 只写 policy，不绑定存储目标。 | -| setup | `harness/setup` + host projection | 安装 hooks、protocol skills、dreaming subagent、memory 文件和环境变量。 | 只负责安装，不参与 runtime 判断。 | +| ops | `harness/ops` + host projection | 安装 hooks、protocol skills、dreaming subagent、memory 文件和环境变量。 | 只负责安装，不参与 runtime 判断。 | | hook | `prime/remind/nudge/compact` | 提供 Host 生命周期时机和短提醒。 | 不承载复杂推理或存储协议。 | | protocol | `memory_get.md` / `memory_set.md` | 定义在线 Mnemon recall 和在线 `MEMORY.md` 编辑。 | 只有 GUIDE 判断需要时才由 HostAgent 调用。 | | subagent | `dreaming` | 将 `MEMORY.md` 巩固到 Mnemon，并重写工作记忆。 | 后台或显式维护流程，不是每轮在线行为。 | diff --git a/docs/zh/harness/modular-agent/DESIGN.md b/docs/zh/harness/modular-agent/DESIGN.md index 3e3f5eb..0bbd0f4 100644 --- a/docs/zh/harness/modular-agent/DESIGN.md +++ b/docs/zh/harness/modular-agent/DESIGN.md @@ -6,12 +6,12 @@ Mnemon 的核心优势是 modular agent 模型：自进化能力应该作为外 harness 挂载到已有 agent 上，而不是重新实现一个 agent framework。 Mnemon 不拥有 agent runtime，但它拥有 harness runtime substrate。这个 -substrate 是让独立 harness modules 能被安装、组合、调度、审计，并安全地与 +substrate 是让独立 harness loops 能被安装、组合、调度、审计，并安全地与 宿主 agent 协作的系统层。 ## 核心判断 -任何支持标准扩展点的宿主 agent，都可以通过安装 Mnemon harness module +任何支持标准扩展点的宿主 agent，都可以通过安装 Mnemon harness loop 获得自进化能力。 宿主 agent 拥有 ReAct loop： @@ -58,13 +58,13 @@ ReAct loop + skill/protocol + hook timing + Markdown policy + durable state model calls 和 session management。Mnemon 聚焦的是可以挂载到这个 runtime 外围的行为层。 -这也是为什么架构强调 harness modules，而不是新的 agent framework。目标是 +这也是为什么架构强调 harness loops，而不是新的 agent framework。目标是 把高级 agent 行为变成可移植、可检查、可安装的模块。 -但是，当多个 module 需要协作时，仅有 skill、hook 和 Markdown 资产还不够。 +但是，当多个 loop 需要协作时，仅有 skill、hook 和 Markdown 资产还不够。 Mnemon 需要自己的 substrate 来处理： -- module registry 和 versioning +- loop registry 和 versioning - canonical filesystem layout - environment 和 configuration resolution - hook binding 和 prompt injection boundaries @@ -72,7 +72,7 @@ Mnemon 需要自己的 substrate 来处理： - proposal、report、audit 和 state schemas - locks、leases、queues 和 background job status - setup、uninstall、upgrade 和 recovery paths -- cross-module protocols +- cross-loop protocols 这个 substrate 仍然不是 agent runtime。它不拥有 ReAct loop，不和用户对话， 也不替代宿主的 tool routing。 @@ -90,7 +90,7 @@ experience -> memory -> skills -> goals -> eval / risk / review / audit ``` Memory 是连续性的中心。Skill evolution 依赖被记住的 evidence 和重复 -workflows。Goal module 依赖 durable objective state。Eval、risk、review 和 +workflows。Goal loop 依赖 durable objective state。Eval、risk、review 和 audit loops 依赖 decisions、changes 和 outcomes 的记录。Backup 和 replication 保护的也是这组以 memory 为中心的 harness state。 @@ -107,16 +107,16 @@ surfaces，除非它们的结果被沉淀为持久 agent state。 | Prompt assembly | Host agent | 决定哪些上下文进入模型。 | | Tool routing | Host agent | 在宿主权限模型下选择和执行工具。 | | Native skills | Host agent | 使用宿主自己的机制发现和调用 skill。 | -| Evolution modules | Mnemon harness | 通过可挂载资产增加 memory、skill evolution、evaluation、review loop。 | +| Evolution loops | Mnemon harness | 通过可挂载资产增加 memory、skill evolution、evaluation、review loop。 | | Canonical state | Mnemon harness | 保存持久记忆、skill lifecycle state、evidence、proposal 和 report。 | -| Harness substrate | Mnemon harness | 提供 module registry、filesystem layout、environment、setup、projection、reports、proposals、locks、queues 和跨模块协议。 | +| Harness substrate | Mnemon harness | 提供 loop registry、filesystem layout、environment、setup、projection、reports、proposals、locks、queues 和跨模块协议。 | | Maintenance runner | Mnemon harness | 可选地调度模块后台任务，但不成为 agent runtime。 | -这个分工让 Mnemon 保持可移植。宿主可以只采用某一个 module，而不必更换 +这个分工让 Mnemon 保持可移植。宿主可以只采用某一个 loop，而不必更换 runtime。 它也避免另一个误解：Mnemon 不应被看作只是一堆 Markdown skills。Harness -substrate 让 modules 可以协作，同时又不变成单体 agent framework。 +substrate 让 loops 可以协作，同时又不变成单体 agent framework。 ## 执行平面与治理循环 @@ -143,8 +143,8 @@ agent framework。 | Hooks | 在 Prime、Remind、Nudge、Compact 或等价宿主事件上安装生命周期提醒。 | | Skills | 暴露 `memory_get`、`memory_set`、`skill_observe`、`skill_manage` 等 protocol 操作。 | | Subagents | 在在线任务路径之外运行 dreaming、curator review 等较重的维护任务。 | -| Daemon | 可选地调度已安装 module 的后台维护任务。 | -| Filesystem | 在可预测目录和 project/user scope 下保存 canonical module state。 | +| Daemon | 可选地调度已安装 loop 的后台维护任务。 | +| Filesystem | 在可预测目录和 project/user scope 下保存 canonical loop state。 | | Environment | 让 protocol skill 通过环境变量解析路径，而不是写死某个宿主 agent。 | 最低要求是宿主具备 hook-like 生命周期机制。Skills 和 subagents 会让集成更 @@ -152,7 +152,7 @@ agent framework。 ## Harness Daemon -`mnemon-daemon` 是 proposed harness daemon：用于已安装 Mnemon modules 的后台 +`mnemon-daemon` 是 proposed harness daemon：用于已安装 Mnemon loops 的后台 maintenance runner。 它有价值，是因为部分模块工作不适合放在在线 ReAct loop 中执行： @@ -162,7 +162,7 @@ maintenance runner。 - evaluation jobs - risk scans - audit 和 report 写入 -- leases、locks、queues 和 module status +- leases、locks、queues 和 loop status daemon 不是宿主 agent，也不是第二个 runtime。它不应和用户对话，不应接管 任务执行，不应替宿主进行 tool routing，也不应绕过 proposal 和 approval @@ -172,19 +172,19 @@ policy。 ```text Host Agent -> 在线任务执行和用户交互 -mnemon-daemon -> 离线 harness maintenance 和定时 module jobs -Harness Modules -> memory、skills、eval、risk、review、audit、policy +mnemon-daemon -> 离线 harness maintenance 和定时 loop jobs +Harness Loops -> memory、skills、eval、risk、review、audit、policy ``` -在 MVP 阶段，module 仍然可以通过人工触发或 host hooks 运行。当多个 module +在 MVP 阶段，loop 仍然可以通过人工触发或 host hooks 运行。当多个 loop 需要共享 scheduling、logs、reports、locks 和 status 时，daemon 会变得重要。 ## 当前 Module | Module | 目的 | 当前参考宿主 | | --- | --- | --- | -| Memory Loop | 增加 working memory、long-term memory 和 dreaming consolidation。 | Claude Code setup 位于 `harness/setup/install.sh --host claude-code --module memory-loop`。 | -| Skill Loop | 增加 active/stale/archived skill lifecycle、evidence capture、curator proposal 和批准后的 lifecycle mutation。 | Claude Code setup 位于 `harness/setup/install.sh --host claude-code --module skill-loop`。 | +| Memory Loop | 增加 working memory、long-term memory 和 dreaming consolidation。 | Claude Code setup 位于 `harness/ops/install.sh --host claude-code --loop memory`。 | +| Skill Loop | 增加 active/stale/archived skill lifecycle、evidence capture、curator proposal 和批准后的 lifecycle mutation。 | Claude Code setup 位于 `harness/ops/install.sh --host claude-code --loop skill`。 | ## 与 Skill Packs 的关系 @@ -199,10 +199,10 @@ Mnemon 位于另一层： ```text Host Agent -> task/workflow skill packs - -> Mnemon harness modules + -> Mnemon harness loops ``` -任务 skill 帮助 agent 做事。Mnemon harness modules 帮助 agent 管理围绕这些 +任务 skill 帮助 agent 做事。Mnemon harness loops 帮助 agent 管理围绕这些 工作的 memory、skill lifecycle、evaluation、risk、audit、review 和 policy。 这两层应当兼容。Mnemon 可以观察、评估、整理、归档、恢复或审计 skill @@ -210,7 +210,7 @@ collections，但不应被描述为仅仅另一个 skill pack。 ## Memory 差异化 -Memory module 使用冷热记忆模型： +Memory loop 使用冷热记忆模型： - Working memory 面向模型。它是小型 Markdown 上下文，进入 prompt，由 agent 维护。 @@ -229,12 +229,12 @@ Memory module 使用冷热记忆模型： - Eval loop：收集结果、运行 benchmark，并把失败反馈为 proposal。 - Risk loop：在 skill 或 memory 变更生效前进行扫描。 - Review loop：协调人工审批、checkpoint 和 release gate。 -- Audit loop：记录哪个 module 因为什么行动，以及改变了什么。 +- Audit loop：记录哪个 loop 因为什么行动，以及改变了什么。 - Policy loop：维护宿主特定的安全与权限策略。 - Backup / replication loop：在不同机器、节点或宿主 agent 环境之间保存和恢复 harness state。 -每个 module 都应保持可独立安装。Module 可以选择使用 `mnemon-daemon` 做后台 +每个 loop 都应保持可独立安装。Module 可以选择使用 `mnemon-daemon` 做后台 调度，但 basic install path 不应强依赖 daemon。 Backup 和 replication 应从保守形态开始。第一版更适合采用 primary-writer @@ -244,7 +244,7 @@ detection、merge proposal 和 audit record。多节点 active-active coordinati ## 可组合 Module Flow -Harness modules 应通过显式 state 和 proposal 边界组合，而不是静默互相调用。 +Harness loops 应通过显式 state 和 proposal 边界组合，而不是静默互相调用。 示例： @@ -257,18 +257,18 @@ Skill Loop 产生 skill proposal ``` 同样的模式也可以用于 memory consolidation、policy update、benchmark failure -或 host setup change。一个 module 可以产生 evidence 或 proposal；另一个 -module 可以 review、scan、approve 或 record。宿主 agent 仍然是决定何时调用 +或 host setup change。一个 loop 可以产生 evidence 或 proposal；另一个 +loop 可以 review、scan、approve 或 record。宿主 agent 仍然是决定何时调用 这些能力的 runtime。 ## 长程 Goal Modules -未来的 `mnemon-goal` module 可以基于这个架构支持长程 agent 工作，但它本身 +未来的 `mnemon-goal` loop 可以基于这个架构支持长程 agent 工作，但它本身 不成为任务 runtime。 `mnemon-goal` 会维护 objective state、milestones、blockers、decisions、 handoffs 和 progress reports。围绕一个长期目标，它可以多次协调其他 harness -modules： +loops： - Memory Loop 在任务开始时 recall context，并在 milestone 后保存 durable decisions。 @@ -280,7 +280,7 @@ modules： - Policy Loop 持续暴露项目约束和用户偏好。 - `mnemon-daemon` 可以发现 stale、blocked 或 due goals，并调度维护任务。 -这使 `mnemon-goal` 成为一个 orchestrating harness module：它围绕 durable +这使 `mnemon-goal` 成为一个 orchestrating harness loop：它围绕 durable objective 协调 memory、skills、evaluation、risk、review、audit 和 policy， 而实际任务执行仍然由宿主 agent 完成。 @@ -298,13 +298,13 @@ objective 协调 memory、skills、evaluation、risk、review、audit 和 policy Claude Code 是第一个 modular-agent case，因为它目前暴露了相对完整的一组扩展 能力：hooks、skills、subagents、filesystem config，以及 project/user scope。 -这让 Claude Code 很适合作为 Mnemon harness modules 的实验性挂载点： +这让 Claude Code 很适合作为 Mnemon harness loops 的实验性挂载点： -- hooks 可以承载 Prime、Remind、Nudge、Compact 和未来 module triggers +- hooks 可以承载 Prime、Remind、Nudge、Compact 和未来 loop triggers - skills 可以暴露可移植的 protocol operations - subagents 可以运行 dreaming、curator review 和其他维护任务 - project/user config 可以验证 local/global install scope -- settings files 可以让 setup 和 uninstall 可重复执行 +- settings files 可以让 ops 和 uninstall 可重复执行 Claude Code 是 reference host，不是唯一支持的 runtime。它的作用是验证 harness attachment model。架构仍应保持可移植，面向任何具备类似扩展点的 diff --git a/docs/zh/harness/skill-loop/DESIGN.md b/docs/zh/harness/skill/DESIGN.md similarity index 94% rename from docs/zh/harness/skill-loop/DESIGN.md rename to docs/zh/harness/skill/DESIGN.md index b0eddf2..66c2b3c 100644 --- a/docs/zh/harness/skill-loop/DESIGN.md +++ b/docs/zh/harness/skill/DESIGN.md @@ -1,10 +1,10 @@ # Skill Loop MVP 设计 -相关可视化页面：[skill-loop](../../../site/skill-loop/index.html) +相关可视化页面：[skill](../../../site/skill/index.html) -英文版本：[DESIGN.md](../../../harness/skill-loop/DESIGN.md) +英文版本：[DESIGN.md](../../../harness/skill/DESIGN.md) -可安装 MVP 资产：[harness/modules/skill-loop](../../../../harness/modules/skill-loop/README.md) +可安装 MVP 资产：[harness/loops/skill](../../../../harness/loops/skill/README.md) Skill loop 的目标是让宿主 Agent 拥有一套可自我演进的 skill library，同时不替换宿主原生的 skill runtime。Skill 仍然是宿主可发现、可调用的原生资产；Mnemon 负责保存 canonical lifecycle state，以及支撑演进判断的 evidence。 @@ -12,14 +12,14 @@ MVP 的边界是“可见性治理”和“生命周期治理”：哪些 skill ## 生命周期控制平面位置 -在生命周期控制平面里，`skill-loop` 把 skill visibility 和 skill lifecycle state +在生命周期控制平面里，`skill` 把 skill visibility 和 skill lifecycle state 变成 lifecycle-native capability，同时不替换宿主原生 skill runtime。 按照统一控制模型： | Layer | Skill-loop 形态 | | --- | --- | -| State | `.mnemon` skill library、active/stale/archived state、evidence、proposals、reports 和 skill-loop status。 | +| State | `.mnemon` skill library、active/stale/archived state、evidence、proposals、reports 和 skill status。 | | Intent | 让正确的 skills 对宿主可见，同时保留 stale 和 archived skills 用于 review、recovery 和 design memory。 | | Reality | Host skill surface、实际 active projection、skill usage evidence、missing 或 misleading skills、curator findings 和 review decisions。 | | Reconcile | 同步 active skills、记录 evidence、提出 lifecycle changes、执行已批准变更，并在 Prime 刷新宿主可见性。 | @@ -28,7 +28,7 @@ MVP 的边界是“可见性治理”和“生命周期治理”：哪些 skill | Entity | Profile | 作用 | | --- | --- | --- | -| `skill-loop` | Template | 可复用 lifecycle capability package。 | +| `skill` | Template | 可复用 lifecycle capability package。 | | skill binding | Controlled | 将 skill visibility 和 lifecycle policy 绑定到某个 host skill surface。 | | host skill surface | Surface | 宿主原生 discovery surface，例如 `.codex/skills` 或 `.claude/skills`。 | | usage signals and curator findings | Evidence | skill usefulness、missing skills、stale skills 或 workflow repetition 等观测证据。 | @@ -73,7 +73,7 @@ reconcile boundary。宿主 skill 目录仍然是可重新生成的视图；当 | 概念 | Skill Loop 资产 | 职责 | 边界 | | --- | --- | --- | --- | | GUIDE | `GUIDE.md` | 定义什么算 skill evidence、reusable workflow signal、review trigger、protected/pinned skill，以及 proposal-first policy。 | 只定义 policy，不生成、不 patch、不移动、不 archive skill。 | -| setup | setup scripts 和 bindings | 安装 hooks、protocol skills、curator subagent，并配置 host-native skill surface binding。 | 只负责安装和挂载，不参与每次 runtime 判断。 | +| ops | ops scripts 和 bindings | 安装 hooks、protocol skills、curator subagent，并配置 host-native skill surface binding。 | 只负责安装和挂载，不参与每次 runtime 判断。 | | hook | `prime`、`remind`、`nudge`、`compact` | 提供时机：Prime 同步 active skills，Nudge 提醒模型观察 evidence，Compact 可作为低频 review 边界，Remind 通常 no-op。 | hook 应保持短小；规则在 GUIDE 中，动作在 protocol skill 中。 | | protocol | `skill_observe.md`、`skill_curate.md`、`skill_manage.md` | 定义 HostAgent 可加载的跨宿主流程：observe、curate、manage。 | protocol skill 通过 harness 环境定位 `.mnemon`，例如 `MNEMON_HARNESS_DIR`。 | | subagent | `curator` | 低频审阅 evidence 和 skill library，并提出 create、patch、consolidate、stale、archive、restore 方案。 | 默认 proposal-first。批准后的变更由 `skill_manage` 执行。 | @@ -281,7 +281,7 @@ MVP 范围外： | Host-facing surface | Host Skill Surface | 宿主原生 skill discovery 读取的位置。 | 由 Prime 从 `.mnemon/skills/active` 生成或挂载。 | | Canonical store | `.mnemon` Skill Library | 保存 active、stale、archived skills 和 usage evidence。 | Source of truth；host-native 目录只是 view。 | | GUIDE | `GUIDE.md` | 定义 evidence、review trigger、protected/pinned 规则和 proposal-first policy。 | 只定义 policy，不做迁移。 | -| setup | setup + bindings | 安装 hooks、protocol skills、curator subagent 和 host-native skill surface binding。 | 只负责安装和挂载。 | +| ops | ops + bindings | 安装 hooks、protocol skills、curator subagent 和 host-native skill surface binding。 | 只负责安装和挂载。 | | hook | `prime/remind/nudge/compact` | 提供同步、observe 提醒和低频 review 边界。 | 只提供时机；规则在 GUIDE。 | | protocol | `skill_observe` / `skill_curate` / `skill_manage` | 定义 observe、curate、manage 的执行流程。 | 通过 harness environment 定位 `.mnemon`。 | | subagent | curator | 执行低频 review、合并、proposal 和 report。 | 默认 proposal-first；批准后通过 `skill_manage` 修改状态。 | diff --git a/harness/bindings/claude-code.memory.json b/harness/bindings/claude-code.memory.json new file mode 100644 index 0000000..f504c84 --- /dev/null +++ b/harness/bindings/claude-code.memory.json @@ -0,0 +1,16 @@ +{ + "schema_version": 1, + "name": "claude-code.memory", + "host": "claude-code", + "loop": "memory", + "projection_path": ".claude", + "runtime_surface": ".claude/mnemon-memory", + "lifecycle_mapping": { + "prime": "SessionStart", + "remind": "UserPromptSubmit", + "nudge": "Stop", + "compact": "PreCompact" + }, + "reconcile": ["read", "write", "compact", "consolidate", "no-op"] +} + diff --git a/harness/bindings/claude-code.skill.json b/harness/bindings/claude-code.skill.json new file mode 100644 index 0000000..b2ca89f --- /dev/null +++ b/harness/bindings/claude-code.skill.json @@ -0,0 +1,16 @@ +{ + "schema_version": 1, + "name": "claude-code.skill", + "host": "claude-code", + "loop": "skill", + "projection_path": ".claude", + "runtime_surface": ".claude/mnemon-skill", + "lifecycle_mapping": { + "prime": "SessionStart", + "remind": "UserPromptSubmit", + "nudge": "Stop", + "compact": "PreCompact" + }, + "reconcile": ["observe", "curate", "propose", "manage", "no-op"] +} + diff --git a/harness/bindings/codex.eval.json b/harness/bindings/codex.eval.json new file mode 100644 index 0000000..ef17a7b --- /dev/null +++ b/harness/bindings/codex.eval.json @@ -0,0 +1,17 @@ +{ + "schema_version": 1, + "name": "codex.eval", + "host": "codex", + "loop": "eval", + "projection_path": ".codex", + "runtime_surface": ".codex/mnemon-eval", + "lifecycle_mapping": { + "prime": "thread/start developer instructions", + "remind": "user prompt guidance", + "nudge": "turn completion guidance", + "compact": "thread compact guidance", + "maintenance": "app-server eval" + }, + "reconcile": ["plan", "run", "analyze", "improve", "retire", "no-op"] +} + diff --git a/harness/bindings/codex.memory.json b/harness/bindings/codex.memory.json new file mode 100644 index 0000000..75a5197 --- /dev/null +++ b/harness/bindings/codex.memory.json @@ -0,0 +1,16 @@ +{ + "schema_version": 1, + "name": "codex.memory", + "host": "codex", + "loop": "memory", + "projection_path": ".codex", + "runtime_surface": ".codex/mnemon-memory", + "lifecycle_mapping": { + "prime": "thread/start developer instructions", + "remind": "user prompt guidance", + "nudge": "turn completion guidance", + "compact": "thread compact guidance" + }, + "reconcile": ["read", "write", "compact", "consolidate", "no-op"] +} + diff --git a/harness/bindings/codex.skill.json b/harness/bindings/codex.skill.json new file mode 100644 index 0000000..3c63771 --- /dev/null +++ b/harness/bindings/codex.skill.json @@ -0,0 +1,16 @@ +{ + "schema_version": 1, + "name": "codex.skill", + "host": "codex", + "loop": "skill", + "projection_path": ".codex", + "runtime_surface": ".codex/mnemon-skill", + "lifecycle_mapping": { + "prime": "thread/start developer instructions", + "remind": "user prompt guidance", + "nudge": "turn completion guidance", + "compact": "thread compact guidance" + }, + "reconcile": ["observe", "curate", "propose", "manage", "no-op"] +} + diff --git a/harness/control/README.md b/harness/control/README.md new file mode 100644 index 0000000..65b029d --- /dev/null +++ b/harness/control/README.md @@ -0,0 +1,24 @@ +# Harness Control Plane + +This directory contains the shared contracts for Mnemon's experimental harness +control plane. It is intentionally small: loops define reusable lifecycle +capabilities, hosts define capability surfaces, bindings define how a loop lands +on a host, and ops executes those bindings. + +```text +State -> Intent -> Projection -> Reality -> Reconcile -> State +``` + +The source tree keeps templates and contracts here. Runtime state is still +written under `.mnemon/harness//`. + +## Contracts + +| Contract | Meaning | +| --- | --- | +| State | Canonical durable loop state under `.mnemon`. | +| Intent | Policy and desired visibility declared by loops and bindings. | +| Projection | Host-readable files, env, hooks, skills, and config. | +| Observation | Host behavior, evidence, drift, reports, and eval output. | +| Reconcile | The action set that decides whether to update state, propose work, or no-op. | + diff --git a/harness/control/contracts/intent.md b/harness/control/contracts/intent.md new file mode 100644 index 0000000..bdc8f06 --- /dev/null +++ b/harness/control/contracts/intent.md @@ -0,0 +1,12 @@ +# Intent Contract + +Intent is the declared desired behavior for a loop on a host. It comes from: + +- `harness/loops//GUIDE.md` +- lifecycle hook prompts +- `harness/loops//loop.json` +- `harness/bindings/..json` + +Intent should be readable by the host agent without making Mnemon own host +execution. + diff --git a/harness/control/contracts/observation.md b/harness/control/contracts/observation.md new file mode 100644 index 0000000..233c962 --- /dev/null +++ b/harness/control/contracts/observation.md @@ -0,0 +1,8 @@ +# Observation Contract + +Observation is how Mnemon sees host reality: hook output, app-server eval +transcripts, usage evidence, reports, status files, drift, and review decisions. + +Observation should be concrete enough for future reconcile tooling to decide +whether to act or no-op. + diff --git a/harness/control/contracts/projection.md b/harness/control/contracts/projection.md new file mode 100644 index 0000000..3301d14 --- /dev/null +++ b/harness/control/contracts/projection.md @@ -0,0 +1,8 @@ +# Projection Contract + +Projection is the host-readable view generated from loop state and binding +intent. Projection files live under host-owned directories such as `.codex` or +`.claude` and must be treated as generated views. + +Projection must not become a second source of truth. + diff --git a/harness/control/contracts/reconcile.md b/harness/control/contracts/reconcile.md new file mode 100644 index 0000000..5781ff2 --- /dev/null +++ b/harness/control/contracts/reconcile.md @@ -0,0 +1,13 @@ +# Reconcile Contract + +Reconcile compares Intent with Reality and writes the result back to State. + +Current reconcile paths are still mostly procedural: + +- host projectors install and refresh projection state +- protocol skills record online evidence or apply approved changes +- maintenance agents curate, consolidate, or propose changes + +Future reconcile tooling should consume `loop.json`, `host.json`, +`bindings/*.json`, host manifests, and loop `status.json`. + diff --git a/harness/control/contracts/state.md b/harness/control/contracts/state.md new file mode 100644 index 0000000..3431f56 --- /dev/null +++ b/harness/control/contracts/state.md @@ -0,0 +1,14 @@ +# State Contract + +State is durable loop-owned data under `.mnemon/harness//`. Source files +under `harness/loops/` are templates, not runtime state. + +Every installed loop should write: + +- `loop.json` +- `GUIDE.md` +- `env.sh` +- `status.json` +- loop-specific runtime files such as `MEMORY.md`, `skills/`, `reports/`, or + eval artifacts + diff --git a/harness/control/schemas/README.md b/harness/control/schemas/README.md new file mode 100644 index 0000000..b59aa02 --- /dev/null +++ b/harness/control/schemas/README.md @@ -0,0 +1,6 @@ +# Control Schemas + +The current schemas are lightweight JSON contracts enforced by +`scripts/validate_harness_loops.sh`. They are intentionally permissive while the +harness is experimental. + diff --git a/harness/eval/README.md b/harness/eval/README.md index 664c58b..3194f51 100644 --- a/harness/eval/README.md +++ b/harness/eval/README.md @@ -2,21 +2,21 @@ This directory documents eval modes for host-wrapped loop testing. -The canonical eval loop module lives under: +The canonical eval loop template lives under: ```text -harness/modules/eval-loop/ +harness/loops/eval/ ``` Use `harness/eval/` for project-local runner notes and app-server operation -details. Use `harness/modules/eval-loop/` for reusable eval-loop policy, +details. Use `harness/loops/eval/` for reusable eval policy, scenarios, suites, rubrics, protocol skills, and lifecycle guidance. ## Codex App-Server Eval The Codex app-server eval uses the real Codex app-server protocol instead of a mock server. It creates an isolated run directory under `.testdata`, installs -Mnemon loop modules into a generated workspace, starts: +Mnemon loop templates into a generated workspace, starts: ```bash codex app-server --listen stdio:// @@ -42,16 +42,16 @@ Run the longer memory regression suite with: make codex-memory-deep-eval ``` -Run the longer skill-loop regression suite with: +Run the longer skill regression suite with: ```bash make codex-skill-deep-eval ``` -Run the eval-loop projection smoke check with: +Run the eval projection smoke check with: ```bash -make codex-eval-loop-smoke +make codex-eval-smoke ``` To run an actual Codex turn, use: @@ -95,7 +95,7 @@ The `memory-deep` suite extends memory coverage with: - rejecting secret-like values and generic restatements of existing safety policy - multi-turn continuity through persisted `MEMORY.md` -The `skill-deep` suite extends skill-loop coverage with: +The `skill-deep` suite extends skill coverage with: - skipping transient one-off workflow evidence - recording missing-skill evidence as JSONL diff --git a/harness/hosts/README.md b/harness/hosts/README.md index fee983e..0da7ff5 100644 --- a/harness/hosts/README.md +++ b/harness/hosts/README.md @@ -1,6 +1,6 @@ # Mnemon Harness Hosts -Host adapters project canonical loop modules into a concrete runtime surface. +Host adapters project canonical loop templates into a concrete runtime surface. ```text harness/hosts/ @@ -8,9 +8,9 @@ harness/hosts/ └── codex/ ``` -Adapters should keep host-specific behavior here. Loop modules should stay -host-agnostic under `harness/modules//`. +Adapters should keep host-specific behavior here. Loop templates should stay +host-agnostic under `harness/loops//`. The Codex adapter projects protocol skills into repo-local `.codex/skills` and -keeps canonical loop state under `.mnemon/harness/`. This shape lets the +keeps canonical loop state under `.mnemon/harness/`. This shape lets the real Codex app-server load the projected skills from an isolated eval workspace. diff --git a/harness/hosts/claude-code/host.json b/harness/hosts/claude-code/host.json index ec1db77..4ad43b2 100644 --- a/harness/hosts/claude-code/host.json +++ b/harness/hosts/claude-code/host.json @@ -1,12 +1,22 @@ { - "schema_version": 1, + "schema_version": 2, "name": "claude-code", - "description": "Projects Mnemon harness modules into Claude Code skills, hooks, agents, and settings.json.", - "projection_surfaces": { - "skills": ".claude/skills", - "hooks": ".claude/hooks", - "subagents": ".claude/agents", - "config": ".claude/settings.json" + "description": "Projects Mnemon harness loops into Claude Code skills, hooks, agents, and settings.json.", + "surfaces": { + "projection": [ + ".claude/skills", + ".claude/hooks", + ".claude/agents", + ".claude/settings.json", + ".claude/mnemon-memory", + ".claude/mnemon-skill" + ], + "observation": [ + ".mnemon/hosts/claude-code/manifest.json", + ".mnemon/harness/*/status.json", + "hook output", + "skill usage evidence" + ] }, "lifecycle_mapping": { "prime": "SessionStart", diff --git a/harness/hosts/claude-code/memory-loop/hooks/remind.sh b/harness/hosts/claude-code/memory-loop/hooks/remind.sh deleted file mode 100644 index 9d2c925..0000000 --- a/harness/hosts/claude-code/memory-loop/hooks/remind.sh +++ /dev/null @@ -1,4 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -echo "[mnemon-memory-loop] Remind: apply GUIDE.md; if prior memory could change this task, load memory_get and run a focused Mnemon recall." diff --git a/harness/hosts/claude-code/memory-loop/hooks/compact.sh b/harness/hosts/claude-code/memory/hooks/compact.sh similarity index 62% rename from harness/hosts/claude-code/memory-loop/hooks/compact.sh rename to harness/hosts/claude-code/memory/hooks/compact.sh index 3dbbd01..b902d9a 100644 --- a/harness/hosts/claude-code/memory-loop/hooks/compact.sh +++ b/harness/hosts/claude-code/memory/hooks/compact.sh @@ -3,7 +3,7 @@ set -euo pipefail HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" CONFIG_DIR="$(cd "${HOOK_DIR}/../.." && pwd)" -ENV_PATH="${MNEMON_MEMORY_LOOP_ENV:-${CONFIG_DIR}/mnemon-memory-loop/env.sh}" +ENV_PATH="${MNEMON_MEMORY_LOOP_ENV:-${CONFIG_DIR}/mnemon-memory/env.sh}" if [[ -f "${ENV_PATH}" ]]; then # shellcheck source=/dev/null source "${ENV_PATH}" @@ -11,7 +11,7 @@ fi INPUT="$(cat)" SESSION_ID="$(printf '%s' "${INPUT}" | sed -n 's/.*"session_id"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)" -MARKER_DIR="${TMPDIR:-/tmp}/mnemon-memory-loop" +MARKER_DIR="${TMPDIR:-/tmp}/mnemon-memory" MARKER="${MARKER_DIR}/compact-${SESSION_ID:-unknown}" mkdir -p "${MARKER_DIR}" @@ -33,9 +33,9 @@ else fi if [[ "${NON_EMPTY_LINES}" -gt "${MAX_NON_EMPTY_LINES}" ]]; then - REASON="[mnemon-memory-loop] Compact: MEMORY.md has ${NON_EMPTY_LINES} non-empty lines. Before compaction, spawn mnemon-dreaming to write durable content to Mnemon and compact MEMORY.md, then retry compaction." + REASON="[mnemon-memory] Compact: MEMORY.md has ${NON_EMPTY_LINES} non-empty lines. Before compaction, spawn mnemon-dreaming to write durable content to Mnemon and compact MEMORY.md, then retry compaction." else - REASON="[mnemon-memory-loop] Compact: MNEMON_MEMORY_LOOP_DIR=${MEMORY_DIR:-unset}. Before compaction, preserve critical continuity with memory_set when needed. If this boundary should consolidate working memory, spawn mnemon-dreaming, then retry compaction." + REASON="[mnemon-memory] Compact: MNEMON_MEMORY_LOOP_DIR=${MEMORY_DIR:-unset}. Before compaction, preserve critical continuity with memory_set when needed. If this boundary should consolidate working memory, spawn mnemon-dreaming, then retry compaction." fi cat < None: def contains_mnemon(value: Any) -> bool: if isinstance(value, str): - return "mnemon-memory-loop" in value + return "mnemon-memory" in value if isinstance(value, dict): return any(contains_mnemon(item) for item in value.values()) if isinstance(value, list): @@ -117,7 +117,7 @@ def add_hook(data: dict[str, Any], event: str, command: Path) -> None: def install(args: argparse.Namespace) -> None: config_dir = Path(args.config_dir) settings_path = config_dir / "settings.json" - hooks_dir = config_dir / "hooks" / "mnemon-memory-loop" + hooks_dir = config_dir / "hooks" / "mnemon-memory" data = load_json(settings_path) remove_hooks(data) diff --git a/harness/hosts/claude-code/projector.sh b/harness/hosts/claude-code/projector.sh index 9d05d5c..75af551 100755 --- a/harness/hosts/claude-code/projector.sh +++ b/harness/hosts/claude-code/projector.sh @@ -3,12 +3,12 @@ set -euo pipefail usage() { cat <<'USAGE' -Project Mnemon harness modules into Claude Code. +Project Mnemon harness loops into Claude Code. Usage: - projector.sh install --module MODULE [options] - projector.sh status --module MODULE [options] - projector.sh uninstall --module MODULE [options] + projector.sh install --loop LOOP [options] + projector.sh status --loop LOOP [options] + projector.sh uninstall --loop LOOP [options] Common options: --global @@ -33,8 +33,8 @@ USAGE } SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -# shellcheck source=../../setup/lib/paths.sh -source "${SCRIPT_DIR}/../../setup/lib/paths.sh" +# shellcheck source=../../ops/lib/paths.sh +source "${SCRIPT_DIR}/../../ops/lib/paths.sh" ACTION="${1:-}" if [[ -z "${ACTION}" ]]; then @@ -43,7 +43,7 @@ if [[ -z "${ACTION}" ]]; then fi shift -MODULE="" +LOOP="" CONFIG_DIR=".claude" CONFIG_DIR_EXPLICIT=0 GLOBAL=0 @@ -57,8 +57,8 @@ PURGE_LIBRARY=0 while [[ $# -gt 0 ]]; do case "$1" in - --module) - MODULE="${2:?missing value for --module}" + --loop) + LOOP="${2:?missing value for --loop}" shift 2 ;; --global) @@ -115,19 +115,19 @@ while [[ $# -gt 0 ]]; do esac done -if [[ -z "${MODULE}" ]]; then - echo "--module is required" >&2 +if [[ -z "${LOOP}" ]]; then + echo "--loop is required" >&2 usage >&2 exit 2 fi -if [[ "${MODULE}" != "memory-loop" && "${MODULE}" != "skill-loop" ]]; then - echo "unsupported module for Claude Code: ${MODULE}" >&2 +if [[ "${LOOP}" != "memory" && "${LOOP}" != "skill" ]]; then + echo "unsupported loop for Claude Code: ${LOOP}" >&2 exit 1 fi -MODULE_DIR="$(mnemon_module_dir "${MODULE}")" -if [[ ! -d "${MODULE_DIR}" ]]; then - echo "module directory not found: ${MODULE_DIR}" >&2 +LOOP_DIR="$(mnemon_loop_dir "${LOOP}")" +if [[ ! -d "${LOOP_DIR}" ]]; then + echo "loop directory not found: ${LOOP_DIR}" >&2 exit 1 fi @@ -136,7 +136,7 @@ if [[ "${GLOBAL}" == "1" && "${CONFIG_DIR_EXPLICIT}" == "0" ]]; then else MNEMON_DIR="${MNEMON_HARNESS_STATE_DIR:-.mnemon}" fi -CANONICAL_MODULE_DIR="${MNEMON_DIR}/harness/${MODULE}" +CANONICAL_LOOP_DIR="${MNEMON_DIR}/harness/${LOOP}" HOST_MANIFEST_DIR="${MNEMON_DIR}/hosts/claude-code" HOST_MANIFEST="${HOST_MANIFEST_DIR}/manifest.json" @@ -165,20 +165,49 @@ ensure_mnemon_binary() { } copy_common_canonical_assets() { - mkdir -p "${CANONICAL_MODULE_DIR}" - install_file "${MODULE_DIR}/GUIDE.md" "${CANONICAL_MODULE_DIR}/GUIDE.md" 0644 - install_file "${MODULE_DIR}/env.sh" "${CANONICAL_MODULE_DIR}/env.sh" 0755 - install_file "${MODULE_DIR}/module.json" "${CANONICAL_MODULE_DIR}/module.json" 0644 + mkdir -p "${CANONICAL_LOOP_DIR}" + install_file "${LOOP_DIR}/GUIDE.md" "${CANONICAL_LOOP_DIR}/GUIDE.md" 0644 + install_file "${LOOP_DIR}/env.sh" "${CANONICAL_LOOP_DIR}/env.sh" 0755 + install_file "${LOOP_DIR}/loop.json" "${CANONICAL_LOOP_DIR}/loop.json" 0644 +} + +write_loop_status() { + local projection_path="$1" + MNEMON_LOOP_JSON="${LOOP_DIR}/loop.json" \ + MNEMON_LOOP_STATUS="${CANONICAL_LOOP_DIR}/status.json" \ + MNEMON_HOST="claude-code" \ + MNEMON_HOST_PROJECT_ROOT="$(pwd)" \ + MNEMON_HOST_PROJECTION_PATH="${projection_path}" \ + python3 - <<'PY' +import json +import os +from datetime import datetime, timezone +from pathlib import Path + +loop = json.loads(Path(os.environ["MNEMON_LOOP_JSON"]).read_text()) +status = { + "schema_version": 2, + "loop": loop["name"], + "host": os.environ["MNEMON_HOST"], + "phase": "projected", + "updated_at": datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z"), + "project_root": os.environ["MNEMON_HOST_PROJECT_ROOT"], + "projection_path": os.environ["MNEMON_HOST_PROJECTION_PATH"], + "state_path": str(Path(os.environ["MNEMON_LOOP_STATUS"]).parent), + "control_model": loop.get("control_model", {}), + "entity_profiles": loop.get("entity_profiles", {}), + "surfaces": loop.get("surfaces", {}), +} +Path(os.environ["MNEMON_LOOP_STATUS"]).write_text(json.dumps(status, indent=2) + "\n") +PY } write_host_manifest() { local projection_path="$1" - local module_version - module_version="$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1])).get("version",""))' "${MODULE_DIR}/module.json")" mkdir -p "${HOST_MANIFEST_DIR}" MNEMON_HOST_MANIFEST="${HOST_MANIFEST}" \ - MNEMON_HOST_MODULE="${MODULE}" \ - MNEMON_HOST_MODULE_VERSION="${module_version}" \ + MNEMON_HOST_LOOP="${LOOP}" \ + MNEMON_HOST_LOOP_JSON="${LOOP_DIR}/loop.json" \ MNEMON_HOST_PROJECT_ROOT="$(pwd)" \ MNEMON_HOST_MNEMON_DIR="${MNEMON_DIR}" \ MNEMON_HOST_STORE="${STORE_NAME:-default}" \ @@ -190,21 +219,36 @@ from datetime import datetime, timezone from pathlib import Path path = Path(os.environ["MNEMON_HOST_MANIFEST"]) +loop = json.loads(Path(os.environ["MNEMON_HOST_LOOP_JSON"]).read_text()) if path.exists() and path.stat().st_size: data = json.loads(path.read_text()) else: - data = {"schema_version": 1, "host": "claude-code", "loops": {}} + data = {"schema_version": 2, "host": "claude-code", "loops": {}} -data["schema_version"] = 1 +data["schema_version"] = 2 data["host"] = "claude-code" data["updated_at"] = datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z") data["project_root"] = os.environ["MNEMON_HOST_PROJECT_ROOT"] data["mnemon_dir"] = os.environ["MNEMON_HOST_MNEMON_DIR"] data["store"] = os.environ["MNEMON_HOST_STORE"] -data.setdefault("loops", {})[os.environ["MNEMON_HOST_MODULE"]] = { - "module_path": f"{os.environ['MNEMON_HOST_MNEMON_DIR']}/harness/{os.environ['MNEMON_HOST_MODULE']}", - "module_version": os.environ["MNEMON_HOST_MODULE_VERSION"], - "projection_path": os.environ["MNEMON_HOST_PROJECTION_PATH"], +data.setdefault("loops", {})[os.environ["MNEMON_HOST_LOOP"]] = { + "loop_path": f"{os.environ['MNEMON_HOST_MNEMON_DIR']}/harness/{os.environ['MNEMON_HOST_LOOP']}", + "loop_version": loop.get("version", ""), + "state_path": f"{os.environ['MNEMON_HOST_MNEMON_DIR']}/harness/{os.environ['MNEMON_HOST_LOOP']}", + "intent_policy": f"{os.environ['MNEMON_HOST_MNEMON_DIR']}/harness/{os.environ['MNEMON_HOST_LOOP']}/GUIDE.md", + "status_path": f"{os.environ['MNEMON_HOST_MNEMON_DIR']}/harness/{os.environ['MNEMON_HOST_LOOP']}/status.json", + "projection": { + "path": os.environ["MNEMON_HOST_PROJECTION_PATH"], + "surfaces": loop.get("surfaces", {}).get("projection", []), + }, + "reality": { + "surfaces": loop.get("surfaces", {}).get("observation", []), + }, + "reconcile": { + "actions": loop.get("control_model", {}).get("reconcile", []), + }, + "control_model": loop.get("control_model", {}), + "entity_profiles": loop.get("entity_profiles", {}), "lifecycle_mapping": { "prime": "SessionStart", "remind": "UserPromptSubmit", @@ -214,11 +258,12 @@ data.setdefault("loops", {})[os.environ["MNEMON_HOST_MODULE"]] = { } path.write_text(json.dumps(data, indent=2) + "\n") PY + write_loop_status "${projection_path}" } -remove_host_manifest_module() { +remove_host_manifest_loop() { [[ -f "${HOST_MANIFEST}" ]] || return 0 - MNEMON_HOST_MANIFEST="${HOST_MANIFEST}" MNEMON_HOST_MODULE="${MODULE}" python3 - <<'PY' + MNEMON_HOST_MANIFEST="${HOST_MANIFEST}" MNEMON_HOST_LOOP="${LOOP}" python3 - <<'PY' import json import os from pathlib import Path @@ -227,7 +272,7 @@ path = Path(os.environ["MNEMON_HOST_MANIFEST"]) data = json.loads(path.read_text()) loops = data.get("loops") if isinstance(loops, dict): - loops.pop(os.environ["MNEMON_HOST_MODULE"], None) + loops.pop(os.environ["MNEMON_HOST_LOOP"], None) if not data.get("loops"): path.unlink() else: @@ -236,38 +281,38 @@ PY } write_memory_projection_env() { - mkdir -p "${CONFIG_DIR}/mnemon-memory-loop" - cat > "${CONFIG_DIR}/mnemon-memory-loop/env.sh" < "${CONFIG_DIR}/mnemon-memory/env.sh" < "${CONFIG_DIR}/mnemon-skill-loop/env.sh" < "${CONFIG_DIR}/mnemon-skill/env.sh" </dev/null || true + rm -f "${CANONICAL_LOOP_DIR}/GUIDE.md" "${CANONICAL_LOOP_DIR}/env.sh" "${CANONICAL_LOOP_DIR}/loop.json" "${CANONICAL_LOOP_DIR}/status.json" + rmdir "${CANONICAL_LOOP_DIR}" 2>/dev/null || true fi - remove_host_manifest_module + remove_host_manifest_loop echo "Removed Mnemon memory loop from ${CONFIG_DIR}." } uninstall_skill_loop() { ensure_python - local env_path="${CONFIG_DIR}/mnemon-skill-loop/env.sh" + local env_path="${CONFIG_DIR}/mnemon-skill/env.sh" if [[ -f "${env_path}" ]]; then # shellcheck source=/dev/null source "${env_path}" @@ -395,35 +445,35 @@ uninstall_skill_loop() { if [[ -d "${host_skills_dir}" ]]; then while IFS= read -r marker; do rm -rf "$(dirname "${marker}")" - done < <(find "${host_skills_dir}" -mindepth 2 -maxdepth 2 -name .mnemon-skill-loop-generated -print 2>/dev/null) + done < <(find "${host_skills_dir}" -mindepth 2 -maxdepth 2 -name .mnemon-skill-generated -print 2>/dev/null) fi - rm -rf "${CONFIG_DIR}/hooks/mnemon-skill-loop" + rm -rf "${CONFIG_DIR}/hooks/mnemon-skill" rm -rf "${host_skills_dir}/skill_observe" rm -rf "${host_skills_dir}/skill_curate" rm -rf "${host_skills_dir}/skill_author" rm -rf "${host_skills_dir}/skill_manage" rm -f "${CONFIG_DIR}/agents/mnemon-skill-curator.md" - rm -rf "${CONFIG_DIR}/mnemon-skill-loop" + rm -rf "${CONFIG_DIR}/mnemon-skill" if [[ "${PURGE_LIBRARY}" == "1" ]]; then - rm -rf "${CANONICAL_MODULE_DIR}" + rm -rf "${CANONICAL_LOOP_DIR}" else - rm -f "${CANONICAL_MODULE_DIR}/GUIDE.md" - rmdir "${CANONICAL_MODULE_DIR}/reports" 2>/dev/null || true - rmdir "${CANONICAL_MODULE_DIR}/proposals" 2>/dev/null || true - rmdir "${CANONICAL_MODULE_DIR}" 2>/dev/null || true + rm -f "${CANONICAL_LOOP_DIR}/GUIDE.md" "${CANONICAL_LOOP_DIR}/env.sh" "${CANONICAL_LOOP_DIR}/loop.json" "${CANONICAL_LOOP_DIR}/status.json" + rmdir "${CANONICAL_LOOP_DIR}/reports" 2>/dev/null || true + rmdir "${CANONICAL_LOOP_DIR}/proposals" 2>/dev/null || true + rmdir "${CANONICAL_LOOP_DIR}" 2>/dev/null || true fi - remove_host_manifest_module + remove_host_manifest_loop echo "Removed Mnemon skill loop from ${CONFIG_DIR}." } -case "${ACTION}:${MODULE}" in - install:memory-loop) install_memory_loop ;; - install:skill-loop) install_skill_loop ;; - status:memory-loop|status:skill-loop) status_module ;; - uninstall:memory-loop) uninstall_memory_loop ;; - uninstall:skill-loop) uninstall_skill_loop ;; +case "${ACTION}:${LOOP}" in + install:memory) install_memory_loop ;; + install:skill) install_skill_loop ;; + status:memory|status:skill) status_loop ;; + uninstall:memory) uninstall_memory_loop ;; + uninstall:skill) uninstall_skill_loop ;; *) - echo "unsupported action/module: ${ACTION}/${MODULE}" >&2 + echo "unsupported action/loop: ${ACTION}/${LOOP}" >&2 exit 1 ;; esac diff --git a/harness/hosts/claude-code/skill-loop/hooks/nudge.sh b/harness/hosts/claude-code/skill-loop/hooks/nudge.sh deleted file mode 100644 index 1bf165b..0000000 --- a/harness/hosts/claude-code/skill-loop/hooks/nudge.sh +++ /dev/null @@ -1,8 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -if cat | grep -q '"stop_hook_active"[[:space:]]*:[[:space:]]*true'; then - exit 0 -fi - -echo "[mnemon-skill-loop] Apply GUIDE.md; if this turn produced skill evidence or reusable workflow signal, load skill_observe." diff --git a/harness/hosts/claude-code/skill-loop/hooks/remind.sh b/harness/hosts/claude-code/skill-loop/hooks/remind.sh deleted file mode 100644 index 7fa9fb3..0000000 --- a/harness/hosts/claude-code/skill-loop/hooks/remind.sh +++ /dev/null @@ -1,4 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -echo "[mnemon-skill-loop] Remind is no-op by default; use host-native skill discovery." diff --git a/harness/hosts/claude-code/skill-loop/hooks/compact.sh b/harness/hosts/claude-code/skill/hooks/compact.sh similarity index 58% rename from harness/hosts/claude-code/skill-loop/hooks/compact.sh rename to harness/hosts/claude-code/skill/hooks/compact.sh index b34a356..b6a6739 100644 --- a/harness/hosts/claude-code/skill-loop/hooks/compact.sh +++ b/harness/hosts/claude-code/skill/hooks/compact.sh @@ -3,13 +3,13 @@ set -euo pipefail HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" CONFIG_DIR="$(cd "${HOOK_DIR}/../.." && pwd)" -ENV_PATH="${MNEMON_SKILL_LOOP_ENV:-${CONFIG_DIR}/mnemon-skill-loop/env.sh}" +ENV_PATH="${MNEMON_SKILL_LOOP_ENV:-${CONFIG_DIR}/mnemon-skill/env.sh}" if [[ -f "${ENV_PATH}" ]]; then # shellcheck source=/dev/null source "${ENV_PATH}" fi -USAGE_FILE="${MNEMON_SKILL_LOOP_USAGE_FILE:-${CONFIG_DIR}/mnemon-skill-loop/skills/.usage.jsonl}" +USAGE_FILE="${MNEMON_SKILL_LOOP_USAGE_FILE:-${CONFIG_DIR}/mnemon-skill/skills/.usage.jsonl}" REVIEW_MIN_EVENTS="${MNEMON_SKILL_LOOP_REVIEW_MIN_EVENTS:-20}" if [[ -f "${USAGE_FILE}" ]]; then @@ -19,7 +19,7 @@ else fi if [[ "${EVENT_COUNT}" -ge "${REVIEW_MIN_EVENTS}" ]]; then - echo "[mnemon-skill-loop] ${EVENT_COUNT} skill evidence event(s) recorded; consider skill_curate or mnemon-skill-curator before/after compaction." + echo "[mnemon-skill] ${EVENT_COUNT} skill evidence event(s) recorded; consider skill_curate or mnemon-skill-curator before/after compaction." else - echo "[mnemon-skill-loop] Compact boundary: consider skill_curate only if this session produced meaningful skill lifecycle evidence." + echo "[mnemon-skill] Compact boundary: consider skill_curate only if this session produced meaningful skill lifecycle evidence." fi diff --git a/harness/hosts/claude-code/skill/hooks/nudge.sh b/harness/hosts/claude-code/skill/hooks/nudge.sh new file mode 100644 index 0000000..5b393d6 --- /dev/null +++ b/harness/hosts/claude-code/skill/hooks/nudge.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +set -euo pipefail + +if cat | grep -q '"stop_hook_active"[[:space:]]*:[[:space:]]*true'; then + exit 0 +fi + +echo "[mnemon-skill] Apply GUIDE.md; if this turn produced skill evidence or reusable workflow signal, load skill_observe." diff --git a/harness/hosts/claude-code/skill-loop/hooks/prime.sh b/harness/hosts/claude-code/skill/hooks/prime.sh similarity index 85% rename from harness/hosts/claude-code/skill-loop/hooks/prime.sh rename to harness/hosts/claude-code/skill/hooks/prime.sh index ceae8d0..ccd6627 100644 --- a/harness/hosts/claude-code/skill-loop/hooks/prime.sh +++ b/harness/hosts/claude-code/skill/hooks/prime.sh @@ -3,13 +3,13 @@ set -euo pipefail HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" CONFIG_DIR="$(cd "${HOOK_DIR}/../.." && pwd)" -ENV_PATH="${MNEMON_SKILL_LOOP_ENV:-${CONFIG_DIR}/mnemon-skill-loop/env.sh}" +ENV_PATH="${MNEMON_SKILL_LOOP_ENV:-${CONFIG_DIR}/mnemon-skill/env.sh}" if [[ -f "${ENV_PATH}" ]]; then # shellcheck source=/dev/null source "${ENV_PATH}" fi -SKILL_LOOP_DIR="${MNEMON_SKILL_LOOP_DIR:-${CONFIG_DIR}/mnemon-skill-loop}" +SKILL_LOOP_DIR="${MNEMON_SKILL_LOOP_DIR:-${CONFIG_DIR}/mnemon-skill}" ACTIVE_DIR="${MNEMON_SKILL_LOOP_ACTIVE_DIR:-${SKILL_LOOP_DIR}/skills/active}" STALE_DIR="${MNEMON_SKILL_LOOP_STALE_DIR:-${SKILL_LOOP_DIR}/skills/stale}" ARCHIVED_DIR="${MNEMON_SKILL_LOOP_ARCHIVED_DIR:-${SKILL_LOOP_DIR}/skills/archived}" @@ -19,7 +19,7 @@ GUIDE_FILE="${SKILL_LOOP_DIR}/GUIDE.md" mkdir -p "${ACTIVE_DIR}" "${STALE_DIR}" "${ARCHIVED_DIR}" "${HOST_SKILLS_DIR}" is_generated_skill() { - [[ -f "$1/.mnemon-skill-loop-generated" ]] + [[ -f "$1/.mnemon-skill-generated" ]] } is_active_skill_id() { @@ -38,7 +38,7 @@ while IFS= read -r marker; do rm -rf "${skill_dir}" REMOVED=$((REMOVED + 1)) fi -done < <(find "${HOST_SKILLS_DIR}" -mindepth 2 -maxdepth 2 -name .mnemon-skill-loop-generated -print 2>/dev/null) +done < <(find "${HOST_SKILLS_DIR}" -mindepth 2 -maxdepth 2 -name .mnemon-skill-generated -print 2>/dev/null) while IFS= read -r src_dir; do skill_id="$(basename "${src_dir}")" @@ -50,7 +50,7 @@ while IFS= read -r src_dir; do if [[ -e "${dst_dir}" ]]; then if ! is_generated_skill "${dst_dir}"; then - echo "[mnemon-skill-loop] Skip active skill '${skill_id}': host skill already exists and is not generated by Mnemon." + echo "[mnemon-skill] Skip active skill '${skill_id}': host skill already exists and is not generated by Mnemon." SKIPPED=$((SKIPPED + 1)) continue fi @@ -58,11 +58,11 @@ while IFS= read -r src_dir; do rm -rf "${dst_dir}" cp -R "${src_dir}" "${dst_dir}" - touch "${dst_dir}/.mnemon-skill-loop-generated" + touch "${dst_dir}/.mnemon-skill-generated" SYNCED=$((SYNCED + 1)) done < <(find "${ACTIVE_DIR}" -mindepth 1 -maxdepth 1 -type d -print 2>/dev/null | sort) -echo "[mnemon-skill-loop] Prime" +echo "[mnemon-skill] Prime" echo echo "MNEMON_SKILL_LOOP_ENV=${ENV_PATH}" echo "MNEMON_SKILL_LOOP_DIR=${SKILL_LOOP_DIR}" diff --git a/harness/hosts/claude-code/skill/hooks/remind.sh b/harness/hosts/claude-code/skill/hooks/remind.sh new file mode 100644 index 0000000..db6fc00 --- /dev/null +++ b/harness/hosts/claude-code/skill/hooks/remind.sh @@ -0,0 +1,4 @@ +#!/usr/bin/env bash +set -euo pipefail + +echo "[mnemon-skill] Remind is no-op by default; use host-native skill discovery." diff --git a/harness/hosts/claude-code/skill-loop/scripts/update_settings.py b/harness/hosts/claude-code/skill/scripts/update_settings.py similarity index 97% rename from harness/hosts/claude-code/skill-loop/scripts/update_settings.py rename to harness/hosts/claude-code/skill/scripts/update_settings.py index a0afceb..9309e1b 100644 --- a/harness/hosts/claude-code/skill-loop/scripts/update_settings.py +++ b/harness/hosts/claude-code/skill/scripts/update_settings.py @@ -66,7 +66,7 @@ def write_json(path: Path, data: dict[str, Any]) -> None: def contains_mnemon(value: Any) -> bool: if isinstance(value, str): - return "mnemon-skill-loop" in value + return "mnemon-skill" in value if isinstance(value, dict): return any(contains_mnemon(item) for item in value.values()) if isinstance(value, list): @@ -117,7 +117,7 @@ def add_hook(data: dict[str, Any], event: str, command: Path) -> None: def install(args: argparse.Namespace) -> None: config_dir = Path(args.config_dir) settings_path = config_dir / "settings.json" - hooks_dir = config_dir / "hooks" / "mnemon-skill-loop" + hooks_dir = config_dir / "hooks" / "mnemon-skill" data = load_json(settings_path) remove_hooks(data) diff --git a/harness/hosts/codex/host.json b/harness/hosts/codex/host.json index 1163289..95ee234 100644 --- a/harness/hosts/codex/host.json +++ b/harness/hosts/codex/host.json @@ -1,14 +1,29 @@ { - "schema_version": 1, + "schema_version": 2, "name": "codex", "display_name": "Codex", - "description": "Projects Mnemon harness modules into Codex repo-local skills and app-server readable state.", - "projection_surfaces": [ - ".codex/skills", - ".codex/mnemon-memory-loop", - ".codex/mnemon-skill-loop", - ".mnemon/hosts/codex/manifest.json" - ], + "description": "Projects Mnemon harness loops into Codex repo-local skills and app-server readable state.", + "surfaces": { + "projection": [ + ".codex/skills", + ".codex/mnemon-memory", + ".codex/mnemon-skill", + ".codex/mnemon-eval" + ], + "observation": [ + ".mnemon/hosts/codex/manifest.json", + ".mnemon/harness/*/status.json", + "app-server eval transcripts", + "skill usage evidence" + ] + }, + "lifecycle_mapping": { + "prime": "thread/start developer instructions", + "remind": "user prompt guidance", + "nudge": "turn completion guidance", + "compact": "thread compact guidance", + "maintenance": "app-server eval or manual skill invocation" + }, "supports": { "skills": true, "hooks": false, diff --git a/harness/hosts/codex/projector.sh b/harness/hosts/codex/projector.sh index 86b539b..ef8874c 100755 --- a/harness/hosts/codex/projector.sh +++ b/harness/hosts/codex/projector.sh @@ -3,12 +3,12 @@ set -euo pipefail usage() { cat <<'USAGE' -Project Mnemon harness modules into Codex. +Project Mnemon harness loops into Codex. Usage: - projector.sh install --module MODULE [options] - projector.sh status --module MODULE [options] - projector.sh uninstall --module MODULE [options] + projector.sh install --loop LOOP [options] + projector.sh status --loop LOOP [options] + projector.sh uninstall --loop LOOP [options] Common options: --global @@ -30,8 +30,8 @@ USAGE } SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -# shellcheck source=../../setup/lib/paths.sh -source "${SCRIPT_DIR}/../../setup/lib/paths.sh" +# shellcheck source=../../ops/lib/paths.sh +source "${SCRIPT_DIR}/../../ops/lib/paths.sh" ACTION="${1:-}" if [[ -z "${ACTION}" ]]; then @@ -40,7 +40,7 @@ if [[ -z "${ACTION}" ]]; then fi shift -MODULE="" +LOOP="" CONFIG_DIR=".codex" CONFIG_DIR_EXPLICIT=0 GLOBAL=0 @@ -51,8 +51,8 @@ PURGE_LIBRARY=0 while [[ $# -gt 0 ]]; do case "$1" in - --module) - MODULE="${2:?missing value for --module}" + --loop) + LOOP="${2:?missing value for --loop}" shift 2 ;; --global) @@ -93,19 +93,19 @@ while [[ $# -gt 0 ]]; do esac done -if [[ -z "${MODULE}" ]]; then - echo "--module is required" >&2 +if [[ -z "${LOOP}" ]]; then + echo "--loop is required" >&2 usage >&2 exit 2 fi -if [[ "${MODULE}" != "memory-loop" && "${MODULE}" != "skill-loop" && "${MODULE}" != "eval-loop" ]]; then - echo "unsupported module for Codex: ${MODULE}" >&2 +if [[ "${LOOP}" != "memory" && "${LOOP}" != "skill" && "${LOOP}" != "eval" ]]; then + echo "unsupported loop for Codex: ${LOOP}" >&2 exit 1 fi -MODULE_DIR="$(mnemon_module_dir "${MODULE}")" -if [[ ! -d "${MODULE_DIR}" ]]; then - echo "module directory not found: ${MODULE_DIR}" >&2 +LOOP_DIR="$(mnemon_loop_dir "${LOOP}")" +if [[ ! -d "${LOOP_DIR}" ]]; then + echo "loop directory not found: ${LOOP_DIR}" >&2 exit 1 fi @@ -114,7 +114,7 @@ if [[ "${GLOBAL}" == "1" && "${CONFIG_DIR_EXPLICIT}" == "0" ]]; then else MNEMON_DIR="${MNEMON_HARNESS_STATE_DIR:-.mnemon}" fi -CANONICAL_MODULE_DIR="${MNEMON_DIR}/harness/${MODULE}" +CANONICAL_LOOP_DIR="${MNEMON_DIR}/harness/${LOOP}" HOST_MANIFEST_DIR="${MNEMON_DIR}/hosts/codex" HOST_MANIFEST="${HOST_MANIFEST_DIR}/manifest.json" @@ -136,26 +136,55 @@ ensure_python() { ensure_mnemon_binary() { if ! command -v mnemon >/dev/null 2>&1; then - echo "mnemon binary not found in PATH. Build or install it before running Codex memory-loop evals." >&2 + echo "mnemon binary not found in PATH. Build or install it before running Codex memory evals." >&2 exit 1 fi } copy_common_canonical_assets() { - mkdir -p "${CANONICAL_MODULE_DIR}" - install_file "${MODULE_DIR}/GUIDE.md" "${CANONICAL_MODULE_DIR}/GUIDE.md" 0644 - install_file "${MODULE_DIR}/env.sh" "${CANONICAL_MODULE_DIR}/env.sh" 0755 - install_file "${MODULE_DIR}/module.json" "${CANONICAL_MODULE_DIR}/module.json" 0644 + mkdir -p "${CANONICAL_LOOP_DIR}" + install_file "${LOOP_DIR}/GUIDE.md" "${CANONICAL_LOOP_DIR}/GUIDE.md" 0644 + install_file "${LOOP_DIR}/env.sh" "${CANONICAL_LOOP_DIR}/env.sh" 0755 + install_file "${LOOP_DIR}/loop.json" "${CANONICAL_LOOP_DIR}/loop.json" 0644 +} + +write_loop_status() { + local projection_path="$1" + MNEMON_LOOP_JSON="${LOOP_DIR}/loop.json" \ + MNEMON_LOOP_STATUS="${CANONICAL_LOOP_DIR}/status.json" \ + MNEMON_HOST="codex" \ + MNEMON_HOST_PROJECT_ROOT="$(pwd)" \ + MNEMON_HOST_PROJECTION_PATH="${projection_path}" \ + python3 - <<'PY' +import json +import os +from datetime import datetime, timezone +from pathlib import Path + +loop = json.loads(Path(os.environ["MNEMON_LOOP_JSON"]).read_text()) +status = { + "schema_version": 2, + "loop": loop["name"], + "host": os.environ["MNEMON_HOST"], + "phase": "projected", + "updated_at": datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z"), + "project_root": os.environ["MNEMON_HOST_PROJECT_ROOT"], + "projection_path": os.environ["MNEMON_HOST_PROJECTION_PATH"], + "state_path": str(Path(os.environ["MNEMON_LOOP_STATUS"]).parent), + "control_model": loop.get("control_model", {}), + "entity_profiles": loop.get("entity_profiles", {}), + "surfaces": loop.get("surfaces", {}), +} +Path(os.environ["MNEMON_LOOP_STATUS"]).write_text(json.dumps(status, indent=2) + "\n") +PY } write_host_manifest() { local projection_path="$1" - local module_version - module_version="$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1])).get("version",""))' "${MODULE_DIR}/module.json")" mkdir -p "${HOST_MANIFEST_DIR}" MNEMON_HOST_MANIFEST="${HOST_MANIFEST}" \ - MNEMON_HOST_MODULE="${MODULE}" \ - MNEMON_HOST_MODULE_VERSION="${module_version}" \ + MNEMON_HOST_LOOP="${LOOP}" \ + MNEMON_HOST_LOOP_JSON="${LOOP_DIR}/loop.json" \ MNEMON_HOST_PROJECT_ROOT="$(pwd)" \ MNEMON_HOST_MNEMON_DIR="${MNEMON_DIR}" \ MNEMON_HOST_STORE="${STORE_NAME:-default}" \ @@ -167,21 +196,36 @@ from datetime import datetime, timezone from pathlib import Path path = Path(os.environ["MNEMON_HOST_MANIFEST"]) +loop = json.loads(Path(os.environ["MNEMON_HOST_LOOP_JSON"]).read_text()) if path.exists() and path.stat().st_size: data = json.loads(path.read_text()) else: - data = {"schema_version": 1, "host": "codex", "loops": {}} + data = {"schema_version": 2, "host": "codex", "loops": {}} -data["schema_version"] = 1 +data["schema_version"] = 2 data["host"] = "codex" data["updated_at"] = datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z") data["project_root"] = os.environ["MNEMON_HOST_PROJECT_ROOT"] data["mnemon_dir"] = os.environ["MNEMON_HOST_MNEMON_DIR"] data["store"] = os.environ["MNEMON_HOST_STORE"] -data.setdefault("loops", {})[os.environ["MNEMON_HOST_MODULE"]] = { - "module_path": f"{os.environ['MNEMON_HOST_MNEMON_DIR']}/harness/{os.environ['MNEMON_HOST_MODULE']}", - "module_version": os.environ["MNEMON_HOST_MODULE_VERSION"], - "projection_path": os.environ["MNEMON_HOST_PROJECTION_PATH"], +data.setdefault("loops", {})[os.environ["MNEMON_HOST_LOOP"]] = { + "loop_path": f"{os.environ['MNEMON_HOST_MNEMON_DIR']}/harness/{os.environ['MNEMON_HOST_LOOP']}", + "loop_version": loop.get("version", ""), + "state_path": f"{os.environ['MNEMON_HOST_MNEMON_DIR']}/harness/{os.environ['MNEMON_HOST_LOOP']}", + "intent_policy": f"{os.environ['MNEMON_HOST_MNEMON_DIR']}/harness/{os.environ['MNEMON_HOST_LOOP']}/GUIDE.md", + "status_path": f"{os.environ['MNEMON_HOST_MNEMON_DIR']}/harness/{os.environ['MNEMON_HOST_LOOP']}/status.json", + "projection": { + "path": os.environ["MNEMON_HOST_PROJECTION_PATH"], + "surfaces": loop.get("surfaces", {}).get("projection", []), + }, + "reality": { + "surfaces": loop.get("surfaces", {}).get("observation", []), + }, + "reconcile": { + "actions": loop.get("control_model", {}).get("reconcile", []), + }, + "control_model": loop.get("control_model", {}), + "entity_profiles": loop.get("entity_profiles", {}), "lifecycle_mapping": { "prime": "thread/start developer instructions", "remind": "user prompt guidance", @@ -190,16 +234,17 @@ data.setdefault("loops", {})[os.environ["MNEMON_HOST_MODULE"]] = { }, "surfaces": { "skills": f"{os.environ['MNEMON_HOST_PROJECTION_PATH']}/skills", - "runtime": f"{os.environ['MNEMON_HOST_PROJECTION_PATH']}/mnemon-{os.environ['MNEMON_HOST_MODULE']}", - }, + "runtime": f"{os.environ['MNEMON_HOST_PROJECTION_PATH']}/mnemon-{os.environ['MNEMON_HOST_LOOP']}", + }, } path.write_text(json.dumps(data, indent=2) + "\n") PY + write_loop_status "${projection_path}" } -remove_host_manifest_module() { +remove_host_manifest_loop() { [[ -f "${HOST_MANIFEST}" ]] || return 0 - MNEMON_HOST_MANIFEST="${HOST_MANIFEST}" MNEMON_HOST_MODULE="${MODULE}" python3 - <<'PY' + MNEMON_HOST_MANIFEST="${HOST_MANIFEST}" MNEMON_HOST_LOOP="${LOOP}" python3 - <<'PY' import json import os from pathlib import Path @@ -208,7 +253,7 @@ path = Path(os.environ["MNEMON_HOST_MANIFEST"]) data = json.loads(path.read_text()) loops = data.get("loops") if isinstance(loops, dict): - loops.pop(os.environ["MNEMON_HOST_MODULE"], None) + loops.pop(os.environ["MNEMON_HOST_LOOP"], None) if not data.get("loops"): path.unlink() else: @@ -223,8 +268,8 @@ write_runtime_env() { mkdir -p "${runtime_dir}" cat > "${runtime_dir}/env.sh" </dev/null | sed 's/^[* ]*//' | grep -qx "${STORE_NAME}"; then @@ -277,7 +322,7 @@ install_memory_loop() { write_host_manifest "${CONFIG_DIR}" echo "Installed Mnemon memory loop for Codex." echo "Config: ${CONFIG_DIR}" - echo "State: ${CANONICAL_MODULE_DIR}" + echo "State: ${CANONICAL_LOOP_DIR}" } install_skill_loop() { @@ -285,42 +330,42 @@ install_skill_loop() { [[ -n "${HOST_SKILLS_DIR}" ]] || HOST_SKILLS_DIR="${CONFIG_DIR}/skills" copy_common_canonical_assets mkdir -p \ - "${CANONICAL_MODULE_DIR}/skills/active" \ - "${CANONICAL_MODULE_DIR}/skills/stale" \ - "${CANONICAL_MODULE_DIR}/skills/archived" \ - "${CANONICAL_MODULE_DIR}/proposals" \ - "${CANONICAL_MODULE_DIR}/reports" \ + "${CANONICAL_LOOP_DIR}/skills/active" \ + "${CANONICAL_LOOP_DIR}/skills/stale" \ + "${CANONICAL_LOOP_DIR}/skills/archived" \ + "${CANONICAL_LOOP_DIR}/proposals" \ + "${CANONICAL_LOOP_DIR}/reports" \ "${HOST_SKILLS_DIR}/skill_observe" \ "${HOST_SKILLS_DIR}/skill_curate" \ "${HOST_SKILLS_DIR}/skill_author" \ "${HOST_SKILLS_DIR}/skill_manage" \ - "${CONFIG_DIR}/mnemon-skill-loop" - write_runtime_env "${CONFIG_DIR}/mnemon-skill-loop" "MNEMON_SKILL_LOOP_ENV" "MNEMON_SKILL_LOOP_DIR" - install_file "${MODULE_DIR}/GUIDE.md" "${CONFIG_DIR}/mnemon-skill-loop/GUIDE.md" 0644 - cat >> "${CONFIG_DIR}/mnemon-skill-loop/env.sh" <> "${CONFIG_DIR}/mnemon-skill/env.sh" <> "${CONFIG_DIR}/mnemon-eval-loop/env.sh" <> "${CONFIG_DIR}/mnemon-eval/env.sh" </dev/null || true + rm -f "${CANONICAL_LOOP_DIR}/GUIDE.md" "${CANONICAL_LOOP_DIR}/env.sh" "${CANONICAL_LOOP_DIR}/loop.json" "${CANONICAL_LOOP_DIR}/status.json" + rmdir "${CANONICAL_LOOP_DIR}" 2>/dev/null || true fi - remove_host_manifest_module + remove_host_manifest_loop echo "Removed Mnemon memory loop from ${CONFIG_DIR}." } uninstall_skill_loop() { - local env_path="${CONFIG_DIR}/mnemon-skill-loop/env.sh" + local env_path="${CONFIG_DIR}/mnemon-skill/env.sh" if [[ -f "${env_path}" ]]; then # shellcheck source=/dev/null source "${env_path}" @@ -420,21 +470,21 @@ uninstall_skill_loop() { rm -rf "${host_skills_dir}/skill_curate" rm -rf "${host_skills_dir}/skill_author" rm -rf "${host_skills_dir}/skill_manage" - rm -rf "${CONFIG_DIR}/mnemon-skill-loop" + rm -rf "${CONFIG_DIR}/mnemon-skill" if [[ "${PURGE_LIBRARY}" == "1" ]]; then - rm -rf "${CANONICAL_MODULE_DIR}" + rm -rf "${CANONICAL_LOOP_DIR}" else - rm -f "${CANONICAL_MODULE_DIR}/GUIDE.md" "${CANONICAL_MODULE_DIR}/env.sh" "${CANONICAL_MODULE_DIR}/module.json" - rmdir "${CANONICAL_MODULE_DIR}/reports" 2>/dev/null || true - rmdir "${CANONICAL_MODULE_DIR}/proposals" 2>/dev/null || true - rmdir "${CANONICAL_MODULE_DIR}" 2>/dev/null || true + rm -f "${CANONICAL_LOOP_DIR}/GUIDE.md" "${CANONICAL_LOOP_DIR}/env.sh" "${CANONICAL_LOOP_DIR}/loop.json" "${CANONICAL_LOOP_DIR}/status.json" + rmdir "${CANONICAL_LOOP_DIR}/reports" 2>/dev/null || true + rmdir "${CANONICAL_LOOP_DIR}/proposals" 2>/dev/null || true + rmdir "${CANONICAL_LOOP_DIR}" 2>/dev/null || true fi - remove_host_manifest_module + remove_host_manifest_loop echo "Removed Mnemon skill loop from ${CONFIG_DIR}." } uninstall_eval_loop() { - local env_path="${CONFIG_DIR}/mnemon-eval-loop/env.sh" + local env_path="${CONFIG_DIR}/mnemon-eval/env.sh" if [[ -f "${env_path}" ]]; then # shellcheck source=/dev/null source "${env_path}" @@ -444,31 +494,31 @@ uninstall_eval_loop() { rm -rf "${host_skills_dir}/eval_run" rm -rf "${host_skills_dir}/eval_analyze" rm -rf "${host_skills_dir}/eval_improve" - rm -rf "${CONFIG_DIR}/mnemon-eval-loop" - rm -rf "${CANONICAL_MODULE_DIR}/scenarios" - rm -rf "${CANONICAL_MODULE_DIR}/suites" - rm -rf "${CANONICAL_MODULE_DIR}/rubrics" - rm -f "${CANONICAL_MODULE_DIR}/GUIDE.md" "${CANONICAL_MODULE_DIR}/env.sh" "${CANONICAL_MODULE_DIR}/module.json" - rmdir "${CANONICAL_MODULE_DIR}/retired" 2>/dev/null || true - rmdir "${CANONICAL_MODULE_DIR}/artifacts" 2>/dev/null || true - rmdir "${CANONICAL_MODULE_DIR}/reports" 2>/dev/null || true - rmdir "${CANONICAL_MODULE_DIR}/candidates" 2>/dev/null || true - rmdir "${CANONICAL_MODULE_DIR}/scratch" 2>/dev/null || true - rmdir "${CANONICAL_MODULE_DIR}" 2>/dev/null || true - remove_host_manifest_module + rm -rf "${CONFIG_DIR}/mnemon-eval" + rm -rf "${CANONICAL_LOOP_DIR}/scenarios" + rm -rf "${CANONICAL_LOOP_DIR}/suites" + rm -rf "${CANONICAL_LOOP_DIR}/rubrics" + rm -f "${CANONICAL_LOOP_DIR}/GUIDE.md" "${CANONICAL_LOOP_DIR}/env.sh" "${CANONICAL_LOOP_DIR}/loop.json" "${CANONICAL_LOOP_DIR}/status.json" + rmdir "${CANONICAL_LOOP_DIR}/retired" 2>/dev/null || true + rmdir "${CANONICAL_LOOP_DIR}/artifacts" 2>/dev/null || true + rmdir "${CANONICAL_LOOP_DIR}/reports" 2>/dev/null || true + rmdir "${CANONICAL_LOOP_DIR}/candidates" 2>/dev/null || true + rmdir "${CANONICAL_LOOP_DIR}/scratch" 2>/dev/null || true + rmdir "${CANONICAL_LOOP_DIR}" 2>/dev/null || true + remove_host_manifest_loop echo "Removed Mnemon eval loop from ${CONFIG_DIR}." } -case "${ACTION}:${MODULE}" in - install:memory-loop) install_memory_loop ;; - install:skill-loop) install_skill_loop ;; - install:eval-loop) install_eval_loop ;; - status:memory-loop|status:skill-loop|status:eval-loop) status_module ;; - uninstall:memory-loop) uninstall_memory_loop ;; - uninstall:skill-loop) uninstall_skill_loop ;; - uninstall:eval-loop) uninstall_eval_loop ;; +case "${ACTION}:${LOOP}" in + install:memory) install_memory_loop ;; + install:skill) install_skill_loop ;; + install:eval) install_eval_loop ;; + status:memory|status:skill|status:eval) status_loop ;; + uninstall:memory) uninstall_memory_loop ;; + uninstall:skill) uninstall_skill_loop ;; + uninstall:eval) uninstall_eval_loop ;; *) - echo "unsupported action/module: ${ACTION}/${MODULE}" >&2 + echo "unsupported action/loop: ${ACTION}/${LOOP}" >&2 exit 1 ;; esac diff --git a/harness/loops/README.md b/harness/loops/README.md new file mode 100644 index 0000000..b0ebc85 --- /dev/null +++ b/harness/loops/README.md @@ -0,0 +1,13 @@ +# Mnemon Harness Loops + +This directory contains canonical, host-agnostic loop templates. + +```text +harness/loops/ +├── memory/ +├── skill/ +└── eval/ +``` + +Each loop follows the Loop Standard and declares its assets in +`loop.json`. Host-specific projection logic belongs under `harness/hosts/`. diff --git a/harness/modules/eval-loop/GUIDE.md b/harness/loops/eval/GUIDE.md similarity index 100% rename from harness/modules/eval-loop/GUIDE.md rename to harness/loops/eval/GUIDE.md diff --git a/harness/modules/eval-loop/README.md b/harness/loops/eval/README.md similarity index 83% rename from harness/modules/eval-loop/README.md rename to harness/loops/eval/README.md index dbf8091..1cddee0 100644 --- a/harness/modules/eval-loop/README.md +++ b/harness/loops/eval/README.md @@ -1,19 +1,19 @@ # Mnemon Eval Loop Harness -This directory is the canonical eval loop module. It is a feedback-facing loop: +This directory is the canonical eval loop template. It is a feedback-facing loop: it designs and runs realistic harness scenarios, collects evidence, and turns stable failures into curated improvement candidates. -The eval loop is not a parent of memory-loop or skill-loop. It is a peer module +The eval loop is not a parent of memory or skill. It is a peer loop that can evaluate interface-facing loops, host projection, setup, documentation workflow, commit discipline, and its own eval assets. ## File Tree ```text -harness/modules/eval-loop/ +harness/loops/eval/ ├── README.md -├── module.json +├── loop.json ├── env.sh ├── GUIDE.md ├── hooks/ @@ -67,8 +67,8 @@ $MNEMON_EVAL_LOOP_DIR/ `env.sh` defines: ```bash -MNEMON_EVAL_LOOP_ENV=/harness/eval-loop/env.sh -MNEMON_EVAL_LOOP_DIR=/harness/eval-loop +MNEMON_EVAL_LOOP_ENV=/harness/eval/env.sh +MNEMON_EVAL_LOOP_DIR=/harness/eval MNEMON_EVAL_LOOP_SCRATCH_DIR=$MNEMON_EVAL_LOOP_DIR/scratch MNEMON_EVAL_LOOP_CANDIDATES_DIR=$MNEMON_EVAL_LOOP_DIR/candidates MNEMON_EVAL_LOOP_REPORTS_DIR=$MNEMON_EVAL_LOOP_DIR/reports @@ -81,19 +81,19 @@ MNEMON_EVAL_LOOP_RETIRED_DIR=$MNEMON_EVAL_LOOP_DIR/retired Install into the current project: ```bash -bash harness/setup/install.sh --host codex --module eval-loop +bash harness/ops/install.sh --host codex --loop eval ``` Check status: ```bash -bash harness/setup/status.sh --host codex --module eval-loop +bash harness/ops/status.sh --host codex --loop eval ``` Remove the installed Codex integration while preserving reports and candidates: ```bash -bash harness/setup/uninstall.sh --host codex --module eval-loop +bash harness/ops/uninstall.sh --host codex --loop eval ``` Existing project-local Codex app-server eval commands remain available through diff --git a/harness/modules/eval-loop/env.sh b/harness/loops/eval/env.sh similarity index 100% rename from harness/modules/eval-loop/env.sh rename to harness/loops/eval/env.sh diff --git a/harness/modules/eval-loop/hooks/compact.md b/harness/loops/eval/hooks/compact.md similarity index 100% rename from harness/modules/eval-loop/hooks/compact.md rename to harness/loops/eval/hooks/compact.md diff --git a/harness/modules/eval-loop/hooks/nudge.md b/harness/loops/eval/hooks/nudge.md similarity index 100% rename from harness/modules/eval-loop/hooks/nudge.md rename to harness/loops/eval/hooks/nudge.md diff --git a/harness/modules/eval-loop/hooks/prime.md b/harness/loops/eval/hooks/prime.md similarity index 100% rename from harness/modules/eval-loop/hooks/prime.md rename to harness/loops/eval/hooks/prime.md diff --git a/harness/modules/eval-loop/hooks/remind.md b/harness/loops/eval/hooks/remind.md similarity index 100% rename from harness/modules/eval-loop/hooks/remind.md rename to harness/loops/eval/hooks/remind.md diff --git a/harness/modules/eval-loop/module.json b/harness/loops/eval/loop.json similarity index 51% rename from harness/modules/eval-loop/module.json rename to harness/loops/eval/loop.json index a82e5bd..36bfb97 100644 --- a/harness/modules/eval-loop/module.json +++ b/harness/loops/eval/loop.json @@ -1,11 +1,81 @@ { - "schema_version": 1, - "name": "eval-loop", + "schema_version": 2, + "name": "eval", "version": "0.1.0", "description": "Runs scenario-driven harness evaluations, collects evidence, and curates improvements without making eval assets canonical by default.", "loop_type": "feedback", "direct_interface_effect": false, "primary_host": "codex", + "control_model": { + "state": [ + "scenarios", + "suites", + "rubrics", + "scratch", + "candidates", + "reports", + "artifacts", + "eval status" + ], + "intent": "Turn lifecycle behavior into scenario evidence and promote only reviewed improvements.", + "reality": [ + "HostAgent eval runs", + "scenario outcomes", + "rubric findings", + "artifact diffs", + "regression signals" + ], + "reconcile": [ + "plan", + "run", + "analyze", + "improve", + "retire", + "no-op" + ] + }, + "entity_profiles": { + "template": "eval", + "controlled": [ + "eval binding" + ], + "surface": [ + "eval protocol skills", + "scenario files", + "suite files", + "rubrics", + "app-server" + ], + "evidence": [ + "eval reports", + "artifacts", + "rubric findings", + "regression signals" + ], + "governance": [ + "candidate improvements", + "reviewed promotions", + "retired assets" + ] + }, + "surfaces": { + "projection": [ + "eval_plan", + "eval_run", + "eval_analyze", + "eval_improve", + "scenarios", + "suites", + "rubrics", + "runtime env" + ], + "observation": [ + "app-server transcripts", + "eval reports", + "artifacts", + "scenario results" + ] + }, "lifecycle_events": [ "prime", "remind", @@ -23,7 +93,7 @@ "scenarios/memory/project-preference-recall.md", "scenarios/skill/skill-creation-reuse.md", "scenarios/docs/bilingual-doc-sync.md", - "scenarios/setup/host-projection-smoke.md" + "scenarios/ops/host-projection-smoke.md" ], "hooks": { "prime": "hooks/prime.md", diff --git a/harness/modules/eval-loop/rubrics/eval-asset-quality.md b/harness/loops/eval/rubrics/eval-asset-quality.md similarity index 100% rename from harness/modules/eval-loop/rubrics/eval-asset-quality.md rename to harness/loops/eval/rubrics/eval-asset-quality.md diff --git a/harness/modules/eval-loop/rubrics/interface-loop-behavior.md b/harness/loops/eval/rubrics/interface-loop-behavior.md similarity index 100% rename from harness/modules/eval-loop/rubrics/interface-loop-behavior.md rename to harness/loops/eval/rubrics/interface-loop-behavior.md diff --git a/harness/modules/eval-loop/scenarios/docs/bilingual-doc-sync.md b/harness/loops/eval/scenarios/docs/bilingual-doc-sync.md similarity index 95% rename from harness/modules/eval-loop/scenarios/docs/bilingual-doc-sync.md rename to harness/loops/eval/scenarios/docs/bilingual-doc-sync.md index 79d5738..f23d9f5 100644 --- a/harness/modules/eval-loop/scenarios/docs/bilingual-doc-sync.md +++ b/harness/loops/eval/scenarios/docs/bilingual-doc-sync.md @@ -2,7 +2,7 @@ Target: - docs workflow -- memory-loop or skill-loop support +- memory or skill support Purpose: Verify that harness changes update relevant English and Chinese documentation diff --git a/harness/modules/eval-loop/scenarios/memory/project-preference-recall.md b/harness/loops/eval/scenarios/memory/project-preference-recall.md similarity index 95% rename from harness/modules/eval-loop/scenarios/memory/project-preference-recall.md rename to harness/loops/eval/scenarios/memory/project-preference-recall.md index d9f1906..70e578e 100644 --- a/harness/modules/eval-loop/scenarios/memory/project-preference-recall.md +++ b/harness/loops/eval/scenarios/memory/project-preference-recall.md @@ -1,7 +1,7 @@ # Project Preference Recall Target: -- memory-loop +- memory - HostAgent project behavior Purpose: @@ -10,7 +10,7 @@ otherwise omit them. Setup: - Start an isolated Codex app-server workspace. -- Install `memory-loop`. +- Install `memory`. - Seed `.mnemon` with a concrete project preference. Task: diff --git a/harness/modules/eval-loop/scenarios/setup/host-projection-smoke.md b/harness/loops/eval/scenarios/ops/host-projection-smoke.md similarity index 56% rename from harness/modules/eval-loop/scenarios/setup/host-projection-smoke.md rename to harness/loops/eval/scenarios/ops/host-projection-smoke.md index 807dc95..53fbe2c 100644 --- a/harness/modules/eval-loop/scenarios/setup/host-projection-smoke.md +++ b/harness/loops/eval/scenarios/ops/host-projection-smoke.md @@ -5,21 +5,21 @@ Target: - host projection Purpose: -Verify that a loop module can be installed into a host surface and reported in +Verify that a loop template can be installed into a host surface and reported in the host manifest. Setup: - Use an isolated workspace. -- Run `harness/setup/install.sh` for the target host and module. +- Run `harness/ops/install.sh` for the target host and loop. Task: -Install the module, inspect projected files, and run setup status. +Install the loop, inspect projected files, and run setup status. Expected Evidence: -- Runtime state exists under `.mnemon/harness/`. +- Runtime state exists under `.mnemon/harness/`. - Host projection files exist. - Manifest contains the installed loop. -- Status reports the module as installed. +- Status reports the loop as installed. Rubric: - pass: projection, manifest, and status agree. diff --git a/harness/modules/eval-loop/scenarios/skill/skill-creation-reuse.md b/harness/loops/eval/scenarios/skill/skill-creation-reuse.md similarity index 95% rename from harness/modules/eval-loop/scenarios/skill/skill-creation-reuse.md rename to harness/loops/eval/scenarios/skill/skill-creation-reuse.md index 1939caf..3cb0047 100644 --- a/harness/modules/eval-loop/scenarios/skill/skill-creation-reuse.md +++ b/harness/loops/eval/scenarios/skill/skill-creation-reuse.md @@ -1,7 +1,7 @@ # Skill Creation And Reuse Target: -- skill-loop +- skill - reusable workflow behavior Purpose: @@ -10,7 +10,7 @@ reviewable skill candidate without immediate uncontrolled activation. Setup: - Start an isolated Codex app-server workspace. -- Install `skill-loop`. +- Install `skill`. - Provide a task that repeats a maintenance pattern with known missed steps. Task: diff --git a/harness/modules/eval-loop/skills/eval_analyze.md b/harness/loops/eval/skills/eval_analyze.md similarity index 95% rename from harness/modules/eval-loop/skills/eval_analyze.md rename to harness/loops/eval/skills/eval_analyze.md index d558bfd..5adede0 100644 --- a/harness/modules/eval-loop/skills/eval_analyze.md +++ b/harness/loops/eval/skills/eval_analyze.md @@ -18,9 +18,9 @@ evidence. - `fail`: behavior contradicts the target expectation. - `invalid`: setup or scenario issue prevents judgement. 4. Identify the likely improvement target: - - memory-loop - - skill-loop - - eval-loop + - memory + - skill + - eval - host adapter - setup - docs diff --git a/harness/modules/eval-loop/skills/eval_improve.md b/harness/loops/eval/skills/eval_improve.md similarity index 100% rename from harness/modules/eval-loop/skills/eval_improve.md rename to harness/loops/eval/skills/eval_improve.md diff --git a/harness/modules/eval-loop/skills/eval_plan.md b/harness/loops/eval/skills/eval_plan.md similarity index 98% rename from harness/modules/eval-loop/skills/eval_plan.md rename to harness/loops/eval/skills/eval_plan.md index 9a8417e..f685407 100644 --- a/harness/modules/eval-loop/skills/eval_plan.md +++ b/harness/loops/eval/skills/eval_plan.md @@ -10,7 +10,7 @@ Use this skill to design a scenario-driven eval before running a HostAgent. ## Procedure 1. Identify the target: loop, setup behavior, host projection, docs workflow, or - eval-loop itself. + eval itself. 2. Choose an existing scenario and suite when one fits. 3. If no scenario fits, draft an ephemeral plan first. Do not promote it during the same step. diff --git a/harness/modules/eval-loop/skills/eval_run.md b/harness/loops/eval/skills/eval_run.md similarity index 94% rename from harness/modules/eval-loop/skills/eval_run.md rename to harness/loops/eval/skills/eval_run.md index 9f417d4..120ef5c 100644 --- a/harness/modules/eval-loop/skills/eval_run.md +++ b/harness/loops/eval/skills/eval_run.md @@ -12,7 +12,7 @@ Use this skill to execute or supervise a planned eval run. 1. Confirm the plan names a host, suite or scenario, and evidence targets. 2. Create or use an isolated workspace. Do not run scenario state in the developer's active workspace unless the eval explicitly requires it. -3. Install the requested loop modules with `harness/setup`. +3. Install the requested loop templates with `harness/ops`. 4. For Codex app-server evals, use the project runner when available: ```bash diff --git a/harness/modules/eval-loop/subagents/evaluator.md b/harness/loops/eval/subagents/evaluator.md similarity index 89% rename from harness/modules/eval-loop/subagents/evaluator.md rename to harness/loops/eval/subagents/evaluator.md index 5509e39..73fe30d 100644 --- a/harness/modules/eval-loop/subagents/evaluator.md +++ b/harness/loops/eval/subagents/evaluator.md @@ -16,5 +16,5 @@ Use this subagent for background eval curation and report synthesis. - Do not automatically make candidate eval assets canonical. - Do not loosen rubrics to reduce failures. - Do not hide setup or HostAgent failures. -- Do not modify memory-loop or skill-loop policy without a separate explicit +- Do not modify memory or skill policy without a separate explicit improvement task. diff --git a/harness/modules/eval-loop/suites/regression.json b/harness/loops/eval/suites/regression.json similarity index 91% rename from harness/modules/eval-loop/suites/regression.json rename to harness/loops/eval/suites/regression.json index 62001e5..fa8fc1a 100644 --- a/harness/modules/eval-loop/suites/regression.json +++ b/harness/loops/eval/suites/regression.json @@ -4,7 +4,7 @@ "host": "codex", "lifecycle": "promoted", "scenarios": [ - "setup/host-projection-smoke", + "ops/host-projection-smoke", "memory/project-preference-recall", "skill/skill-creation-reuse", "docs/bilingual-doc-sync" diff --git a/harness/modules/eval-loop/suites/smoke.json b/harness/loops/eval/suites/smoke.json similarity index 66% rename from harness/modules/eval-loop/suites/smoke.json rename to harness/loops/eval/suites/smoke.json index 72dfdc3..006d21b 100644 --- a/harness/modules/eval-loop/suites/smoke.json +++ b/harness/loops/eval/suites/smoke.json @@ -1,10 +1,10 @@ { "name": "smoke", - "description": "Fast checks for eval-loop setup and core interface-loop behavior.", + "description": "Fast checks for eval setup and core interface-loop behavior.", "host": "codex", "lifecycle": "promoted", "scenarios": [ - "setup/host-projection-smoke", + "ops/host-projection-smoke", "memory/project-preference-recall", "skill/skill-creation-reuse" ], diff --git a/harness/modules/memory-loop/GUIDE.md b/harness/loops/memory/GUIDE.md similarity index 100% rename from harness/modules/memory-loop/GUIDE.md rename to harness/loops/memory/GUIDE.md diff --git a/harness/modules/memory-loop/MEMORY.md b/harness/loops/memory/MEMORY.md similarity index 100% rename from harness/modules/memory-loop/MEMORY.md rename to harness/loops/memory/MEMORY.md diff --git a/harness/modules/memory-loop/README.md b/harness/loops/memory/README.md similarity index 80% rename from harness/modules/memory-loop/README.md rename to harness/loops/memory/README.md index 570ad8b..a62a718 100644 --- a/harness/modules/memory-loop/README.md +++ b/harness/loops/memory/README.md @@ -1,15 +1,15 @@ # Mnemon Memory Loop Harness -This directory is the canonical memory loop module. It is host-agnostic: a +This directory is the canonical memory loop template. It is host-agnostic: a capable host agent can read these Markdown assets, while host adapters project the loop into concrete runtimes such as Claude Code or Codex. ## File Tree ```text -harness/modules/memory-loop/ +harness/loops/memory/ ├── README.md -├── module.json +├── loop.json ├── env.sh ├── GUIDE.md ├── MEMORY.md @@ -37,14 +37,14 @@ harness/modules/memory-loop/ | Asset | Purpose | | --- | --- | -| `module.json` | Machine-readable loop manifest for standard lifecycle events, assets, state, and host adapters. | +| `loop.json` | Machine-readable loop manifest for standard lifecycle events, assets, state, and host adapters. | | `env.sh` | Runtime config: memory directory, env path, and dreaming threshold. | | `GUIDE.md` | Policy: when to read memory, when to write memory, and what is worth keeping. | | `hooks/*.md` | Four lifecycle reminders: Prime, Remind, Nudge, and Compact. | | `skills/memory_get.md` | Online long-term recall skill backed by `mnemon recall`. | | `skills/memory_set.md` | Online working-memory update skill backed by `MEMORY.md` edits. | | `subagents/dreaming.md` | Offline consolidation worker backed by Mnemon writes and `MEMORY.md` compaction. | -| Host adapter | Host-specific projection lives outside the module under `harness/hosts//`. | +| Host adapter | Host-specific projection lives outside the loop under `harness/hosts//`. | ## Runtime Directory Protocol @@ -61,8 +61,8 @@ $MNEMON_MEMORY_LOOP_DIR/ `env.sh` defines: ```bash -MNEMON_MEMORY_LOOP_ENV=/harness/memory-loop/env.sh -MNEMON_MEMORY_LOOP_DIR=/harness/memory-loop +MNEMON_MEMORY_LOOP_ENV=/harness/memory/env.sh +MNEMON_MEMORY_LOOP_DIR=/harness/memory MNEMON_MEMORY_LOOP_MAX_NON_EMPTY_LINES=200 ``` @@ -94,17 +94,17 @@ dreaming.md maps maintenance behavior to Mnemon write + MEMORY.md compaction. Install into the current project: ```bash -bash harness/setup/install.sh --host claude-code --module memory-loop +bash harness/ops/install.sh --host claude-code --loop memory ``` Install globally: ```bash -bash harness/setup/install.sh --host claude-code --module memory-loop --global +bash harness/ops/install.sh --host claude-code --loop memory --global ``` Remove the installed Claude Code integration while preserving `MEMORY.md`: ```bash -bash harness/setup/uninstall.sh --host claude-code --module memory-loop +bash harness/ops/uninstall.sh --host claude-code --loop memory ``` diff --git a/harness/modules/memory-loop/env.sh b/harness/loops/memory/env.sh similarity index 100% rename from harness/modules/memory-loop/env.sh rename to harness/loops/memory/env.sh diff --git a/harness/modules/memory-loop/hooks/compact.md b/harness/loops/memory/hooks/compact.md similarity index 100% rename from harness/modules/memory-loop/hooks/compact.md rename to harness/loops/memory/hooks/compact.md diff --git a/harness/modules/memory-loop/hooks/nudge.md b/harness/loops/memory/hooks/nudge.md similarity index 100% rename from harness/modules/memory-loop/hooks/nudge.md rename to harness/loops/memory/hooks/nudge.md diff --git a/harness/modules/memory-loop/hooks/prime.md b/harness/loops/memory/hooks/prime.md similarity index 100% rename from harness/modules/memory-loop/hooks/prime.md rename to harness/loops/memory/hooks/prime.md diff --git a/harness/modules/memory-loop/hooks/remind.md b/harness/loops/memory/hooks/remind.md similarity index 100% rename from harness/modules/memory-loop/hooks/remind.md rename to harness/loops/memory/hooks/remind.md diff --git a/harness/loops/memory/loop.json b/harness/loops/memory/loop.json new file mode 100644 index 0000000..c8557fd --- /dev/null +++ b/harness/loops/memory/loop.json @@ -0,0 +1,111 @@ +{ + "schema_version": 2, + "name": "memory", + "version": "0.1.0", + "description": "Connects prompt-facing working memory, Mnemon long-term memory, and dreaming consolidation.", + "control_model": { + "state": [ + "MEMORY.md", + ".mnemon stores", + "reports", + "manifests", + "memory status" + ], + "intent": "Keep useful agent, user, and project continuity available across lifecycle boundaries.", + "reality": [ + "host prompt", + "current task", + "working-memory contents", + "recall results", + "context pressure", + "consolidation state" + ], + "reconcile": [ + "read", + "write", + "compact", + "consolidate", + "no-op" + ] + }, + "entity_profiles": { + "template": "memory", + "controlled": [ + "memory binding" + ], + "surface": [ + "MEMORY.md", + "Mnemon recall/write", + "host hooks", + "protocol skills" + ], + "evidence": [ + "recall usefulness", + "write results", + "context pressure", + "stale working memory" + ], + "governance": [ + "memory proposals", + "memory audits" + ] + }, + "surfaces": { + "projection": [ + "GUIDE.md", + "hooks", + "memory_get", + "memory_set", + "dreaming", + "runtime env" + ], + "observation": [ + "hook output", + "MEMORY.md length", + "recall results", + "write outcomes", + "dreaming reports" + ] + }, + "lifecycle_events": [ + "prime", + "remind", + "nudge", + "compact" + ], + "assets": { + "guide": "GUIDE.md", + "env": "env.sh", + "runtime_files": [ + "MEMORY.md" + ], + "hooks": { + "prime": "hooks/prime.md", + "remind": "hooks/remind.md", + "nudge": "hooks/nudge.md", + "compact": "hooks/compact.md" + }, + "skills": [ + "skills/memory_get.md", + "skills/memory_set.md" + ], + "subagents": [ + "subagents/dreaming.md" + ] + }, + "state": { + "canonical": [ + ".mnemon/data", + ".mnemon/reports", + ".mnemon/proposals", + ".mnemon/audit" + ], + "loop_runtime": [ + "MEMORY.md" + ] + }, + "host_adapters": { + "claude-code": "../../hosts/claude-code", + "codex": "../../hosts/codex" + } +} diff --git a/harness/modules/memory-loop/skills/memory_get.md b/harness/loops/memory/skills/memory_get.md similarity index 100% rename from harness/modules/memory-loop/skills/memory_get.md rename to harness/loops/memory/skills/memory_get.md diff --git a/harness/modules/memory-loop/skills/memory_set.md b/harness/loops/memory/skills/memory_set.md similarity index 100% rename from harness/modules/memory-loop/skills/memory_set.md rename to harness/loops/memory/skills/memory_set.md diff --git a/harness/modules/memory-loop/subagents/dreaming.md b/harness/loops/memory/subagents/dreaming.md similarity index 100% rename from harness/modules/memory-loop/subagents/dreaming.md rename to harness/loops/memory/subagents/dreaming.md diff --git a/harness/modules/skill-loop/GUIDE.md b/harness/loops/skill/GUIDE.md similarity index 100% rename from harness/modules/skill-loop/GUIDE.md rename to harness/loops/skill/GUIDE.md diff --git a/harness/modules/skill-loop/README.md b/harness/loops/skill/README.md similarity index 82% rename from harness/modules/skill-loop/README.md rename to harness/loops/skill/README.md index c02e21c..369bfde 100644 --- a/harness/modules/skill-loop/README.md +++ b/harness/loops/skill/README.md @@ -1,15 +1,15 @@ # Mnemon Skill Loop Harness -This directory is the canonical skill loop module. It is host-agnostic: a host +This directory is the canonical skill loop template. It is host-agnostic: a host agent keeps its native skill runtime, while Mnemon owns the canonical skill lifecycle state and the evidence used to evolve it. ## File Tree ```text -harness/modules/skill-loop/ +harness/loops/skill/ ├── README.md -├── module.json +├── loop.json ├── env.sh ├── GUIDE.md ├── hooks/ @@ -32,13 +32,13 @@ harness/modules/skill-loop/ | --- | --- | | HostAgent | Owns the ReAct loop, tool routing, native skill discovery, and subagent execution. | | Host Skill Surface | The host-native skill directory, such as `.claude/skills`. It is a generated view. | -| Mnemon Skill Library | Canonical skill state under `mnemon-skill-loop/skills/{active,stale,archived}`. | +| Mnemon Skill Library | Canonical skill state under `mnemon-skill/skills/{active,stale,archived}`. | ## Support Assets | Asset | Purpose | | --- | --- | -| `module.json` | Machine-readable loop manifest for standard lifecycle events, assets, state, and host adapters. | +| `loop.json` | Machine-readable loop manifest for standard lifecycle events, assets, state, and host adapters. | | `env.sh` | Runtime config: canonical skill library, host skill surface, usage log, and proposal paths. | | `GUIDE.md` | Policy for evidence, review triggers, lifecycle movement, and proposal-first changes. | | `hooks/*.md` | Four lifecycle reminders. Prime syncs active skills; Nudge records evidence; Compact may trigger review; Remind is no-op by default. | @@ -47,7 +47,7 @@ harness/modules/skill-loop/ | `skills/skill_author.md` | Protocol for drafting reviewable `SKILL.md` content. | | `skills/skill_manage.md` | Approved lifecycle mutation protocol. | | `subagents/curator.md` | Background reviewer that proposes create, patch, consolidate, stale, archive, or restore actions. | -| Host adapter | Host-specific projection lives outside the module under `harness/hosts//`. | +| Host adapter | Host-specific projection lives outside the loop under `harness/hosts//`. | ## Runtime Directory Protocol @@ -68,8 +68,8 @@ $MNEMON_SKILL_LOOP_DIR/ `env.sh` defines: ```bash -MNEMON_SKILL_LOOP_ENV=/harness/skill-loop/env.sh -MNEMON_SKILL_LOOP_DIR=/harness/skill-loop +MNEMON_SKILL_LOOP_ENV=/harness/skill/env.sh +MNEMON_SKILL_LOOP_DIR=/harness/skill MNEMON_SKILL_LOOP_HOST_SKILLS_DIR=/skills MNEMON_SKILL_LOOP_ACTIVE_DIR=$MNEMON_SKILL_LOOP_DIR/skills/active MNEMON_SKILL_LOOP_STALE_DIR=$MNEMON_SKILL_LOOP_DIR/skills/stale @@ -102,18 +102,18 @@ prime.sh projects active canonical skills into the host skill surface. Install into the current project: ```bash -bash harness/setup/install.sh --host claude-code --module skill-loop +bash harness/ops/install.sh --host claude-code --loop skill ``` Install globally: ```bash -bash harness/setup/install.sh --host claude-code --module skill-loop --global +bash harness/ops/install.sh --host claude-code --loop skill --global ``` Remove the installed Claude Code integration while preserving the canonical skill library: ```bash -bash harness/setup/uninstall.sh --host claude-code --module skill-loop +bash harness/ops/uninstall.sh --host claude-code --loop skill ``` diff --git a/harness/modules/skill-loop/env.sh b/harness/loops/skill/env.sh similarity index 100% rename from harness/modules/skill-loop/env.sh rename to harness/loops/skill/env.sh diff --git a/harness/modules/skill-loop/hooks/compact.md b/harness/loops/skill/hooks/compact.md similarity index 100% rename from harness/modules/skill-loop/hooks/compact.md rename to harness/loops/skill/hooks/compact.md diff --git a/harness/modules/skill-loop/hooks/nudge.md b/harness/loops/skill/hooks/nudge.md similarity index 100% rename from harness/modules/skill-loop/hooks/nudge.md rename to harness/loops/skill/hooks/nudge.md diff --git a/harness/modules/skill-loop/hooks/prime.md b/harness/loops/skill/hooks/prime.md similarity index 100% rename from harness/modules/skill-loop/hooks/prime.md rename to harness/loops/skill/hooks/prime.md diff --git a/harness/modules/skill-loop/hooks/remind.md b/harness/loops/skill/hooks/remind.md similarity index 100% rename from harness/modules/skill-loop/hooks/remind.md rename to harness/loops/skill/hooks/remind.md diff --git a/harness/loops/skill/loop.json b/harness/loops/skill/loop.json new file mode 100644 index 0000000..4561be5 --- /dev/null +++ b/harness/loops/skill/loop.json @@ -0,0 +1,118 @@ +{ + "schema_version": 2, + "name": "skill", + "version": "0.1.0", + "description": "Manages active, stale, and archived skills through evidence, curator review, and approved lifecycle changes.", + "control_model": { + "state": [ + "active skills", + "stale skills", + "archived skills", + "usage evidence", + "proposals", + "reports", + "skill status" + ], + "intent": "Keep the right skills visible to the host while preserving stale and archived skills for review, recovery, and design memory.", + "reality": [ + "host skill surface", + "actual active projection", + "skill usage evidence", + "missing skills", + "misleading skills", + "curator findings", + "review decisions" + ], + "reconcile": [ + "observe", + "curate", + "propose", + "manage", + "no-op" + ] + }, + "entity_profiles": { + "template": "skill", + "controlled": [ + "skill binding" + ], + "surface": [ + "host skill surface", + "protocol skills", + "curator subagent" + ], + "evidence": [ + "usage signals", + "curator findings", + "missing skill signals", + "stale skill signals" + ], + "governance": [ + "proposals", + "reviews", + "audits" + ] + }, + "surfaces": { + "projection": [ + "active skills", + "skill_observe", + "skill_curate", + "skill_author", + "skill_manage", + "curator", + "runtime env" + ], + "observation": [ + "usage sidecar", + "signal reports", + "curator reports", + "host skill drift", + "review decisions" + ] + }, + "lifecycle_events": [ + "prime", + "remind", + "nudge", + "compact" + ], + "assets": { + "guide": "GUIDE.md", + "env": "env.sh", + "hooks": { + "prime": "hooks/prime.md", + "remind": "hooks/remind.md", + "nudge": "hooks/nudge.md", + "compact": "hooks/compact.md" + }, + "skills": [ + "skills/skill_observe.md", + "skills/skill_curate.md", + "skills/skill_author.md", + "skills/skill_manage.md" + ], + "subagents": [ + "subagents/curator.md" + ] + }, + "state": { + "canonical": [ + ".mnemon/data", + ".mnemon/reports", + ".mnemon/proposals", + ".mnemon/audit" + ], + "loop_runtime": [ + "skills/active", + "skills/stale", + "skills/archived", + "skills/.usage.jsonl", + "proposals" + ] + }, + "host_adapters": { + "claude-code": "../../hosts/claude-code", + "codex": "../../hosts/codex" + } +} diff --git a/harness/modules/skill-loop/skills/skill_author.md b/harness/loops/skill/skills/skill_author.md similarity index 97% rename from harness/modules/skill-loop/skills/skill_author.md rename to harness/loops/skill/skills/skill_author.md index 04cb667..5d927e7 100644 --- a/harness/modules/skill-loop/skills/skill_author.md +++ b/harness/loops/skill/skills/skill_author.md @@ -1,6 +1,6 @@ --- name: skill_author -description: Draft or revise high-quality SKILL.md content for approved or proposed Mnemon skill-loop changes. +description: Draft or revise high-quality SKILL.md content for approved or proposed Mnemon skill changes. --- # skill_author diff --git a/harness/modules/skill-loop/skills/skill_curate.md b/harness/loops/skill/skills/skill_curate.md similarity index 100% rename from harness/modules/skill-loop/skills/skill_curate.md rename to harness/loops/skill/skills/skill_curate.md diff --git a/harness/modules/skill-loop/skills/skill_manage.md b/harness/loops/skill/skills/skill_manage.md similarity index 100% rename from harness/modules/skill-loop/skills/skill_manage.md rename to harness/loops/skill/skills/skill_manage.md diff --git a/harness/modules/skill-loop/skills/skill_observe.md b/harness/loops/skill/skills/skill_observe.md similarity index 100% rename from harness/modules/skill-loop/skills/skill_observe.md rename to harness/loops/skill/skills/skill_observe.md diff --git a/harness/modules/skill-loop/subagents/curator.md b/harness/loops/skill/subagents/curator.md similarity index 100% rename from harness/modules/skill-loop/subagents/curator.md rename to harness/loops/skill/subagents/curator.md diff --git a/harness/modules/README.md b/harness/modules/README.md deleted file mode 100644 index bc50623..0000000 --- a/harness/modules/README.md +++ /dev/null @@ -1,13 +0,0 @@ -# Mnemon Harness Modules - -This directory contains canonical, host-agnostic loop modules. - -```text -harness/modules/ -├── memory-loop/ -├── skill-loop/ -└── eval-loop/ -``` - -Each module follows the Loop Module Standard and declares its assets in -`module.json`. Host-specific projection logic belongs under `harness/hosts/`. diff --git a/harness/modules/memory-loop/module.json b/harness/modules/memory-loop/module.json deleted file mode 100644 index e7f9698..0000000 --- a/harness/modules/memory-loop/module.json +++ /dev/null @@ -1,47 +0,0 @@ -{ - "schema_version": 1, - "name": "memory-loop", - "version": "0.1.0", - "description": "Connects prompt-facing working memory, Mnemon long-term memory, and dreaming consolidation.", - "lifecycle_events": [ - "prime", - "remind", - "nudge", - "compact" - ], - "assets": { - "guide": "GUIDE.md", - "env": "env.sh", - "runtime_files": [ - "MEMORY.md" - ], - "hooks": { - "prime": "hooks/prime.md", - "remind": "hooks/remind.md", - "nudge": "hooks/nudge.md", - "compact": "hooks/compact.md" - }, - "skills": [ - "skills/memory_get.md", - "skills/memory_set.md" - ], - "subagents": [ - "subagents/dreaming.md" - ] - }, - "state": { - "canonical": [ - ".mnemon/data", - ".mnemon/reports", - ".mnemon/proposals", - ".mnemon/audit" - ], - "loop_runtime": [ - "MEMORY.md" - ] - }, - "host_adapters": { - "claude-code": "../../hosts/claude-code", - "codex": "../../hosts/codex" - } -} diff --git a/harness/modules/skill-loop/module.json b/harness/modules/skill-loop/module.json deleted file mode 100644 index 537fdaf..0000000 --- a/harness/modules/skill-loop/module.json +++ /dev/null @@ -1,50 +0,0 @@ -{ - "schema_version": 1, - "name": "skill-loop", - "version": "0.1.0", - "description": "Manages active, stale, and archived skills through evidence, curator review, and approved lifecycle changes.", - "lifecycle_events": [ - "prime", - "remind", - "nudge", - "compact" - ], - "assets": { - "guide": "GUIDE.md", - "env": "env.sh", - "hooks": { - "prime": "hooks/prime.md", - "remind": "hooks/remind.md", - "nudge": "hooks/nudge.md", - "compact": "hooks/compact.md" - }, - "skills": [ - "skills/skill_observe.md", - "skills/skill_curate.md", - "skills/skill_author.md", - "skills/skill_manage.md" - ], - "subagents": [ - "subagents/curator.md" - ] - }, - "state": { - "canonical": [ - ".mnemon/data", - ".mnemon/reports", - ".mnemon/proposals", - ".mnemon/audit" - ], - "loop_runtime": [ - "skills/active", - "skills/stale", - "skills/archived", - "skills/.usage.jsonl", - "proposals" - ] - }, - "host_adapters": { - "claude-code": "../../hosts/claude-code", - "codex": "../../hosts/codex" - } -} diff --git a/harness/ops/README.md b/harness/ops/README.md new file mode 100644 index 0000000..5d6b5d0 --- /dev/null +++ b/harness/ops/README.md @@ -0,0 +1,25 @@ +# Mnemon Harness Ops + +This directory contains the shared ops entrypoints for projecting canonical +Mnemon harness loops into host runtimes. + +```text +harness/ops/ +├── install.sh +├── status.sh +├── uninstall.sh +└── lib/ +``` + +Use the shared entrypoints for new integrations: + +```bash +bash harness/ops/install.sh --host claude-code --loop memory +bash harness/ops/status.sh --host claude-code +bash harness/ops/uninstall.sh --host claude-code --loop memory +bash harness/ops/install.sh --host codex --loop memory +bash harness/ops/install.sh --host codex --loop eval +``` + +Host-specific projection logic lives under `harness/hosts//`. Loop assets +live under `harness/loops//`. diff --git a/harness/setup/install.sh b/harness/ops/install.sh similarity index 56% rename from harness/setup/install.sh rename to harness/ops/install.sh index 024b4ff..5ad63fd 100755 --- a/harness/setup/install.sh +++ b/harness/ops/install.sh @@ -3,21 +3,21 @@ set -euo pipefail usage() { cat <<'USAGE' -Install Mnemon harness modules into a host runtime. +Install Mnemon harness loops into a host runtime. Usage: - install.sh --host HOST --module MODULE [--module MODULE ...] [host options] + install.sh --host HOST --loop LOOP [--loop LOOP ...] [host options] Examples: - bash harness/setup/install.sh --host claude-code --module memory-loop - bash harness/setup/install.sh --host claude-code --module skill-loop --global + bash harness/ops/install.sh --host claude-code --loop memory + bash harness/ops/install.sh --host claude-code --loop skill --global USAGE } SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" HOST="" -MODULES=() +LOOPS=() HOST_ARGS=() while [[ $# -gt 0 ]]; do @@ -26,8 +26,8 @@ while [[ $# -gt 0 ]]; do HOST="${2:?missing value for --host}" shift 2 ;; - --module) - MODULES+=("${2:?missing value for --module}") + --loop) + LOOPS+=("${2:?missing value for --loop}") shift 2 ;; -h|--help) @@ -46,8 +46,8 @@ if [[ -z "${HOST}" ]]; then usage >&2 exit 2 fi -if [[ "${#MODULES[@]}" -eq 0 ]]; then - echo "at least one --module is required" >&2 +if [[ "${#LOOPS[@]}" -eq 0 ]]; then + echo "at least one --loop is required" >&2 usage >&2 exit 2 fi @@ -58,6 +58,6 @@ if [[ ! -x "${PROJECTOR}" ]]; then exit 1 fi -for module in "${MODULES[@]}"; do - "${PROJECTOR}" install --module "${module}" "${HOST_ARGS[@]}" +for loop in "${LOOPS[@]}"; do + "${PROJECTOR}" install --loop "${loop}" "${HOST_ARGS[@]}" done diff --git a/harness/setup/lib/paths.sh b/harness/ops/lib/paths.sh similarity index 81% rename from harness/setup/lib/paths.sh rename to harness/ops/lib/paths.sh index bb7b22a..7723aab 100755 --- a/harness/setup/lib/paths.sh +++ b/harness/ops/lib/paths.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash set -euo pipefail -mnemon_setup_dir() { +mnemon_ops_dir() { cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd } @@ -13,11 +13,11 @@ mnemon_repo_root() { cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd } -mnemon_module_dir() { - local module="$1" +mnemon_loop_dir() { + local loop="$1" local harness_dir harness_dir="$(mnemon_harness_dir)" - printf '%s/modules/%s\n' "${harness_dir}" "${module}" + printf '%s/loops/%s\n' "${harness_dir}" "${loop}" } mnemon_host_dir() { diff --git a/harness/setup/status.sh b/harness/ops/status.sh similarity index 63% rename from harness/setup/status.sh rename to harness/ops/status.sh index 7881b32..e5abe2e 100755 --- a/harness/setup/status.sh +++ b/harness/ops/status.sh @@ -6,18 +6,18 @@ usage() { Show Mnemon harness projection status for a host runtime. Usage: - status.sh --host HOST [--module MODULE ...] [host options] + status.sh --host HOST [--loop LOOP ...] [host options] Examples: - bash harness/setup/status.sh --host claude-code - bash harness/setup/status.sh --host claude-code --module memory-loop + bash harness/ops/status.sh --host claude-code + bash harness/ops/status.sh --host claude-code --loop memory USAGE } SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" HOST="" -MODULES=() +LOOPS=() HOST_ARGS=() while [[ $# -gt 0 ]]; do @@ -26,8 +26,8 @@ while [[ $# -gt 0 ]]; do HOST="${2:?missing value for --host}" shift 2 ;; - --module) - MODULES+=("${2:?missing value for --module}") + --loop) + LOOPS+=("${2:?missing value for --loop}") shift 2 ;; -h|--help) @@ -46,8 +46,8 @@ if [[ -z "${HOST}" ]]; then usage >&2 exit 2 fi -if [[ "${#MODULES[@]}" -eq 0 ]]; then - MODULES=("memory-loop" "skill-loop") +if [[ "${#LOOPS[@]}" -eq 0 ]]; then + LOOPS=("memory" "skill") fi PROJECTOR="${SCRIPT_DIR}/../hosts/${HOST}/projector.sh" @@ -56,6 +56,6 @@ if [[ ! -x "${PROJECTOR}" ]]; then exit 1 fi -for module in "${MODULES[@]}"; do - "${PROJECTOR}" status --module "${module}" "${HOST_ARGS[@]}" +for loop in "${LOOPS[@]}"; do + "${PROJECTOR}" status --loop "${loop}" "${HOST_ARGS[@]}" done diff --git a/harness/setup/uninstall.sh b/harness/ops/uninstall.sh similarity index 55% rename from harness/setup/uninstall.sh rename to harness/ops/uninstall.sh index 2922681..669681a 100755 --- a/harness/setup/uninstall.sh +++ b/harness/ops/uninstall.sh @@ -3,21 +3,21 @@ set -euo pipefail usage() { cat <<'USAGE' -Uninstall Mnemon harness module projections from a host runtime. +Uninstall Mnemon harness loop projections from a host runtime. Usage: - uninstall.sh --host HOST --module MODULE [--module MODULE ...] [host options] + uninstall.sh --host HOST --loop LOOP [--loop LOOP ...] [host options] Examples: - bash harness/setup/uninstall.sh --host claude-code --module memory-loop - bash harness/setup/uninstall.sh --host claude-code --module skill-loop --global + bash harness/ops/uninstall.sh --host claude-code --loop memory + bash harness/ops/uninstall.sh --host claude-code --loop skill --global USAGE } SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" HOST="" -MODULES=() +LOOPS=() HOST_ARGS=() while [[ $# -gt 0 ]]; do @@ -26,8 +26,8 @@ while [[ $# -gt 0 ]]; do HOST="${2:?missing value for --host}" shift 2 ;; - --module) - MODULES+=("${2:?missing value for --module}") + --loop) + LOOPS+=("${2:?missing value for --loop}") shift 2 ;; -h|--help) @@ -46,8 +46,8 @@ if [[ -z "${HOST}" ]]; then usage >&2 exit 2 fi -if [[ "${#MODULES[@]}" -eq 0 ]]; then - echo "at least one --module is required" >&2 +if [[ "${#LOOPS[@]}" -eq 0 ]]; then + echo "at least one --loop is required" >&2 usage >&2 exit 2 fi @@ -58,6 +58,6 @@ if [[ ! -x "${PROJECTOR}" ]]; then exit 1 fi -for module in "${MODULES[@]}"; do - "${PROJECTOR}" uninstall --module "${module}" "${HOST_ARGS[@]}" +for loop in "${LOOPS[@]}"; do + "${PROJECTOR}" uninstall --loop "${loop}" "${HOST_ARGS[@]}" done diff --git a/harness/setup/README.md b/harness/setup/README.md deleted file mode 100644 index 9a7e7c5..0000000 --- a/harness/setup/README.md +++ /dev/null @@ -1,26 +0,0 @@ -# Mnemon Harness Setup - -This directory contains the shared setup entrypoints for projecting canonical -Mnemon harness modules into host runtimes. - -```text -harness/setup/ -├── install.sh -├── status.sh -├── uninstall.sh -├── lib/ -└── schema/ -``` - -Use the shared entrypoints for new integrations: - -```bash -bash harness/setup/install.sh --host claude-code --module memory-loop -bash harness/setup/status.sh --host claude-code -bash harness/setup/uninstall.sh --host claude-code --module memory-loop -bash harness/setup/install.sh --host codex --module memory-loop -bash harness/setup/install.sh --host codex --module eval-loop -``` - -Host-specific projection logic lives under `harness/hosts//`. Loop assets -live under `harness/modules//`. diff --git a/scripts/codex_app_server_eval.py b/scripts/codex_app_server_eval.py index adb8a33..9a57e58 100755 --- a/scripts/codex_app_server_eval.py +++ b/scripts/codex_app_server_eval.py @@ -195,11 +195,11 @@ def setup_workspace(args: argparse.Namespace, root: Path) -> tuple[Path, Path, P env = dict(os.environ) env["MNEMON_HARNESS_STATE_DIR"] = str(mnemon_dir) env["MNEMON_DATA_DIR"] = str(mnemon_dir / "data") - if "memory-loop" in args.modules: - env["MNEMON_MEMORY_LOOP_ENV"] = str(mnemon_dir / "harness" / "memory-loop" / "env.sh") - env["MNEMON_MEMORY_LOOP_DIR"] = str(mnemon_dir / "harness" / "memory-loop") - if "skill-loop" in args.modules: - skill_dir = mnemon_dir / "harness" / "skill-loop" + if "memory" in args.loops: + env["MNEMON_MEMORY_LOOP_ENV"] = str(mnemon_dir / "harness" / "memory" / "env.sh") + env["MNEMON_MEMORY_LOOP_DIR"] = str(mnemon_dir / "harness" / "memory") + if "skill" in args.loops: + skill_dir = mnemon_dir / "harness" / "skill" env["MNEMON_SKILL_LOOP_ENV"] = str(skill_dir / "env.sh") env["MNEMON_SKILL_LOOP_DIR"] = str(skill_dir) env["MNEMON_SKILL_LOOP_LIBRARY_DIR"] = str(skill_dir / "skills") @@ -208,8 +208,8 @@ def setup_workspace(args: argparse.Namespace, root: Path) -> tuple[Path, Path, P env["MNEMON_SKILL_LOOP_ARCHIVED_DIR"] = str(skill_dir / "skills" / "archived") env["MNEMON_SKILL_LOOP_USAGE_FILE"] = str(skill_dir / "skills" / ".usage.jsonl") env["MNEMON_SKILL_LOOP_PROPOSALS_DIR"] = str(skill_dir / "proposals") - if "eval-loop" in args.modules: - eval_dir = mnemon_dir / "harness" / "eval-loop" + if "eval" in args.loops: + eval_dir = mnemon_dir / "harness" / "eval" env["MNEMON_EVAL_LOOP_ENV"] = str(eval_dir / "env.sh") env["MNEMON_EVAL_LOOP_DIR"] = str(eval_dir) env["MNEMON_EVAL_LOOP_SCRATCH_DIR"] = str(eval_dir / "scratch") @@ -223,10 +223,10 @@ def setup_workspace(args: argparse.Namespace, root: Path) -> tuple[Path, Path, P env["CODEX_HOME"] = str(codex_home) env = ensure_mnemon_binary(root, run_root, env) - install = root / "harness" / "setup" / "install.sh" - modules = args.modules - for module in modules: - cmd = ["bash", str(install), "--host", "codex", "--module", module, "--config-dir", str(workspace / ".codex")] + install = root / "harness" / "ops" / "install.sh" + loops = args.loops + for loop in loops: + cmd = ["bash", str(install), "--host", "codex", "--loop", loop, "--config-dir", str(workspace / ".codex")] run(cmd, workspace, env) return run_root, workspace, mnemon_dir, env @@ -295,14 +295,14 @@ class Scenario: def __init__( self, name: str, - modules: list[str], + loops: list[str], expected_skills: list[str], prompt: str | list[str], setup: Callable[[Path, Path, dict[str, str]], None], assert_result: Callable[[dict[str, Any], Path, Path, dict[str, str]], list[dict[str, Any]]], ) -> None: self.name = name - self.modules = modules + self.loops = loops self.expected_skills = expected_skills self.prompts = prompt if isinstance(prompt, list) else [prompt] self.prompt = self.prompts[0] @@ -349,7 +349,7 @@ def setup_local_fact(workspace: Path, mnemon_dir: Path, env: dict[str, str]) -> def memory_path(mnemon_dir: Path) -> Path: - return mnemon_dir / "harness" / "memory-loop" / "MEMORY.md" + return mnemon_dir / "harness" / "memory" / "MEMORY.md" def append_memory(mnemon_dir: Path, text: str) -> None: @@ -535,7 +535,7 @@ def assert_skill_observe(report: dict[str, Any], workspace: Path, mnemon_dir: Pa def skill_loop_path(mnemon_dir: Path) -> Path: - return mnemon_dir / "harness" / "skill-loop" + return mnemon_dir / "harness" / "skill" def skill_usage_path(mnemon_dir: Path) -> Path: @@ -726,7 +726,7 @@ def assert_skill_author_draft(report: dict[str, Any], workspace: Path, mnemon_di SCENARIOS: dict[str, Scenario] = { "memory-skip-local": Scenario( name="memory-skip-local", - modules=["memory-loop"], + loops=["memory"], expected_skills=["memory_get", "memory_set"], setup=setup_local_fact, prompt=( @@ -737,7 +737,7 @@ def assert_skill_author_draft(report: dict[str, Any], workspace: Path, mnemon_di ), "memory-focused-recall": Scenario( name="memory-focused-recall", - modules=["memory-loop"], + loops=["memory"], expected_skills=["memory_get", "memory_set"], setup=setup_memory_seed, prompt=( @@ -749,20 +749,20 @@ def assert_skill_author_draft(report: dict[str, Any], workspace: Path, mnemon_di ), "memory-write-decision": Scenario( name="memory-write-decision", - modules=["memory-loop"], + loops=["memory"], expected_skills=["memory_get", "memory_set"], setup=setup_none, prompt=( "Use the Mnemon memory loop to record this durable project decision: " "future loop optimization should be driven by app-server eval scenarios before broad host expansion. " - "Edit only the Mnemon memory-loop MEMORY.md in this eval workspace. " + "Edit only the Mnemon memory MEMORY.md in this eval workspace. " "Use the phrase 'app-server eval scenarios' in the saved memory. Then reply done." ), assert_result=assert_memory_write, ), "memory-no-pollution": Scenario( name="memory-no-pollution", - modules=["memory-loop"], + loops=["memory"], expected_skills=["memory_get", "memory_set"], setup=setup_none, prompt=( @@ -773,20 +773,20 @@ def assert_skill_author_draft(report: dict[str, Any], workspace: Path, mnemon_di ), "memory-merge-supersede": Scenario( name="memory-merge-supersede", - modules=["memory-loop"], + loops=["memory"], expected_skills=["memory_get", "memory_set"], setup=setup_memory_merge, prompt=( "Use the Mnemon memory loop to update existing working memory. " "The current durable decision supersedes the older host-first note: " - "memory-loop optimization should be driven by app-server eval scenarios before broad host expansion. " + "memory optimization should be driven by app-server eval scenarios before broad host expansion. " "Merge or replace the existing entry instead of appending a duplicate. Reply done." ), assert_result=assert_memory_merge, ), "memory-uncertain-preference": Scenario( name="memory-uncertain-preference", - modules=["memory-loop"], + loops=["memory"], expected_skills=["memory_get", "memory_set"], setup=setup_memory_uncertain_preference, prompt=( @@ -798,7 +798,7 @@ def assert_skill_author_draft(report: dict[str, Any], workspace: Path, mnemon_di ), "memory-secret-rejection": Scenario( name="memory-secret-rejection", - modules=["memory-loop"], + loops=["memory"], expected_skills=["memory_get", "memory_set"], setup=setup_none, prompt=( @@ -809,7 +809,7 @@ def assert_skill_author_draft(report: dict[str, Any], workspace: Path, mnemon_di ), "memory-recall-noise-filter": Scenario( name="memory-recall-noise-filter", - modules=["memory-loop"], + loops=["memory"], expected_skills=["memory_get", "memory_set"], setup=setup_memory_noise, prompt=( @@ -820,7 +820,7 @@ def assert_skill_author_draft(report: dict[str, Any], workspace: Path, mnemon_di ), "memory-multiturn-continuity": Scenario( name="memory-multiturn-continuity", - modules=["memory-loop"], + loops=["memory"], expected_skills=["memory_get", "memory_set"], setup=setup_none, prompt=[ @@ -834,7 +834,7 @@ def assert_skill_author_draft(report: dict[str, Any], workspace: Path, mnemon_di ), "skill-observe-evidence": Scenario( name="skill-observe-evidence", - modules=["skill-loop"], + loops=["skill"], expected_skills=SKILL_LOOP_EXPECTED_SKILLS, setup=setup_none, prompt=( @@ -846,7 +846,7 @@ def assert_skill_author_draft(report: dict[str, Any], workspace: Path, mnemon_di ), "skill-skip-transient": Scenario( name="skill-skip-transient", - modules=["skill-loop"], + loops=["skill"], expected_skills=SKILL_LOOP_EXPECTED_SKILLS, setup=setup_none, prompt=( @@ -858,7 +858,7 @@ def assert_skill_author_draft(report: dict[str, Any], workspace: Path, mnemon_di ), "skill-observe-missing": Scenario( name="skill-observe-missing", - modules=["skill-loop"], + loops=["skill"], expected_skills=SKILL_LOOP_EXPECTED_SKILLS, setup=setup_none, prompt=( @@ -871,7 +871,7 @@ def assert_skill_author_draft(report: dict[str, Any], workspace: Path, mnemon_di ), "skill-manage-approved-create": Scenario( name="skill-manage-approved-create", - modules=["skill-loop"], + loops=["skill"], expected_skills=SKILL_LOOP_EXPECTED_SKILLS, setup=setup_none, prompt=( @@ -885,7 +885,7 @@ def assert_skill_author_draft(report: dict[str, Any], workspace: Path, mnemon_di ), "skill-curate-proposal": Scenario( name="skill-curate-proposal", - modules=["skill-loop"], + loops=["skill"], expected_skills=SKILL_LOOP_EXPECTED_SKILLS, setup=setup_skill_curate_evidence, prompt=( @@ -898,7 +898,7 @@ def assert_skill_author_draft(report: dict[str, Any], workspace: Path, mnemon_di ), "skill-manage-unapproved-noop": Scenario( name="skill-manage-unapproved-noop", - modules=["skill-loop"], + loops=["skill"], expected_skills=SKILL_LOOP_EXPECTED_SKILLS, setup=setup_skill_active_release, prompt=( @@ -910,7 +910,7 @@ def assert_skill_author_draft(report: dict[str, Any], workspace: Path, mnemon_di ), "skill-manage-approved-stale": Scenario( name="skill-manage-approved-stale", - modules=["skill-loop"], + loops=["skill"], expected_skills=SKILL_LOOP_EXPECTED_SKILLS, setup=setup_skill_active_legacy, prompt=( @@ -922,7 +922,7 @@ def assert_skill_author_draft(report: dict[str, Any], workspace: Path, mnemon_di ), "skill-manage-approved-restore": Scenario( name="skill-manage-approved-restore", - modules=["skill-loop"], + loops=["skill"], expected_skills=SKILL_LOOP_EXPECTED_SKILLS, setup=setup_skill_stale_release, prompt=( @@ -934,7 +934,7 @@ def assert_skill_author_draft(report: dict[str, Any], workspace: Path, mnemon_di ), "skill-author-draft": Scenario( name="skill-author-draft", - modules=["skill-loop"], + loops=["skill"], expected_skills=SKILL_LOOP_EXPECTED_SKILLS, setup=setup_none, prompt=( @@ -986,7 +986,7 @@ def assert_skill_author_draft(report: dict[str, Any], workspace: Path, mnemon_di def scenario_args(base: argparse.Namespace, scenario: Scenario) -> argparse.Namespace: args = argparse.Namespace(**vars(base)) - args.modules = scenario.modules + args.loops = scenario.loops args.expected_skills = scenario.expected_skills args.prompt = scenario.prompt args.prompts = scenario.prompts @@ -1008,7 +1008,7 @@ def run_eval(args: argparse.Namespace) -> dict[str, Any]: "run_dir": str(run_dir), "workspace": str(workspace), "mnemon_dir": str(mnemon_dir), - "modules": args.modules, + "loops": args.loops, "scenario": args.scenario, "agent_turn": args.agent_turn, "started_at": datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z"), @@ -1135,19 +1135,19 @@ def parse_args(argv: list[str]) -> argparse.Namespace: help="Scenario suite to run with --suite.", ) parser.add_argument( - "--module", - dest="modules", + "--loop", + dest="loops", action="append", - choices=["memory-loop", "skill-loop", "eval-loop"], + choices=["memory", "skill", "eval"], default=[], - help="Harness module to install. May be repeated. Defaults to memory-loop.", + help="Harness loop to install. May be repeated. Defaults to memory.", ) parser.add_argument( "--expected-skill", dest="expected_skills", action="append", default=[], - help="Projected Codex skill name that must appear in skills/list. Defaults are derived from selected modules.", + help="Projected Codex skill name that must appear in skills/list. Defaults are derived from selected loops.", ) parser.add_argument("--agent-turn", action="store_true", help="Start a real Codex turn after app-server smoke checks.") parser.add_argument( @@ -1165,15 +1165,15 @@ def parse_args(argv: list[str]) -> argparse.Namespace: help="Set CODEX_HOME inside the eval run directory. This is suitable for smoke checks and may not have auth for real turns.", ) args = parser.parse_args(argv) - if not args.modules: - args.modules = ["memory-loop"] + if not args.loops: + args.loops = ["memory"] if not args.expected_skills: expected: list[str] = [] - if "memory-loop" in args.modules: + if "memory" in args.loops: expected.extend(["memory_get", "memory_set"]) - if "skill-loop" in args.modules: + if "skill" in args.loops: expected.extend(SKILL_LOOP_EXPECTED_SKILLS) - if "eval-loop" in args.modules: + if "eval" in args.loops: expected.extend(EVAL_LOOP_EXPECTED_SKILLS) args.expected_skills = expected return args diff --git a/scripts/validate_harness_loops.sh b/scripts/validate_harness_loops.sh new file mode 100755 index 0000000..8aa7b14 --- /dev/null +++ b/scripts/validate_harness_loops.sh @@ -0,0 +1,154 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)" +LOOPS_DIR="${ROOT_DIR}/harness/loops" +HOSTS_DIR="${ROOT_DIR}/harness/hosts" +BINDINGS_DIR="${ROOT_DIR}/harness/bindings" + +if ! command -v jq >/dev/null 2>&1; then + echo "jq is required" >&2 + exit 1 +fi + +validate_loop() { + local loop_dir="$1" + local manifest="${loop_dir}/loop.json" + local name + + if [[ ! -f "${manifest}" ]]; then + echo "missing loop manifest: ${manifest}" >&2 + return 1 + fi + + jq . "${manifest}" >/dev/null + name="$(jq -r '.name // empty' "${manifest}")" + if [[ -z "${name}" ]]; then + echo "loop manifest missing name: ${manifest}" >&2 + return 1 + fi + if [[ "$(jq -r '.schema_version // 0' "${manifest}")" -lt 2 ]]; then + echo "loop manifest schema_version must be 2 or higher: ${manifest}" >&2 + return 1 + fi + for field in control_model entity_profiles surfaces; do + if [[ "$(jq -r "has(\"${field}\")" "${manifest}")" != "true" ]]; then + echo "loop manifest missing ${field}: ${manifest}" >&2 + return 1 + fi + done + for field in state intent reality reconcile; do + if [[ "$(jq -r ".control_model | has(\"${field}\")" "${manifest}")" != "true" ]]; then + echo "loop control_model missing ${field}: ${manifest}" >&2 + return 1 + fi + done + for field in projection observation; do + if [[ "$(jq -r ".surfaces | has(\"${field}\")" "${manifest}")" != "true" ]]; then + echo "loop surfaces missing ${field}: ${manifest}" >&2 + return 1 + fi + done + + while IFS= read -r rel; do + [[ -n "${rel}" ]] || continue + if [[ ! -e "${loop_dir}/${rel}" ]]; then + echo "missing ${name} asset: ${rel}" >&2 + return 1 + fi + done < <( + jq -r ' + .assets.guide, + .assets.env, + ((.assets.runtime_files // [])[]), + (.assets.hooks[]), + (.assets.skills[]), + (.assets.subagents[]) + ' "${manifest}" + ) + + while IFS= read -r rel; do + [[ -n "${rel}" ]] || continue + if [[ ! -e "${loop_dir}/${rel}" ]]; then + echo "missing ${name} host adapter path: ${rel}" >&2 + return 1 + fi + done < <(jq -r '.host_adapters[]' "${manifest}") + + echo "ok ${name}" +} + +validate_host() { + local host_manifest="$1" + local name + + jq . "${host_manifest}" >/dev/null + name="$(jq -r '.name // empty' "${host_manifest}")" + if [[ -z "${name}" ]]; then + echo "host manifest missing name: ${host_manifest}" >&2 + return 1 + fi + if [[ "$(jq -r '.schema_version // 0' "${host_manifest}")" -lt 2 ]]; then + echo "host manifest schema_version must be 2 or higher: ${host_manifest}" >&2 + return 1 + fi + for field in surfaces lifecycle_mapping; do + if [[ "$(jq -r "has(\"${field}\")" "${host_manifest}")" != "true" ]]; then + echo "host manifest missing ${field}: ${host_manifest}" >&2 + return 1 + fi + done + for field in projection observation; do + if [[ "$(jq -r ".surfaces | has(\"${field}\")" "${host_manifest}")" != "true" ]]; then + echo "host surfaces missing ${field}: ${host_manifest}" >&2 + return 1 + fi + done + + echo "ok host ${name}" +} + +validate_binding() { + local binding_manifest="$1" + local name host loop + + jq . "${binding_manifest}" >/dev/null + name="$(jq -r '.name // empty' "${binding_manifest}")" + host="$(jq -r '.host // empty' "${binding_manifest}")" + loop="$(jq -r '.loop // empty' "${binding_manifest}")" + if [[ -z "${name}" || -z "${host}" || -z "${loop}" ]]; then + echo "binding manifest missing name, host, or loop: ${binding_manifest}" >&2 + return 1 + fi + if [[ ! -f "${HOSTS_DIR}/${host}/host.json" ]]; then + echo "binding references missing host: ${binding_manifest}" >&2 + return 1 + fi + if [[ ! -f "${LOOPS_DIR}/${loop}/loop.json" ]]; then + echo "binding references missing loop: ${binding_manifest}" >&2 + return 1 + fi + for field in projection_path runtime_surface lifecycle_mapping reconcile; do + if [[ "$(jq -r "has(\"${field}\")" "${binding_manifest}")" != "true" ]]; then + echo "binding manifest missing ${field}: ${binding_manifest}" >&2 + return 1 + fi + done + + echo "ok binding ${name}" +} + +for loop_dir in "${LOOPS_DIR}"/*; do + [[ -d "${loop_dir}" ]] || continue + validate_loop "${loop_dir}" +done + +for host_manifest in "${HOSTS_DIR}"/*/host.json; do + [[ -f "${host_manifest}" ]] || continue + validate_host "${host_manifest}" +done + +for binding_manifest in "${BINDINGS_DIR}"/*.json; do + [[ -f "${binding_manifest}" ]] || continue + validate_binding "${binding_manifest}" +done diff --git a/scripts/validate_harness_modules.sh b/scripts/validate_harness_modules.sh deleted file mode 100755 index ff73e6c..0000000 --- a/scripts/validate_harness_modules.sh +++ /dev/null @@ -1,60 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)" -MODULES_DIR="${ROOT_DIR}/harness/modules" - -if ! command -v jq >/dev/null 2>&1; then - echo "jq is required" >&2 - exit 1 -fi - -validate_module() { - local module_dir="$1" - local manifest="${module_dir}/module.json" - local name - - if [[ ! -f "${manifest}" ]]; then - echo "missing module manifest: ${manifest}" >&2 - return 1 - fi - - jq . "${manifest}" >/dev/null - name="$(jq -r '.name // empty' "${manifest}")" - if [[ -z "${name}" ]]; then - echo "module manifest missing name: ${manifest}" >&2 - return 1 - fi - - while IFS= read -r rel; do - [[ -n "${rel}" ]] || continue - if [[ ! -e "${module_dir}/${rel}" ]]; then - echo "missing ${name} asset: ${rel}" >&2 - return 1 - fi - done < <( - jq -r ' - .assets.guide, - .assets.env, - ((.assets.runtime_files // [])[]), - (.assets.hooks[]), - (.assets.skills[]), - (.assets.subagents[]) - ' "${manifest}" - ) - - while IFS= read -r rel; do - [[ -n "${rel}" ]] || continue - if [[ ! -e "${module_dir}/${rel}" ]]; then - echo "missing ${name} host adapter path: ${rel}" >&2 - return 1 - fi - done < <(jq -r '.host_adapters[]' "${manifest}") - - echo "ok ${name}" -} - -for module_dir in "${MODULES_DIR}"/*; do - [[ -d "${module_dir}" ]] || continue - validate_module "${module_dir}" -done From 9229c5bb1a3c12f06811006d90cd26f435322d66 Mon Sep 17 00:00:00 2001 From: Grivn Date: Wed, 20 May 2026 17:13:34 +0000 Subject: [PATCH 6/6] docs(harness): add lifecycle control UI browser Add an interactive harness control browser that explains the current lifecycle layout through source, host projection, and runtime state trees. The page can inspect loops, hosts, bindings, and ops for the selected binding, with bilingual labels and optional repo JSON refresh for live-ish updates. Validation: node parsed the embedded page script and git diff --check passed. --- docs/site/harness-ui/index.html | 1453 +++++++++++++++++++++++++++++++ docs/site/index.html | 8 + 2 files changed, 1461 insertions(+) create mode 100644 docs/site/harness-ui/index.html diff --git a/docs/site/harness-ui/index.html b/docs/site/harness-ui/index.html new file mode 100644 index 0000000..77254e0 --- /dev/null +++ b/docs/site/harness-ui/index.html @@ -0,0 +1,1453 @@ + + + + + + + Mnemon Harness Control UI + + + +
+
+
+
+ Docs Home +
Mnemon Harness UI
+
+
+ + + +
+ + +
+
+
+

Harness lifecycle control browser

+

这个页面把当前项目结构当成可浏览的控制面：Loop 定义能力，Host 定义宿主 surface，Binding 定义二者如何组合，Ops 执行安装、status 和卸载。

+
+
+
+ +
+
+ + +
+
+
+

Source tree

+

Repo-owned definitions before install.

+
+
+
+

Host projection

+

Files the selected host actually reads.

+
+
+
+

Runtime state

+

Generated state, manifest, status, and durable loop records.

+
+
+
+ +
+
+

+

+
+
+
    +
    +
    + +
    + +
    +
    +

    +
    +

    +
    +
    +
    +
    +

    +
    +

    +
    +
    +
    +
    +

    +
    +

    +
    +
    +
    +
    + +
    +
    +

    +
      +
      +
      +

      +
        +
        +
        +
        + + +
        +
        + + + + diff --git a/docs/site/index.html b/docs/site/index.html index c9c0009..911fb7c 100644 --- a/docs/site/index.html +++ b/docs/site/index.html @@ -175,6 +175,14 @@

        Lifecycle Control Plane

        Open site + + +

        Harness Control UI

        +

        Interactive browser for loops, hosts, bindings, lifecycle flow, and generated state surfaces.

        +         + Open site +         +

        Documentation Tree