dsh-memory-graph-chiyo 0.0.0-stage → 0.7.0

package/docs/API.md

@@ -0,0 +1,124 @@
+# API 速查
+
+所有入口都从包根导入：
+
+```js
+import { createMemory, write, ... } from 'dsh-memory-graph-chiyo';
+const mem = createMemory({ dir: './memory-data', options: {} });
+```
+
+## 记忆图
+
+### `mem.write(scope, { nodes, messages?, allowSensitive?, sensitiveAllow? })`
+写节点。`fact`/`plan` 必须有锚点；传了 `messages` 时锚点必须能在原文里找到。
+- `nodes[].kind`: `fact` | `impression` | `plan`
+- `nodes[].anchors`: `[{ quote, source?, at? }]`
+- `nodes[].relations`: `[{ type, targetId, weight? }]`，类型见 `REL_TYPES`
+- `nodes[].idempotencyKey` / `mentionKey`：幂等去重
+- `nodes[].validDays` / `validTo`：plan 专用
+返回 `{ written, merged, total }`。
+
+### `mem.recall(scope, { query, limit, includeCold, includeArchived, hops })`
+召回。`hops=1` 沿关系边扩展（出边 + 入边）。命中会提升 `recallCount` 与重要度。
+
+### `mem.recallAcross(scopes, { query, limit, perScopeLimit, includeCold })`
+多 scope 合并召回，结果带 `scope` 字段。
+
+### `mem.load(scope)` / `mem.tickLayers(scope, { now, apply })`
+读全部节点（last-wins）/ 推进层状态。
+
+### `mem.tickPlans(scope)` / `mem.setPlanStatus(scope, id, status, reason)`
+计划过期与手动改状态。
+
+## 即时记忆
+
+```js
+mem.writeInstant(scope, { text, topicKey, eventKey, personKey? });
+mem.tickInstant(scope, { now, apply });
+mem.reviveInstant(scope, { topicKey, eventKey, personKey? });
+```
+
+## 共享记忆
+
+```js
+const e = mem.proposeShared({ text, sourceScope, judgment?, dependsOn? }); // 默认每天 3 条
+mem.approveShared(e.id, { by });
+mem.revokeShared(e.id, { by, reason, cascade: true });
+mem.listShared({ status });
+mem.recallShared({ query, limit });   // 只返回 approved
+mem.shared.audit({ limit });
+```
+
+## 抽取 / 装配
+
+```js
+mem.heuristicExtract(messages, { speaker });
+mem.extractAndWrite(scope, messages, { speaker, max });
+mem.buildExtractionPrompt(messages);            // 给大模型用
+mem.assembleContext({ scopes, query, tokenBudget });
+// → { text, tokens, used, total }
+```
+
+## 压缩
+
+```js
+const comp = mem.compactor({ windowTokens: 128000, thresholdRatio: 0.3, keepTurns: 10 });
+const r = await comp.compact(events);
+comp.expand(r);   // 取回被折叠原文
+comp.stats();     // 每次压缩放掉多少
+```
+
+## 整理 / 体检 / 计划任务
+
+```js
+mem.consolidate(scope, { apply });
+mem.healthReport({ scope });     // 六项指标
+mem.nightly(['user:alice'], { apply: true });
+mem.tickAll({ scope, apply: true });
+```
+
+## 规则 / 人物 / 时间线 / 星图
+
+```js
+extractRules(text, { speaker });                 // 返回可写入的规则节点
+mem.person.upsert({ name, aliases, note });
+mem.person.proposeMerge(a, b); mem.person.approveMerge(id, { by });
+mem.episode({ scope, from, to });
+mem.missedScan({ scope, messages });
+mem.starMap(nodes, { title });                   // SVG 字符串
+mem.mermaid(nodes);                              // Mermaid 字符串
+```
+
+## 快照
+
+```js
+const bundle = mem.exportBundle({ note: 'before cleanup' });
+saveBundle(bundle, './backup.json');
+importBundle(loadBundle('./backup.json'), './memory-data', { overwrite: true });
+```
+
+## 关系衰减
+
+```js
+mem.decayRelations(scope, { halfLifeDays: 180, minWeight: 0.05, apply: true });
+```
+
+## 人格（可选，角色扮演层）
+
+```js
+mem.persona.get();
+mem.persona.tune('initiative', 0.05, { by: 'owner', reason: '…' }); // ≤0.05/次，1 次/天，漂移 ≤0.15
+mem.persona.summary();
+mem.persona.revert();
+```
+
+## 命令行
+
+```bash
+npx memory-graph health   --dir ./data --scope user:alice
+npx memory-graph recall   --dir ./data --scope user:alice --query 下雨
+npx memory-graph recall-all --dir ./data --scopes user:alice,agent:chiyo --query 下雨
+npx memory-graph nightly  --dir ./data --scopes user:alice --apply
+npx memory-graph shared-list --dir ./data
+npx memory-graph shared-approve --dir ./data --id s_xxx --by owner
+```

