Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

feat: cross-encoder reranking, working memory, skill extraction (#93)

Rohit Ghumare69bb78762969
diff --git a/package-lock.json b/package-lock.json
index 416b6856..a0804c8f 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "@agentmemory/agentmemory",
- "version": "0.7.5",
+ "version": "0.8.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@agentmemory/agentmemory",
- "version": "0.7.5",
+ "version": "0.8.0",
"license": "Apache-2.0",
"dependencies": {
"@anthropic-ai/claude-agent-sdk": "^0.2.56",
diff --git a/package.json b/package.json
index 38a5ff22..c79375da 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "@agentmemory/agentmemory",
- "version": "0.7.5",
+ "version": "0.8.0",
"description": "Persistent memory for AI coding agents, powered by iii-engine's three primitives",
"type": "module",
"main": "dist/index.mjs",
diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json
index 1c04afc8..b6bfb7e7 100644
--- a/plugin/.claude-plugin/plugin.json
+++ b/plugin/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "agentmemory",
- "version": "0.7.5",
+ "version": "0.8.0",
"description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 43 MCP tools, 4 skills, real-time viewer.",
"author": "Rohit Ghumare",
"license": "Apache-2.0",
diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts
index 1e796e20..702a98b6 100644
--- a/src/functions/export-import.ts
+++ b/src/functions/export-import.ts
@@ -170,7 +170,7 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void {
const strategy = data.strategy || "merge";
const importData = data.exportData;
- const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5"]);
+ const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.8.0"]);
if (!supportedVersions.has(importData.version)) {
return {
success: false,
diff --git a/src/functions/skill-extract.ts b/src/functions/skill-extract.ts
new file mode 100644
index 00000000..60a3c505
--- /dev/null
+++ b/src/functions/skill-extract.ts
@@ -0,0 +1,304 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import type {
+ CompressedObservation,
+ SessionSummary,
+ ProceduralMemory,
+ Session,
+ MemoryProvider,
+} from "../types.js";
+import { KV, generateId, fingerprintId } from "../state/schema.js";
+import { StateKV } from "../state/kv.js";
+import { recordAudit } from "./audit.js";
+
+const SKILL_EXTRACT_SYSTEM = `You are a skill extraction engine. Given a completed multi-step task session, extract a reusable procedural skill document.
+
+Output format:
+<skill>
+<trigger>When the agent encounters [specific situation/pattern]</trigger>
+<title>Short skill title</title>
+<steps>
+<step>First concrete action</step>
+<step>Second concrete action</step>
+</steps>
+<expected_outcome>What success looks like</expected_outcome>
+<tags>comma,separated,tags</tags>
+</skill>
+
+Rules:
+- Extract ONLY if the session shows a clear multi-step procedure that succeeded
+- Steps must be concrete and actionable, not vague
+- The trigger should describe WHEN to apply this skill
+- If the session is exploratory with no clear procedure, output <no-skill/>
+- Maximum 10 steps per skill`;
+
+function buildSkillPrompt(
+ summary: SessionSummary,
+ observations: CompressedObservation[],
+): string {
+ const obsText = observations
+ .filter((o) => o.importance >= 4)
+ .sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime())
+ .slice(0, 30)
+ .map(
+ (o) =>
+ `[${o.type}] ${o.title}${o.narrative ? ": " + o.narrative : ""}`,
+ )
+ .join("\n");
+
+ return `## Session Summary
+Title: ${summary.title}
+Narrative: ${summary.narrative}
+Key Decisions: ${summary.keyDecisions.join("; ")}
+Files Modified: ${summary.filesModified.join(", ")}
+Concepts: ${summary.concepts.join(", ")}
+
+## Observations (${observations.length} total, showing top by importance)
+${obsText}`;
+}
+
+function parseSkillXml(
+ xml: string,
+): {
+ trigger: string;
+ title: string;
+ steps: string[];
+ expectedOutcome: string;
+ tags: string[];
+} | null {
+ if (xml.includes("<no-skill/>")) return null;
+
+ const triggerMatch = xml.match(/<trigger>([\s\S]*?)<\/trigger>/);
+ const titleMatch = xml.match(/<title>([\s\S]*?)<\/title>/);
+ const stepsMatch = xml.match(/<steps>([\s\S]*?)<\/steps>/);
+ const outcomeMatch = xml.match(
+ /<expected_outcome>([\s\S]*?)<\/expected_outcome>/,
+ );
+ const tagsMatch = xml.match(/<tags>([\s\S]*?)<\/tags>/);
+
+ if (!triggerMatch || !titleMatch || !stepsMatch) return null;
+
+ const stepRegex = /<step>([\s\S]*?)<\/step>/g;
+ const steps: string[] = [];
+ let match;
+ while ((match = stepRegex.exec(stepsMatch[1])) !== null) {
+ const step = match[1].trim();
+ if (step) steps.push(step);
+ }
+
+ if (steps.length < 2) return null;
+
+ return {
+ trigger: triggerMatch[1].trim(),
+ title: titleMatch[1].trim(),
+ steps,
+ expectedOutcome: outcomeMatch?.[1]?.trim() || "",
+ tags: tagsMatch?.[1]
+ ?.split(",")
+ .map((t) => t.trim())
+ .filter(Boolean) || [],
+ };
+}
+
+export function registerSkillExtractFunctions(
+ sdk: ISdk,
+ kv: StateKV,
+ provider: MemoryProvider,
+): void {
+ sdk.registerFunction(
+ {
+ id: "mem::skill-extract",
+ description:
+ "Extract a reusable skill document from a completed session",
+ },
+ async (data: { sessionId: string }) => {
+ const ctx = getContext();
+ if (!data?.sessionId) {
+ return { success: false, error: "sessionId is required" };
+ }
+
+ const session = await kv
+ .get<Session>(KV.sessions, data.sessionId)
+ .catch(() => null);
+ if (!session) {
+ return { success: false, error: "session not found" };
+ }
+ if (session.status !== "completed") {
+ return {
+ success: false,
+ error: "session must be completed before skill extraction",
+ };
+ }
+
+ const [summary, observations] = await Promise.all([
+ kv.get<SessionSummary>(KV.summaries, data.sessionId).catch(() => null),
+ kv.list<CompressedObservation>(KV.observations(data.sessionId)).catch(() => []),
+ ]);
+ if (!summary) {
+ return {
+ success: false,
+ error: "no summary — run mem::summarize first",
+ };
+ }
+ if (observations.length < 3) {
+ return { success: false, error: "too few observations for skill extraction" };
+ }
+
+ try {
+ const prompt = buildSkillPrompt(summary, observations);
+ const response = await provider.summarize(
+ SKILL_EXTRACT_SYSTEM,
+ prompt,
+ );
+ const parsed = parseSkillXml(response);
+
+ if (!parsed) {
+ ctx.logger.info("No skill extracted — session was exploratory", {
+ sessionId: data.sessionId,
+ });
+ return { success: true, extracted: false, reason: "no clear procedure found" };
+ }
+
+ const fp = fingerprintId(
+ "skill",
+ JSON.stringify({
+ title: parsed.title.toLowerCase(),
+ trigger: parsed.trigger.toLowerCase(),
+ steps: parsed.steps.map((s) => s.toLowerCase().trim()),
+ }),
+ );
+ const existing = await kv
+ .get<ProceduralMemory>(KV.procedural, fp)
+ .catch(() => null);
+
+ if (existing) {
+ const alreadyReinforced = existing.sourceSessionIds.includes(data.sessionId);
+ if (!alreadyReinforced) {
+ existing.strength = Math.min(1.0, existing.strength + 0.15);
+ existing.frequency++;
+ existing.sourceSessionIds = [...existing.sourceSessionIds, data.sessionId];
+ }
+ existing.updatedAt = new Date().toISOString();
+ await kv.set(KV.procedural, existing.id, existing);
+
+ try {
+ await recordAudit(kv, "skill_extract", "mem::skill-extract", [], {
+ skillId: existing.id,
+ reinforced: true,
+ sessionId: data.sessionId,
+ });
+ } catch {}
+
+ ctx.logger.info("Skill reinforced", {
+ id: existing.id,
+ name: parsed.title,
+ });
+ return {
+ success: true,
+ extracted: true,
+ reinforced: true,
+ skill: existing,
+ };
+ }
+
+ const now = new Date().toISOString();
+ const skill: ProceduralMemory = {
+ id: fp,
+ name: parsed.title,
+ triggerCondition: parsed.trigger,
+ steps: parsed.steps,
+ expectedOutcome: parsed.expectedOutcome,
+ strength: 0.6,
+ frequency: 1,
+ tags: parsed.tags,
+ concepts: summary.concepts,
+ sourceSessionIds: [data.sessionId],
+ sourceObservationIds: observations
+ .slice(0, 10)
+ .map((o) => o.id),
+ createdAt: now,
+ updatedAt: now,
+ };
+
+ await kv.set(KV.procedural, skill.id, skill);
+
+ try {
+ await recordAudit(kv, "skill_extract", "mem::skill-extract", [], {
+ skillId: skill.id,
+ title: parsed.title,
+ steps: parsed.steps.length,
+ sessionId: data.sessionId,
+ });
+ } catch {}
+
+ ctx.logger.info("Skill extracted", {
+ id: skill.id,
+ title: parsed.title,
+ steps: parsed.steps.length,
+ });
+
+ return { success: true, extracted: true, reinforced: false, skill };
+ } catch (err) {
+ const msg = err instanceof Error ? err.message : String(err);
+ ctx.logger.error("Skill extraction failed", { error: msg });
+ return { success: false, error: msg };
+ }
+ },
+ );
+
+ sdk.registerFunction(
+ {
+ id: "mem::skill-list",
+ description: "List extracted procedural skills",
+ },
+ async (data: { limit?: number }) => {
+ const limit = data?.limit ?? 50;
+ const skills = await kv.list<ProceduralMemory>(KV.procedural);
+ const sorted = skills.sort((a, b) => b.strength - a.strength);
+ return {
+ success: true,
+ skills: sorted.slice(0, limit),
+ total: sorted.length,
+ };
+ },
+ );
+
+ sdk.registerFunction(
+ {
+ id: "mem::skill-match",
+ description: "Find skills relevant to a given task description",
+ },
+ async (data: { query: string; limit?: number }) => {
+ if (!data?.query?.trim()) {
+ return { success: false, error: "query is required" };
+ }
+
+ const limit = data.limit ?? 5;
+ const query = data.query.toLowerCase();
+ const terms = query.split(/\s+/).filter((t) => t.length > 2);
+
+ const skills = await kv.list<ProceduralMemory>(KV.procedural);
+
+ const scored = skills
+ .map((skill) => {
+ const text =
+ `${skill.name} ${skill.triggerCondition} ${(skill.tags || []).join(" ")} ${skill.steps.join(" ")}`.toLowerCase();
+ const matchCount = terms.filter((t) => text.includes(t)).length;
+ if (matchCount === 0) return null;
+ const relevance = matchCount / terms.length;
+ return { skill, score: relevance * skill.strength };
+ })
+ .filter(Boolean) as Array<{
+ skill: ProceduralMemory;
+ score: number;
+ }>;
+
+ scored.sort((a, b) => b.score - a.score);
+
+ return {
+ success: true,
+ matches: scored.slice(0, limit),
+ };
+ },
+ );
+}
diff --git a/src/functions/working-memory.ts b/src/functions/working-memory.ts
new file mode 100644
index 00000000..fcb6b707
--- /dev/null
+++ b/src/functions/working-memory.ts
@@ -0,0 +1,272 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import type { Memory, CompressedObservation, ContextBlock } from "../types.js";
+import { KV, generateId } from "../state/schema.js";
+import { StateKV } from "../state/kv.js";
+import { recordAudit } from "./audit.js";
+
+const CORE_SCOPE = "mem:core-memory";
+
+interface CoreMemoryEntry {
+ id: string;
+ content: string;
+ importance: number;
+ pinned: boolean;
+ accessCount: number;
+ lastAccessedAt: string;
+ createdAt: string;
+}
+
+function estimateTokens(text: string): number {
+ return Math.ceil(text.length / 3);
+}
+
+function scoreEntry(entry: CoreMemoryEntry, now: number): number {
+ const recencyMs = now - new Date(entry.lastAccessedAt).getTime();
+ const recencyDays = recencyMs / (1000 * 60 * 60 * 24);
+ const recencyScore = 1 / (1 + recencyDays * 0.1);
+ const accessScore = Math.log2(entry.accessCount + 1) / 10;
+ const importanceScore = entry.importance / 10;
+ return importanceScore * 0.5 + recencyScore * 0.3 + accessScore * 0.2;
+}
+
+export function registerWorkingMemoryFunctions(
+ sdk: ISdk,
+ kv: StateKV,
+ tokenBudget: number,
+): void {
+ sdk.registerFunction(
+ {
+ id: "mem::core-add",
+ description: "Add a fact to core memory (always included in context)",
+ },
+ async (data: {
+ content: string;
+ importance?: number;
+ pinned?: boolean;
+ }) => {
+ if (!data?.content?.trim()) {
+ return { success: false, error: "content is required" };
+ }
+ const now = new Date().toISOString();
+ const entry: CoreMemoryEntry = {
+ id: generateId("core"),
+ content: data.content.trim(),
+ importance: Math.min(10, Math.max(1, data.importance ?? 7)),
+ pinned: data.pinned ?? false,
+ accessCount: 0,
+ lastAccessedAt: now,
+ createdAt: now,
+ };
+ await kv.set(CORE_SCOPE, entry.id, entry);
+
+ try {
+ await recordAudit(kv, "core_add", "mem::core-add", [entry.id], {
+ content: entry.content.slice(0, 100),
+ importance: entry.importance,
+ pinned: entry.pinned,
+ });
+ } catch {}
+
+ return { success: true, id: entry.id };
+ },
+ );
+
+ sdk.registerFunction(
+ {
+ id: "mem::core-remove",
+ description: "Remove a fact from core memory",
+ },
+ async (data: { id: string }) => {
+ if (!data?.id) return { success: false, error: "id is required" };
+ await kv.delete(CORE_SCOPE, data.id);
+
+ try {
+ await recordAudit(kv, "core_remove", "mem::core-remove", [data.id], {});
+ } catch {}
+
+ return { success: true };
+ },
+ );
+
+ sdk.registerFunction(
+ {
+ id: "mem::core-list",
+ description: "List all core memory entries",
+ },
+ async () => {
+ const entries = await kv.list<CoreMemoryEntry>(CORE_SCOPE);
+ entries.sort((a, b) => b.importance - a.importance);
+ return {
+ success: true,
+ entries,
+ totalTokens: entries.reduce(
+ (sum, e) => sum + estimateTokens(e.content),
+ 0,
+ ),
+ };
+ },
+ );
+
+ sdk.registerFunction(
+ {
+ id: "mem::working-context",
+ description:
+ "Build working context: core memory (pinned) + paged archival (by relevance/recency)",
+ },
+ async (data: { budget?: number }) => {
+ const ctx = getContext();
+ const budget = data.budget || tokenBudget;
+ const now = Date.now();
+ let usedTokens = 0;
+
+ const coreEntries = await kv.list<CoreMemoryEntry>(CORE_SCOPE);
+
+ const pinned = coreEntries.filter((e) => e.pinned);
+ const unpinned = coreEntries
+ .filter((e) => !e.pinned)
+ .sort((a, b) => scoreEntry(b, now) - scoreEntry(a, now));
+
+ const coreLines: string[] = [];
+ const coreBudget = Math.floor(budget * 0.3);
+ const accessUpdates: Array<{ id: string; entry: CoreMemoryEntry }> = [];
+ const accessTimestamp = new Date().toISOString();
+
+ for (const entry of [...pinned, ...unpinned]) {
+ const tokens = estimateTokens(entry.content);
+ if (usedTokens + tokens > coreBudget && !entry.pinned) continue;
+ coreLines.push(`- ${entry.content}`);
+ usedTokens += tokens;
+
+ entry.accessCount++;
+ entry.lastAccessedAt = accessTimestamp;
+ accessUpdates.push({ id: entry.id, entry });
+ }
+
+ Promise.allSettled(
+ accessUpdates.map(({ id, entry }) => kv.set(CORE_SCOPE, id, entry)),
+ ).catch(() => {});
+
+ const archivalLines: string[] = [];
+
+ const memories = await kv.list<Memory>(KV.memories);
+ const active = memories
+ .filter((m) => m.isLatest !== false)
+ .sort((a, b) => {
+ const strengthDiff = b.strength - a.strength;
+ if (Math.abs(strengthDiff) > 0.2) return strengthDiff;
+ return (
+ new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime()
+ );
+ });
+
+ for (const mem of active) {
+ const tokens = estimateTokens(mem.content);
+ if (usedTokens + tokens > budget) continue;
+ archivalLines.push(`- [${mem.type}] ${mem.title}: ${mem.content}`);
+ usedTokens += tokens;
+ }
+
+ const pagedOut = active.length - archivalLines.length;
+
+ const sections: string[] = [];
+ if (coreLines.length > 0) {
+ sections.push(`## Core Memory\n${coreLines.join("\n")}`);
+ }
+ if (archivalLines.length > 0) {
+ sections.push(`## Archival Memory\n${archivalLines.join("\n")}`);
+ }
+ if (pagedOut > 0) {
+ sections.push(
+ `_${pagedOut} memories paged to archival (use mem::search to retrieve)_`,
+ );
+ }
+
+ const context = sections.join("\n\n");
+
+ ctx.logger.info("Working context built", {
+ coreEntries: coreLines.length,
+ archivalEntries: archivalLines.length,
+ pagedOut,
+ tokens: usedTokens,
+ budget,
+ });
+
+ return {
+ success: true,
+ context,
+ coreEntries: coreLines.length,
+ archivalEntries: archivalLines.length,
+ pagedOut,
+ tokens: usedTokens,
+ budget,
+ };
+ },
+ );
+
+ sdk.registerFunction(
+ {
+ id: "mem::auto-page",
+ description:
+ "Automatically page low-value core memory entries to archival when over budget",
+ },
+ async (data: { budget?: number }) => {
+ const budget = data?.budget || tokenBudget;
+ const coreBudget = Math.floor(budget * 0.3);
+
+ const entries = await kv.list<CoreMemoryEntry>(CORE_SCOPE);
+ let totalTokens = entries.reduce(
+ (sum, e) => sum + estimateTokens(e.content),
+ 0,
+ );
+
+ if (totalTokens <= coreBudget) {
+ return { success: true, paged: 0, totalTokens, budget: coreBudget };
+ }
+
+ const now = Date.now();
+ const unpinned = entries
+ .filter((e) => !e.pinned)
+ .sort((a, b) => scoreEntry(a, now) - scoreEntry(b, now));
+
+ let paged = 0;
+ const pagedIds: string[] = [];
+ for (const entry of unpinned) {
+ if (totalTokens <= coreBudget) break;
+ const tokens = estimateTokens(entry.content);
+
+ const archivalMemory: Memory = {
+ id: generateId("mem"),
+ createdAt: entry.createdAt,
+ updatedAt: new Date().toISOString(),
+ type: "fact",
+ title: entry.content.slice(0, 80),
+ content: entry.content,
+ concepts: [],
+ files: [],
+ sessionIds: [],
+ strength: entry.importance / 10,
+ version: 1,
+ isLatest: true,
+ };
+ await kv.set(KV.memories, archivalMemory.id, archivalMemory);
+ await kv.delete(CORE_SCOPE, entry.id);
+
+ totalTokens -= tokens;
+ paged++;
+ pagedIds.push(entry.id);
+ }
+
+ if (paged > 0) {
+ try {
+ await recordAudit(kv, "auto_page", "mem::auto-page", pagedIds, {
+ paged,
+ budget: coreBudget,
+ });
+ } catch {}
+ }
+
+ return { success: true, paged, totalTokens, budget: coreBudget };
+ },
+ );
+}
diff --git a/src/index.ts b/src/index.ts
index 3b83f884..a0219d0f 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -67,6 +67,8 @@ import { registerCascadeFunction } from "./functions/cascade.js";
import { registerLessonsFunctions } from "./functions/lessons.js";
import { registerObsidianExportFunction } from "./functions/obsidian-export.js";
import { registerReflectFunctions } from "./functions/reflect.js";
+import { registerWorkingMemoryFunctions } from "./functions/working-memory.js";
+import { registerSkillExtractFunctions } from "./functions/skill-extract.js";
import { registerSlidingWindowFunction } from "./functions/sliding-window.js";
import { registerQueryExpansionFunction } from "./functions/query-expansion.js";
import { registerTemporalGraphFunctions } from "./functions/temporal-graph.js";
@@ -196,6 +198,8 @@ async function main() {
registerLessonsFunctions(sdk, kv);
registerObsidianExportFunction(sdk, kv);
registerReflectFunctions(sdk, kv, provider);
+ registerWorkingMemoryFunctions(sdk, kv, config.tokenBudget);
+ registerSkillExtractFunctions(sdk, kv, provider);
registerCascadeFunction(sdk, kv);
registerSlidingWindowFunction(sdk, kv, provider);
diff --git a/src/state/hybrid-search.ts b/src/state/hybrid-search.ts
index 4953739f..d05fca2f 100644
--- a/src/state/hybrid-search.ts
+++ b/src/state/hybrid-search.ts
@@ -13,6 +13,7 @@ import {
type GraphRetrievalResult,
} from "../functions/graph-retrieval.js";
import { extractEntitiesFromQuery } from "../functions/query-expansion.js";
+import { rerank } from "./reranker.js";
const RRF_K = 60;
@@ -27,6 +28,7 @@ export class HybridSearch {
private bm25Weight = 0.4,
private vectorWeight = 0.6,
private graphWeight = 0.3,
+ private rerankEnabled = process.env.RERANK_ENABLED === "true",
) {
this.graphRetrieval = new GraphRetrieval(kv);
}
@@ -215,8 +217,24 @@ export class HybridSearch {
}));
combined.sort((a, b) => b.combinedScore - a.combinedScore);
- const diversified = this.diversifyBySession(combined, limit);
- return this.enrichResults(diversified, limit);
+
+ const retrievalDepth = Math.max(limit, 20);
+ const rerankWindow = 20;
+ const diversified = this.diversifyBySession(combined, retrievalDepth);
+ const enriched = await this.enrichResults(diversified, retrievalDepth);
+
+ if (this.rerankEnabled && enriched.length > 1) {
+ try {
+ const head = enriched.slice(0, rerankWindow);
+ const tail = enriched.slice(rerankWindow);
+ const reranked = await rerank(query, head, rerankWindow);
+ return reranked.concat(tail).slice(0, limit);
+ } catch {
+ return enriched.slice(0, limit);
+ }
+ }
+
+ return enriched.slice(0, limit);
}
private diversifyBySession(
diff --git a/src/state/reranker.ts b/src/state/reranker.ts
new file mode 100644
index 00000000..d0aae68c
--- /dev/null
+++ b/src/state/reranker.ts
@@ -0,0 +1,74 @@
+import type { HybridSearchResult } from "../types.js";
+
+let pipeline: any = null;
+let pipelineLoading: Promise<any> | null = null;
+let pipelineUnavailable = false;
+
+async function loadPipeline(): Promise<any> {
+ if (pipelineUnavailable) return null;
+ if (pipeline) return pipeline;
+ if (pipelineLoading) return pipelineLoading;
+
+ pipelineLoading = (async () => {
+ try {
+ const { pipeline: createPipeline } = await import(
+ "@xenova/transformers"
+ );
+ pipeline = await createPipeline(
+ "text-classification",
+ "Xenova/ms-marco-MiniLM-L-6-v2",
+ { quantized: true },
+ );
+ return pipeline;
+ } catch {
+ pipeline = null;
+ pipelineUnavailable = true;
+ return null;
+ } finally {
+ pipelineLoading = null;
+ }
+ })();
+ return pipelineLoading;
+}
+
+export async function rerank(
+ query: string,
+ results: HybridSearchResult[],
+ topK = 20,
+): Promise<HybridSearchResult[]> {
+ if (results.length <= 1) return results;
+
+ const reranker = await loadPipeline();
+ if (!reranker) return results;
+
+ const candidates = results.slice(0, Math.min(results.length, topK));
+
+ const pairs = candidates.map((r) => ({
+ text: `${query} [SEP] ${r.observation.title || ""} ${r.observation.narrative || ""}`.slice(0, 512),
+ result: r,
+ }));
+
+ const scores: Array<{ result: HybridSearchResult; rerankScore: number }> = [];
+
+ for (const pair of pairs) {
+ try {
+ const output = await reranker(pair.text);
+ const score = Array.isArray(output) ? output[0]?.score ?? 0 : 0;
+ scores.push({ result: pair.result, rerankScore: score });
+ } catch {
+ scores.push({ result: pair.result, rerankScore: pair.result.combinedScore });
+ }
+ }
+
+ scores.sort((a, b) => b.rerankScore - a.rerankScore);
+
+ return scores.map((s, i) => ({
+ ...s.result,
+ combinedScore: s.rerankScore,
+ rerankPosition: i + 1,
+ }));
+}
+
+export function isRerankerAvailable(): boolean {
+ return pipeline !== null;
+}
diff --git a/src/types.ts b/src/types.ts
index f244c050..65557185 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -249,7 +249,7 @@ export interface ExportPagination {
}
export interface ExportData {
- version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5";
+ version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.8.0";
exportedAt: string;
sessions: Session[];
observations: Record<string, CompressedObservation[]>;
@@ -398,8 +398,12 @@ export interface ProceduralMemory {
name: string;
steps: string[];
triggerCondition: string;
+ expectedOutcome?: string;
frequency: number;
sourceSessionIds: string[];
+ sourceObservationIds?: string[];
+ tags?: string[];
+ concepts?: string[];
strength: number;
createdAt: string;
updatedAt: string;
@@ -467,7 +471,11 @@ export interface AuditEntry {
| "lesson_strengthen"
| "obsidian_export"
| "reflect"
- | "insight_search";
+ | "insight_search"
+ | "skill_extract"
+ | "core_add"
+ | "core_remove"
+ | "auto_page";
userId?: string;
functionId: string;
targetIds: string[];
diff --git a/src/version.ts b/src/version.ts
index f073b912..44273fb7 100644
--- a/src/version.ts
+++ b/src/version.ts
@@ -1 +1 @@
-export const VERSION: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" = "0.7.5";
+export const VERSION: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.8.0" = "0.8.0";
diff --git a/test/export-import.test.ts b/test/export-import.test.ts
index 274a5196..b013f007 100644
--- a/test/export-import.test.ts
+++ b/test/export-import.test.ts
@@ -118,7 +118,7 @@ describe("Export/Import Functions", () => {
it("export produces valid ExportData structure", async () => {
const result = (await sdk.trigger("mem::export", {})) as ExportData;
- expect(result.version).toBe("0.7.5");
+ expect(result.version).toBe("0.8.0");
expect(result.exportedAt).toBeDefined();
expect(result.sessions.length).toBe(1);
expect(result.sessions[0].id).toBe("ses_1");
diff --git a/test/reranker.test.ts b/test/reranker.test.ts
new file mode 100644
index 00000000..0694e6d5
--- /dev/null
+++ b/test/reranker.test.ts
@@ -0,0 +1,62 @@
+import { describe, it, expect, vi } from "vitest";
+
+vi.mock("@xenova/transformers", () => {
+ throw new Error("not installed");
+});
+
+import { rerank, isRerankerAvailable } from "../src/state/reranker.js";
+
+describe("reranker", () => {
+ it("returns results unchanged when @xenova/transformers is unavailable", async () => {
+ const results = [
+ {
+ observation: {
+ id: "o1",
+ title: "First",
+ narrative: "First result",
+ },
+ bm25Score: 0.5,
+ vectorScore: 0.6,
+ graphScore: 0,
+ combinedScore: 0.8,
+ sessionId: "s1",
+ },
+ {
+ observation: {
+ id: "o2",
+ title: "Second",
+ narrative: "Second result",
+ },
+ bm25Score: 0.3,
+ vectorScore: 0.4,
+ graphScore: 0,
+ combinedScore: 0.5,
+ sessionId: "s1",
+ },
+ ] as any;
+
+ const reranked = await rerank("test query", results);
+ expect(reranked).toEqual(results);
+ });
+
+ it("isRerankerAvailable returns false when not loaded", () => {
+ expect(isRerankerAvailable()).toBe(false);
+ });
+
+ it("handles single result gracefully", async () => {
+ const results = [
+ {
+ observation: { id: "o1", title: "Only" },
+ combinedScore: 1.0,
+ },
+ ] as any;
+
+ const reranked = await rerank("query", results);
+ expect(reranked).toHaveLength(1);
+ });
+
+ it("handles empty results", async () => {
+ const reranked = await rerank("query", []);
+ expect(reranked).toHaveLength(0);
+ });
+});
diff --git a/test/skill-extract.test.ts b/test/skill-extract.test.ts
new file mode 100644
index 00000000..cce85231
--- /dev/null
+++ b/test/skill-extract.test.ts
@@ -0,0 +1,199 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const mockKv = {
+ get: vi.fn(),
+ set: vi.fn(),
+ list: vi.fn(),
+ delete: vi.fn(),
+};
+
+const mockSdk = {
+ registerFunction: vi.fn(),
+};
+
+const mockProvider = {
+ name: "test",
+ compress: vi.fn(),
+ summarize: vi.fn(),
+};
+
+vi.mock("iii-sdk", () => ({
+ getContext: () => ({
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+ }),
+}));
+
+vi.mock("../src/functions/audit.js", () => ({
+ recordAudit: vi.fn(),
+}));
+
+import { registerSkillExtractFunctions } from "../src/functions/skill-extract.js";
+
+describe("skill-extract", () => {
+ let handlers: Record<string, Function>;
+
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mockKv.get.mockResolvedValue(null);
+ mockKv.set.mockResolvedValue(undefined);
+ mockKv.list.mockResolvedValue([]);
+
+ handlers = {};
+ mockSdk.registerFunction.mockImplementation((meta: any, handler: any) => {
+ handlers[meta.id] = handler;
+ });
+
+ registerSkillExtractFunctions(mockSdk as any, mockKv as any, mockProvider);
+ });
+
+ it("registers all skill functions", () => {
+ expect(handlers["mem::skill-extract"]).toBeDefined();
+ expect(handlers["mem::skill-list"]).toBeDefined();
+ expect(handlers["mem::skill-match"]).toBeDefined();
+ });
+
+ it("skill-extract requires sessionId", async () => {
+ const result = await handlers["mem::skill-extract"]({});
+ expect(result.success).toBe(false);
+ });
+
+ it("skill-extract returns error for missing session", async () => {
+ mockKv.get.mockReturnValue(Promise.resolve(null));
+ const result = await handlers["mem::skill-extract"]({
+ sessionId: "nonexistent",
+ });
+ expect(result.success).toBe(false);
+ expect(result.error).toContain("session not found");
+ });
+
+ it("skill-extract parses LLM response into ProceduralMemory", async () => {
+ mockKv.get.mockImplementation((scope: string, key: string) => {
+ if (scope === "mem:sessions")
+ return Promise.resolve({ id: "s1", project: "test", status: "completed" });
+ if (scope === "mem:summaries")
+ return Promise.resolve({
+ sessionId: "s1",
+ project: "test",
+ title: "Fix auth bug",
+ narrative: "Debugged and fixed JWT expiration",
+ keyDecisions: ["Switch to RS256"],
+ filesModified: ["auth.ts"],
+ concepts: ["authentication", "JWT"],
+ createdAt: new Date().toISOString(),
+ observationCount: 10,
+ });
+ return Promise.resolve(null);
+ });
+
+ mockKv.list.mockReturnValue(
+ Promise.resolve(Array.from({ length: 5 }, (_, i) => ({
+ id: `obs${i}`,
+ sessionId: "s1",
+ timestamp: new Date().toISOString(),
+ type: "file_edit",
+ title: `Edit auth.ts step ${i}`,
+ narrative: `Modified JWT validation logic step ${i}`,
+ importance: 7,
+ concepts: ["JWT"],
+ files: ["auth.ts"],
+ facts: [],
+ }))),
+ );
+
+ mockProvider.summarize.mockResolvedValue(`
+<skill>
+<trigger>When the agent encounters JWT authentication failures or token expiration issues</trigger>
+<title>Fix JWT Token Expiration</title>
+<steps>
+<step>Check the JWT library configuration for clock skew tolerance</step>
+<step>Verify the signing algorithm matches between issuer and verifier</step>
+<step>Update token expiration to use RS256 with proper key rotation</step>
+</steps>
+<expected_outcome>JWT auth works reliably with proper expiration handling</expected_outcome>
+<tags>jwt,authentication,security</tags>
+</skill>
+ `);
+
+ const result = await handlers["mem::skill-extract"]({ sessionId: "s1" });
+ expect(result.success).toBe(true);
+ expect(result.extracted).toBe(true);
+ expect(result.skill.name).toBe("Fix JWT Token Expiration");
+ expect(result.skill.steps).toHaveLength(3);
+ expect(result.skill.triggerCondition).toContain("JWT");
+ expect(mockKv.set).toHaveBeenCalled();
+ });
+
+ it("skill-extract returns no-skill for exploratory sessions", async () => {
+ mockKv.get.mockImplementation((scope: string) => {
+ if (scope === "mem:sessions") return Promise.resolve({ id: "s1", project: "test", status: "completed" });
+ if (scope === "mem:summaries")
+ return Promise.resolve({
+ sessionId: "s1",
+ project: "test",
+ title: "Explore codebase",
+ narrative: "Browsed files",
+ keyDecisions: [],
+ filesModified: [],
+ concepts: [],
+ createdAt: new Date().toISOString(),
+ observationCount: 3,
+ });
+ return Promise.resolve(null);
+ });
+ mockKv.list.mockReturnValue(
+ Promise.resolve(Array.from({ length: 4 }, (_, i) => ({
+ id: `obs${i}`,
+ sessionId: "s1",
+ timestamp: new Date().toISOString(),
+ type: "file_read",
+ title: `Read file ${i}`,
+ importance: 5,
+ concepts: [],
+ files: [],
+ facts: [],
+ narrative: "",
+ }))),
+ );
+ mockProvider.summarize.mockResolvedValue("<no-skill/>");
+
+ const result = await handlers["mem::skill-extract"]({ sessionId: "s1" });
+ expect(result.success).toBe(true);
+ expect(result.extracted).toBe(false);
+ });
+
+ it("skill-list returns sorted by strength", async () => {
+ mockKv.list.mockResolvedValue([
+ { id: "s1", name: "Low", strength: 0.3 },
+ { id: "s2", name: "High", strength: 0.9 },
+ ]);
+ const result = await handlers["mem::skill-list"]({});
+ expect(result.skills[0].name).toBe("High");
+ });
+
+ it("skill-match finds relevant skills", async () => {
+ mockKv.list.mockResolvedValue([
+ {
+ id: "s1",
+ name: "Fix JWT Auth",
+ triggerCondition: "JWT failures",
+ tags: ["jwt", "auth"],
+ steps: ["check config", "update key"],
+ strength: 0.8,
+ },
+ {
+ id: "s2",
+ name: "Deploy Docker",
+ triggerCondition: "container deployment",
+ tags: ["docker", "deploy"],
+ steps: ["build image", "push"],
+ strength: 0.7,
+ },
+ ]);
+
+ const result = await handlers["mem::skill-match"]({
+ query: "JWT authentication token expired",
+ });
+ expect(result.matches.length).toBe(1);
+ expect(result.matches[0].skill.name).toBe("Fix JWT Auth");
+ });
+});
diff --git a/test/working-memory.test.ts b/test/working-memory.test.ts
new file mode 100644
index 00000000..06d0afed
--- /dev/null
+++ b/test/working-memory.test.ts
@@ -0,0 +1,145 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const mockKv = {
+ get: vi.fn(),
+ set: vi.fn(),
+ list: vi.fn(),
+ delete: vi.fn(),
+};
+
+const mockSdk = {
+ registerFunction: vi.fn(),
+};
+
+vi.mock("iii-sdk", () => ({
+ getContext: () => ({
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+ }),
+}));
+
+vi.mock("../src/functions/audit.js", () => ({
+ recordAudit: vi.fn(),
+}));
+
+import { registerWorkingMemoryFunctions } from "../src/functions/working-memory.js";
+
+describe("working-memory", () => {
+ let handlers: Record<string, Function>;
+
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mockKv.list.mockResolvedValue([]);
+ mockKv.get.mockResolvedValue(null);
+ mockKv.set.mockResolvedValue(undefined);
+ mockKv.delete.mockResolvedValue(undefined);
+
+ handlers = {};
+ mockSdk.registerFunction.mockImplementation((meta: any, handler: any) => {
+ handlers[meta.id] = handler;
+ });
+
+ registerWorkingMemoryFunctions(mockSdk as any, mockKv as any, 4000);
+ });
+
+ it("registers all working memory functions", () => {
+ expect(handlers["mem::core-add"]).toBeDefined();
+ expect(handlers["mem::core-remove"]).toBeDefined();
+ expect(handlers["mem::core-list"]).toBeDefined();
+ expect(handlers["mem::working-context"]).toBeDefined();
+ expect(handlers["mem::auto-page"]).toBeDefined();
+ });
+
+ it("core-add creates an entry", async () => {
+ const result = await handlers["mem::core-add"]({
+ content: "Always use feature branches",
+ importance: 8,
+ });
+ expect(result.success).toBe(true);
+ expect(result.id).toMatch(/^core_/);
+ expect(mockKv.set).toHaveBeenCalledOnce();
+ });
+
+ it("core-add rejects empty content", async () => {
+ const result = await handlers["mem::core-add"]({ content: "" });
+ expect(result.success).toBe(false);
+ });
+
+ it("core-add clamps importance", async () => {
+ await handlers["mem::core-add"]({ content: "test", importance: 99 });
+ const saved = mockKv.set.mock.calls[0][2];
+ expect(saved.importance).toBe(10);
+ });
+
+ it("core-remove deletes entry", async () => {
+ const result = await handlers["mem::core-remove"]({ id: "core_123" });
+ expect(result.success).toBe(true);
+ expect(mockKv.delete).toHaveBeenCalledOnce();
+ });
+
+ it("core-list returns sorted entries", async () => {
+ mockKv.list.mockResolvedValue([
+ { id: "a", content: "low", importance: 3 },
+ { id: "b", content: "high", importance: 9 },
+ ]);
+ const result = await handlers["mem::core-list"]();
+ expect(result.entries[0].importance).toBe(9);
+ });
+
+ it("working-context builds core + archival sections", async () => {
+ mockKv.list.mockImplementation((scope: string) => {
+ if (scope === "mem:core-memory") {
+ return [
+ {
+ id: "c1",
+ content: "Use iii primitives",
+ importance: 9,
+ pinned: true,
+ accessCount: 5,
+ lastAccessedAt: new Date().toISOString(),
+ createdAt: new Date().toISOString(),
+ },
+ ];
+ }
+ if (scope === "mem:memories") {
+ return [
+ {
+ id: "m1",
+ type: "pattern",
+ title: "API pattern",
+ content: "REST endpoints follow /api/resource convention",
+ isLatest: true,
+ strength: 0.8,
+ updatedAt: new Date().toISOString(),
+ },
+ ];
+ }
+ return [];
+ });
+
+ const result = await handlers["mem::working-context"]({
+ sessionId: "s1",
+ project: "test",
+ });
+ expect(result.success).toBe(true);
+ expect(result.coreEntries).toBe(1);
+ expect(result.context).toContain("Core Memory");
+ expect(result.context).toContain("Use iii primitives");
+ });
+
+ it("auto-page removes lowest-value unpinned entries", async () => {
+ const entries = Array.from({ length: 20 }, (_, i) => ({
+ id: `c${i}`,
+ content: "x".repeat(300),
+ importance: i,
+ pinned: i === 19,
+ accessCount: i,
+ lastAccessedAt: new Date(Date.now() - i * 86400000).toISOString(),
+ createdAt: new Date().toISOString(),
+ }));
+ mockKv.list.mockResolvedValue(entries);
+
+ const result = await handlers["mem::auto-page"]({ budget: 4000 });
+ expect(result.success).toBe(true);
+ expect(result.paged).toBeGreaterThan(0);
+ });
+});