pi-okf-memory 0.1.0

package/lib/index.js

@@ -0,0 +1,381 @@
+import { TYPE_VOCAB } from "./concept.js";
+import { defaultRoot, ensureRoot, readConcept, scanBundle, writeConcept } from "./store.js";
+import { search } from "./dedupe.js";
+import { consolidate, loadMeta, rank, startConsolidation } from "./learning.js";
+import { preload, recall } from "./recall.js";
+import { MEMORY_DISCIPLINE, RECALL_GUIDE } from "./capture.js";
+import { buildGraph } from "./graph.js";
+import { forgetCore, rememberCore } from "./memory.js";
+import path from "node:path";
+import { promises } from "node:fs";
+//#region src/server/index.ts
+/**
+* okf-memory — 会话记忆 → OKF 知识沉淀:dsh 适配层(src/server/index.ts)。
+* pi 侧入口见 src/pi/index.ts;两者共用本目录下的运行时无关核心。
+*
+* 工具:okf_remember / okf_search / okf_read / okf_forget / okf_graph
+* 服务:ctx.okfMemory(root, search, read, write, consolidate, meta, preload, graph)
+* 记忆库:OKF v0.1 bundle,默认 ~/.dsh/memory/(环境变量 OKF_MEMORY_ROOT 可覆盖)
+*/
+/**
+* defineTool 动态解析:dsh 运行时提供 @deepseek-ai/dsh-tools 时用官方 API,
+* 不可用时降级为透传定义对象(兼容运行时不暴露该包的情况)。
+*/
+async function loadDefineTool() {
+	try {
+		return (await import("@deepseek-ai/dsh-tools")).defineTool || ((def) => def);
+	} catch {
+		return (def) => def;
+	}
+}
+const name = "okf-memory";
+const inject = ["tools", "systemPrompt"];
+/** 解析记忆库根目录(优先级:settings > env > 默认) */
+function resolveRoot(ctx) {
+	try {
+		const s = ctx.settings?.okfMemory?.root;
+		if (s) return path.resolve(String(s));
+	} catch {}
+	return defaultRoot();
+}
+/**
+* 注入系统提示片段(正确 API:dsh-system-prompt 的 section,字段 name/order/text。
+* 之前误用 add() 静默失效;不能用 register()。失败时静默跳过,不阻塞插件加载)。
+*/
+function addPrompt(ctx, name, content, order) {
+	try {
+		if (ctx.systemPrompt?.section) ctx.systemPrompt.section({
+			name,
+			order,
+			text: content
+		});
+	} catch {}
+}
+/** 把根 index.md 摘要整理成提示片段(模型每轮可见"库里有啥") */
+async function buildIndexPrompt(root) {
+	try {
+		const text = await promises.readFile(path.join(root, "index.md"), "utf8");
+		return `记忆库共有 ${(await scanBundle(root)).length} 个概念(路径即概念 ID)。库目录:\n${text.slice(0, 3e3)}`;
+	} catch {
+		return "OKF 记忆库为空或不可读。";
+	}
+}
+async function apply(ctx) {
+	const defineTool = await loadDefineTool();
+	const root = resolveRoot(ctx);
+	await ensureRoot(root);
+	const service = {
+		root,
+		search: (q, opts) => search(root, q, opts),
+		read: (id) => recall(root, id),
+		write: (meta, body) => writeConcept(root, meta, body),
+		remember: (meta, body, opts) => rememberCore(root, meta, body, opts),
+		consolidate: () => consolidate(root),
+		meta: () => loadMeta(root),
+		preload: (query, opts) => preload(root, query, opts),
+		graph: (opts) => buildGraph(root, opts)
+	};
+	try {
+		ctx.provide?.("okfMemory", service);
+	} catch {
+		ctx.okfMemory = service;
+	}
+	ctx.okfMemory = service;
+	if (typeof ctx.inject === "function") ctx.inject(["webServer"], (scope) => {
+		try {
+			scope.webServer.register({
+				name: "okf-memory-graph",
+				kind: "exact",
+				path: "/okf-graph",
+				handler: async (_req, res) => {
+					try {
+						const g = await buildGraph(root);
+						res.writeHead(200, { "content-type": "application/json" });
+						res.end(JSON.stringify(g));
+					} catch (e) {
+						res.writeHead(500, { "content-type": "application/json" });
+						res.end(JSON.stringify({ error: String(e.message || e) }));
+					}
+				}
+			});
+		} catch {}
+	});
+	ctx.tools.register(defineTool({
+		name: "okf_remember",
+		description: "把一条新知识按 OKF v0.1 规范写入长期记忆库(概念文档 + index/log 更新)。type 词表:Fact/Preference/Decision/Method/Insight/Idea/Lesson/TechChoice。Decision/Insight 正文建议用 # 数据/# 分析/# 结论 三段式;TechChoice 用 # Options 候选表 + # Active。写入前自动去重:标题相同则更新/跳过,相近则返回建议。Write a new piece of knowledge into the long-term memory library as an OKF v0.1 concept (updates index/log). Types: Fact/Preference/Decision/Method/Insight/Idea/Lesson/TechChoice. Deduplicates automatically: same title → update or skip; similar → returns suggestion.",
+		parameters: {
+			title: {
+				type: "string",
+				required: true,
+				description: "概念标题(简洁,一句话可懂)"
+			},
+			type: {
+				type: "string",
+				required: true,
+				description: `概念类型,可选:${TYPE_VOCAB.join("/")}`
+			},
+			content: {
+				type: "string",
+				required: true,
+				description: "结构化正文(Markdown,含 # 小节标题)。Decision/Insight 传三段式;TechChoice 传 Options 表与 Active"
+			},
+			tags: {
+				type: "array",
+				items: { type: "string" },
+				description: "横切标签"
+			},
+			related: {
+				type: "array",
+				items: { type: "string" },
+				description: "相关概念 ID 列表(将互建交叉链接)"
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: true,
+				properties: {
+					status: { type: "string" },
+					conceptId: { type: "string" },
+					filePath: { type: "string" },
+					reason: { type: "string" }
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.status === "error" ? `记忆写入失败:${value.reason}` : value.status === "created" ? `已沉淀记忆 ${value.conceptId}` : value.status === "updated" ? `已更新记忆 ${value.conceptId}` : value.status === "skipped" ? `跳过写入:${value.reason}` : `记忆写入:${value.status}`
+			}]
+		},
+		async execute(args) {
+			try {
+				return await rememberCore(root, {
+					title: args.title,
+					type: args.type,
+					tags: args.tags,
+					related: args.related
+				}, args.content);
+			} catch (e) {
+				return {
+					status: "error",
+					conceptId: null,
+					reason: String(e.message || e)
+				};
+			}
+		}
+	}));
+	ctx.tools.register(defineTool({
+		name: "okf_search",
+		description: "检索 OKF 长期记忆库,按唤起评分(相关度×权重×近因)排序返回概念摘要。命中 TechChoice 类型时附加返回完整 Options 候选表,供技术选型三档规则展示。写入新记忆前必须先搜索去重。Search the OKF long-term memory library, returning concept summaries ranked by recall score (relevance × weight × recency). TechChoice hits additionally return the full Options table. Always search before writing new memory.",
+		parameters: {
+			query: {
+				type: "string",
+				required: true,
+				description: "检索关键词"
+			},
+			type: {
+				type: "string",
+				description: "按类型过滤(如 TechChoice/Fact/Decision)"
+			},
+			tags: {
+				type: "array",
+				items: { type: "string" },
+				description: "按标签过滤"
+			},
+			limit: {
+				type: "number",
+				description: "返回条数,默认 8"
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: true,
+				properties: {
+					count: { type: "number" },
+					results: {
+						type: "array",
+						items: {
+							type: "object",
+							additionalProperties: true
+						}
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.count === 0 ? "记忆库无匹配。" : `检索到 ${value.count} 条记忆:\n` + value.results.map((r) => `- ${r.conceptId} (${r.type}, 权重 ${r.weight}) ${r.description}`).join("\n")
+			}]
+		},
+		async execute(args) {
+			const raw = await search(root, args.query, {
+				type: args.type,
+				tags: args.tags,
+				limit: Math.min(args.limit || 8, 30)
+			});
+			const ranked = await rank(root, raw);
+			const results = [];
+			for (const h of ranked) {
+				const item = { ...h };
+				if (h.type === "TechChoice") try {
+					const { body } = await readConcept(root, h.conceptId);
+					const optsMatch = /## Options[\s\S]*?(?=## |$)/.exec(body || "");
+					item.options = optsMatch ? optsMatch[0].trim() : null;
+				} catch {}
+				results.push(item);
+			}
+			return {
+				count: results.length,
+				results
+			};
+		}
+	}));
+	ctx.tools.register(defineTool({
+		name: "okf_read",
+		description: "读取记忆库中某个概念全文(含交叉链接),并记录一次使用反馈(权重更新)。Read a full concept from the memory library (with cross-links) and record one usage feedback (weight update).",
+		parameters: { concept_id: {
+			type: "string",
+			required: true,
+			description: "概念 ID(如 facts/meituan-data-source,可省略 .md)"
+		} },
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: true,
+				properties: {
+					conceptId: { type: "string" },
+					title: { type: "string" },
+					type: { type: "string" },
+					body: { type: "string" },
+					links: {
+						type: "array",
+						items: {
+							type: "object",
+							additionalProperties: true
+						}
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: `# ${value.title} (${value.type})\n\n${value.body}`
+			}]
+		},
+		async execute(args) {
+			const id = String(args.concept_id).replace(/\.md$/, "");
+			const concept = await recall(root, id);
+			return {
+				conceptId: concept.conceptId,
+				title: concept.meta?.title || id,
+				type: concept.meta?.type || "",
+				body: concept.body || "",
+				links: concept.links || []
+			};
+		}
+	}));
+	ctx.tools.register(defineTool({
+		name: "okf_graph",
+		description: "导出记忆库的图谱 JSON:nodes(概念:title/type/tags/weight/state)+edges(交叉链接)+timeline(权重历史)。供图谱可视化前端渲染,契约稳定。Export the memory graph JSON: nodes (concepts: title/type/tags/weight/state) + edges (cross-links) + timeline (weight history).",
+		parameters: { limit: {
+			type: "number",
+			description: "可选:节点上限,默认全部"
+		} },
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: true,
+				properties: {
+					meta: {
+						type: "object",
+						additionalProperties: true
+					},
+					nodes: {
+						type: "array",
+						items: {
+							type: "object",
+							additionalProperties: true
+						}
+					},
+					edges: {
+						type: "array",
+						items: {
+							type: "object",
+							additionalProperties: true
+						}
+					},
+					timeline: {
+						type: "array",
+						items: {
+							type: "object",
+							additionalProperties: true
+						}
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: `记忆图谱:${value.nodes?.length || 0} 节点 · ${value.edges?.length || 0} 边 · ${value.timeline?.length || 0} 权重历史`
+			}]
+		},
+		async execute(args) {
+			const g = await buildGraph(root);
+			if (args.limit && args.limit > 0) g.nodes = g.nodes.slice(0, Math.min(args.limit, 500));
+			return {
+				meta: g.meta,
+				nodes: g.nodes,
+				edges: g.edges,
+				timeline: g.timeline
+			};
+		}
+	}));
+	ctx.tools.register(defineTool({
+		name: "okf_forget",
+		description: "从记忆库索引撤回一条概念(默认保留文件,可从 index/log 追溯;可选删除文件)。Withdraw a concept from the memory library index (keeps the file by default, traceable via index/log; optionally deletes the file).",
+		parameters: {
+			concept_id: {
+				type: "string",
+				required: true,
+				description: "概念 ID"
+			},
+			delete_file: {
+				type: "boolean",
+				description: "true 时同时删除文件(默认 false 仅移出索引)"
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: true,
+				properties: {
+					status: { type: "string" },
+					conceptId: { type: "string" },
+					reason: { type: "string" }
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.status === "forgotten" ? `已撤回记忆 ${value.conceptId}${value.reason ? `(${value.reason})` : ""}` : value.status === "not_found" ? `记忆 ${value.conceptId} 不存在或已撤回` : `撤回失败:${value.reason || value.status}`
+			}]
+		},
+		async execute(args) {
+			const id = String(args.concept_id).replace(/\.md$/, "");
+			try {
+				return await forgetCore(root, id, args.delete_file === true);
+			} catch (e) {
+				return {
+					status: "error",
+					conceptId: id,
+					reason: String(e.message || e)
+				};
+			}
+		}
+	}));
+	addPrompt(ctx, "okf-memory-discipline", MEMORY_DISCIPLINE, 50);
+	addPrompt(ctx, "okf-memory-index", await buildIndexPrompt(root), 150);
+	addPrompt(ctx, "okf-memory-recall-guide", RECALL_GUIDE, 160);
+	const stopConsolidation = startConsolidation(root);
+	return () => {
+		stopConsolidation();
+	};
+}
+//#endregion
+export { apply, inject, name };