package/index.d.ts

@@ -0,0 +1,337 @@
+// Type definitions for dsh-memory-graph-chiyo 0.6
+// 手写声明，追求"能用、不骗人"：不确定的结构用宽松类型。
+
+export type Scope = string;
+export type Kind = 'fact' | 'impression' | 'plan';
+export type Category = 'preference' | 'experience' | 'relationship' | 'plan' | 'emotion' | 'topic';
+export type Layer = 'instant' | 'short' | 'long' | 'cold' | 'permanent';
+export type RelationType = 'person' | 'relationship' | 'because' | 'derivedFrom' | 'supports' | 'contradicts';
+export type PlanStatus = 'active' | 'done' | 'abandoned' | 'expired';
+
+export interface Anchor {
+  quote: string;
+  source?: string;
+  at?: number;
+}
+
+export interface Relation {
+  type: RelationType;
+  targetId: string;
+  weight?: number;
+}
+
+export interface MemoryNode {
+  id: string;
+  scope: Scope;
+  kind: Kind | 'instant';
+  text: string;
+  anchors: Anchor[];
+  relations?: Relation[];
+  category?: Category | string;
+  layer?: Layer;
+  cluster?: string;
+  status?: PlanStatus;
+  validTo?: number;
+  mentionCount?: number;
+  recallCount?: number;
+  importance?: number;
+  idempotencyKey?: string;
+  mentionKey?: string;
+  superseded?: boolean;
+  supersededBy?: string;
+  supersedes?: string;
+  archived?: boolean;
+  createdAt: number;
+  updatedAt: number;
+  lastTouchedAt?: number;
+  [key: string]: unknown;
+}
+
+export interface WriteInput {
+  kind: Kind;
+  text: string;
+  anchors?: Anchor[];
+  relations?: Relation[];
+  category?: Category | string;
+  cluster?: string;
+  idempotencyKey?: string;
+  mentionKey?: string;
+  validDays?: number;
+  validTo?: number;
+}
+
+export interface WriteOptions {
+  nodes: WriteInput[];
+  writer?: string;
+  messages?: Array<string | { text?: string; content?: string }> | null;
+  allowSensitive?: boolean;
+  sensitiveAllow?: string[];
+}
+
+export interface WriteResult {
+  written: MemoryNode[];
+  merged: Array<{ id: string; text: string; mentionCount: number }>;
+  total: number;
+}
+
+export interface RecallOptions {
+  query?: string;
+  limit?: number;
+  includeCold?: boolean;
+  includeArchived?: boolean;
+  includeSuperseded?: boolean;
+  hops?: number;
+}
+
+export interface RecalledNode extends MemoryNode {
+  score: number;
+  via?: string;
+  relation?: RelationType;
+}
+
+export interface AssembleOptions {
+  scopes: Scope[];
+  query?: string;
+  tokenBudget?: number;
+  includeShared?: boolean;
+  includePlans?: boolean;
+  limit?: number;
+}
+
+export interface AssembleResult {
+  text: string;
+  tokens: number;
+  used: string[];
+  total: number;
+}
+
+export interface CompactOptions {
+  windowTokens?: number;
+  thresholdRatio?: number;
+  keepTurns?: number;
+  pruner?: { thresholdChars?: number; headChars?: number; tailChars?: number };
+  summaryMaxChars?: number;
+  summarizer?: (events: unknown[], ctx: { estimateTokens: (s: string) => number; maxChars: number }) => string | Promise<string>;
+}
+
+export interface CompactResult {
+  compacted: boolean;
+  events: unknown[];
+  beforeTokens: number;
+  afterTokens: number;
+  shadowed?: unknown[];
+  anchors?: string[];
+  summary?: string;
+  pruned?: number;
+  savedChars?: number;
+  note?: string;
+}
+
+export interface SharedEntry {
+  id: string;
+  text: string;
+  judgment?: string;
+  sourceScope: string;
+  status: 'proposed' | 'approved' | 'revoked';
+  dependsOn?: string[];
+  proposedAt: number;
+  updatedAt: number;
+  [key: string]: unknown;
+}
+
+export interface HealthCheck {
+  name: string;
+  ok: boolean;
+  value: number;
+  detail: string;
+}
+
+export interface HealthReport {
+  scope: Scope;
+  at: string;
+  total: number;
+  live: number;
+  archived: number;
+  byLayer: Record<string, number>;
+  byKind: Record<string, number>;
+  checks: HealthCheck[];
+  ok: boolean;
+  failed: string[];
+}
+
+export interface Memory {
+  store: unknown;
+  graph: unknown;
+  instant: unknown;
+  shared: unknown;
+  person: unknown;
+  persona: unknown;
+
+  write(scope: Scope, input: WriteOptions): WriteResult;
+  recall(scope: Scope, opts?: RecallOptions): RecalledNode[];
+  recallAcross(scopes: Scope[], opts?: RecallOptions & { perScopeLimit?: number }): RecalledNode[];
+  load(scope: Scope): MemoryNode[];
+
+  tickLayers(scope: Scope, opts?: { now?: number; apply?: boolean }): Array<{ id: string; from: string; to: string }>;
+  tickPlans(scope: Scope, opts?: { now?: number; apply?: boolean }): Array<{ id: string; text: string }>;
+  setPlanStatus(scope: Scope, id: string, status: PlanStatus, reason?: string): MemoryNode;
+
+  writeInstant(scope: Scope, input: { text: string; topicKey: string; eventKey: string; personKey?: string }): MemoryNode;
+  tickInstant(scope: Scope, opts?: { now?: number; apply?: boolean }): Array<{ id: string; from: string; to: string }>;
+  reviveInstant(scope: Scope, input: { topicKey: string; eventKey: string; personKey?: string }): unknown;
+
+  proposeShared(input: { text: string; sourceScope: string; judgment?: string; by?: string; dependsOn?: string[] }): SharedEntry;
+  approveShared(id: string, opts?: { by?: string }): SharedEntry;
+  revokeShared(id: string, opts?: { by?: string; reason?: string; cascade?: boolean }): SharedEntry;
+  listShared(opts?: { status?: string }): SharedEntry[];
+  recallShared(opts?: { query?: string; limit?: number }): Array<SharedEntry & { score: number }>;
+
+  heuristicExtract(messages: unknown[], opts?: { speaker?: 'owner' | 'self'; max?: number }): WriteInput[];
+  extractAndWrite(scope: Scope, messages: unknown[], opts?: { speaker?: 'owner' | 'self'; max?: number }): { written: MemoryNode[]; merged: unknown[]; skipped: unknown[] };
+  buildExtractionPrompt(messages: unknown[]): string;
+  assembleContext(opts: AssembleOptions): AssembleResult;
+
+  exportBundle(opts?: { dir?: string; note?: string }): unknown;
+  importBundle(bundle: unknown, opts?: { dir?: string; overwrite?: boolean }): { written: number; skipped: number; dir: string };
+  decayRelations(scope: Scope, opts?: { now?: number; halfLifeDays?: number; minWeight?: number; apply?: boolean }): unknown;
+
+  scanConflicts(scope: Scope, opts?: { apply?: boolean; minSubjectSim?: number }): Array<{ oldId: string; newId: string; oldText: string; newText: string }>;
+  scanStore(opts?: { dir?: string }): unknown;
+  repairStore(opts?: { dir?: string; apply?: boolean }): unknown;
+
+  extractRules(text: string, opts?: { speaker?: 'owner' | 'self' }): WriteInput[];
+  episode(opts: { scope: Scope; from?: number; to?: number }): unknown;
+  missedScan(opts: { scope: Scope; messages: unknown[] }): unknown;
+  healthReport(opts: { scope: Scope; now?: number }): HealthReport;
+  starMap(nodes?: MemoryNode[], opts?: { width?: number; height?: number; title?: string; showLabels?: boolean }): string;
+  mermaid(nodes?: MemoryNode[], opts?: { maxNodes?: number }): string;
+  scanSensitive(text: string, opts?: { allow?: string[] }): Array<{ type: string; label: string }>;
+
+  consolidate(scope: Scope, opts?: { apply?: boolean }): unknown;
+  health(scope: Scope, opts?: { now?: number }): unknown;
+  tickAll(opts: { scope?: Scope; now?: number; apply?: boolean }): unknown;
+  nightly(scopes: Scope[], opts?: { now?: number; apply?: boolean }): unknown;
+
+  compactor(opts?: CompactOptions): { compact(events: unknown[]): Promise<CompactResult>; expand(record: CompactResult | unknown): unknown[]; stats(): unknown[] };
+}
+
+export function createMemory(config?: { dir?: string; options?: Record<string, unknown>; clock?: () => number }): Memory;
+export default createMemory;
+
+export function estimateTokens(text: string): number;
+export function pruneToolResults(events: unknown[], options?: Record<string, unknown>): { events: unknown[]; pruned: number; savedChars: number };
+export function createCompactor(options?: CompactOptions): Memory['compactor'] extends (o?: CompactOptions) => infer R ? R : never;
+
+export function scanSensitive(text: string, opts?: { allow?: string[] }): Array<{ type: string; label: string }>;
+export function assertNotSensitive(text: string, opts?: { allow?: string[] }): true;
+export function findMissingAnchors(anchors: Array<{ quote: string }>, messages: unknown[]): string[];
+export function quoteExists(quote: string, messages: unknown[]): boolean;
+export function extractAnchors(text: string, messages: unknown[], opts?: { max?: number; minLen?: number }): Anchor[];
+
+export function heuristicExtract(messages: unknown[], opts?: { speaker?: 'owner' | 'self'; max?: number }): WriteInput[];
+export function extractAndWrite(memory: Memory, scope: Scope, messages: unknown[], opts?: Record<string, unknown>): unknown;
+export function buildExtractionPrompt(messages: unknown[]): string;
+export function assembleContext(memory: Memory, opts: AssembleOptions): AssembleResult;
+
+export function exportBundle(dir: string, opts?: { note?: string }): unknown;
+export function importBundle(bundle: unknown, dir: string, opts?: { overwrite?: boolean }): unknown;
+export function saveBundle(bundle: unknown, file: string): string;
+export function loadBundle(file: string): unknown;
+
+export function scanConflicts(graph: unknown, scope: Scope, opts?: Record<string, unknown>): unknown;
+export function findConflict(existing: MemoryNode[], candidate: { text: string; kind: string; category?: string }, opts?: { minSubjectSim?: number }): unknown;
+export function polarityOf(text: string): 'pos' | 'neg' | 'neutral';
+export function scanStore(dir: string): unknown;
+export function repairStore(dir: string, opts?: { apply?: boolean }): unknown;
+
+export function renderStarMap(nodes: MemoryNode[], opts?: Record<string, unknown>): string;
+export function renderMermaid(nodes: MemoryNode[], opts?: Record<string, unknown>): string;
+export function healthReport(memory: Memory, scope: Scope, opts?: Record<string, unknown>): HealthReport;
+
+export function extractRules(text: string, opts?: { speaker?: 'owner' | 'self'; at?: number; max?: number }): WriteInput[];
+export function classifyRule(text: string, opts?: { speaker?: 'owner' | 'self' }): string | null;
+
+export function consolidate(graph: unknown, scope: Scope, opts?: { apply?: boolean; now?: number }): unknown;
+export function health(graph: unknown, scope: Scope, opts?: { now?: number }): unknown;
+export function tickAll(memory: Memory, opts?: { scope?: Scope; now?: number; apply?: boolean }): unknown;
+export function nightly(memory: Memory, opts?: { scopes?: Scope[]; now?: number; apply?: boolean }): unknown;
+
+export function buildEpisode(memory: Memory, opts: { scope: Scope; from?: number; to?: number }): unknown;
+export function missedScan(memory: Memory, opts: { scope: Scope; messages: unknown[] }): unknown;
+
+export const LAYERS: Layer[];
+export const KINDS: Kind[];
+export const CATEGORIES: Category[];
+export const REL_TYPES: RelationType[];
+export const PLAN_STATUSES: PlanStatus[];
+export const DEFAULT_KNOBS: Record<string, number>;
+export const KNOB_LABELS: Record<string, string>;
+export const PERSONA_LIMITS: { maxStep: number; maxPerDay: number; maxDrift: number };
+
+export function similarity(query: string, text: string): number;
+export function normalizeText(text: string): string;
+export function importanceOf(node: Partial<MemoryNode>, now?: number): number;
+export function scopeKey(scope: string): string;
+
+export class JsonlStore {
+  constructor(options: { dir: string });
+  dir: string;
+  append(scope: Scope, record: object): object;
+  load(scope: Scope): object[];
+  listScopes(): Scope[];
+}
+
+export class MemoryGraph {
+  constructor(options: { store: JsonlStore; options?: Record<string, unknown>; clock?: () => number });
+  write(scope: Scope, input: WriteOptions): WriteResult;
+  recall(scope: Scope, opts?: RecallOptions): RecalledNode[];
+  recallAcross(scopes: Scope[], opts?: RecallOptions & { perScopeLimit?: number }): RecalledNode[];
+  load(scope: Scope): MemoryNode[];
+  tick(scope: Scope, opts?: Record<string, unknown>): unknown;
+  tickPlans(scope: Scope, opts?: Record<string, unknown>): unknown;
+  setPlanStatus(scope: Scope, id: string, status: PlanStatus, reason?: string): MemoryNode;
+  decayRelations(scope: Scope, opts?: Record<string, unknown>): unknown;
+}
+
+export class InstantMemory {
+  constructor(options: { graph: MemoryGraph; options?: Record<string, unknown>; clock?: () => number });
+  write(scope: Scope, input: Record<string, unknown>): MemoryNode;
+  tick(scope: Scope, opts?: Record<string, unknown>): unknown;
+  revive(scope: Scope, input: Record<string, unknown>): unknown;
+}
+
+export class SharedMemory {
+  constructor(options: { store: JsonlStore; clock?: () => number; dailyQuota?: number });
+  propose(input: Record<string, unknown>): SharedEntry;
+  approve(id: string, opts?: { by?: string }): SharedEntry;
+  revoke(id: string, opts?: { by?: string; reason?: string; cascade?: boolean }): SharedEntry;
+  list(opts?: { status?: string }): SharedEntry[];
+  recall(opts?: { query?: string; limit?: number }): Array<SharedEntry & { score: number }>;
+  audit(opts?: { limit?: number }): unknown[];
+}
+
+export class PersonLayer {
+  constructor(options: { store: JsonlStore; clock?: () => number });
+  upsert(input: { name: string; aliases?: string[]; note?: string; confirmed?: boolean }): unknown;
+  resolve(name: string): unknown;
+  proposeMerge(a: string, b: string, opts?: { reason?: string }): unknown;
+  approveMerge(id: string, opts?: { by?: string }): unknown;
+  list(opts?: { includeProposals?: boolean }): unknown;
+}
+
+export class Persona {
+  constructor(options: { store: JsonlStore; clock?: () => number; limits?: Record<string, number> });
+  get(): Record<string, number>;
+  tune(key: string, delta: number, opts?: { by?: string; reason?: string }): Record<string, number>;
+  revert(): Record<string, number>;
+  summary(): string;
+  state(): unknown;
+}
+
+export class Compactor {
+  constructor(options?: CompactOptions);
+  compact(events: unknown[]): Promise<CompactResult>;
+  expand(record: CompactResult | unknown): unknown[];
+  stats(): unknown[];
+  count(events: unknown[]): number;
+}

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "dsh-memory-graph-chiyo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.7.0",
+  "description": "Memory system for AI agents: anchored graph, auto-extraction, prompt assembly, conflict detection, snapshot, shared memory, consolidation. TypeScript types, zero deps.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./plugin": "./plugin.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "bin",
+    "docs",
+    "plugin.js",
+    "cordis.patch.yml",
+    "index.d.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "ai-agent",
+    "memory",
+    "knowledge-graph",
+    "long-term-memory",
+    "anchors",
+    "forgetting-curve",
+    "consolidation",
+    "context-compaction",
+    "summarization",
+    "context-window",
+    "persona",
+    "knowledge-graph-viz",
+    "rules-extraction",
+    "sensitive-filter",
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20",
+    "dsh": ">=0.1.7-rc.1"
+  },
+  "author": "浮水梦华",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fushui-menghua/dsh-memory-graph-chiyo.git"
+  },
+  "homepage": "https://github.com/fushui-menghua/dsh-memory-graph-chiyo",
+  "bugs": {
+    "url": "https://github.com/fushui-menghua/dsh-memory-graph-chiyo/issues"
+  },
+  "bin": {
+    "memory-graph": "./bin/cli.mjs"
+  },
+  "types": "./index.d.ts",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "test": "node --test",
+    "demo": "node test/demo.mjs",
+    "cli": "node bin/cli.mjs",
+    "bench": "node bin/bench.mjs",
+    "test:plugin": "node test/plugin.test.mjs"
+  }
 }

