@pencil-agent/nano-mem 0.0.1

package/src/insights-html.ts

@@ -0,0 +1,476 @@
+/**
+ * [INPUT]: InsightsReport, locale
+ * [OUTPUT]: Standalone HTML report
+ * [POS]: Pure renderer, no side effects
+ */
+
+import { PROMPTS } from "./i18n.js";
+import type { InsightsReport, MemoryEntry, PatternInsight, StruggleInsight } from "./types.js";
+
+type UiText = {
+	subtitle: string;
+	atAGlance: string;
+	whatsWorking: string;
+	whatsHindering: string;
+	quickWins: string;
+	focusArea: string;
+	noneYet: string;
+	workOn: string;
+	workOnIntro: string;
+	sessionWord: string;
+	distribution: string;
+	topProjects: string;
+	frequentTags: string;
+	successes: string;
+	successesIntro: string;
+	frictions: string;
+	frictionsIntro: string;
+	details: string;
+	weight: string;
+	access: string;
+	importance: string;
+	attempts: string;
+	solution: string;
+	status: string;
+	resolved: string;
+	unresolved: string;
+	knowledgePrefs: string;
+	lessons: string;
+	knowledge: string;
+	preferences: string;
+	generatedBy: string;
+};
+
+const UI: Record<"en" | "zh", UiText> = {
+	en: {
+		subtitle: "sessions analyzed",
+		atAGlance: "At a Glance",
+		whatsWorking: "What's Working",
+		whatsHindering: "What's Hindering",
+		quickWins: "Quick Wins",
+		focusArea: "Focus Area",
+		noneYet: "No strong signal yet.",
+		workOn: "What You Work On",
+		workOnIntro: "Top project areas inferred from your memory graph.",
+		sessionWord: "sessions",
+		distribution: "Focus Distribution",
+		topProjects: "Top Projects",
+		frequentTags: "Frequent Tags",
+		successes: "Impressive Things You Solved",
+		successesIntro: "Resolved struggles and high-value lessons worth repeating.",
+		frictions: "Where Things Still Go Wrong",
+		frictionsIntro: "Open struggles that are still costing time.",
+		details: "Details",
+		weight: "Weight",
+		access: "Access",
+		importance: "Importance",
+		attempts: "Attempts",
+		solution: "Solution",
+		status: "Status",
+		resolved: "resolved",
+		unresolved: "open",
+		knowledgePrefs: "Knowledge and Preferences",
+		lessons: "Top Lessons",
+		knowledge: "Knowledge Base",
+		preferences: "User Preferences",
+		generatedBy: "Generated by NanoMem",
+	},
+	zh: {
+		subtitle: "已分析会话",
+		atAGlance: "总览",
+		whatsWorking: "做得好的地方",
+		whatsHindering: "当前阻碍",
+		quickWins: "快速改进",
+		focusArea: "主要方向",
+		noneYet: "暂时没有明显信号。",
+		workOn: "你在做什么",
+		workOnIntro: "基于记忆图谱推断的项目重点领域。",
+		sessionWord: "次会话",
+		distribution: "关注分布",
+		topProjects: "主要项目",
+		frequentTags: "高频标签",
+		successes: "你解决得很好的事",
+		successesIntro: "已解决问题与高价值经验，建议重复复用。",
+		frictions: "仍在反复消耗的点",
+		frictionsIntro: "尚未关闭的问题，持续影响效率。",
+		details: "详情",
+		weight: "权重",
+		access: "访问",
+		importance: "重要度",
+		attempts: "尝试",
+		solution: "解法",
+		status: "状态",
+		resolved: "已解决",
+		unresolved: "待处理",
+		knowledgePrefs: "知识与偏好",
+		lessons: "关键经验",
+		knowledge: "知识库",
+		preferences: "用户偏好",
+		generatedBy: "由 NanoMem 自动生成",
+	},
+};
+
+function escapeHtml(str: string): string {
+	return str
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&#039;");
+}
+
+function formatDate(iso: string, locale: string): string {
+	const d = new Date(iso);
+	if (Number.isNaN(d.getTime())) return iso;
+	return d.toLocaleString(locale === "zh" ? "zh-CN" : "en-US");
+}
+
+function dedupeById(entries: MemoryEntry[]): MemoryEntry[] {
+	const map = new Map<string, MemoryEntry>();
+	for (const entry of entries) map.set(entry.id, entry);
+	return [...map.values()];
+}
+
+function topTags(entries: MemoryEntry[], limit = 8): Array<{ label: string; value: number }> {
+	const counts = new Map<string, number>();
+	for (const entry of entries) {
+		for (const tag of entry.tags ?? []) counts.set(tag, (counts.get(tag) ?? 0) + 1);
+	}
+	return [...counts.entries()]
+		.map(([label, value]) => ({ label, value }))
+		.sort((a, b) => b.value - a.value)
+		.slice(0, limit);
+}
+
+function topProjects(entries: MemoryEntry[], limit = 6): Array<{ label: string; value: number }> {
+	const counts = new Map<string, number>();
+	for (const entry of entries) {
+		if (!entry.project) continue;
+		counts.set(entry.project, (counts.get(entry.project) ?? 0) + 1);
+	}
+	return [...counts.entries()]
+		.map(([label, value]) => ({ label, value }))
+		.sort((a, b) => b.value - a.value)
+		.slice(0, limit);
+}
+
+function renderBarRows(rows: Array<{ label: string; value: number }>, colorClass: string, empty: string): string {
+	if (!rows.length) return `<p class="empty">${escapeHtml(empty)}</p>`;
+	const max = Math.max(...rows.map((row) => row.value), 1);
+	return rows
+		.map((row) => {
+			const width = Math.max(8, Math.round((row.value / max) * 100));
+			return `<div class="bar-row">
+  <div class="bar-label" title="${escapeHtml(row.label)}">${escapeHtml(row.label)}</div>
+  <div class="bar-track"><div class="bar-fill ${colorClass}" style="width:${width}%"></div></div>
+  <div class="bar-value">${row.value}</div>
+</div>`;
+		})
+		.join("");
+}
+
+function renderProjectAreas(projects: Array<{ label: string; value: number }>, entries: MemoryEntry[], ui: UiText): string {
+	if (!projects.length) return `<p class="empty">${escapeHtml(ui.noneYet)}</p>`;
+	return projects
+		.map((project) => {
+			const scopeEntries = entries.filter((entry) => entry.project === project.label);
+			const tags = topTags(scopeEntries, 4).map((item) => item.label);
+			const desc =
+				tags.length > 0
+					? `Top signals: ${tags.map((tag) => `#${escapeHtml(tag)}`).join(" ")}`
+					: "No dominant tag signal yet.";
+			return `<article class="project-area">
+  <div class="area-header">
+    <span class="area-name">${escapeHtml(project.label)}</span>
+    <span class="area-count">~${project.value} ${escapeHtml(ui.sessionWord)}</span>
+  </div>
+  <p class="area-desc">${desc}</p>
+</article>`;
+		})
+		.join("");
+}
+
+function renderPatternRows(patterns: PatternInsight[], ui: UiText): string {
+	if (!patterns.length) return `<p class="empty">${escapeHtml(ui.noneYet)}</p>`;
+	const maxWeight = Math.max(...patterns.map((item) => item.weight), 1);
+	return patterns
+		.slice(0, 12)
+		.map((item) => {
+			const width = Math.max(8, Math.round((item.weight / maxWeight) * 100));
+			return `<article class="item-card">
+  <div class="item-title"><strong>${escapeHtml(item.trigger)}</strong> <span class="arrow">-></span> ${escapeHtml(item.behavior)}</div>
+  <div class="weight-track"><div class="weight-fill" style="width:${width}%"></div></div>
+  <div class="meta-row">
+    <span>${escapeHtml(ui.weight)}: ${item.weight.toFixed(2)}</span>
+    <span>${escapeHtml(ui.access)}: ${item.entry.accessCount}</span>
+    <span>${escapeHtml(ui.importance)}: ${item.entry.importance}</span>
+  </div>
+</article>`;
+		})
+		.join("");
+}
+
+function renderStruggleRows(struggles: StruggleInsight[], ui: UiText): string {
+	if (!struggles.length) return `<p class="empty">${escapeHtml(ui.noneYet)}</p>`;
+	return struggles
+		.slice(0, 12)
+		.map((item) => {
+			const attempts = item.attempts.length
+				? `<div class="sub-line"><strong>${escapeHtml(ui.attempts)}:</strong> ${item.attempts.map((a) => escapeHtml(a)).join(" | ")}</div>`
+				: "";
+			const solution = item.solution
+				? `<div class="sub-line"><strong>${escapeHtml(ui.solution)}:</strong> ${escapeHtml(item.solution)}</div>`
+				: "";
+			return `<article class="item-card ${item.resolved ? "ok" : "warn"}">
+  <div class="item-title">${escapeHtml(item.problem)}</div>
+  ${attempts}
+  ${solution}
+  <div class="meta-row">
+    <span>${escapeHtml(ui.status)}: ${item.resolved ? escapeHtml(ui.resolved) : escapeHtml(ui.unresolved)}</span>
+    <span>${escapeHtml(ui.weight)}: ${item.weight.toFixed(2)}</span>
+  </div>
+</article>`;
+		})
+		.join("");
+}
+
+function renderMemoryList(entries: MemoryEntry[], empty: string): string {
+	if (!entries.length) return `<p class="empty">${escapeHtml(empty)}</p>`;
+	return `<ul class="list">${entries
+		.map((entry) => `<li>${escapeHtml(entry.content)}${entry.tags.length ? ` <span class="tags">${entry.tags.slice(0, 4).map((tag) => `#${escapeHtml(tag)}`).join(" ")}</span>` : ""}</li>`)
+		.join("")}</ul>`;
+}
+
+function renderAtAGlance(report: InsightsReport, projects: Array<{ label: string; value: number }>, ui: UiText): string {
+	const unresolved = report.struggles.filter((item) => !item.resolved);
+	const resolved = report.struggles.filter((item) => item.resolved);
+	const topPattern = report.patterns[0];
+	const topRec = report.recommendations[0];
+	const topProject = projects[0];
+	const working =
+		resolved.length > 0
+			? `${resolved.length} struggles are already resolved; keep reusing those fixes.`
+			: report.topLessons.length
+				? `${report.topLessons.length} lessons captured; convert the top ones into repeatable checklists.`
+				: ui.noneYet;
+	const hindering = unresolved.length
+		? `${unresolved.length} open struggles remain. Most frequent: "${unresolved[0]?.problem ?? ""}".`
+		: "No unresolved struggles currently visible.";
+	const quickWins = topRec ? topRec : ui.noneYet;
+	const focus = topProject
+		? `${topProject.label} appears most often (${topProject.value} memories).`
+		: topPattern
+			? `Dominant behavior: when "${topPattern.trigger}", you often "${topPattern.behavior}".`
+			: ui.noneYet;
+	return `<section class="glance">
+  <h2>${escapeHtml(ui.atAGlance)}</h2>
+  <div class="glance-grid">
+    <article class="glance-card">
+      <h3>${escapeHtml(ui.whatsWorking)}</h3>
+      <p>${escapeHtml(working)}</p>
+    </article>
+    <article class="glance-card warn">
+      <h3>${escapeHtml(ui.whatsHindering)}</h3>
+      <p>${escapeHtml(hindering)}</p>
+    </article>
+    <article class="glance-card">
+      <h3>${escapeHtml(ui.quickWins)}</h3>
+      <p>${escapeHtml(quickWins)}</p>
+    </article>
+    <article class="glance-card">
+      <h3>${escapeHtml(ui.focusArea)}</h3>
+      <p>${escapeHtml(focus)}</p>
+    </article>
+  </div>
+</section>`;
+}
+
+function renderRecommendations(report: InsightsReport, title: string, empty: string): string {
+	if (!report.recommendations.length) return `<section class="section"><h2>${escapeHtml(title)}</h2><p class="empty">${escapeHtml(empty)}</p></section>`;
+	return `<section id="section-recommendations" class="section">
+  <h2>${escapeHtml(title)}</h2>
+  <ul class="recommend-list">${report.recommendations.map((rec) => `<li>${escapeHtml(rec)}</li>`).join("")}</ul>
+</section>`;
+}
+
+export function renderInsightsHtml(report: InsightsReport, locale: string): string {
+	const isZh = locale === "zh";
+	const ui = UI[isZh ? "zh" : "en"];
+	const prompts = PROMPTS[locale] ?? PROMPTS.en;
+
+	const allEntries = dedupeById([...report.topKnowledge, ...report.topLessons, ...report.preferences]);
+	const projects = topProjects(allEntries);
+	const tags = topTags(allEntries);
+	const unresolved = report.struggles.filter((item) => !item.resolved);
+	const resolved = report.struggles.filter((item) => item.resolved);
+
+	const statsRow = [
+		{ label: "Sessions", value: report.stats.totalSessions },
+		{ label: "Knowledge", value: report.stats.knowledge },
+		{ label: "Lessons", value: report.stats.lessons },
+		{ label: "Preferences", value: report.stats.preferences },
+		{ label: "Struggles", value: report.struggles.length },
+		{ label: "Patterns", value: report.patterns.length },
+	];
+
+	const css = `
+*{box-sizing:border-box}
+body{margin:0;padding:48px 24px;font-family:Inter,"Segoe UI",Arial,sans-serif;background:#f8fafc;color:#334155;line-height:1.65}
+.container{max-width:960px;margin:0 auto}
+h1{font-size:34px;font-weight:700;color:#0f172a;margin:0 0 8px}
+h2{font-size:22px;font-weight:700;color:#0f172a;margin:0 0 14px}
+h3{font-size:15px;font-weight:700;color:#1e293b;margin:0 0 8px}
+.subtitle{color:#64748b;font-size:14px;margin:0 0 24px}
+.toc{display:flex;flex-wrap:wrap;gap:8px;padding:14px;background:#fff;border:1px solid #e2e8f0;border-radius:10px;margin:0 0 24px}
+.toc a{font-size:12px;color:#475569;background:#f1f5f9;border-radius:6px;padding:6px 10px;text-decoration:none}
+.toc a:hover{background:#e2e8f0}
+.stats{display:grid;grid-template-columns:repeat(auto-fit,minmax(120px,1fr));gap:12px;padding:20px 0;border-top:1px solid #e2e8f0;border-bottom:1px solid #e2e8f0;margin:0 0 28px}
+.stat{text-align:center}
+.stat-value{font-size:24px;font-weight:700;color:#0f172a}
+.stat-label{font-size:11px;color:#64748b;text-transform:uppercase}
+.glance{background:linear-gradient(135deg,#fef3c7 0%,#fde68a 100%);border:1px solid #f59e0b;border-radius:12px;padding:20px 22px;margin:0 0 28px}
+.glance-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:10px}
+.glance-card{background:rgba(255,255,255,.62);border:1px solid rgba(245,158,11,.28);border-radius:8px;padding:12px}
+.glance-card.warn{background:rgba(255,241,242,.82);border-color:#fca5a5}
+.glance-card p{margin:0;font-size:13px;color:#78350f}
+.section{background:#fff;border:1px solid #e2e8f0;border-radius:10px;padding:18px;margin:0 0 16px}
+.section-intro{font-size:13px;color:#64748b;margin:0 0 12px}
+.project-list{display:flex;flex-direction:column;gap:10px}
+.project-area{background:#f8fafc;border:1px solid #e2e8f0;border-radius:8px;padding:14px}
+.area-header{display:flex;justify-content:space-between;align-items:center;gap:10px}
+.area-name{font-size:15px;font-weight:700;color:#0f172a}
+.area-count{font-size:12px;color:#64748b;background:#f1f5f9;padding:2px 8px;border-radius:4px}
+.area-desc{margin:8px 0 0;font-size:13px;color:#475569}
+.charts{display:grid;grid-template-columns:1fr 1fr;gap:16px}
+.chart{background:#fff;border:1px solid #e2e8f0;border-radius:8px;padding:14px}
+.chart-title{font-size:12px;color:#64748b;text-transform:uppercase;margin:0 0 10px}
+.bar-row{display:flex;align-items:center;gap:8px;margin-bottom:7px}
+.bar-label{width:120px;flex-shrink:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-size:12px;color:#475569}
+.bar-track{flex:1;height:7px;background:#f1f5f9;border-radius:99px}
+.bar-fill{height:100%;border-radius:99px}
+.bar-fill.blue{background:#2563eb}
+.bar-fill.cyan{background:#0891b2}
+.bar-value{width:24px;text-align:right;font-size:12px;color:#64748b}
+.recommend-list{margin:0;padding:0;list-style:none;display:flex;flex-direction:column;gap:8px}
+.recommend-list li{background:#f0fdf4;border:1px solid #bbf7d0;border-left:4px solid #16a34a;border-radius:8px;padding:11px 12px;font-size:14px}
+.item-grid{display:flex;flex-direction:column;gap:10px}
+.item-card{background:#f8fafc;border:1px solid #e2e8f0;border-radius:8px;padding:12px}
+.item-card.ok{background:#f0fdf4;border-color:#86efac}
+.item-card.warn{background:#fef2f2;border-color:#fca5a5}
+.item-title{font-size:14px;color:#0f172a}
+.arrow{color:#94a3b8}
+.weight-track{margin-top:8px;height:6px;background:#e2e8f0;border-radius:99px}
+.weight-fill{height:100%;background:#2563eb;border-radius:99px}
+.sub-line{margin-top:8px;font-size:13px;color:#334155}
+.meta-row{display:flex;gap:12px;flex-wrap:wrap;margin-top:8px;font-size:12px;color:#64748b}
+details{border:1px solid #e2e8f0;border-radius:8px;background:#f8fafc;padding:10px 12px;margin-bottom:10px}
+summary{cursor:pointer;font-size:14px;font-weight:700;color:#334155}
+.list{margin:10px 0 0;padding-left:18px}
+.list li{margin:0 0 8px;font-size:13px;color:#334155}
+.tags{font-size:12px;color:#64748b}
+.empty{font-size:13px;color:#94a3b8}
+footer{margin-top:22px;text-align:center;font-size:12px;color:#94a3b8}
+@media (max-width:760px){body{padding:28px 14px}.charts{grid-template-columns:1fr}.bar-label{width:96px}}
+`;
+
+	return `<!doctype html>
+<html lang="${isZh ? "zh-CN" : "en"}">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${escapeHtml(prompts.insightsTitle)}</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
+  <style>${css}</style>
+</head>
+<body>
+  <main class="container">
+    <h1>${escapeHtml(prompts.insightsTitle)}</h1>
+    <p class="subtitle">${report.stats.totalSessions} ${escapeHtml(ui.subtitle)} | ${escapeHtml(prompts.insightsGeneratedAt)}: ${escapeHtml(formatDate(report.generatedAt, locale))}</p>
+
+    <nav class="toc">
+      <a href="#section-work">${escapeHtml(ui.workOn)}</a>
+      <a href="#section-distribution">${escapeHtml(ui.distribution)}</a>
+      <a href="#section-recommendations">${escapeHtml(prompts.insightsSectionRecommendations)}</a>
+      <a href="#section-patterns">${escapeHtml(prompts.insightsSectionPatterns)}</a>
+      <a href="#section-struggles">${escapeHtml(prompts.insightsSectionStruggles)}</a>
+      <a href="#section-memory">${escapeHtml(ui.knowledgePrefs)}</a>
+    </nav>
+
+    <section class="stats">
+      ${statsRow
+				.map((item) => `<div class="stat"><div class="stat-value">${item.value}</div><div class="stat-label">${escapeHtml(item.label)}</div></div>`)
+				.join("")}
+    </section>
+
+    ${renderAtAGlance(report, projects, ui)}
+
+    <section id="section-work" class="section">
+      <h2>${escapeHtml(ui.workOn)}</h2>
+      <p class="section-intro">${escapeHtml(ui.workOnIntro)}</p>
+      <div class="project-list">${renderProjectAreas(projects, allEntries, ui)}</div>
+    </section>
+
+    <section id="section-distribution" class="section">
+      <h2>${escapeHtml(ui.distribution)}</h2>
+      <div class="charts">
+        <div class="chart">
+          <p class="chart-title">${escapeHtml(ui.topProjects)}</p>
+          ${renderBarRows(projects, "blue", ui.noneYet)}
+        </div>
+        <div class="chart">
+          <p class="chart-title">${escapeHtml(ui.frequentTags)}</p>
+          ${renderBarRows(tags, "cyan", ui.noneYet)}
+        </div>
+      </div>
+    </section>
+
+    ${renderRecommendations(report, prompts.insightsSectionRecommendations, prompts.insightsNoData)}
+
+    <section class="section">
+      <h2>${escapeHtml(ui.successes)}</h2>
+      <p class="section-intro">${escapeHtml(ui.successesIntro)}</p>
+      <div class="item-grid">
+        ${renderStruggleRows(resolved, ui)}
+        ${renderMemoryList(report.topLessons.slice(0, 5), ui.noneYet)}
+      </div>
+    </section>
+
+    <section class="section">
+      <h2>${escapeHtml(ui.frictions)}</h2>
+      <p class="section-intro">${escapeHtml(ui.frictionsIntro)}</p>
+      <div class="item-grid">${renderStruggleRows(unresolved, ui)}</div>
+    </section>
+
+    <section id="section-patterns" class="section">
+      <h2>${escapeHtml(prompts.insightsSectionPatterns)}</h2>
+      <div class="item-grid">${renderPatternRows(report.patterns, ui)}</div>
+    </section>
+
+    <section id="section-struggles" class="section">
+      <h2>${escapeHtml(prompts.insightsSectionStruggles)}</h2>
+      <div class="item-grid">${renderStruggleRows(report.struggles, ui)}</div>
+    </section>
+
+    <section id="section-memory" class="section">
+      <h2>${escapeHtml(ui.knowledgePrefs)}</h2>
+      <details open>
+        <summary>${escapeHtml(ui.lessons)} (${report.topLessons.length})</summary>
+        ${renderMemoryList(report.topLessons.slice(0, 12), ui.noneYet)}
+      </details>
+      <details>
+        <summary>${escapeHtml(ui.knowledge)} (${report.topKnowledge.length})</summary>
+        ${renderMemoryList(report.topKnowledge.slice(0, 12), ui.noneYet)}
+      </details>
+      <details>
+        <summary>${escapeHtml(ui.preferences)} (${report.preferences.length})</summary>
+        ${renderMemoryList(report.preferences.slice(0, 12), ui.noneYet)}
+      </details>
+    </section>
+
+    <footer>${escapeHtml(ui.generatedBy)}</footer>
+  </main>
+</body>
+</html>`;
+}

package/src/linking.ts

@@ -0,0 +1,43 @@
+/**
+ * [INPUT]: new MemoryEntry, existing entries
+ * [OUTPUT]: bidirectional relatedIds links established
+ * [POS]: A-MEM style Zettelkasten linking — atomic storage + dynamic associations
+ */
+
+import { tagOverlap } from "./scoring.js";
+import type { MemoryEntry } from "./types.js";
+
+const LINK_THRESHOLD = 0.5;
+const MAX_LINKS = 5;
+
+/** Find related entries by tag overlap and establish bidirectional links */
+export function linkNewEntry(newEntry: MemoryEntry, allEntries: MemoryEntry[]): void {
+	if (!newEntry.relatedIds) newEntry.relatedIds = [];
+
+	const candidates = allEntries
+		.filter((e) => e.id !== newEntry.id)
+		.map((e) => ({ entry: e, overlap: tagOverlap(newEntry.tags, e.tags) }))
+		.filter((c) => c.overlap >= LINK_THRESHOLD)
+		.sort((a, b) => b.overlap - a.overlap)
+		.slice(0, MAX_LINKS);
+
+	for (const { entry } of candidates) {
+		if (!newEntry.relatedIds.includes(entry.id)) {
+			newEntry.relatedIds.push(entry.id);
+		}
+		if (!entry.relatedIds) entry.relatedIds = [];
+		if (!entry.relatedIds.includes(newEntry.id)) {
+			entry.relatedIds.push(newEntry.id);
+		}
+	}
+}
+
+/** Get content summaries for related entries (for injection enrichment) */
+export function getRelatedSummaries(entry: MemoryEntry, allEntries: MemoryEntry[], maxCount = 3): string[] {
+	if (!entry.relatedIds?.length) return [];
+	const idSet = new Set(entry.relatedIds);
+	return allEntries
+		.filter((e) => idSet.has(e.id))
+		.slice(0, maxCount)
+		.map((e) => e.content.slice(0, 80));
+}

package/src/privacy.ts

@@ -0,0 +1,52 @@
+/**
+ * [INPUT]: text content, MemoryEntry with scope/ttl
+ * [OUTPUT]: sanitized text, scope-filtered entries, ttl-expired entries removed
+ * [POS]: MemoryOps layer — scope isolation, TTL enforcement, PII filtering
+ */
+
+import { daysSince } from "./scoring.js";
+import type { MemoryEntry, MemoryScope, WorkEntry } from "./types.js";
+
+const PII_PATTERNS = [
+	/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g, // email
+	/\b(?:\+?1[-.]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/g, // US phone
+	/\b1[3-9]\d{9}\b/g, // CN mobile
+	/\b\d{3}-\d{2}-\d{4}\b/g, // US SSN
+	/\b[1-9]\d{5}(?:19|20)\d{2}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\d|3[01])\d{3}[\dXx]\b/g, // CN ID
+	/\b(?:4\d{3}|5[1-5]\d{2}|6011|3[47]\d{2})[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/g, // credit card
+];
+
+export function filterPII(text: string): string {
+	let result = text;
+	for (const pattern of PII_PATTERNS) {
+		result = result.replace(pattern, "[REDACTED]");
+	}
+	return result;
+}
+
+export function matchesScope(entry: { scope?: MemoryScope }, required?: MemoryScope): boolean {
+	if (!required) return true;
+	if (!entry.scope) return true;
+	if (required.userId && entry.scope.userId && entry.scope.userId !== required.userId) return false;
+	if (required.agentId && entry.scope.agentId && entry.scope.agentId !== required.agentId) return false;
+	return true;
+}
+
+export function filterByScope<T extends { scope?: MemoryScope }>(entries: T[], scope?: MemoryScope): T[] {
+	if (!scope) return entries;
+	return entries.filter((e) => matchesScope(e, scope));
+}
+
+export function evictExpiredEntries(entries: MemoryEntry[]): MemoryEntry[] {
+	return entries.filter((e) => {
+		if (e.ttl === undefined) return true;
+		return daysSince(e.created) < e.ttl;
+	});
+}
+
+export function evictExpiredWork(entries: WorkEntry[]): WorkEntry[] {
+	return entries.filter((w) => {
+		if (w.ttl === undefined) return true;
+		return daysSince(w.created) < w.ttl;
+	});
+}

package/src/scoring.ts

@@ -0,0 +1,94 @@
+/**
+ * [INPUT]: MemoryEntry/Episode/WorkEntry, project, context tags, config weights
+ * [OUTPUT]: retrieval score (Stanford: Recency + Importance + Relevance)
+ * [POS]: Core ranking algorithm — used by engine for injection budget allocation
+ *
+ * Key innovation: uses per-entry adaptive strength (not global half-life)
+ * for Recency, implementing Ebbinghaus spaced repetition.
+ */
+
+import type { Episode, MemoryEntry, WorkEntry } from "./types.js";
+
+export function daysSince(iso: string): number {
+	return Math.max(0, (Date.now() - new Date(iso).getTime()) / 86_400_000);
+}
+
+/** Ebbinghaus decay: R = e^(-t * ln2 / S) where S = per-entry strength */
+export function decay(ageDays: number, strength: number): number {
+	return Math.exp((-ageDays * Math.LN2) / Math.max(1, strength));
+}
+
+export function extractTags(text: string): string[] {
+	return [...new Set(text.toLowerCase().match(/[a-z0-9\u4e00-\u9fff_.-]{2,}/g) || [])].slice(0, 30);
+}
+
+export function tagOverlap(a: string[], b: string[]): number {
+	if (!a.length || !b.length) return 0;
+	const setB = new Set(b);
+	return a.filter((t) => setB.has(t)).length / Math.max(a.length, b.length);
+}
+
+export interface ScoreWeights {
+	recency: number;
+	importance: number;
+	relevance: number;
+}
+
+export function scoreEntry(
+	e: MemoryEntry,
+	project: string,
+	ctx: string[],
+	defaultHalfLife: Record<string, number>,
+	weights: ScoreWeights,
+): number {
+	const strength = e.strength || defaultHalfLife[e.type] || 30;
+	const recency = decay(daysSince(e.created), strength);
+	const importanceNorm = Math.min(1, e.importance / 10);
+	const projectMatch = e.project === project ? 1 : 0.5;
+	const relevance = projectMatch * (0.3 + 0.7 * tagOverlap(e.tags, ctx));
+	return weights.recency * recency + weights.importance * importanceNorm + weights.relevance * relevance;
+}
+
+export function scoreEpisode(
+	ep: Episode,
+	project: string,
+	ctx: string[],
+	defaultHalfLife: Record<string, number>,
+	weights: ScoreWeights,
+): number {
+	const strength = defaultHalfLife.episode || 14;
+	const recency = decay(daysSince(ep.date), strength);
+	const importanceNorm = Math.min(1, ep.importance / 10);
+	const projectMatch = ep.project === project ? 1 : 0.5;
+	const relevance = projectMatch * (0.3 + 0.7 * tagOverlap(ep.tags, ctx));
+	return weights.recency * recency + weights.importance * importanceNorm + weights.relevance * relevance;
+}
+
+export function scoreWorkEntry(
+	w: WorkEntry,
+	project: string,
+	ctx: string[],
+	defaultHalfLife: Record<string, number>,
+	weights: ScoreWeights,
+): number {
+	const strength = w.strength || defaultHalfLife.work || 45;
+	const recency = decay(daysSince(w.created), strength);
+	const importanceNorm = Math.min(1, w.importance / 10);
+	const projectMatch = w.project === project ? 1 : 0.5;
+	const relevance = projectMatch * (0.3 + 0.7 * tagOverlap(w.tags, ctx));
+	return weights.recency * recency + weights.importance * importanceNorm + weights.relevance * relevance;
+}
+
+/** Budget-constrained top-k selection by score */
+export function pickTop<T>(items: T[], scoreFn: (t: T) => number, lenFn: (t: T) => number, budget: number): T[] {
+	const scored = items.map((t) => ({ item: t, score: scoreFn(t) })).sort((a, b) => b.score - a.score);
+	const result: T[] = [];
+	let used = 0;
+	for (const { item } of scored) {
+		const len = lenFn(item);
+		if (used + len > budget) continue;
+		used += len;
+		result.push(item);
+	}
+	return result;
+}