@fonlan/dsh-gitmemo 0.3.1 → 0.4.0

package/README.md

@@ -16,6 +16,9 @@ dependency, and no manual memory commands are ever needed.
 - **Git-only** — no runtime dependency beyond the `git` CLI
 - **Token-efficient** — reuses prior conclusions via `mem_search`; subagents carry neither the workflow rules nor the tool schemas
 - **Immutable entries** — every write creates a new file; corrections use `mem_replace` (one commit deletes the old file and adds the new one), withdrawal uses `mem_delete`
+- **Knowledge freshness** — `mem_replace` is not just for user corrections: work that overrules a stored conclusion actively replaces it; `mem_search` scores hits as distinct matched keywords + a mild recency bonus (≤ +0.5, linearly decaying to 0 over ~180 days), so conflicting stale conclusions lose to their replacements
+- **Topic pages (MOC)** — a `kind: "topic"` entry aggregates a topic's "current truth": the summary states the currently-valid conclusions and the page evolves via `mem_replace` (kind is inherited), not per-task rewrites
+- **Wiki links between entries** — content references other entries as `[[<commit-hash>]]`; `mem_read` with `expand: true` resolves those links one hop and automatically follows the `GitMemo-Replaces` chain to a replaced target's active version (dangling links come back with an error)
 - **Structured search** — commit messages carry `GitMemo-*` trailers (keywords, digest, search-text projections); search is `git log --grep --fixed-strings` over commit messages only — entry bodies are never scanned
 - **Auditable** — every memory action is a commit in `.mem`'s Git history; replaced/deleted entries stay readable by hash
 - **Crash-safe** — write/delete/replace run under a cross-process lock with a journal written before entry mutation; migration uses a sibling swap journal so an interrupted directory exchange is recovered before automatic initialization
@@ -25,11 +28,11 @@ dependency, and no manual memory commands are ever needed.
 
 | Piece | Description |
 | --- | --- |
-| `mem_search` | Search memories: `keywords` (array of 1–12, 中英文同义词), `skip` + `snapshot` (stable pagination). Returns up to 20 scored hits with `summary` / `keywords` / `matched_keywords` |
-| `mem_read` | Read one memory entry by create/replace commit hash (full markdown; historical hashes stay readable) |
-| `mem_write` | Store a task outcome: `title` + `summary` + `keywords` (2–12) + `content` (engine generates front matter), optional `related_branches` / `related_paths`. One ADD commit per immutable file |
+| `mem_search` | Search memories: `keywords` (array of 1–12, 中英文同义词), `skip` + `snapshot` (stable pagination). Returns up to 20 scored hits with `summary` / `keywords` / `kind` / `matched_keywords` (score = matched keywords + recency bonus) |
+| `mem_read` | Read one memory entry by create/replace commit hash (full markdown; historical hashes stay readable); returns `kind`; optional `expand: true` resolves `[[hash]]` links one hop |
+| `mem_write` | Store a task outcome: `title` + `summary` + `keywords` (2–12) + `content` (engine generates front matter), optional `kind` (`"task"` default / `"topic"` aggregated page), `related_branches` / `related_paths`. One ADD commit per immutable file |
 | `mem_delete` | Withdraw an obsolete conclusion (requires `commit_hash` + `reason`) |
-| `mem_replace` | Correct an outdated conclusion in ONE atomic commit (D old + A new) — never delete-then-write |
+| `mem_replace` | Correct an outdated conclusion in ONE atomic commit (D old + A new) — never delete-then-write. Triggered by user corrections AND by work that overrules a stored conclusion; `kind` defaults to the replaced entry's kind |
 | Scoped rules | The workflow rules + the five tools are registered into **root agents only** (`delegationDepth === 0`) at `agent/created`; subagents carry neither |
 
 ## Installation
@@ -83,7 +86,8 @@ The `.mem` repository lives at the **project root** of the calling session's wor
   `.gitignore`), and refuses to run when the parent repo already tracks `.mem` content.
 - Every write creates a brand-new file with an exclusive create (never overwrites), commits
   one ADD commit with structured trailers, and records the code branch/SHA/related paths in
-  the entry front matter.
+  the entry front matter. Front matter always carries `kind` (`"task"` or `"topic"`); topic
+  entries additionally carry a `GitMemo-Kind: topic` commit trailer.
 
 The whole memory stays readable with plain `git`:
 
@@ -97,17 +101,27 @@ git -C .mem show <commit-hash>
 1. **Before work — search.** For repo-related tasks, extract 1–12 中英文关键词 → `mem_search`.
    Pure chat and general Q&A need no search.
 2. **Preselect results.** Based on `title` / `summary` / `keywords` / `score` /