package/plugin.js

@@ -0,0 +1,143 @@
+/**
+ * plugin.js —— DSH 插件入口（把记忆库包成能装进 DSH 的插件）
+ *
+ * 同一个包两种用法：
+ *   1. 库：import { createMemory } from 'dsh-memory-graph-chiyo'
+ *   2. 插件：在 DSH profile 里列出本包，cordis 会调这里的 apply(ctx)
+ *
+ * 插件注册 5 个工具，够用又不撑爆工具表：
+ *   memory_write   写一条记忆（带锚点）
+ *   memory_recall  召回
+ *   memory_health  体检
+ *   memory_nightly 夜间整理（默认 dry-run）
+ *   memory_shared  共享记忆（list / propose / approve / revoke）
+ */
+import path from 'node:path';
+import os from 'node:os';
+import fs from 'node:fs';
+import { createMemory } from './src/index.js';
+
+// ── defineTool：宿主给了就用宿主的，没给就用本地兜底（照抄 toolkit 的思路）──
+let base = (spec) => spec;
+let usingHost = false;
+try {
+  const m = await import('dsh-tools');
+  if (typeof m.defineTool === 'function') { base = m.defineTool; usingHost = true; }
+} catch { /* 宿主没暴露就用本地兜底 */ }
+
+export const textOutput = {
+  schema: { type: 'object', properties: {}, additionalProperties: true },
+  render: (_args, value) => [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }],
+};
+
+export function toJsonSchema(params) {
+  if (!params) return { type: 'object', properties: {}, required: [] };
+  if (params.type === 'object') return params;
+  const props = {};
+  const required = [];
+  for (const [key, val] of Object.entries(params)) {
+    if (!val || typeof val !== 'object') continue;
+    const { required: isRequired, ...schema } = val;
+    props[key] = schema;
+    if (isRequired === true) required.push(key);
+  }
+  return { type: 'object', properties: props, required, additionalProperties: false };
+}
+
+function defineTool(spec) {
+  if (usingHost) return base({ output: textOutput, ...spec });
+  return base({ output: textOutput, ...spec, parameters: toJsonSchema(spec.parameters) });
+}
+
+export const name = 'memory-graph';
+
+export function apply(ctx, config = {}) {
+  const home = process.env.DSH_HOME || path.join(os.homedir(), '.dsh');
+  const dir = path.resolve(config.dir || path.join(home, 'memory-graph'));
+  const defaultScope = String(config.scope || 'agent:memory');
+  fs.mkdirSync(dir, { recursive: true });
+  const mem = createMemory({ dir });
+  const scopeOf = (s) => String(s || defaultScope);
+
+  const tools = [
+    {
+      name: 'memory_write',
+      description: '写一条长期记忆。fact/plan 必须带原话锚点（anchors.quote）。同一件事重复写会自动合并。',
+      parameters: {
+        kind: { type: 'string', enum: ['fact', 'impression', 'plan'], required: true, description: '记忆类型' },
+        text: { type: 'string', required: true, description: '一句话陈述' },
+        anchors: { type: 'array', items: { type: 'object' }, description: '原话片段，如 [{quote:"我最喜欢下雨了"}]' },
+        category: { type: 'string', description: 'preference/experience/relationship/plan/emotion/topic' },
+        scope: { type: 'string', description: `记忆分区，默认 ${defaultScope}` },
+      },
+      execute: async (args = {}) => {
+        const r = mem.write(scopeOf(args.scope), {
+          nodes: [{ kind: args.kind, text: args.text, anchors: args.anchors || [], category: args.category }],
+        });
+        return { written: r.written.length, merged: r.merged.length, id: r.written[0]?.id };
+      },
+    },
+    {
+      name: 'memory_recall',
+      description: '按关键词/相似度召回长期记忆，返回带 id 的条目。',
+      parameters: {
+        query: { type: 'string', description: '想找什么' },
+        limit: { type: 'number', description: '最多几条，默认 10' },
+        scope: { type: 'string', description: `记忆分区，默认 ${defaultScope}` },
+      },
+      execute: async (args = {}) => {
+        const hits = mem.recall(scopeOf(args.scope), { query: args.query || '', limit: Number(args.limit) || 10 });
+        return hits.map((h) => ({ id: h.id, kind: h.kind, layer: h.layer, text: h.text, score: h.score }));
+      },
+    },
+    {
+      name: 'memory_health',
+      description: '记忆体检：锚点覆盖率、重复率、分层占比、陈旧度等六项。',
+      parameters: { scope: { type: 'string', description: `记忆分区，默认 ${defaultScope}` } },
+      execute: async (args = {}) => mem.healthReport({ scope: scopeOf(args.scope) }),
+    },
+    {
+      name: 'memory_nightly',
+      description: '夜间整理：推进层与即时记忆、归档噪声、强化重要记忆。默认 dry-run，apply=true 才真改。',
+      parameters: {
+        scope: { type: 'string', description: `记忆分区，默认 ${defaultScope}` },
+        apply: { type: 'boolean', description: 'true 才真正写入，默认只报告' },
+      },
+      execute: async (args = {}) => mem.nightly([scopeOf(args.scope)], { apply: args.apply === true }),
+    },
+    {
+      name: 'memory_shared',
+      description: '共享记忆：list 列出、propose 提名、approve 批准、revoke 撤销。只有 approved 能被其他会话召回。',
+      parameters: {
+        action: { type: 'string', enum: ['list', 'propose', 'approve', 'revoke'], required: true },
+        id: { type: 'string', description: '条目 id（approve/revoke 用）' },
+        text: { type: 'string', description: '提名内容（propose 用）' },
+        sourceScope: { type: 'string', description: '来源分区（propose 用）' },
+        by: { type: 'string', description: '操作人，默认 plugin' },
+      },
+      execute: async (args = {}) => {
+        const by = String(args.by || 'plugin');
+        if (args.action === 'list') return mem.listShared({ status: args.status || '' });
+        if (args.action === 'propose') return mem.proposeShared({ text: args.text, sourceScope: scopeOf(args.sourceScope), by });
+        if (args.action === 'approve') return mem.approveShared(args.id, { by });
+        if (args.action === 'revoke') return mem.revokeShared(args.id, { by });
+        throw new Error(`未知 action：${args.action}`);
+      },
+    },
+  ];
+
+  let registered = 0;
+  for (const spec of tools) {
+    try {
+      ctx.tools.register(defineTool(spec));
+      registered += 1;
+    } catch (e) {
+      // 单个工具没注册上不影响别的
+      try { ctx.logger?.warn?.(`[memory-graph] 工具 ${spec.name} 注册失败：${e?.message ?? e}`); } catch {}
+    }
+  }
+  try { ctx.logger?.info?.(`[memory-graph] 已挂载 ${registered}/${tools.length} 个工具，数据目录 ${dir}，默认分区 ${defaultScope}`); } catch {}
+  return { dir, defaultScope, registered };
+}
+
+export default apply;