dsh-continual-evolve 0.6.1 → 0.7.0

package/README.md

@@ -7,7 +7,7 @@
 [![CI](https://github.com/ZK-Andy/dsh-continual-evolve/actions/workflows/ci.yml/badge.svg)](https://github.com/ZK-Andy/dsh-continual-evolve/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-339933)](package.json)
-[![Tests](https://img.shields.io/badge/tests-576%20passing-brightgreen)]()
+[![Tests](https://img.shields.io/badge/tests-600%20passing-brightgreen)]()
 
 Continual self-evolution for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): a versioned, auditable, rollback-safe harness state layer — prompt notes, memories, skills, subagent specs — refined from session trajectories.
 
@@ -17,7 +17,8 @@ Continual self-evolution for [DeepSeek Harness](https://github.com/deepseek-ai/d
 
 Agents accumulate reusable experience (repeated failures, durable facts, reusable procedures) and forget it next session. This plugin turns that experience into first-class state:
 
-- **Local scope** per session; **global scope** across sessions with merge semantics — plus mechanical promotion guards so only portable, substantial, non-duplicate knowledge reaches global
+- **Three scopes** with merge semantics (global < project < local): **local** per-session staging, **project** per-workspace cross-session store, **global** cross-project — plus mechanical promotion guards so only portable, substantial, non-duplicate knowledge reaches global
+- **Typed one-fact memories**: every memory entry carries a recall type (`user | feedback | project | reference`); pitfalls (`feedback`) must include Why + How to apply
 - **Deterministic rollback**: inverse edits generated from applied results — no LLM re-guessing
 - **Benchmark loop**: candidate refinements are evaluated against frozen cases by a separate scorer before acceptance (rubric encrypted at rest)
 - **Store hygiene**: `/evolve consolidate` turns write-time conflict hints and zero-use staleness into one approved, fully reversible batch of archives — with `merge`, near-duplicate content folds into the surviving original
@@ -26,8 +27,8 @@ Agents accumulate reusable experience (repeated failures, durable facts, reusabl
 
 1. **Sediment** — the model creates entries via `evolve_add`, or the automatic review gate proposes them from the session trajectory (turn-interval + compaction checkpoints).
 2. **Guard** — code-enforced validation: edit schema, blast-radius/scope coherence, and the promotion policy (project-scoped markers, thin content, near-duplicate detection, credential screening keep the global store clean — secrets are rejected at every write sink, including mount materialization). Global creates that near-duplicate an existing entry are rejected at write time (≥0.8 similarity); moderate overlaps carry a `conflictHint` for later consolidation.
-3. **Approve** — global writes require explicit human approval; local-fate proposals are consulted before they land.
-4. **Apply & inject** — atomic apply with snapshot + audit event. Prompt notes and delegation specs inject into the system prompt (capped, relevance-ranked, contradicted entries demoted, zero tokens when empty); memories/skills appear as a capped directory index.
+3. **Approve** — global and project writes require explicit human approval; local-fate proposals are consulted before they land.
+4. **Apply & inject** — atomic apply with snapshot + audit event. Prompt notes and delegation specs inject into the system prompt (capped, relevance-ranked, contradicted entries demoted, zero tokens when empty); memories/skills appear as a relevance-ordered capped directory index (`- [memory:type:id] title` hooks, full text one `evolve_list` away).
 5. **Validate & roll back** — benchmarks score candidates against frozen cases; rejected candidates roll back deterministically and are captured as draft regression cases (`auto_regression` benchmark).
 
 ## Install
@@ -49,7 +50,7 @@ Commands (in-session):
 | Command | Effect |
 |---|---|
 | `/evolve` | help + current local store |
-| `/evolve list · history · rollback <id>` | inspect and revert (add `global` for the cross-session store) |
+| `/evolve list · history · rollback <id>` | inspect and revert (add `project` for this project's store, `global` for the cross-project store) |
 | `/evolve plan [msg]` | run the LLM planner against the store |
 | `/evolve wrapup` | assess this session's local entries: promote / archive / keep |
 | `/evolve archive · unarchive · demote <id>` | hide from injection (data kept, restorable) — `demote` targets global noise |
@@ -65,7 +66,7 @@ Model tools: `evolve_list / add / update / delete / rollback`.
 
 For third-party consumers: every applied evolution (gate or manual) appends a structured `evolve_complete` event to `reviews.jsonl` (`src/evolve-event.ts` defines the shape) alongside the human-readable audit records.
 
-Injection shape: prompt notes and delegation specs inject with content (≤6/kind × 180 chars, relevance-ranked). Memories and skills appear as a directory index (`[kind:id] title`, capped at 15 lines with a fold counter) — full text via `evolve_list`. Empty store = zero injected tokens.
+Injection shape: prompt notes and delegation specs inject with content (≤6/kind × 180 chars, relevance-ranked). Memories and skills appear as a relevance-ordered directory index (`[memory:type:id] title` hooks, capped at 15 lines with a fold counter) — full text via `evolve_list`. Empty store = zero injected tokens.
 
 ## Configuration
 
@@ -77,7 +78,7 @@ Injection shape: prompt notes and delegation specs inject with content (≤6/kin
 | `maxReviewInputChars` | `40000` | trajectory slice handed to the gate |
 | `reviewBudgetTokens` | `4096` | output budget for the gate call |
 | `notifyOnAutoReview` | `true` | visible follow-up notice after an applied gate run |
-| `requireGlobalApproval` | `true` | global edits ask for explicit approval |
+| `requireGlobalApproval` | `true` | global and project edits ask for explicit approval |
 | `localFate` | `true` | gate audits local entries and proposes promote/archive (consulted, never silent) |
 | `fateIntervalTurns` | follows `reviewIntervalTurns` | minimum turns between fate assessments |
 | `goalBlockedWrapupTurns` | `3` | consecutive blocked-goal gate runs trigger one fate assessment (`0` disables) |
@@ -105,7 +106,7 @@ Example profile patch:
 
 ```bash
 pnpm install && pnpm build   # deps + tsc -> lib/
-pnpm test                    # vitest (576 tests)
+pnpm test                    # vitest (600 tests)
 pnpm test:coverage           # v8 coverage, thresholds enforced in CI
 pnpm lint                    # oxlint src test
 ```
@@ -114,7 +115,7 @@ Project layout:
 
 ```
 ├── src/                   # engine, tools, commands, gate, fate, benchmark, usage…
-├── test/                  # vitest suites (36 files)
+├── test/                  # vitest suites (37 files)
 ├── lib/                   # build output (tsc)
 ├── docs/
 │   ├── design.md          # full design doc (hardening matrix)

package/README.zh.md

@@ -7,7 +7,7 @@
 [![CI](https://github.com/ZK-Andy/dsh-continual-evolve/actions/workflows/ci.yml/badge.svg)](https://github.com/ZK-Andy/dsh-continual-evolve/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-339933)](package.json)
-[![Tests](https://img.shields.io/badge/tests-576%20passing-brightgreen)]()
+[![Tests](https://img.shields.io/badge/tests-600%20passing-brightgreen)]()
 
 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）的持续自进化插件：一套**版本化、可审计、可回滚**的 harness 状态层——提示词补充、记忆、技能、子代理规格——从会话轨迹中沉淀而来。
 
@@ -17,7 +17,8 @@
 
 Agent 在每个会话里积累可复用经验（重复失败、持久事实、可复用流程），下个会话就忘掉。本插件把这些经验变成一等公民的持久状态：
 
-- **local 会话级 / global 跨会话** 双作用域与合并语义——配合机械化晋升守卫，只有可携带、有分量、非重复的知识才能进全局
+- **三作用域**与合并语义（global < project < local）：**local** 本会话暂存、**project** 本项目跨会话库、**global** 跨项目——配合机械化晋升守卫，只有可携带、有分量、非重复的知识才能进全局
+- **类型化单条记忆**：每条 memory 带召回类型（`user | feedback | project | reference`）；踩坑（`feedback`）必须含 Why + How to apply
 - **确定性回滚**：逆操作编辑由已应用结果生成——不靠 LLM 重新猜测
 - **benchmark 闭环**：候选沉淀先经冻结用例 + 独立评分者评估再接受（rubric 加密落盘）
 - **store 卫生**：`/evolve consolidate` 把写入时冲突提示与零使用陈旧条目变成一次批准、完全可逆的批量归档——加 `merge` 可将近重复内容并入幸存原条目
@@ -26,8 +27,8 @@ Agent 在每个会话里积累可复用经验（重复失败、持久事实、
 
 1. **沉淀**——模型经 `evolve_add` 创建条目，或自动 review 门禁从会话轨迹提议（回合间隔 + 压缩检查点）。
 2. **守卫**——代码强制校验：编辑 schema、blast-radius 与作用域一致性、晋升政策（项目专属标记 / 过薄内容 / 近似重复检测 / 凭据筛查保持全局库干净——密钥类内容在所有写入出口被拒，含 mount 物化）。全局 create 与既有条目高度相似（≥0.8）时写入即拒；中等重叠带 `conflictHint` 供后续合并。
-3. **审批**——全局写入需明确人工批准；local 归宿提议先征询后落地。
-4. **应用与注入**——原子应用带快照与审计事件。prompt 补充与委派规格注入系统提示词（封顶、按相关性排序、被证伪条目降权、空 store 零 token）；memory/skill 以目录索引出现。
+3. **审批**——全局与项目写入需明确人工批准；local 归宿提议先征询后落地。
+4. **应用与注入**——原子应用带快照与审计事件。prompt 补充与委派规格注入系统提示词（封顶、按相关性排序、被证伪条目降权、空 store 零 token）；memory/skill 以按相关性排序的目录索引出现（`[memory:type:id] 标题`钩子）。
 5. **验证与回滚**——benchmark 用冻结用例为候选打分；被拒候选确定性回滚，并自动沉淀为 draft 回归用例（`auto_regression` 基准）。
 
 ## 安装
@@ -49,7 +50,7 @@ dsh plugin add ZK-Andy/dsh-continual-evolve
 | 命令 | 效果 |
 |---|---|
 | `/evolve` | 帮助 + 当前 local store |
-| `/evolve list · history · rollback <id>` | 查看与回滚（加 `global` 操作跨会话库） |
+| `/evolve list · history · rollback <id>` | 查看与回滚（加 `project` 操作本项目库，`global` 操作跨项目库） |
 | `/evolve plan [msg]` | 对 store 运行 LLM 规划器 |
 | `/evolve wrapup` | 收尾本会话 local 条目：晋升 / 归档 / 保留 |
 | `/evolve archive · unarchive · demote <id>` | 从注入中隐藏（数据保留可恢复）——`demote` 针对全局噪声 |
@@ -65,7 +66,7 @@ dsh plugin add ZK-Andy/dsh-continual-evolve
 
 第三方消费：每次进化落地（门禁或手动）都会向 `reviews.jsonl` 追加结构化 `evolve_complete` 事件（shape 见 `src/evolve-event.ts`），与人类可读的审计记录并存。
 
-注入形态：prompt 补充与委派规格带内容注入（每 kind ≤6 条 × 180 字符，按相关性排序）。memory/skill 以目录索引出现（`[kind:id] 标题`，15 行封顶 + 折叠计数行）——全文经 `evolve_list` 获取。空 store = 零注入 token。
+注入形态：prompt 补充与委派规格带内容注入（每 kind ≤6 条 × 180 字符，按相关性排序）。memory/skill 以按相关性排序的目录索引出现（`[memory:type:id] 标题`钩子，15 行封顶 + 折叠计数行）——全文经 `evolve_list` 获取。空 store = 零注入 token。
 
 ## 配置
 
@@ -77,7 +78,7 @@ dsh plugin add ZK-Andy/dsh-continual-evolve
 | `maxReviewInputChars` | `40000` | 交给门禁的轨迹切片 |
 | `reviewBudgetTokens` | `4096` | 门禁调用输出预算 |
 | `notifyOnAutoReview` | `true` | 门禁应用后发可见跟进通知 |
-| `requireGlobalApproval` | `true` | 全局写入需明确批准 |
+| `requireGlobalApproval` | `true` | 全局与项目写入需明确批准 |
 | `localFate` | `true` | 门禁审计本地条目并提议晋升/归档（先征询，绝不静默） |
 | `fateIntervalTurns` | 跟随 `reviewIntervalTurns` | 归宿评估的最小回合间隔 |
 | `goalBlockedWrapupTurns` | `3` | 连续阻塞目标的门禁轮数触发一次归宿评估（`0` 关闭） |
@@ -105,7 +106,7 @@ profile patch 示例：
 
 ```bash
 pnpm install && pnpm build   # 依赖 + tsc -> lib/
-pnpm test                    # vitest（576 例）
+pnpm test                    # vitest（600 例）
 pnpm test:coverage           # v8 覆盖率，CI 强制阈值
 pnpm lint                    # oxlint src test
 ```
@@ -114,7 +115,7 @@ pnpm lint                    # oxlint src test
 
 ```
 ├── src/                   # 引擎、工具、命令、门禁、fate、benchmark、usage…
-├── test/                  # vitest 测试套件（36 个文件）
+├── test/                  # vitest 测试套件（37 个文件）
 ├── lib/                   # 构建产物（tsc）
 ├── docs/
 │   ├── design.md          # 完整设计文档（硬化矩阵）

package/lib/auto.d.ts

@@ -103,14 +103,16 @@ export declare function parseReviewModel(reviewModel: string | undefined, fallba
 } | undefined;
 /**
  * The state view the gate and planner judge: the session's local entries
- * merged with the global store, each entry carrying its real scope. Without
- * the global half the gate cannot see that a topic is already covered
- * cross-session and happily re-sediments a local duplicate of it.
+ * merged with the project and global stores, each entry carrying its real
+ * scope. Without the global half the gate cannot see that a topic is already
+ * covered cross-session and happily re-sediments a local duplicate of it.
  *
  * The merged view is read-only context — applying still targets the raw
  * local state (baseline checks compare local entries only).
  */
-export declare function loadGateHarnessView(engine: EvolutionEngine, sessionId: string): HarnessState;
+export declare function loadGateHarnessView(engine: EvolutionEngine, sessionId: string, opts?: {
+    projectKey?: string;
+}): HarnessState;
 /**
  * D3 (goal blocked → wrap-up coupling, reverse direction): count consecutive
  * gate runs whose goal is in phase "blocked"; when the streak reaches

package/lib/auto.js

@@ -25,6 +25,7 @@ import { notifyAutoReview } from "./notify.js";
 import { runLocalFatePhase } from "./fate.js";
 import { entrySourceOf } from "./source.js";
 import { mergeHarnessStates } from "./state.js";
+import { projectKeyOf } from "./project.js";
 import { questionServiceOf } from "./approval.js";
 import { buildEvolveCompleteEvent, emitEvolveComplete } from "./evolve-event.js";
 import { captureAutoCase } from "./autocase.js";
@@ -153,15 +154,16 @@ function stateFor(map, sessionId) {
 }
 /**
  * The state view the gate and planner judge: the session's local entries
- * merged with the global store, each entry carrying its real scope. Without
- * the global half the gate cannot see that a topic is already covered
- * cross-session and happily re-sediments a local duplicate of it.
+ * merged with the project and global stores, each entry carrying its real
+ * scope. Without the global half the gate cannot see that a topic is already
+ * covered cross-session and happily re-sediments a local duplicate of it.
  *
  * The merged view is read-only context — applying still targets the raw
  * local state (baseline checks compare local entries only).
  */
-export function loadGateHarnessView(engine, sessionId) {
-    return mergeHarnessStates(engine.load("global", undefined), engine.load("local", sessionId));
+export function loadGateHarnessView(engine, sessionId, opts) {
+    const projectState = opts?.projectKey ? engine.load("project", opts.projectKey) : undefined;
+    return mergeHarnessStates(engine.load("global", undefined), engine.load("local", sessionId), projectState ? { projectState } : undefined);
 }
 /**
  * One gate run = review phase + local-fate phase (#11 P2). The review phase
@@ -239,7 +241,8 @@ async function runReviewPhase(ctx, engine, agent, config, state, reason, record)
     // can recognize topics already covered globally and decline duplicates;
     // applying still targets the raw local store.
     const localState = engine.load("local", sessionId);
-    const harnessState = loadGateHarnessView(engine, sessionId);
+    const projectKey = projectKeyOf(agent);
+    const harnessState = loadGateHarnessView(engine, sessionId, projectKey ? { projectKey } : undefined);
     const history = engine.history("local", sessionId);
     // Gap C1: resolve optional review model override.
     const reviewRoute = parseReviewModel(config.reviewModel, agent.options.provider);

package/lib/command.js

@@ -13,11 +13,12 @@ import { executeGoalCommand } from "./goal-command.js";
 import { executeMountCommand, executeUnmountCommand } from "./mount-command.js";
 import { executeBenchmarkCommand } from "./benchmark-command.js";
 import { executeWrapupCommand } from "./wrapup-command.js";
+import { projectKeyOf } from "./project.js";
 import { loadUsage } from "./usage.js";
 import { planConsolidation } from "./consolidate.js";
 const USAGE = `Usage:
   /evolve                  show this help and the current local store
-  /evolve list [global]    list entries (add "global" for the cross-session store)
+  /evolve list [project|global]    list entries (default local staging; "project" = this project's cross-session store, "global" = cross-project store)
   /evolve history [global] show applied refinements (rollback ids)
   /evolve rollback <id> [global]  deterministically revert a refinement
   /evolve plan [msg]       run the LLM planner against the current store
@@ -52,8 +53,29 @@ function scopeArg(tokens) {
     if (tokens[0] === "global") {
         return { scope: "global", rest: tokens.slice(1) };
     }
+    if (tokens[0] === "project") {
+        return { scope: "project", rest: tokens.slice(1) };
+    }
     return { scope: "local", rest: tokens };
 }
+/**
+ * The store id a scope reads/writes from the human command: live session id
+ * for local, derived project key for project, undefined for global. Throws
+ * for project when the session cwd is unavailable.
+ */
+function storeIdForCommand(scope, invocation) {
+    if (scope === "local") {
+        return invocation.agent.id;
+    }
+    if (scope === "project") {
+        const key = projectKeyOf(invocation.agent);
+        if (!key) {
+            throw new Error("project scope needs the session cwd (unavailable here) — use local or global instead");
+        }
+        return key;
+    }
+    return undefined;
+}
 /**
  * Tokenize a command's raw input with shell-like quoting:
  * - a `#` outside quotes starts a comment (rest of the line is dropped);
@@ -129,11 +151,11 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                 return success(`${USAGE}\n\n${formatHarnessStateForPrompt(engine.load("local", sessionId))}`);
             case "list": {
                 const { scope } = scopeArg(rest);
-                return success(formatHarnessStateForPrompt(engine.load(scope, sessionId)));
+                return success(formatHarnessStateForPrompt(engine.load(scope, storeIdForCommand(scope, invocation))));
             }
             case "history": {
                 const { scope } = scopeArg(rest);
-                const history = engine.history(scope, sessionId);
+                const history = engine.history(scope, storeIdForCommand(scope, invocation));
                 return success(historyForPrompt(history) || "(no refinements yet)");
             }
             case "rollback": {
@@ -142,7 +164,7 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                 if (!id) {
                     return error(`rollback requires a refinement id.\n${USAGE}`);
                 }
-                const result = engine.rollback(scope, sessionId, id);
+                const result = engine.rollback(scope, storeIdForCommand(scope, invocation), id);
                 return success(renderResult(result));
             }
             case "archive":
@@ -154,9 +176,9 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                     return error(`${sub} requires an entry id.\n${USAGE}`);
                 }
                 if (sub === "demote") {
-                    return demoteEntry(engine, id, sessionId);
+                    return demoteEntry(engine, id, sessionId, projectKeyOf(invocation.agent));
                 }
-                const state = engine.load(scope, sessionId);
+                const state = engine.load(scope, storeIdForCommand(scope, invocation));
                 const found = findEntryById(state, id);
                 if (!found) {
                     return error(`entry ${id} not found in the ${scope} store`);
@@ -170,7 +192,7 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                     delete metadata[ARCHIVED_AT_KEY];
                 }
                 const archived = sub === "archive";
-                const result = engine.apply(scope, sessionId, {
+                const result = engine.apply(scope, storeIdForCommand(scope, invocation), {
                     summary: `${archived ? "Archive" : "Unarchive"} entry ${kind}:${id}`,
                     rationale: "Human-invoked archive/unarchive via the /evolve command.",
                     expectedOutcome: `Entry ${archived ? "is hidden from injection (data kept, restorable)" : "is injected again"}.`,
@@ -260,8 +282,8 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                 if (!path) {
                     return error(`export requires an output path.\n${USAGE}`);
                 }
-                const state = engine.load(scope, sessionId);
-                const history = engine.history(scope, sessionId);
+                const state = engine.load(scope, storeIdForCommand(scope, invocation));
+                const history = engine.history(scope, storeIdForCommand(scope, invocation));
                 const payload = {
                     version: 1,
                     scope,
@@ -293,7 +315,7 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                     },
                     refinements: Array.isArray(payload["refinements"]) ? payload["refinements"] : [],
                 };
-                const paths = storePaths(engine.baseDir, scope, sessionId);
+                const paths = storePaths(engine.baseDir, scope, storeIdForCommand(scope, invocation));
                 saveHarnessState(paths.stateDir, state);
                 if (Array.isArray(payload["history"])) {
                     for (const result of payload["history"]) {
@@ -307,8 +329,8 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
             case "plan": {
                 const { scope, rest: after } = scopeArg(rest);
                 const instructions = after.length > 0 ? after.join(" ") : undefined;
-                const state = engine.load(scope, sessionId);
-                const history = engine.history(scope, sessionId);
+                const state = engine.load(scope, storeIdForCommand(scope, invocation));
+                const history = engine.history(scope, storeIdForCommand(scope, invocation));
                 const proposal = await planWithLlm(ctx, {
                     agent: invocation.agent,
                     state,
@@ -319,10 +341,10 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                     // skill-creator template facts (fallback: builtin guide).
                     skillsRoot: join(engine.baseDir, "skills"),
                 });
-                if (scope === "global" && opts.requireGlobalApproval && proposal.edits.length > 0) {
-                    await requireGlobalApproval(ctx, invocation.agent, invocation.signal, `/evolve plan global 将应用 ${proposal.edits.length} 条编辑到跨会话 store：${proposal.summary}`);
+                if ((scope === "global" || scope === "project") && opts.requireGlobalApproval && proposal.edits.length > 0) {
+                    await requireGlobalApproval(ctx, invocation.agent, invocation.signal, `/evolve plan ${scope} 将应用 ${proposal.edits.length} 条编辑到${scope === "project" ? "本项目" : "跨会话"} store：${proposal.summary}`);
                 }
-                const result = engine.apply(scope, sessionId, proposal, {
+                const result = engine.apply(scope, storeIdForCommand(scope, invocation), proposal, {
                     scope,
                     baselineState: state,
                     ...(entrySourceOf(invocation.agent, sessionId) ? { source: entrySourceOf(invocation.agent, sessionId) } : {}),
@@ -354,18 +376,23 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
 }
 /**
  * Demote (2026-08-22): hide an entry from injection WITHOUT deleting it —
- * the one-command remedy for global-store pollution. Searches the global
- * store first (the primary target: cross-project noise), then the session's
- * local store. The data stays; `/evolve unarchive` restores it.
+ * the one-command remedy for store pollution. Searches the global store
+ * first (the primary target: cross-project noise), then the project store,
+ * then the session's local store. The data stays; `/evolve unarchive` restores it.
  */
-function demoteEntry(engine, id, sessionId) {
-    for (const scope of ["global", "local"]) {
-        const state = engine.load(scope, sessionId);
+function demoteEntry(engine, id, sessionId, projectKey) {
+    const targets = [
+        { scope: "global", storeId: undefined },
+        ...(projectKey ? [{ scope: "project", storeId: projectKey }] : []),
+        { scope: "local", storeId: sessionId },
+    ];
+    for (const { scope, storeId } of targets) {
+        const state = engine.load(scope, storeId);
         const found = findEntryById(state, id);
         if (!found)
             continue;
         const [kind, entry] = found;
-        const result = engine.apply(scope, sessionId, {
+        const result = engine.apply(scope, storeId, {
             summary: `demote: archive ${kind}:${id} from the ${scope} store`,
             rationale: "Human-invoked demote via the /evolve command.",
             expectedOutcome: "The entry is hidden from injection in every scope it touched; data is kept and restorable.",
@@ -380,10 +407,10 @@ function demoteEntry(engine, id, sessionId) {
                 },
             ],
         }, { scope });
-        const restoreScope = scope === "global" ? " global" : "";
+        const restoreScope = scope === "global" ? " global" : scope === "project" ? " project" : "";
         return success(`demoted ${kind}:${id} from the ${scope} store (archived — restore with /evolve unarchive ${id}${restoreScope})\n${renderResult(result)}`);
     }
-    return error(`entry ${id} not found in the global or local store`);
+    return error(`entry ${id} not found in the global, project, or local store`);
 }
 function renderResult(result) {
     const applied = result.appliedEdits.filter((e) => e.applied);

package/lib/fate.js

@@ -26,7 +26,7 @@ export function planLocalFates(items, candidates, globalState, policy = DEFAULT_
             splitSkipped.push({ key: item.key, reason: "not in the audited candidate list" });
             continue;
         }
-        const blocked = splitPromoteBlocked(item, globalState, candidate.kind, policy);
+        const blocked = splitPromoteBlocked(item, globalState, candidate.kind, policy, candidate.metadata);
         if (blocked) {
             splitSkipped.push({ key: item.key, reason: blocked });
             continue;

package/lib/index.js

@@ -116,7 +116,7 @@ export function apply(ctx, config) {
     ctx.systemPrompt.section({
         name: "tool:continual-evolve",
         order: config.sectionOrder ?? 118,
-        text: "You have a continual harness: versioned, persistent prompt notes, memories, skills, and subagent specs. Prompt notes and delegation specs are injected below; use evolve_list for the full state. Create an entry (evolve_add) after a repeated failure, a reusable tactic, a durable fact or preference, a repeated procedure, or a repeated delegation role. Keep edits small and evidence-backed; prefer local scope, use global: true only for stable cross-session lessons. Update or delete (evolve_update / evolve_delete) when an entry is wrong or obsolete; roll back faulty refinements with evolve_rollback. Every edit is snapshotted, versioned, and recorded — no edit can be silently lost.",
+        text: "You have a continual harness: versioned, persistent prompt notes, memories, skills, and subagent specs. Memories are ONE FACT per entry, typed user/feedback/project/reference (feedback = pitfall + Why + How to apply). Stores: local (this session's staging), project (this project's cross-session store), global (cross-project). Prompt notes and delegation specs are injected below; use evolve_list for the full state. Create an entry (evolve_add) after a repeated failure, a reusable tactic, a durable fact or preference, a repeated procedure, or a repeated delegation role. Keep edits small and evidence-backed; prefer local scope, use project for repo-specific lessons, global: true only for stable cross-project lessons. Update or delete (evolve_update / evolve_delete) when an entry is wrong or obsolete; roll back faulty refinements with evolve_rollback. Every edit is snapshotted, versioned, and recorded — no edit can be silently lost.",
     });
     // Phase 2: make prompt entries real system-prompt content and subagent
     // entries real delegation specs. The text is a provider evaluated at every

package/lib/inject.d.ts

@@ -114,20 +114,42 @@ export declare function formatPromptEntriesSection(entries: readonly HarnessEntr
 export declare function formatSubagentSpecsSection(entries: readonly HarnessEntry[], query?: string): string;
 /**
  * Gap B3: a lightweight directory of ALL non-archived entries across all
- * kinds — one line per entry (`- [kind:id] title`), no content. This gives
- * the model a zero-cost overview of what exists so it can ask for full text
- * via `evolve_list` or `/evolve list`. The directory is appended after the
- * curated top-N injection sections and adds minimal tokens.
+ * kinds — one line per entry, no content. Memory lines carry their recall
+ * type (`- [memory:feedback:id] title`) so the model can judge relevance
+ * from the index alone. This gives the model a zero-cost overview of what
+ * exists so it can ask for full text via `evolve_list` or `/evolve list`.
+ * The directory is appended after the curated top-N injection sections and
+ * adds minimal tokens.
  *
  * 2026-08-22 throttle: the directory is CAPPED at {@link DEFAULT_DIRECTORY_LINES}
- * lines (oldest-sorted stable order) with the remainder folded into a single
- * counter line — an uncapped directory across a polluted global store was
- * measured at ~2K chars of every build in every project.
+ * lines with the remainder folded into a single counter line — an uncapped
+ * directory across a polluted global store was measured at ~2K chars of
+ * every build in every project.
+ *
+ * 2026-09-23 relevance order: the directory is sorted by
+ * {@link rankEntries} against the assembly's relevance query, so the lines
+ * folded below the cap are the least relevant — not the dictionary tail.
  */
 export declare const DEFAULT_DIRECTORY_LINES = 15;
+/** One directory index line: memory lines carry their recall-type hook. */
+export declare function directoryLine(entry: HarnessEntry): string;
 export declare function formatEntriesDirectory(...kindEntries: readonly HarnessEntry[][]): string;
 /** {@link formatEntriesDirectory} with an explicit cap (configurable). */
 export declare function formatEntriesDirectoryCapped(maxLines: number, ...kindEntries: readonly HarnessEntry[][]): string;
+/**
+ * {@link formatEntriesDirectoryCapped} with a relevance query: entries are
+ * ordered by {@link rankEntries} (relevance first, then recency) so the cap
+ * folds the least relevant entries — never the dictionary tail. An empty
+ * query degrades to the valence/recency/stable order, still deterministic.
+ */
+export declare function formatEntriesDirectoryRanked(maxLines: number, query: string | undefined, ...kindEntries: readonly HarnessEntry[][]): string;
+/**
+ * The directory entries actually shown under the cap, in display order —
+ * the single source for both the rendered text and usage accounting (so a
+ * memory's injection IS its directory line even with the `:type` hook).
+ * Returns [] when the directory is suppressed or empty.
+ */
+export declare function rankedDirectoryEntries(maxLines: number, query: string | undefined, ...kindEntries: readonly HarnessEntry[][]): HarnessEntry[];
 /**
  * Walk the parent-session chain from `agent` upward and return the nearest
  * session whose local store is non-empty, if any. Children inherit their
@@ -138,19 +160,23 @@ export declare function formatEntriesDirectoryCapped(maxLines: number, ...kindEn
 export declare function nearestLocalStateWithEntries(engine: EvolutionEngine, agent: AgentLike): HarnessState | undefined;
 /**
  * Compose the full injected block for one assembling agent: global entries
- * merged with the nearest carrying local store (local wins on id collision).
+ * merged with this project's store (when the session cwd resolves one) and
+ * the nearest carrying local store (precedence global < project < local).
  * The optional `query` — when absent, derived from the agent's most recent
  * direct user messages — ranks which entries fill the per-kind cap
  * (relevance first, then recency; see {@link rankEntries}). Returns "" when
  * nothing is injectable — the prompt renderer then drops the section, so an
  * empty store adds zero tokens to every assembly.
  *
- * `opts.directoryLines` caps the entry-directory index (2026-08-22 throttle).
+ * `opts.directoryLines` caps the entry-directory index (2026-08-22 throttle);
+ * `opts.projectKey` pins the project layer explicitly (tests, tools) —
+ * otherwise it is derived from the agent's session cwd, best-effort.
  * Usage recording covers ALL kinds — memories and skills appear as directory
  * lines, prompts/subagents as content — and is deduped per session so the
  * counts read "how many sessions saw this", not "how many prompt builds".
  */
 export declare function entriesSectionText(engine: EvolutionEngine, agent: AgentLike | undefined, query?: string, opts?: {
     directoryLines?: number;
+    projectKey?: string;
 }): string;
 //# sourceMappingURL=inject.d.ts.map