package/lib/learning.js

@@ -0,0 +1,185 @@
+import { withLock } from "./store.js";
+import path from "node:path";
+import { promises } from "node:fs";
+//#region src/server/learning.ts
+/**
+* learning.ts — 神经自我学习核心:记忆权重元数据、强化反馈回路、巩固与遗忘。
+* 唤起评分 = relevance × weight × recency_factor(相关度 × 历史权重 × 近因)。
+* 元数据存 <root>/.meta/weights.json(点目录,不影响 OKF 符合性)。
+*/
+/** 学习参数(起步默认值,可随使用校准) */
+const PARAMS = {
+	SELECT_DELTA: 1,
+	SKIP_DELTA: .5,
+	HIT_DELTA: .1,
+	MIN_WEIGHT: .05,
+	MAX_WEIGHT: 10,
+	DECAY_DAYS: 30,
+	DECAY_FACTOR: .9,
+	MAX_DECAY_STEPS: 30,
+	ARCHIVE_THRESHOLD: .3,
+	ARCHIVE_RECOVER: .6,
+	CONSOLIDATE_INTERVAL_MS: 864e5
+};
+function metaFile(root) {
+	return path.join(root, ".meta", "weights.json");
+}
+function emptyMeta() {
+	return {
+		version: 1,
+		updatedAt: null,
+		entries: {}
+	};
+}
+async function ensureMetaDir(root) {
+	await promises.mkdir(path.dirname(metaFile(root)), { recursive: true });
+}
+/** 加载元数据(不存在则初始化) */
+async function loadMeta(root) {
+	await ensureMetaDir(root);
+	try {
+		const raw = await promises.readFile(metaFile(root), "utf8");
+		const m = JSON.parse(raw);
+		if (!m.entries) m.entries = {};
+		return m;
+	} catch {
+		return emptyMeta();
+	}
+}
+async function saveMeta(root, meta) {
+	meta.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+	await ensureMetaDir(root);
+	await promises.writeFile(metaFile(root), JSON.stringify(meta, null, 2), "utf8");
+}
+function entryOf(meta, conceptId) {
+	if (!meta.entries[conceptId]) meta.entries[conceptId] = {
+		weight: 1,
+		accessCount: 0,
+		lastAccessed: null,
+		state: "active",
+		createdAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	return meta.entries[conceptId];
+}
+/** 触摸时间基线:读过用 lastAccessed;只入表未读过用 createdAt;两者都缺(旧数据)→ 视为现在(保守,不衰减) */
+function touchedAtMs(e, now) {
+	const t = e.lastAccessed || e.createdAt;
+	if (!t) return now;
+	const ms = new Date(t).getTime();
+	return Number.isFinite(ms) ? ms : now;
+}
+/** 衰减因子:宽限期内为 1;超出后按 (超出天数 / DECAY_DAYS) 做 DECAY_FACTOR 幂衰减 */
+function decayFactor(elapsedDays) {
+	if (elapsedDays <= PARAMS.DECAY_DAYS) return 1;
+	const over = (elapsedDays - PARAMS.DECAY_DAYS) / PARAMS.DECAY_DAYS;
+	return Math.pow(PARAMS.DECAY_FACTOR, Math.min(over, PARAMS.MAX_DECAY_STEPS));
+}
+/** 交互反馈:用户选中(如 TechChoice 候选被拍板);写锁内串行防权重丢失 */
+async function recordSelect(root, conceptId, delta = PARAMS.SELECT_DELTA) {
+	return withLock(async () => {
+		const meta = await loadMeta(root);
+		const e = entryOf(meta, conceptId);
+		e.weight = Math.min(PARAMS.MAX_WEIGHT, e.weight + delta);
+		e.accessCount += 1;
+		e.lastAccessed = (/* @__PURE__ */ new Date()).toISOString();
+		e.lastDecayDays = 0;
+		if (e.state === "inactive") {
+			e.weight = Math.max(e.weight, PARAMS.ARCHIVE_RECOVER);
+			e.state = "active";
+		}
+		await saveMeta(root, meta);
+		return e.weight;
+	});
+}
+/** 交互反馈:用户跳过/否定;写锁内串行防权重丢失 */
+async function recordSkip(root, conceptId, delta = PARAMS.SKIP_DELTA) {
+	return withLock(async () => {
+		const meta = await loadMeta(root);
+		const e = entryOf(meta, conceptId);
+		e.weight = Math.max(PARAMS.MIN_WEIGHT, e.weight - delta);
+		await saveMeta(root, meta);
+		return e.weight;
+	});
+}
+/** 交互反馈:被唤起且被使用 */
+async function recordHit(root, conceptId) {
+	return recordSelect(root, conceptId, PARAMS.HIT_DELTA);
+}
+/**
+* 巩固:增量衰减 + 阈值归档(不删除,可复活);写锁内串行。
+*
+* 幂等性:衰减按「本次因子 / 上次已应用的因子」增量施加。两次调用之间 elapsedDays
+* 不变时比值为 1,所以时间没流逝就不会重复扣血 —— 这正是旧实现的问题:
+* 它每次都把 factor 乘到已衰减的权重上,连调 N 次就衰减 N 次(24h 定时器 + 每次
+* 重启/reload 多跑一次即反复扣血)。
+*/
+async function consolidate(root) {
+	return withLock(async () => {
+		const meta = await loadMeta(root);
+		const now = Date.now();
+		let changed = false;
+		for (const e of Object.values(meta.entries)) {
+			const elapsedDays = (now - touchedAtMs(e, now)) / 864e5;
+			if (elapsedDays > PARAMS.DECAY_DAYS) {
+				const prev = typeof e.lastDecayDays === "number" ? e.lastDecayDays : PARAMS.DECAY_DAYS;
+				const ratio = Math.min(1, decayFactor(elapsedDays) / decayFactor(prev));
+				if (ratio < 1) {
+					e.weight = Math.max(PARAMS.MIN_WEIGHT, e.weight * ratio);
+					changed = true;
+				}
+				if (e.lastDecayDays !== elapsedDays) {
+					e.lastDecayDays = elapsedDays;
+					changed = true;
+				}
+			}
+			if (e.state === "active" && e.weight < PARAMS.ARCHIVE_THRESHOLD) {
+				e.state = "inactive";
+				changed = true;
+			}
+		}
+		if (changed) await saveMeta(root, meta);
+		return meta;
+	});
+}
+/**
+* 启动巩固定时器:每 intervalMs 对记忆库做一次巩固(衰减+归档),返回停止函数。
+* 定时器 unref(不阻止进程退出);内部吞异常,单次失败不中断进程。
+*/
+function startConsolidation(root, intervalMs = PARAMS.CONSOLIDATE_INTERVAL_MS) {
+	const id = setInterval(() => {
+		consolidate(root).catch(() => {});
+	}, intervalMs);
+	if (typeof id.unref === "function") id.unref();
+	return () => clearInterval(id);
+}
+/**
+* 唤起评分:relevance × weight × recency_factor。
+*/
+function recallScore(relevance, weight = 1, lastAccessed = null) {
+	let recency = 1;
+	if (lastAccessed) {
+		const days = (Date.now() - new Date(lastAccessed).getTime()) / 864e5;
+		recency = Math.max(.4, 1 / (1 + days / 30));
+	}
+	return relevance * weight * recency;
+}
+/** 把检索结果与学习权重合并,按唤起评分排序 */
+async function rank(root, searchHits) {
+	const meta = await loadMeta(root);
+	const ranked = searchHits.map((h) => {
+		const e = meta.entries[h.conceptId];
+		const weight = e ? e.weight : 1;
+		const state = e ? e.state : "active";
+		const score = recallScore(h.score, weight, e ? e.lastAccessed : null);
+		return {
+			...h,
+			weight: +weight.toFixed(2),
+			state,
+			score: +score.toFixed(3)
+		};
+	});
+	ranked.sort((a, b) => b.score - a.score);
+	return ranked;
+}
+//#endregion
+export { PARAMS, consolidate, loadMeta, rank, recallScore, recordHit, recordSelect, recordSkip, saveMeta, startConsolidation };

package/lib/memory.js

@@ -0,0 +1,135 @@
+import { mergeConceptBodies, normalizeType } from "./concept.js";
+import { appendLog, filePathOf, readConcept, refreshIndex, withLock, writeConcept } from "./store.js";
+import { findSimilarByTitle } from "./dedupe.js";
+import { loadMeta, saveMeta } from "./learning.js";
+import path from "node:path";
+import { promises } from "node:fs";
+//#region src/server/memory.ts
+/**
+* memory.ts — 运行时无关的记忆写入/撤回核心逻辑。
+*
+* 从 index.ts 抽出,供多运行时适配层共用:
+*  - dsh 适配层(src/server/index.ts)用它注册 okf_remember / okf_forget
+*  - pi 适配层(src/pi/index.ts)用它注册同名工具
+* 本模块零 dsh / 零 pi 依赖,只有 node:fs 与包内核模块。
+*/
+/**
+* remember 核心(服务与工具共用):类型校验 → 去重 → 小节级合并/新建 → 反馈。
+* 全程持写锁,保证"判断→写入"原子,避免并发下同标题概念被重复创建。
+*/
+async function rememberCore(root, meta, body, opts = {}) {
+	return withLock(async () => {
+		const { title, type, tags, related } = meta;
+		if (!title || !body) throw new Error("title/content 必填");
+		const normType = normalizeType(type);
+		const similar = await findSimilarByTitle(root, title, normType);
+		if (similar.length > 0) {
+			const top = similar[0];
+			if (top.similarity >= 1) {
+				const existing = await readConcept(root, top.conceptId);
+				const existingLen = String(existing.body || "").trim().length;
+				const newLen = String(body || "").trim().length;
+				if (newLen > existingLen * .7 && opts.force !== false) {
+					const mergedBody = mergeConceptBodies(existing.body || "", body);
+					const res = await writeConcept(root, {
+						...existing.meta,
+						title,
+						type: normType,
+						tags: tags || existing.meta?.tags,
+						timestamp: (/* @__PURE__ */ new Date()).toISOString()
+					}, mergedBody);
+					return {
+						status: "updated",
+						conceptId: res.conceptId,
+						filePath: res.filePath,
+						reason: "标题相同,按小节合并更新"
+					};
+				}
+				return {
+					status: "skipped",
+					conceptId: top.conceptId,
+					reason: `标题相同的概念已存在(${existingLen}字),新内容(${newLen}字)未显著增加`
+				};
+			}
+			return {
+				status: "linked",
+				conceptId: top.conceptId,
+				reason: `存在相近概念[${top.title}](${top.conceptId}),已返回其 ID;建议新建后与该概念互建交叉链接,而非复制内容`,
+				similarTo: top.conceptId
+			};
+		}
+		const res = await writeConcept(root, {
+			type: normType,
+			title,
+			description: opts.description || String(body).split("\n").find((l) => l.trim().startsWith(">"))?.replace(/^>\s*/, "").trim() || firstLine(body),
+			tags: tags || [],
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			source: opts.source || "session"
+		}, body);
+		if (Array.isArray(related) && related.length > 0) for (const rid of related) try {
+			const r = await readConcept(root, String(rid).replace(/\.md$/, ""));
+			const linkLine = `\n\n## 相关\n\n- [${title}](/${res.conceptId}.md)`;
+			if (!(r.body || "").includes(res.conceptId)) await writeConcept(root, {
+				...r.meta,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			}, `${r.body?.trim() || ""}${linkLine}`);
+		} catch {}
+		return {
+			status: "created",
+			conceptId: res.conceptId,
+			filePath: res.filePath,
+			reason: "新建"
+		};
+	});
+}
+/**
+* forget 核心:概念不存在返回 not_found;默认移到 .meta/forgotten/(保留目录结构防同名冲突),
+* delete_file=true 时直接删除文件。全程持写锁。
+*/
+async function forgetCore(root, id, deleteFile) {
+	return withLock(async () => {
+		const filePath = filePathOf(root, id);
+		let exists = true;
+		try {
+			await promises.access(filePath);
+		} catch {
+			exists = false;
+		}
+		if (!exists) return {
+			status: "not_found",
+			conceptId: id,
+			reason: "概念不存在(可能已撤回)"
+		};
+		if (deleteFile) await promises.rm(filePath, { force: true });
+		else {
+			const forgottenDir = path.join(root, ".meta", "forgotten");
+			const dest = path.join(forgottenDir, path.relative(root, filePath));
+			await promises.mkdir(path.dirname(dest), { recursive: true });
+			await promises.rename(filePath, dest);
+		}
+		await refreshIndex(root);
+		await appendLog(root, {
+			action: deleteFile ? "forgotten(deleted)" : "forgotten",
+			conceptId: id,
+			type: "—",
+			title: deleteFile ? "已删除文件" : "已移至 .meta/forgotten/"
+		});
+		const meta = await loadMeta(root);
+		if (meta.entries[id]) {
+			meta.entries[id].state = "inactive";
+			await saveMeta(root, meta);
+		}
+		return {
+			status: "forgotten",
+			conceptId: id,
+			reason: deleteFile ? "已删除文件" : "已移至 .meta/forgotten/"
+		};
+	});
+}
+/** 取正文首个非标题行,作为缺省 description */
+function firstLine(s) {
+	const line = String(s || "").split("\n").map((l) => l.trim()).find((l) => l && !l.startsWith("#"));
+	return line ? line.slice(0, 120) : "";
+}
+//#endregion
+export { firstLine, forgetCore, rememberCore };