-   `matched_keywords`, `mem_read` at most 5 most relevant memories; paginate with `skip` +
+   `matched_keywords`, `mem_read` at most 5 most relevant memories (`kind: "topic"` entries
+   are a topic's aggregated entry point — prefer them); paginate with `skip` +
    the returned `snapshot`.
 3. **End-of-session checkpoint — the only write path.** When the conversation is ending,
    `mem_write` every completed repo-related task that still lacks a memory and whose outcome is
    **valuable/reusable** (or was explicitly asked to be remembered). Never duplicate an
    already-written entry. Never write for pure Q&A, incomplete tasks, non-repo work, or purely
-   operational git actions.
-4. **User correction.** If a stored conclusion is outdated and a replacement exists →
+   operational git actions. `keywords` should be task-related words NOT already present in
+   `title` / `summary` (中英文同义词 both fine) — words already there are searchable via
+   `title` / `summary` themselves, so repeating them does not improve recall.
+4. **Keep fresh.** If the user corrects a stored conclusion and a replacement exists →
    `mem_replace` (never delete-then-write). If it is obsolete with no replacement →
-   `mem_delete` with a `reason`.
-5. **Subagent results.** Only the root agent decides whether a session-level memory is written.
+   `mem_delete` with a `reason`. The same applies — without waiting for the user — when this
+   session's own work overrules a stored conclusion (implemented/refactored away). When search
+   returns conflicting old/new conclusions, trust the newer one (score already includes the
+   recency bonus).
+5. **Topic pages.** Once a topic has accumulated several memories — or needs a "current truth"
+   entry point — write one `kind: "topic"` aggregated entry: the summary states the currently
+   valid conclusions, and the content links the evidence entries as `[[<commit-hash>]]` with a
+   one-line status each; evolve topic pages via `mem_replace`.
+6. **Subagent results.** Only the root agent decides whether a session-level memory is written.
 
 ## Development
 

package/README.zh.md

@@ -15,6 +15,9 @@
 - **仅依赖 Git** —— 除 `git` CLI 外无任何运行时依赖
 - **省 token** —— 通过 `mem_search` 复用既有结论；子代理既不携带工作流规则也不携带工具 schema
 - **条目不可变** —— 每次写入都创建新文件；更正用 `mem_replace`（一个提交同时删除旧文件、新增新文件），作废用 `mem_delete`
+- **知识保鲜** —— `mem_replace` 不只用于用户更正：本次工作覆盖旧结论时同样主动替换；`mem_search` 评分为「命中关键词数 + 温和的 recency 加成（≤ +0.5，180 天线性衰减到 0）」，新旧结论冲突时自动偏向新条目
+- **主题聚合页（MOC）** —— `kind: "topic"` 条目聚合一个主题的「当前真相」：summary 概括当下有效结论，靠 `mem_replace` 演进（kind 自动继承），不按任务重复新增
+- **条目间 Wiki 链接** —— content 里用 `[[<commit-hash>]]` 引用其他条目；`mem_read` 传 `expand: true` 一跳展开链接目标，并自动跟随 `GitMemo-Replaces` 链到被替换条目的最新版本（悬空链接带 error 返回）
 - **结构化搜索** —— commit message 携带 `GitMemo-*` trailers（keywords、digest、search-text 投影）；搜索只对 commit message 执行 `git log --grep --fixed-strings`，绝不扫描条目正文
 - **可审计** —— 每次记忆操作都是 `.mem` Git 历史中的一次提交；被替换/删除的条目仍可按哈希读取
 - **崩溃安全** —— write/delete/replace 在修改条目前先写事务 journal；迁移另用 sibling swap journal，目录交换中断后会在自动初始化前恢复
@@ -24,11 +27,11 @@
 
 | 内容 | 说明 |
 | --- | --- |
-| `mem_search` | 搜索记忆：`keywords`（1–12 个关键词数组，建议中英文同义词）、`skip` + `snapshot`（稳定分页）。每次最多返回 20 条带 `summary` / `keywords` / `matched_keywords` 的评分结果 |
-| `mem_read` | 按创建/替换提交哈希读取一条记忆的完整 markdown（历史哈希仍可读） |
-| `mem_write` | 存储任务结论：`title` + `summary` + `keywords`（2–12）+ `content`（front matter 由引擎生成），可选 `related_branches` / `related_paths`。每个不可变文件对应一个 ADD 提交 |
+| `mem_search` | 搜索记忆：`keywords`（1–12 个关键词数组，建议中英文同义词）、`skip` + `snapshot`（稳定分页）。每次最多返回 20 条带 `summary` / `keywords` / `kind` / `matched_keywords` 的评分结果（score = 命中关键词数 + recency 加成） |
+| `mem_read` | 按创建/替换提交哈希读取一条记忆的完整 markdown（历史哈希仍可读）；返回 `kind`；可选 `expand: true` 一跳展开条目内的 `[[hash]]` 链接 |
+| `mem_write` | 存储任务结论：`title` + `summary` + `keywords`（2–12）+ `content`（front matter 由引擎生成），可选 `kind`（`"task"` 缺省 / `"topic"` 聚合页）、`related_branches` / `related_paths`。每个不可变文件对应一个 ADD 提交 |
 | `mem_delete` | 作废无替代结论（需要 `commit_hash` + `reason`） |
-| `mem_replace` | 一个原子提交内更正旧结论（D 旧文件 + A 新文件）—— 禁止先删后写 |
+| `mem_replace` | 一个原子提交内更正旧结论（D 旧文件 + A 新文件）—— 禁止先删后写。触发面不只是用户更正：本次工作覆盖旧结论时同样应主动 replace；`kind` 缺省继承被替换条目 |
 | 作用域规则 | 工作流规则与五个工具只在 `agent/created` 时注册进**根 Agent**（`delegationDepth === 0`）；子代理两者皆无 |
 
 ## 安装
@@ -78,7 +81,8 @@ bundle patch 自带合理默认值，可在 profile 的 `cordis.patch.yml` 中
 - `.mem` 初始化在自己的 `main` 分支上；初始化时把 `.mem/` 与锁文件路径写入父仓库的
   `.git/info/exclude`（绝不写入受版本控制的 `.gitignore`），且当父仓库已跟踪 `.mem` 内容时拒绝初始化。
 - 每次写入都用独占创建生成全新文件（绝不覆盖），以带结构化 trailers 的 ADD 提交落库，并把代码
-  分支/SHA/相关路径记录在条目 front matter 中。
+  分支/SHA/相关路径记录在条目 front matter 中。front matter 固定携带 `kind`（`"task"` 或 `"topic"`）；
+  topic 条目的 commit message 额外带 `GitMemo-Kind: topic` trailer。
 
 整个记忆可以用普通 `git` 命令查看：
 
@@ -91,13 +95,14 @@ git -C .mem show <commit-hash>
 
 1. **开工前 —— 搜索。** 仓库相关任务开始前提取 1–12 个中英文关键词 → `mem_search`。纯闲聊和通用问答无需搜索。
 2. **结果预筛。** 根据 `title` / `summary` / `keywords` / `score` / `matched_keywords` 最多
-   `mem_read` 5 条最相关记忆；用 `skip` + 返回的 `snapshot` 翻页。
+   `mem_read` 5 条最相关记忆（`kind: "topic"` 的条目是该主题的聚合入口，优先读）；用 `skip` + 返回的
+   `snapshot` 翻页。
 3. **会话结束检查点 —— 唯一的写入路径。** 对话即将结束时，`mem_write` **每一条**已完成、与仓库
    相关、且结论**有价值/可复用**（或用户明确要求记住）但还没有记忆的任务。绝不重复写已存在的条目。
-   纯问答、未完成任务、与仓库无关的工作、纯操作性的 git 动作一律不写。
-4. **用户更正。** 已存结论过时且有替代结论 → `mem_replace`（禁止先 delete 再 write）；结论作废且无
-   替代 → 带 `reason` 的 `mem_delete`。
-5. **子代理结果。** 是否形成一条会话级记忆，由根 Agent 汇总后决定。
+   纯问答、未完成任务、与仓库无关的工作、纯操作性的 git 动作一律不写。`keywords` 应选用与任务相关但未出现在 `title` / `summary` 中的词（中英文同义词皆可）——`title` / `summary` 已有的词本身就能被检索到，重复它们不会提高召回率。
+4. **知识保鲜（KEEP FRESH）。** 用户更正旧结论：有替代用 `mem_replace`（禁止先 delete 再 write），作废无替代用带 `reason` 的 `mem_delete`；本次会话的工作覆盖/推翻某条已存结论时同样主动处理，不必等用户指出。检索结果中新旧冲突时优先采信更新的条目（score 已含 recency 加成）。
+5. **主题聚合页（TOPIC PAGE）。** 同一主题积累多条记忆、或需要「当前真相」入口时，写一条 `kind: "topic"` 聚合条目：summary 概括当下有效结论，content 用 `[[<commit-hash>]]` 链接证据条目并各配一句话状态；topic 条目靠 `mem_replace` 演进。
+6. **子代理结果。** 是否形成一条会话级记忆，由根 Agent 汇总后决定。
 
 ## 开发
 

package/lib/index.js

@@ -70,7 +70,16 @@ const SEARCH_HIT = {
             items: { type: "string" },
             description: "Structured keywords stored with the entry."
         },
-        score: { type: "number", required: true, description: "Number of distinct query keywords matched." },
+        kind: {
+            type: "string",
+            required: true,
+            description: "Entry kind: task (task-outcome record) or topic (aggregated topic page)."
+        },
+        score: {
+            type: "number",
+            required: true,
+            description: "Relevance: distinct matched keywords + a mild recency bonus (≤ +0.5, decaying to 0 by ~180 days)."
+        },
         matched_keywords: {
             type: "array",
             required: true,
@@ -79,6 +88,29 @@ const SEARCH_HIT = {
         }
     }
 };
