@scotthuang/engram 0.1.0

package/src/settle.ts

@@ -0,0 +1,277 @@
+/**
+ * Memory System Plugin - Settle (沉淀机制)
+ * 
+ * 凌晨 Cron 5 步流程：
+ * 1. 结构化短期记忆
+ * 2. 筛选 + 向量化
+ * 3. 更新画像
+ * 4. 生成画像摘要
+ * 5. 归档清理
+ */
+
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { ProfileManager } from "./profile.js";
+import { type MemorySystemConfig } from "./config.js";
+
+type SettleOptions = {
+  workspaceDir: string;
+  config: MemorySystemConfig;
+  llmCall?: (prompt: string, systemPrompt?: string) => Promise<string>;
+  vectorStore?: (text: string, category: string) => Promise<void>;
+};
+
+/**
+ * 步骤 1: 结构化短期记忆
+ * 读取当天原始记录，用 LLM 整理成结构化格式
+ */
+export async function structurizeShortTerm(
+  opts: SettleOptions,
+  date: string = new Date().toISOString().split("T")[0]
+): Promise<string> {
+  const filePath = join(opts.workspaceDir, "memory", `${date}.md`);
+  try {
+    const raw = await fs.readFile(filePath, "utf-8");
+    if (!raw.trim()) return "No content to structurize.";
+
+    if (!opts.llmCall) return "No LLM configured for structurization.";
+
+    const systemPrompt = `你是一个记忆整理助手。请将以下原始对话记录整理成结构化格式。
+
+规则：
+1. 按时间倒序排列
+2. 每条记录格式：### HH:MM [分类标签]\n摘要内容（一句话）
+3. 过滤掉无意义的闲聊（打招呼、HEARTBEAT_OK、确认回复、"好的"、"嗯"等）
+4. 保留所有有价值的信息（决策、偏好、事件、数字、人名、地点等）
+5. 分类标签可选值：饮食、工作、家庭、技术、决策、健康、购物、出行、随聊
+
+只输出整理后的内容，不要解释。`;
+
+    const result = await opts.llmCall(raw, systemPrompt);
+
+    // 写回结构化内容到 short-term 目录
+    const shortTermDir = join(opts.workspaceDir, "memory", "short-term");
+    await fs.mkdir(shortTermDir, { recursive: true });
+    await fs.writeFile(join(shortTermDir, `${date}.md`), result, "utf-8");
+
+    return `Structurized ${date}.md → short-term/${date}.md`;
+  } catch (err) {
+    return `Skipped: ${date}.md not found or error: ${err}`;
+  }
+}
+
+/**
+ * 步骤 2: 筛选有价值条目 + 向量化
+ */
+export async function extractAndVectorize(
+  opts: SettleOptions,
+  date: string = new Date().toISOString().split("T")[0]
+): Promise<string> {
+  const filePath = join(opts.workspaceDir, "memory", "short-term", `${date}.md`);
+  try {
+    const content = await fs.readFile(filePath, "utf-8");
+    if (!content.trim()) return "No content.";
+
+    if (!opts.llmCall || !opts.vectorStore) return "No LLM/vector configured.";
+
+    const systemPrompt = `你是一个信息筛选助手。从以下结构化记忆中筛选出值得长期保留的条目。
+
+保留标准：
+- 包含用户偏好、决策、重要事件、具体信息（地点、金额、人名）
+- 去掉纯闲聊、日常寒暄、临时信息
+
+对每条保留的条目，输出 JSON 数组：
+[{"text": "条目摘要", "category": "分类"}]
+
+只输出 JSON，不要其他内容。`;
+
+    const result = await opts.llmCall(content, systemPrompt);
+    const items = JSON.parse(result);
+
+    let stored = 0;
+    for (const item of items) {
+      if (item.text && item.category) {
+        await opts.vectorStore(item.text, item.category);
+        stored++;
+      }
+    }
+
+    return `Extracted ${stored} items for vectorization.`;
+  } catch (err) {
+    return `Skipped: ${err}`;
+  }
+}
+
+/**
+ * 步骤 3: 更新画像
+ */
+export async function updateProfile(
+  opts: SettleOptions,
+  date: string = new Date().toISOString().split("T")[0]
+): Promise<string> {
+  const filePath = join(opts.workspaceDir, "memory", "short-term", `${date}.md`);
+  try {
+    const content = await fs.readFile(filePath, "utf-8");
+    if (!content.trim()) return "No content.";
+
+    if (!opts.llmCall) return "No LLM configured.";
+
+    const profileManager = new ProfileManager(opts.workspaceDir);
+    const profile = await profileManager.load();
+
+    const systemPrompt = `你是一个用户画像分析助手。从以下记忆中抽取用户标签，更新画像。
+
+当前画像：
+${JSON.stringify(profile.tags, null, 2)}
+
+请输出 JSON：
+{
+  "added": [{"dimension": "分类", "value": "标签"}],
+  "removed": [{"dimension": "分类", "value": "标签"}],
+  "reason": "简要说明"
+}
+
+规则：
+- 只添加有充分依据的标签（至少 2 条记忆佐证）
+- 如果旧标签与新信息矛盾，放入 removed
+- 不要重复添加已有标签
+
+只输出 JSON。`;
+
+    const result = await opts.llmCall(content, systemPrompt);
+    const changes = JSON.parse(result);
+
+    let added = 0;
+    let removed = 0;
+
+    if (changes.added) {
+      for (const tag of changes.added) {
+        profileManager.addTag(profile, tag.dimension, tag.value);
+        added++;
+      }
+    }
+
+    if (changes.removed) {
+      for (const tag of changes.removed) {
+        if (profile.tags[tag.dimension]) {
+          profile.tags[tag.dimension] = profile.tags[tag.dimension].filter(
+            t => t.value !== tag.value
+          );
+          removed++;
+        }
+      }
+    }
+
+    // 衰减未更新的标签
+    profileManager.decayTags(profile, 0.98);
+
+    await profileManager.save(profile);
+
+    return `Profile updated: +${added} -${removed}`;
+  } catch (err) {
+    return `Skipped: ${err}`;
+  }
+}
+
+/**
+ * 步骤 4: 生成画像摘要
+ */
+export async function generateProfileSummary(
+  opts: SettleOptions
+): Promise<string> {
+  if (!opts.llmCall) return "No LLM configured.";
+
+  const profileManager = new ProfileManager(opts.workspaceDir);
+  const profile = await profileManager.load();
+
+  const allTags = Object.entries(profile.tags)
+    .map(([dim, tags]) => `${dim}: ${tags.map(t => t.value).join(", ")}`)
+    .join("\n");
+
+  if (!allTags) return "No tags to summarize.";
+
+  const systemPrompt = `将以下用户画像标签压缩为一段 100 字以内的中文摘要，用于 AI 检索时快速理解用户特征。
+
+标签：
+${allTags}
+
+只输出摘要文本，不要其他内容。`;
+
+  try {
+    const summary = await opts.llmCall(allTags, systemPrompt);
+    profile.summary = summary.trim();
+
+    // 更新 coreTags：取每个维度置信度最高的标签
+    const coreTags: string[] = [];
+    for (const tags of Object.values(profile.tags)) {
+      const sorted = [...tags].sort((a, b) => b.confidence - a.confidence);
+      if (sorted.length > 0) {
+        coreTags.push(sorted[0].value);
+      }
+    }
+    profile.coreTags = coreTags.slice(0, 10);
+
+    await profileManager.save(profile);
+    return `Summary generated: "${summary.trim()}"`;
+  } catch (err) {
+    return `Failed: ${err}`;
+  }
+}
+
+/**
+ * 步骤 5: 归档清理
+ */
+export async function archiveShortTerm(
+  opts: SettleOptions
+): Promise<string> {
+  const shortTermDir = join(opts.workspaceDir, "memory", "short-term");
+  const coldStorageDir = join(opts.workspaceDir, "memory", "cold-storage");
+
+  try {
+    await fs.mkdir(coldStorageDir, { recursive: true });
+    const files = await fs.readdir(shortTermDir);
+    let archived = 0;
+
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - opts.config.shortTermDays);
+
+    for (const file of files) {
+      if (!file.endsWith(".md")) continue;
+      const filePath = join(shortTermDir, file);
+      const stat = await fs.stat(filePath);
+
+      if (stat.mtime < cutoff) {
+        // 按月归档
+        const monthMatch = file.match(/(\d{4}-\d{2})/);
+        const month = monthMatch ? monthMatch[1] : "unknown";
+        const destDir = join(coldStorageDir, month);
+        await fs.mkdir(destDir, { recursive: true });
+        await fs.rename(filePath, join(destDir, file));
+        archived++;
+      }
+    }
+
+    return `Archived ${archived} files to cold-storage.`;
+  } catch (err) {
+    return `Archive skipped: ${err}`;
+  }
+}
+
+/**
+ * 执行完整沉淀流程
+ */
+export async function runSettlement(opts: SettleOptions): Promise<string[]> {
+  const date = new Date().toISOString().split("T")[0];
+  const results: string[] = [];
+
+  console.log(`[engram] Starting settlement for ${date}...`);
+
+  results.push(await structurizeShortTerm(opts, date));
+  results.push(await extractAndVectorize(opts, date));
+  results.push(await updateProfile(opts, date));
+  results.push(await generateProfileSummary(opts));
+  results.push(await archiveShortTerm(opts));
+
+  console.log(`[engram] Settlement complete: ${results.join("; ")}`);
+  return results;
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}