+const LINK_RESOLUTION = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        link_hash: { type: "string", required: true, description: "Hash exactly as written inside the [[...]] link." },
+        resolved_hash: {
+            type: "string",
+            required: true,
+            description: "Hash actually read: the active version of the linked entry (empty string when unresolvable)."
+        },
+        active: {
+            type: "boolean",
+            required: true,
+            description: "True when the link still points at the active version; false = superseded or dangling."
+        },
+        file: { type: "string", description: "Entry file path inside the memory repo." },
+        title: { type: "string", description: "Target entry title." },
+        summary: { type: "string", description: "Target entry summary." },
+        keywords: { type: "array", items: { type: "string" }, description: "Target entry keywords." },
+        kind: { type: "string", description: "Target entry kind: task or topic." },
+        error: { type: "string", description: "Present when the link target could not be resolved (dangling link)." }
+    }
+};
 const KEYWORDS_ARRAY = {
     type: "array",
     items: { type: "string" },
@@ -109,6 +141,8 @@ function formatSearchResults(value) {
             hit.title +
             "|" +
             hit.date +
+            "|kind=" +
+            hit.kind +
             "|score=" +
             hit.score +
             "|matched=" +
@@ -128,7 +162,7 @@ function formatSearchResults(value) {
 function registerMemTools(ctx, config) {
     ctx.tools.register(defineTool({
         name: "mem_search",
-        description: "Search the gitmemo long-term memory (.mem git repo) for past task outcomes. Call BEFORE starting repo-related work: extract 1-12 中英文关键词 from the user request (include synonyms in both languages when useful) and run mem_search; pure chat and general Q&A need no search. Returns a snapshot, total, next_skip and up to 20 scored hits with summary/keywords/matched_keywords — select at most 5 most relevant hits and mem_read them. Paginate by passing skip and the returned snapshot back unchanged; a stale snapshot is rejected explicitly.",
+        description: "Search the gitmemo long-term memory (.mem git repo) for past task outcomes. Call BEFORE starting repo-related work: extract 1-12 中英文关键词 from the user request (include synonyms in both languages when useful) and run mem_search; pure chat and general Q&A need no search. Returns a snapshot, total, next_skip and up to 20 scored hits with summary/keywords/kind/matched_keywords — score = distinct matched keywords + a mild recency bonus, so newer entries rank slightly higher and superseded conclusions lose to their replacements. Select at most 5 most relevant hits and mem_read them (prefer kind:\"topic\" hits as topic-page entry points). Paginate by passing skip and the returned snapshot back unchanged; a stale snapshot is rejected explicitly.",
         parameters: {
             keywords: { ...KEYWORDS_ARRAY, required: true },
             skip: {
@@ -181,12 +215,16 @@ function registerMemTools(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: "mem_read",
-        description: "Read one gitmemo memory entry by commit hash (returned by mem_search). Select only the most relevant memories before reading — at most 5 when a search returns more. Historical entries that were replaced or deleted stay readable for audit.",
+        description: "Read one gitmemo memory entry by commit hash (returned by mem_search). Select only the most relevant memories before reading — at most 5 when a search returns more. Historical entries that were replaced or deleted stay readable for audit. Pass expand:true to also resolve [[<commit-hash>]] wiki links in the entry body one hop to their target entries (each target follows forward to its active version) — use it when reading a kind:\"topic\" topic page or any entry that links others.",
         parameters: {
             commit_hash: {
                 type: "string",
                 required: true,
                 description: "Commit hash of the memory entry to read (create or replace hash)."
+            },
+            expand: {
+                type: "boolean",
+                description: "Resolve [[<commit-hash>]] links in the entry body one hop to their (active) target entries. Default false."
             }
         },
         output: {
@@ -197,16 +235,57 @@ function registerMemTools(ctx, config) {
                     commit_hash: { type: "string", required: true },
                     file: { type: "string", required: true, description: "Entry file path inside the memory repo." },
                     content: { type: "string", required: true, description: "Full markdown of the memory entry." },
+                    kind: {
+                        type: "string",
+                        required: true,
+                        description: "Entry kind: task (task-outcome record) or topic (aggregated topic page)."
+                    },
+                    links: {
+                        type: "array",
+                        items: LINK_RESOLUTION,
+                        description: "One-hop resolution of the entry's [[<commit-hash>]] links; present only when expand:true."
+                    },
                     legacy: { type: "boolean", description: "True for legacy-format commits (pre-migration)." }
                 }
             },
-            render: (_args, value) => textBlock((value.legacy === true ? "[legacy entry]\n" : "") + value.content)
+            render: (_args, value) => {
+                const parts = [(value.legacy === true ? "[legacy entry]\n" : "") + value.content];
+                if (value.links !== undefined && value.links.length > 0) {
+                    parts.push("--- linked entries (" + value.links.length + ") ---");
+                    for (const link of value.links) {
+                        if (link.error !== undefined) {
+                            parts.push("x " + link.link_hash.slice(0, 8) + " — unresolved: " + link.error);
+                            continue;
+                        }
+                        const state = link.active
+                            ? "active"
+                            : link.resolved_hash !== link.link_hash
+                                ? "superseded → " + link.resolved_hash.slice(0, 8)
+                                : "not active (withdrawn)";
+                        parts.push("= " + link.resolved_hash.slice(0, 8) + " [" + (link.kind ?? "task") + "] " +
+                            (link.title ?? "") + " (" + state + ")");
+                        if (link.summary !== undefined && link.summary.length > 0) {
+                            parts.push("  " + link.summary.replace(/\s+/g, " ").slice(0, 400));
+                        }
+                    }
+                }
+                return textBlock(parts.join("\n"));
+            }
         },
         isConcurrencySafe: () => true,
         async execute(args, exec) {
             const memo = await engineFor(exec, config);
-            const { hash, file, content, legacy } = await memo.read(args.commit_hash);
-            return { commit_hash: hash, file, content, ...(legacy ? { legacy: true } : {}) };
+            const { hash, file, content, kind, links, legacy } = await memo.read(args.commit_hash, {
+                expand: args.expand === true
+            });
+            return {
+                commit_hash: hash,
+                file,
+                content,
+                kind,
+                ...(links !== undefined ? { links } : {}),
+                ...(legacy ? { legacy: true } : {})
+            };
         },
         presentCall: (args) => ({
             card: "generic",
@@ -216,7 +295,7 @@ function registerMemTools(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: "mem_write",
-        description: "Store a completed task outcome in the gitmemo long-term memory (.mem git repo). Write ONLY when the task is complete AND repo-related AND the outcome is valuable/reusable OR the user explicitly asked to remember. Entries are immutable: title (single line, ≤200 chars, \"[module] action + object\"), summary (≤4000 chars), keywords (2-12, include 中英文同义词) and content (markdown body; the engine generates front matter) are all required; related_branches/related_paths are optional. Corrections use mem_replace, withdrawal uses mem_delete — never rewrite in place.",
+        description: "Store a completed task outcome in the gitmemo long-term memory (.mem git repo). Write ONLY when the task is complete AND repo-related AND the outcome is valuable/reusable OR the user explicitly asked to remember. Entries are immutable: title (single line, ≤200 chars, \"[module] action + object\"), summary (≤4000 chars), keywords (2-12, include 中英文同义词) and content (markdown body; the engine generates front matter) are all required; related_branches/related_paths are optional. kind selects the entry type: \"task\" (default) is a task-outcome record; \"topic\" is an aggregated topic page (MOC) — its summary states the currently-valid conclusions and its content links evidence entries as [[<commit-hash>]] with a one-line status each; a topic page evolves via mem_replace, not per-task rewrites. Keywords must ADD new search angles — pick task-related terms (中英文同义词 both fine) that are NOT already present in title/summary: words already in title/summary are searchable via those fields themselves, so repeating them does not improve recall. Corrections and superseded conclusions use mem_replace, withdrawal uses mem_delete — never rewrite in place.",
         parameters: {
             title: {
                 type: "string",
@@ -231,12 +310,16 @@ function registerMemTools(ctx, config) {
             keywords: {
                 ...KEYWORDS_ARRAY,
                 required: true,
-                description: "2-12 keywords (1-64 chars each); include 中英文同义词, e.g. [\"auth\", \"rate-limit\", \"登录\", \"限流\"]."
+                description: "2-12 keywords (1-64 chars each); task-related words NOT already present in title/summary (重复 title/summary 已有的词不会提高召回率); include 中英文同义词, e.g. [\"auth\", \"rate-limit\", \"登录\", \"限流\"]."
             },
             content: {
                 type: "string",
                 required: true,
-                description: "The memory markdown body (engine generates front matter and standard sections)."
+                description: "The memory markdown body (engine generates front matter and standard sections). Reference other entries as [[<commit-hash>]]."
+            },
+            kind: {
+                type: "string",
+                description: "Entry kind: \"task\" (default) or \"topic\" (aggregated topic page linking evidence entries via [[<commit-hash>]])."
             },
             related_branches: RELATED_BRANCHES,
             related_paths: RELATED_PATHS
@@ -265,7 +348,8 @@ function registerMemTools(ctx, config) {
                 keywords: args.keywords ?? [],
                 content: args.content ?? "",
                 related_branches: args.related_branches,
-                related_paths: args.related_paths
+                related_paths: args.related_paths,
+                kind: args.kind
             });
         },
         presentCall: (args) => ({
@@ -313,7 +397,7 @@ function registerMemTools(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: "mem_replace",
-        description: "Replace an active gitmemo memory entry with a new conclusion in ONE atomic commit (deletes the old entry file, adds the new one). Use when the user corrects a stored outcome — never delete-then-write. commit_hash must be the ACTIVE hash returned by mem_search; stale hashes are rejected. Takes the same fields as mem_write.",
+        description: "Replace an active gitmemo memory entry with a new conclusion in ONE atomic commit (deletes the old entry file, adds the new one). Use it whenever a stored conclusion is superseded — the user corrects a stored outcome, OR this session's own work overrules it (implemented/refactored away) — never delete-then-write. commit_hash must be the ACTIVE hash returned by mem_search; stale hashes are rejected. Takes the same fields as mem_write; kind defaults to the replaced entry's kind (refreshing a topic page stays a topic page).",
         parameters: {
             commit_hash: {
                 type: "string",
@@ -333,12 +417,16 @@ function registerMemTools(ctx, config) {
             keywords: {
                 ...KEYWORDS_ARRAY,
                 required: true,
-                description: "2-12 keywords (1-64 chars each); include 中英文同义词."
+                description: "2-12 keywords (1-64 chars each); task-related words NOT already present in title/summary; include 中英文同义词."
             },
             content: {
                 type: "string",
                 required: true,
-                description: "The new memory markdown body."
+                description: "The new memory markdown body. Keep [[<commit-hash>]] links to evidence entries up to date."
+            },
+            kind: {
+                type: "string",
+                description: "Entry kind: \"task\" or \"topic\". Defaults to the replaced entry's kind when omitted."
             },
             related_branches: RELATED_BRANCHES,
             related_paths: RELATED_PATHS
@@ -364,7 +452,8 @@ function registerMemTools(ctx, config) {
                 keywords: args.keywords ?? [],
                 content: args.content ?? "",
                 related_branches: args.related_branches,
-                related_paths: args.related_paths
+                related_paths: args.related_paths,
+                kind: args.kind
             });
         },
         presentCall: (args) => ({
@@ -384,9 +473,12 @@ function registerPromptSection(ctx) {
         text: [
             "This deployment provides gitmemo long-term memory: a local .mem git repository at the project root stores past task outcomes as immutable markdown entries; git is the only dependency. Use the dedicated tools only (mem_search / mem_read / mem_write / mem_delete / mem_replace — all auto-initialize, and legacy-format .mem repos migrate automatically on first use); never shell out to git or read .mem files directly.",
             "- BEFORE WORK — search: 仓库相关任务开始前提取 1–12 个中英文关键词调用 mem_search（含中英文同义词）；纯闲聊和通用问答无需搜索。",
-            "- RESULT PRESELECT — 根据 title、summary、keywords、score 和 matched keywords 选择最多 5 条执行 mem_read，复用相关结论；无相关结果时用返回的 snapshot + skip 翻页。",
+            "- RESULT PRESELECT — 根据 title、summary、keywords、score 和 matched keywords 选择最多 5 条执行 mem_read，复用相关结论；kind 为 topic 的条目是该主题的聚合入口，优先读；无相关结果时用返回的 snapshot + skip 翻页。",
             "- END-OF-SESSION CHECKPOINT — the ONLY write path: 会话结束时回顾全程，仅当结论有价值、可复用或用户明确要求记住时 mem_write；纯问答、未完成任务、非仓库工作、纯操作类 git 动作（仅 commit/push）不写；避免语义重复。",
-            "- USER CORRECTION — 用户更正已有结论：有替代结论时调用 mem_replace（不得先 delete 再 write）；结论作废且无替代时调用带 reason 的 mem_delete。",
+            "- KEYWORD SELECTION — mem_write/mem_replace 的 keywords 应选择与任务相关但未出现在 title/summary 中的词（中英文同义词皆可）；title/summary 里已有的词本身就能被检索到，重复它们不会提高召回率。",
+            "- KEEP FRESH — 结论保鲜是写路径的一部分，不必等用户指出：用户更正旧结论时，有替代结论用 mem_replace（禁止先 delete 再 write），作废且无替代用带 reason 的 mem_delete；本次会话的工作覆盖/推翻了某条已存结论（被后续实现、重构取代）时，同样主动 mem_replace 或 mem_delete 对应旧条目；检索结果中新旧结论冲突时，优先采信 score 更高/日期更新的条目（score 已含温和的 recency 加成）。",
+            "- TOPIC PAGE — 同一主题已积累多条记忆、或需要一个「当前真相」入口时，用 mem_write 写一条 kind:\"topic\" 聚合条目：summary 概括当下仍然有效的结论，content 用 [[<commit-hash>]] 链接各证据条目并各配一句话状态；topic 条目靠 mem_replace 演进（kind 自动继承），不是按任务新增。",
+            "- WIKI LINKS — content 中引用其他记忆条目一律写 [[<commit-hash>]]（用 mem_search/mem_read 返回的 hash）；mem_read 传 expand:true 会把链接一跳展开到各条目的最新版本（悬空链接以 error 返回），读 topic 条目时建议展开。",
             "- SUBAGENT RESULTS — 子代理结果由根 Agent 汇总后决定是否形成一条会话级记忆。"
         ].join("\n")
     });

package/lib/mem.d.ts

@@ -35,6 +35,14 @@ export interface SearchHit {
     date: string;
     summary: string;
     keywords: string[];
+    /** Entry kind: `task` (task-outcome record) or `topic` (aggregated topic page). */
+    kind: "task" | "topic";
+    /**
+     * Relevance = distinct matched keywords + a mild recency bonus (at most
+     * +0.5, linearly decaying to 0 between 30 and 180 days of age). The bonus
+     * never outweighs an extra matched keyword, so it only reorders entries
+     * with equal match counts.
+     */
     score: number;
     matched_keywords: string[];
 }
@@ -65,6 +73,12 @@ export interface WriteInput {
     content: string;
     related_branches?: string[];
     related_paths?: string[];
+    /**
+     * Entry kind. `task` (default) is a task-outcome record; `topic` is an
+     * aggregated topic page (MOC) whose content links evidence entries via
+     * `[[<commit-hash>]]` and is evolved with mem_replace, not rewritten per task.
+     */
+    kind?: "task" | "topic";
 }
 /** One-version compatibility shape accepted by the engine, not model-facing tools. */
 export interface LegacyWriteInput {
@@ -85,11 +99,41 @@ export interface WriteResult {
     file: string;
     legacy?: boolean;
 }
+/** Options for {@link GitMemo.read}. */
+export interface ReadOptions {
+    /**
+     * Resolve `[[<commit-hash>]]` links found in the entry content one hop to
+     * their target entries. Link targets automatically follow forward to the
+     * ACTIVE version of the linked entry file, so a topic page link survives
+     * its targets being replaced; the original link hash stays recorded.
+     */
+    expand?: boolean;
+}
+/** One-hop resolution of a `[[<commit-hash>]]` link inside an entry. */
+export interface LinkedEntryResolution {
+    /** Hash exactly as written inside the [[...]] link (lowercased). */
+    link_hash: string;
+    /** Hash actually read: the active version of the linked entry file ("" when unresolvable). */
+    resolved_hash: string;
+    /** True when the link hash still IS the active version (false = superseded or dangling). */
+    active: boolean;
+    file?: string;
+    title?: string;
+    summary?: string;
+    keywords?: string[];
+    kind?: "task" | "topic";
+    /** Present instead of title/summary when the link target cannot be resolved. */
+    error?: string;
+}
 export interface ReadResult {
     hash: string;
     file: string;
     content: string;
+    /** Entry kind parsed from the create/replace commit (legacy entries read as "task"). */
+    kind: "task" | "topic";
     legacy?: boolean;
+    /** Present only when the read was requested with `expand: true`. */
+    links?: LinkedEntryResolution[];
 }
 export interface DeleteInput {
     commit_hash: string;
@@ -104,6 +148,8 @@ export interface ParsedCommitMessage {
     summary: string;
     type: "add" | "replace" | "delete" | "unknown";
     keywords: string[];
+    /** Entry kind from the `GitMemo-Kind` trailer; absence means "task". */
+    kind: "task" | "topic";
     digest?: string;
     deletes?: string;
     replaces?: string;
@@ -176,6 +222,7 @@ export interface ValidatedWriteInput {
     content: string;
     related_branches: string[];
     related_paths: string[];
+    kind: "task" | "topic";
 }
 /**
  * Validate a write/replace payload (plan 5.3). `legacy` relaxes the keyword
@@ -190,7 +237,7 @@ export declare function validateWriteInput(input: WriteInput, legacy?: boolean):
  * an exact duplicate because of when/where it was written, and a withdrawn
  * conclusion can be re-written later.
  */
-export declare function computeDigest(title: string, summary: string, keywords: string[], content: string): string;
+export declare function computeDigest(title: string, summary: string, keywords: string[], content: string, kind?: "task" | "topic"): string;
 /** UTC millisecond timestamp for filenames: `20260823T113612.123Z`. */
 export declare function utcMs(date: Date): string;
 /** ISO date for a committer timestamp; falls back to the epoch for out-of-range values. */
@@ -205,18 +252,30 @@ export declare function createEntryFile(memDir: string, baseName: string, conten
 export declare function buildEntryMarkdown(input: ValidatedWriteInput, ctx: CodeContext & {
     relatedBranches: string[];
 }, digest: string, date: Date): string;
+/**
+ * Recency bonus for search scoring: +0.5 for entries at most 30 days old,
+ * linearly decaying to 0 at 180 days, 0 beyond. Bounded below one whole
+ * matched keyword, so freshness only reorders equal-match entries.
+ */
+export declare function recencyBonus(committerTime: number, nowMs?: number): number;
 /** ADD commit message (plan 4.1). */
-export declare function buildAddMessage(title: string, summary: string, keywords: string[], digest: string, legacy?: boolean): string;
+export declare function buildAddMessage(title: string, summary: string, keywords: string[], digest: string, legacy?: boolean, kind?: "task" | "topic"): string;
 /** DELETE commit message (plan 4.2). */
 export declare function buildDeleteMessage(entryName: string, reason: string, deletesHash: string): string;
 /** REPLACE commit message (plan 4.3). */
-export declare function buildReplaceMessage(title: string, summary: string, keywords: string[], digest: string, replacesHash: string): string;
+export declare function buildReplaceMessage(title: string, summary: string, keywords: string[], digest: string, replacesHash: string, kind?: "task" | "topic"): string;
 /**
  * Parse a commit message into logical search fields. The trailer block is the
  * contiguous run at the end; everything between subject and the block is the
  * summary. Malformed input degrades to `type: "unknown"` (legacy commits).
  */
 export declare function parseCommitMessage(raw: string): ParsedCommitMessage;
+/**
+ * Extract unique `[[<commit-hash>]]` wiki links from an entry body, in order
+ * of first appearance, capped at 32 per entry. Anything that is not a plain
+ * hex hash inside double brackets is ignored.
+ */
+export declare function extractEntryLinks(content: string): string[];
 /**
  * Parse the NUL-delimited log stream
  * (`--format=%x00%H%x00%ct%x00%s%x00%B%x00 --name-status --no-renames`).
@@ -299,9 +358,20 @@ export declare class GitMemo {
     /**
      * Read one memory entry by create/replace commit hash. Historical entries
      * (deleted or replaced) stay readable for audit; `mem_read` accepts legacy
-     * hashes too.
+     * hashes too. With `options.expand`, `[[<commit-hash>]]` links in the entry
+     * body are resolved one hop to their target entries (each target follows
+     * forward to the active version of its entry file).
+     */
+    read(commitHash: string, options?: ReadOptions): Promise<ReadResult>;
+    /**
+     * One-hop resolution of `[[<commit-hash>]]` links (caller must hold the
+     * operation lock). A link whose entry was later REPLACED is followed
+     * forward along the `GitMemo-Replaces` chain to the active version, so a
+     * topic page's links survive their targets being refreshed; withdrawn or
+     * dangling links come back with `active: false` (plus an `error` field
+     * when the link hash cannot be resolved at all).
      */
-    read(commitHash: string): Promise<ReadResult>;
+    private resolveEntryLinks;
     /**
      * Write a memory entry (plan 5.3). Entries are immutable: each write
      * creates a brand-new file `entries/<utc-ms>-<digest-prefix>-<slug>.md`

package/lib/mem.js

@@ -8,8 +8,8 @@
  *    ADD commit; corrections use `replace` (one commit deleting the old file
  *    and adding the new one), withdrawal uses `delete`.
  *  - Commit messages are structured: subject = title, body = summary, then a
- *    contiguous trailer block (`GitMemo-Type/Keyword/Digest/Deletes/Replaces/
- *    Search-Text/Legacy`). Search only reads commit messages via
+ *    contiguous trailer block (`GitMemo-Type/Kind/Keyword/Digest/Deletes/
+ *    Replaces/Search-Text/Legacy`). Search only reads commit messages via
  *    `git log --grep --fixed-strings`; entry bodies are never scanned.
  *  - All state transitions (init/write/delete/replace/migrate) run under a
  *    cross-process lock (sibling lock file + in-process mutex) with a short
@@ -306,7 +306,10 @@ export function validateWriteInput(input, legacy = false) {
         }
         related_paths = dedupe(related_paths);
     }
-    return { title, summary, keywords, content, related_branches, related_paths };
+    if (input.kind !== undefined && input.kind !== "task" && input.kind !== "topic") {
+        throw new GitMemoError('gitmemo: kind must be "task" or "topic"');
+    }
+    return { title, summary, keywords, content, related_branches, related_paths, kind: input.kind ?? "task" };
 }
 async function adaptLegacyWriteInput(input) {
     const legacyInput = input;
@@ -342,9 +345,9 @@ async function adaptLegacyWriteInput(input) {
  * an exact duplicate because of when/where it was written, and a withdrawn
  * conclusion can be re-written later.
  */
-export function computeDigest(title, summary, keywords, content) {
+export function computeDigest(title, summary, keywords, content, kind = "task") {
     const normalizedKeywords = [...new Set(keywords.map((k) => normalizeKeyword(k)))].sort();
-    const payload = JSON.stringify({ title, summary, keywords: normalizedKeywords, content });
+    const payload = JSON.stringify({ title, summary, keywords: normalizedKeywords, content, kind });
     return createHash("sha256").update(payload, "utf8").digest("hex");
 }
 /** UTC millisecond timestamp for filenames: `20260823T113612.123Z`. */
@@ -455,6 +458,7 @@ export function buildEntryMarkdown(input, ctx, digest, date) {
         "---",
         "gitmemo_version: " + yamlJson(GITMEMO_FORMAT_VERSION),
         "date: " + yamlJson(date.toISOString()),
+        "kind: " + yamlJson(input.kind),
         "code_branch: " + yamlJson(ctx.branch),
         "code_commit: " + yamlJson(ctx.commit),
         "related_branches: " + yamlArray(ctx.relatedBranches),
@@ -478,9 +482,26 @@ export function buildEntryMarkdown(input, ctx, digest, date) {
 function searchTexts(title, summary, keywords) {
     return [normalizeText(title), normalizeText(summary.replace(/\s+/g, " ")), ...keywords.map((k) => normalizeText(k))];
 }
+/**
+ * Recency bonus for search scoring: +0.5 for entries at most 30 days old,
+ * linearly decaying to 0 at 180 days, 0 beyond. Bounded below one whole
+ * matched keyword, so freshness only reorders equal-match entries.
+ */
+export function recencyBonus(committerTime, nowMs = Date.now()) {
+    const ageDays = Math.max(0, (nowMs / 1000 - committerTime) / 86400);
+    if (ageDays <= 30)
+        return 0.5;
+    if (ageDays >= 180)
+        return 0;
+    return Math.round(((0.5 * (180 - ageDays)) / 150) * 100) / 100;
+}
+/** Commit trailer emitted only for topic pages (absence means "task"). */
+const KIND_TRAILER_TOPIC = "GitMemo-Kind: topic";
 /** ADD commit message (plan 4.1). */
-export function buildAddMessage(title, summary, keywords, digest, legacy = false) {
+export function buildAddMessage(title, summary, keywords, digest, legacy = false, kind = "task") {
     const lines = [title, "", summary, "", "GitMemo-Type: add"];
+    if (kind === "topic")
+        lines.push(KIND_TRAILER_TOPIC);
     if (legacy)
         lines.push("GitMemo-Legacy: true");
     for (const kw of keywords)
@@ -502,8 +523,10 @@ export function buildDeleteMessage(entryName, reason, deletesHash) {
     ].join("\n") + "\n";
 }
 /** REPLACE commit message (plan 4.3). */
-export function buildReplaceMessage(title, summary, keywords, digest, replacesHash) {
+export function buildReplaceMessage(title, summary, keywords, digest, replacesHash, kind = "task") {
     const lines = [title, "", summary, "", "GitMemo-Type: replace", "GitMemo-Replaces: " + replacesHash];
+    if (kind === "topic")
+        lines.push(KIND_TRAILER_TOPIC);
     for (const kw of keywords)
         lines.push("GitMemo-Keyword: " + kw);
     lines.push("GitMemo-Digest: sha256:" + digest);
@@ -553,12 +576,32 @@ export function parseCommitMessage(raw) {
         summary,
         type,
         keywords: trailers.get("Keyword") ?? [],
+        kind: trailers.get("Kind")?.[0] === "topic" ? "topic" : "task",
         digest: trailers.get("Digest")?.[0]?.replace(/^sha256:/, "") || undefined,
         deletes: trailers.get("Deletes")?.[0] || undefined,
         replaces: trailers.get("Replaces")?.[0] || undefined,
         legacy: trailers.get("Legacy")?.[0] === "true"
     };
 }
+/**
+ * Extract unique `[[<commit-hash>]]` wiki links from an entry body, in order
+ * of first appearance, capped at 32 per entry. Anything that is not a plain
+ * hex hash inside double brackets is ignored.
+ */
+export function extractEntryLinks(content) {
+    const links = [];
+    const seen = new Set();
+    for (const match of content.matchAll(/\[\[([0-9a-fA-F]{7,64})\]\]/g)) {
+        const hash = match[1].toLowerCase();
+        if (seen.has(hash))
+            continue;
+        seen.add(hash);
+        links.push(hash);
+        if (links.length >= 32)
+            break;
+    }
+    return links;
+}
 // ---------------------------------------------------------------------------
 // git log parsing
 // ---------------------------------------------------------------------------
@@ -1339,6 +1382,7 @@ export class GitMemo {
         const hits = [];
         const diagnostics = [...(legacySnapshot?.diagnostics ?? [])];
         const seenFiles = new Set();
+        const nowMs = Date.now();
         for (const record of candidates) {
             if (record.added.length !== 1) {
                 if (record.added.length > 1)
@@ -1371,20 +1415,24 @@ export class GitMemo {
                 date: safeIsoDate(record.committerTime),
                 summary: record.message.summary,
                 keywords: record.message.keywords,
-                score: matched.length,
+                kind: record.message.kind,
+                score: Math.round((matched.length + recencyBonus(record.committerTime, nowMs)) * 100) / 100,
                 matched_keywords: matched
             });
         }
-        // plan 6.6: score desc, committer time desc, full hash desc (deterministic)
+        // plan 6.6: score desc (matches + mild recency bonus), committer time desc,
+        // full hash desc (deterministic)
         hits.sort((a, b) => b.score - a.score || b.date.localeCompare(a.date) || (a.hash < b.hash ? 1 : a.hash > b.hash ? -1 : 0));
         return { hits, diagnostics };
     }
     /**
      * Read one memory entry by create/replace commit hash. Historical entries
      * (deleted or replaced) stay readable for audit; `mem_read` accepts legacy
-     * hashes too.
+     * hashes too. With `options.expand`, `[[<commit-hash>]]` links in the entry
+     * body are resolved one hop to their target entries (each target follows
+     * forward to the active version of its entry file).
      */
-    async read(commitHash) {
+    async read(commitHash, options = {}) {
         if (!/^[0-9a-f]{7,64}$/.test(commitHash))
             throw new GitMemoError("gitmemo: read requires a commit hash");
         return withLock(this.root, this.config, "read", async () => {
@@ -1401,9 +1449,123 @@ export class GitMemo {
             const body = await git(this.memDir, ["log", "-1", "--format=%B", full], this.config.gitTimeoutMs);
             const message = parseCommitMessage(body);
             const legacy = message.type === "unknown";
-            return { hash: full, file: added[0], content, ...(legacy ? { legacy: true } : {}) };
+            const result = {
+                hash: full,
+                file: added[0],
+                content,
+                kind: message.kind,
+                ...(legacy ? { legacy: true } : {})
+            };
+            if (options.expand === true) {
+                result.links = await this.resolveEntryLinks(content);
+            }
+            return result;
         });
     }
+    /**
+     * One-hop resolution of `[[<commit-hash>]]` links (caller must hold the
+     * operation lock). A link whose entry was later REPLACED is followed
+     * forward along the `GitMemo-Replaces` chain to the active version, so a
+     * topic page's links survive their targets being refreshed; withdrawn or
+     * dangling links come back with `active: false` (plus an `error` field
+     * when the link hash cannot be resolved at all).
+     */
+    async resolveEntryLinks(content) {
+        const linkHashes = extractEntryLinks(content);
+        if (linkHashes.length === 0)
+            return [];
+        let snapshot = "";
+        try {
+            snapshot = (await git(this.memDir, ["rev-parse", "--verify", "refs/heads/main^{commit}"], this.config.gitTimeoutMs)).trim();
+        }
+        catch {
+            try {
+                snapshot = (await git(this.memDir, ["rev-parse", "--verify", "HEAD^{commit}"], this.config.gitTimeoutMs)).trim();
+            }
+            catch {
+                snapshot = "";
+            }
+        }
+        const resolutions = [];
+        for (const link of linkHashes) {
+            try {
+                const full = await resolveCommit(this.memDir, link, this.config.gitTimeoutMs);
+                const added = await addedFilesOf(this.memDir, full, this.config.gitTimeoutMs);
+                if (added.length !== 1) {
+                    resolutions.push({
+                        link_hash: link,
+                        resolved_hash: full,
+                        active: false,
+                        error: `commit ${link} maps to ${added.length} entry files — cannot resolve a single entry`
+                    });
+                    continue;
+                }
+                const activeHash = snapshot.length > 0
+                    ? (await git(this.memDir, ["log", "-1", "--format=%H", snapshot, "--", added[0]], this.config.gitTimeoutMs)).trim()
+                    : "";
+                let resolved = full;
+                let resolvedFile = added[0];
+                let isActive = activeHash === full;
+                if (!isActive) {
+                    // The linked entry is not the active version of its file — either
+                    // replaced (the last commit touching the old file is its replace
+                    // commit, or the file is gone from the active tree entirely) or
+                    // withdrawn. Follow the GitMemo-Replaces chain forward to the
+                    // active successor; when there is none the chain ends at the link.
+                    for (let hop = 0; hop < 16; hop += 1) {
+                        const successorOut = await git(this.memDir, [
+                            "log",
+                            ...(snapshot.length > 0 ? [snapshot] : []),
+                            "--fixed-strings",
+                            "--grep=GitMemo-Replaces: " + resolved,
+                            "--format=%H"
+                        ], this.config.gitTimeoutMs).catch(() => "");
+                        const successors = successorOut.split("\n").map((h) => h.trim()).filter((h) => COMMIT_RE.test(h));
+                        let next = null;
+                        for (const candidate of successors) {
+                            const candidateFiles = await addedFilesOf(this.memDir, candidate, this.config.gitTimeoutMs);
+                            if (candidateFiles.length !== 1)
+                                continue;
+                            const candidateActive = snapshot.length > 0
+                                ? (await git(this.memDir, ["log", "-1", "--format=%H", snapshot, "--", candidateFiles[0]], this.config.gitTimeoutMs)).trim()
+                                : "";
+                            if (candidateActive === candidate) {
+                                next = { hash: candidate, file: candidateFiles[0] };
+                                break;
+                            }
+                        }
+                        if (next === null)
+                            break;
+                        resolved = next.hash;
+                        resolvedFile = next.file;
+                        // isActive stays false: the LINK hash is not the active version —
+                        // only resolved_hash carries it (the "superseded" case).
+                    }
+                }
+                const body = await git(this.memDir, ["log", "-1", "--format=%B", resolved], this.config.gitTimeoutMs);
+                const message = parseCommitMessage(body);
+                resolutions.push({
+                    link_hash: link,
+                    resolved_hash: resolved,
+                    active: isActive,
+                    file: resolvedFile,
+                    title: message.subject,
+                    summary: message.summary,
+                    keywords: message.keywords,
+                    kind: message.kind
+                });
+            }
+            catch (error) {
+                resolutions.push({
+                    link_hash: link,
+                    resolved_hash: "",
+                    active: false,
+                    error: String(error instanceof GitMemoError ? error.message : error).replace(/^gitmemo: /, "")
+                });
+            }
+        }
+        return resolutions;
+    }
     /**
      * Write a memory entry (plan 5.3). Entries are immutable: each write
      * creates a brand-new file `entries/<utc-ms>-<digest-prefix>-<slug>.md`
@@ -1413,7 +1575,7 @@ export class GitMemo {
     async write(input, legacy = false) {
         const adapted = legacy ? await adaptLegacyWriteInput(input) : input;
         const validated = validateWriteInput(adapted, legacy);
-        const digest = computeDigest(validated.title, validated.summary, validated.keywords, validated.content);
+        const digest = computeDigest(validated.title, validated.summary, validated.keywords, validated.content, validated.kind);
         return withLock(this.root, this.config, "write", async () => {
             await this.ensureWritable();
             await recoverJournal(this.memDir, this.config.gitTimeoutMs);
@@ -1445,7 +1607,7 @@ export class GitMemo {
             try {
                 await git(this.memDir, ["add", "--", file], this.config.gitTimeoutMs);
                 await assertStagedExactly(this.memDir, [{ status: "A", path: file }], this.config.gitTimeoutMs);
-                const hash = await commitWithIdentity(this.memDir, buildAddMessage(validated.title, validated.summary, validated.keywords, digest, legacy), this.config.gitTimeoutMs);
+                const hash = await commitWithIdentity(this.memDir, buildAddMessage(validated.title, validated.summary, validated.keywords, digest, legacy, validated.kind), this.config.gitTimeoutMs);
                 await rm(journalPath(this.memDir), { force: true });
                 return { hash, file, ...(legacy ? { legacy: true } : {}) };
             }
@@ -1519,8 +1681,6 @@ export class GitMemo {
      * legal; colliding with any OTHER active entry is rejected.
      */
     async replace(input) {
-        const validated = validateWriteInput(input);
-        const digest = computeDigest(validated.title, validated.summary, validated.keywords, validated.content);
         return withLock(this.root, this.config, "replace", async () => {
             await this.ensureWritable();
             await recoverJournal(this.memDir, this.config.gitTimeoutMs);
@@ -1529,7 +1689,11 @@ export class GitMemo {
             const ctx = await codeContext(this.root, this.config.gitTimeoutMs);
             const baseHead = (await git(this.memDir, ["rev-parse", "HEAD"], this.config.gitTimeoutMs)).trim();
             const full = await resolveCommit(this.memDir, input.commit_hash, this.config.gitTimeoutMs);
-            const { file: oldFile } = await activeEntryForHash(this.memDir, full, baseHead, this.config.gitTimeoutMs);
+            const { file: oldFile, message: oldMessage } = await activeEntryForHash(this.memDir, full, baseHead, this.config.gitTimeoutMs);
+            // kind inherits the replaced entry's kind unless explicitly overridden,
+            // so refreshing a topic page never silently demotes it to a task record.
+            const validated = validateWriteInput({ ...input, kind: input.kind ?? oldMessage.kind });
+            const digest = computeDigest(validated.title, validated.summary, validated.keywords, validated.content, validated.kind);
             const { active, records, claimed } = await activeSnapshot(this.memDir, baseHead, this.config.gitTimeoutMs);
             void active;
             for (const [file, entry] of claimed) {
@@ -1560,7 +1724,7 @@ export class GitMemo {
                     { status: "D", path: oldFile },
                     { status: "A", path: newFile }
                 ], this.config.gitTimeoutMs);
-                const hash = await commitWithIdentity(this.memDir, buildReplaceMessage(validated.title, validated.summary, validated.keywords, digest, full), this.config.gitTimeoutMs);
+                const hash = await commitWithIdentity(this.memDir, buildReplaceMessage(validated.title, validated.summary, validated.keywords, digest, full, validated.kind), this.config.gitTimeoutMs);
                 await rm(journalPath(this.memDir), { force: true });
                 return { hash, file: newFile };
             }

package/lib/migrate.js

@@ -490,7 +490,8 @@ async function migrateApplyUnlocked(root, baseline, options = {}) {
                 keywords: entry.keywords,
                 content: entry.content,
                 related_branches: entry.relatedBranches,
-                related_paths: entry.relatedPaths
+                related_paths: entry.relatedPaths,
+                kind: "task"
             }, { branch: entry.codeBranch, commit: entry.codeCommit, relatedBranches: entry.relatedBranches }, entry.digest, entryDate);
             const file = await createEntryFile(tmp, baseName, markdown);
             await git(tmp, ["add", "--", file], gitTimeoutMs);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fonlan/dsh-gitmemo",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Git-backed long-term memory for DeepSeek Harness: a local .mem git repo (single main branch, immutable entries, structured commit messages) with mem_search / mem_read / mem_write / mem_delete / mem_replace tools and fully automatic legacy migration (no CLI needed; the CLI remains for explicit control), auto-managed by the root agent with zero manual steps.",
   "author": "fonlan",
   "publishConfig": {
@@ -49,8 +49,8 @@
     "release:major": "npm version major && git push && git push --tags"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.7",
-    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.2",
+    "@deepseek-ai/schemastery": "^3.18.2",
     "@types/node": "^26.2.0",
     "typescript": "^5.5.0"
   },