om-memory-system 3.0.0

package/dist/core/memory-operations.js

@@ -0,0 +1,247 @@
+import { CONFIG, isConfigured } from "../config.js";
+import { memoryClient } from "../services/client.js";
+import { getLanguageName } from "../services/language-detector.js";
+import { stripPrivateContent, isFullyPrivate } from "../services/privacy.js";
+import { getTags } from "../services/tags.js";
+function formatSearchResults(query, results, limit) {
+    const memoryResults = results.results || [];
+    return {
+        success: true,
+        query,
+        count: memoryResults.length,
+        results: memoryResults.slice(0, limit || 10).map((result) => ({
+            id: result.id,
+            content: result.memory || result.chunk,
+            similarity: Math.round(result.similarity * 100),
+        })),
+    };
+}
+export async function executeMemoryOperation(args, context) {
+    if (!isConfigured()) {
+        return {
+            success: false,
+            error: "Memory system not configured properly.",
+        };
+    }
+    const mode = args.mode || "help";
+    const needsEmbedding = !["help", "list-shards", "migrate", "export"].includes(mode);
+    if (needsEmbedding) {
+        const embeddingInitError = memoryClient.getEmbeddingInitError?.();
+        if (embeddingInitError) {
+            return { success: false, error: embeddingInitError };
+        }
+    }
+    try {
+        if (needsEmbedding) {
+            await memoryClient.warmup();
+        }
+        else if (mode !== "help") {
+            await memoryClient.ensureStorageReady();
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            success: false,
+            error: `Memory system failed to initialize: ${message}`,
+        };
+    }
+    const tags = context.tags ?? getTags(context.directory);
+    const langName = getLanguageName(CONFIG.autoCaptureLanguage || "en");
+    try {
+        switch (mode) {
+            case "help":
+                return {
+                    success: true,
+                    message: "Memory System Usage Guide",
+                    commands: [
+                        {
+                            command: "add",
+                            description: `Store new memory (MATCH USER LANGUAGE: ${langName})`,
+                            args: ["content", "type?", "tags?"],
+                        },
+                        {
+                            command: "search",
+                            description: `Search memories via keywords (MATCH USER LANGUAGE: ${langName})`,
+                            args: ["query"],
+                        },
+                        {
+                            command: "profile",
+                            description: "View user profile or save an explicit preference (provide content to write)",
+                            args: ["content?"],
+                        },
+                        { command: "list", description: "List recent memories", args: ["limit?"] },
+                        { command: "forget", description: "Remove memory", args: ["memoryId"] },
+                        {
+                            command: "list-shards",
+                            description: "List project memory shards and orphaned path associations",
+                            args: [],
+                        },
+                        {
+                            command: "migrate",
+                            description: "Reassociate orphaned project shards after a directory move (target must be empty)",
+                            args: ["fromPath?", "fromHash?", "dryRun?", "allowLinkedSource?"],
+                        },
+                        {
+                            command: "export",
+                            description: "Export current project memories to a portable JSON file",
+                            args: ["outputPath"],
+                        },
+                        {
+                            command: "import",
+                            description: "Import memories from a portable JSON file (re-embeds; aborts on duplicate ids)",
+                            args: ["inputPath", "dryRun?"],
+                        },
+                    ],
+                    tagGuidance: "Use technical keywords for search. Tags rank highest.",
+                };
+            case "add": {
+                if (!args.content)
+                    return { success: false, error: "content required" };
+                const sanitizedContent = stripPrivateContent(args.content);
+                if (isFullyPrivate(args.content)) {
+                    return { success: false, error: "Private content blocked" };
+                }
+                const tagInfo = tags.project;
+                const parsedTags = args.tags
+                    ? args.tags.split(",").map((tag) => tag.trim().toLowerCase())
+                    : undefined;
+                const result = await memoryClient.addMemory(sanitizedContent, tagInfo.tag, {
+                    type: args.type,
+                    tags: parsedTags,
+                    host: context.host,
+                    hostSessionId: context.hostSessionId,
+                    displayName: tagInfo.displayName,
+                    userName: tagInfo.userName,
+                    userEmail: tagInfo.userEmail,
+                    projectPath: tagInfo.projectPath,
+                    projectName: tagInfo.projectName,
+                    gitRepoUrl: tagInfo.gitRepoUrl,
+                });
+                return {
+                    success: result.success,
+                    message: result.success ? "Memory added" : result.error,
+                    id: result.success ? result.id : undefined,
+                    tags: parsedTags,
+                };
+            }
+            case "search": {
+                if (!args.query)
+                    return { success: false, error: "query required" };
+                const result = await memoryClient.searchMemories(args.query, tags.project.tag, args.scope ?? CONFIG.memory.defaultScope);
+                if (!result.success)
+                    return { success: false, error: result.error };
+                return formatSearchResults(args.query, result, args.limit);
+            }
+            case "profile": {
+                if (args.query) {
+                    return {
+                        success: false,
+                        error: "query is not valid for profile mode. Use content to write a preference or omit all args to read.",
+                    };
+                }
+                const { userProfileManager } = await import("../services/user-profile/user-profile-manager.js");
+                const userId = tags.user.userEmail || "unknown";
+                if (args.content !== undefined) {
+                    const trimmed = args.content.trim();
+                    if (!trimmed)
+                        return { success: false, error: "content must not be blank" };
+                    if (!tags.user.userEmail) {
+                        return {
+                            success: false,
+                            error: "Cannot save profile preference because no user email could be resolved. Configure userEmailOverride or git user.email.",
+                        };
+                    }
+                    const sanitizedContent = stripPrivateContent(trimmed);
+                    const hasNonPrivateContent = sanitizedContent.replace(/\[REDACTED\]/g, "").trim().length > 0;
+                    if (isFullyPrivate(trimmed) || !hasNonPrivateContent) {
+                        return { success: false, error: "Private content blocked" };
+                    }
+                    const newPreference = {
+                        category: "explicit",
+                        description: sanitizedContent,
+                        confidence: 1.0,
+                        frequency: 1,
+                        evidence: ["manual-write"],
+                        lastSeen: Date.now(),
+                    };
+                    const existingProfile = await userProfileManager.getActiveProfile(userId);
+                    if (existingProfile) {
+                        const existingData = JSON.parse(existingProfile.profileData);
+                        const mergedData = await userProfileManager.mergeProfileData(existingData, { preferences: [newPreference] }, undefined, existingProfile.id);
+                        await userProfileManager.updateProfile(existingProfile.id, mergedData, 0, `Explicit preference added: ${sanitizedContent.slice(0, 80)}`);
+                        return { success: true, message: "Preference saved to profile" };
+                    }
+                    await userProfileManager.createProfile(userId, tags.user.displayName || userId, tags.user.userName || userId, tags.user.userEmail || userId, { preferences: [newPreference], patterns: [], workflows: [] }, 0);
+                    return { success: true, message: "Profile created with preference" };
+                }
+                const profile = await userProfileManager.getActiveProfile(userId);
+                if (!profile)
+                    return { success: true, profile: null };
+                const profileData = JSON.parse(profile.profileData);
+                return {
+                    success: true,
+                    profile: {
+                        ...profileData,
+                        version: profile.version,
+                        lastAnalyzed: profile.lastAnalyzedAt,
+                    },
+                };
+            }
+            case "list": {
+                const result = await memoryClient.listMemories(tags.project.tag, args.limit || 20, args.scope ?? CONFIG.memory.defaultScope);
+                if (!result.success)
+                    return { success: false, error: result.error };
+                return {
+                    success: true,
+                    count: result.memories?.length,
+                    memories: result.memories?.map((memory) => ({
+                        id: memory.id,
+                        content: memory.summary,
+                        createdAt: memory.createdAt,
+                    })),
+                };
+            }
+            case "forget": {
+                if (!args.memoryId)
+                    return { success: false, error: "memoryId required" };
+                const result = await memoryClient.deleteMemory(args.memoryId);
+                return { success: result.success, message: "Memory removed" };
+            }
+            case "list-shards":
+                return { ...(await memoryClient.listShards(context.directory)) };
+            case "migrate": {
+                if (!args.fromPath && !args.fromHash) {
+                    return {
+                        success: false,
+                        error: "fromPath or fromHash required. Run memory list-shards to discover orphaned shards.",
+                    };
+                }
+                return {
+                    ...(await memoryClient.migrateProjectPath({
+                        currentDirectory: context.directory,
+                        fromPath: args.fromPath,
+                        fromHash: args.fromHash,
+                        dryRun: args.dryRun,
+                        allowLinkedSource: args.allowLinkedSource,
+                    })),
+                };
+            }
+            case "export": {
+                if (!args.outputPath)
+                    return { success: false, error: "outputPath required" };
+                return { ...(await memoryClient.exportMemories(context.directory, args.outputPath)) };
+            }
+            case "import": {
+                if (!args.inputPath)
+                    return { success: false, error: "inputPath required" };
+                return {
+                    ...(await memoryClient.importMemories(context.directory, args.inputPath, args.dryRun)),
+                };
+            }
+        }
+    }
+    catch (error) {
+        return { success: false, error: String(error) };
+    }
+}

package/dist/core/retrieval.d.ts

@@ -0,0 +1,12 @@
+export declare const RETRIEVAL_SECTION_TAG = "omms-retrieval";
+/**
+ * Prompt-aware semantic retrieval shared by every host (Pi `before_agent_start`,
+ * OpenCode v2 `prompt`/`context` hooks): search the shared project memory with
+ * the incoming prompt and format a bounded context section (memory + user
+ * profile). Returns null when nothing relevant is found.
+ */
+export declare function buildRetrievalSection(prompt: string, directory: string, sessionId: string): Promise<string | null>;
+/** Delimit a retrieval section so it is recognisable as injected memory, not user text. */
+export declare function wrapRetrievalSection(section: string): string;
+/** Format a session's own memories for re-injection after compaction. */
+export declare function formatMemoriesForCompaction(memories: any[]): string;

package/dist/core/retrieval.js

@@ -0,0 +1,72 @@
+import { CONFIG } from "../config.js";
+import { formatContextForPrompt } from "../services/context.js";
+import { memoryClient } from "../services/client.js";
+import { getTags } from "../services/tags.js";
+export const RETRIEVAL_SECTION_TAG = "omms-retrieval";
+/**
+ * Prompt-aware semantic retrieval shared by every host (Pi `before_agent_start`,
+ * OpenCode v2 `prompt`/`context` hooks): search the shared project memory with
+ * the incoming prompt and format a bounded context section (memory + user
+ * profile). Returns null when nothing relevant is found.
+ */
+export async function buildRetrievalSection(prompt, directory, sessionId) {
+    if (!prompt.trim())
+        return null;
+    const tags = getTags(directory);
+    const search = await memoryClient.searchMemories(prompt, tags.project.tag);
+    if (!search.success)
+        return null;
+    const results = CONFIG.chatMessage.excludeCurrentSession
+        ? search.results.filter((result) => result.metadata?.sessionID !== sessionId)
+        : search.results;
+    if (results.length === 0)
+        return null;
+    const memoryContext = await formatContextForPrompt(tags.user.userEmail || null, {
+        results,
+    });
+    return memoryContext || null;
+}
+/** Delimit a retrieval section so it is recognisable as injected memory, not user text. */
+export function wrapRetrievalSection(section) {
+    return `<${RETRIEVAL_SECTION_TAG}>\n${section}\n</${RETRIEVAL_SECTION_TAG}>`;
+}
+const EMBEDDED_TAGS_FOOTER_RE = /\n*Tags: ([^\n]*)\s*$/;
+function normalizeTagsKey(tags) {
+    return tags
+        .map((tag) => tag.trim())
+        .filter((tag) => tag.length > 0)
+        .sort()
+        .join("\0");
+}
+function stripMatchingEmbeddedTagsFooter(memory, tags) {
+    const match = memory.match(EMBEDDED_TAGS_FOOTER_RE);
+    if (!match) {
+        return memory;
+    }
+    const footerValue = match[1];
+    if (footerValue === undefined) {
+        return memory;
+    }
+    const embeddedTags = footerValue
+        .split(",")
+        .map((tag) => tag.trim())
+        .filter((tag) => tag.length > 0);
+    if (normalizeTagsKey(embeddedTags) !== normalizeTagsKey(tags)) {
+        return memory;
+    }
+    return memory.replace(EMBEDDED_TAGS_FOOTER_RE, "");
+}
+/** Format a session's own memories for re-injection after compaction. */
+export function formatMemoriesForCompaction(memories) {
+    let output = `## Restored Session Memory\n\n`;
+    memories.forEach((m, i) => {
+        const tags = Array.isArray(m.tags) ? m.tags : [];
+        const body = tags.length > 0 ? stripMatchingEmbeddedTagsFooter(m.memory ?? "", tags) : (m.memory ?? "");
+        output += `### Memory ${i + 1}\n`;
+        output += `${body}\n\n`;
+        if (tags.length > 0) {
+            output += `Tags: ${tags.join(", ")}\n\n`;
+        }
+    });
+    return output;
+}

package/dist/importer/discovery.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Discovery of Pi session files for the historical importer. Read-only: only
+ * the first line (the session header) is parsed here, so discovery stays cheap
+ * and full parsing happens later per candidate session.
+ *
+ * Files that are not Pi session format (for example subagent artifacts, which
+ * use a different record format without a `type: "session"` header) are
+ * reported as unrecognized and skipped rather than treated as errors.
+ */
+export declare const DEFAULT_PI_SESSION_ROOT: string;
+export interface DiscoveredPiSession {
+    file: string;
+    sessionId: string | null;
+    cwd: string | null;
+    version: number | null;
+    /** Header ISO timestamp converted to epoch ms, when present. */
+    timestamp: number | null;
+}
+export interface UnrecognizedFile {
+    file: string;
+    reason: string;
+}
+export interface DiscoveryResult {
+    sessions: DiscoveredPiSession[];
+    unrecognized: UnrecognizedFile[];
+}
+export interface DiscoveryOptions {
+    root?: string;
+    maxSessions?: number;
+}
+export declare function discoverPiSessions(options?: DiscoveryOptions): DiscoveryResult;

package/dist/importer/discovery.js

@@ -0,0 +1,88 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+/**
+ * Discovery of Pi session files for the historical importer. Read-only: only
+ * the first line (the session header) is parsed here, so discovery stays cheap
+ * and full parsing happens later per candidate session.
+ *
+ * Files that are not Pi session format (for example subagent artifacts, which
+ * use a different record format without a `type: "session"` header) are
+ * reported as unrecognized and skipped rather than treated as errors.
+ */
+export const DEFAULT_PI_SESSION_ROOT = join(homedir(), ".pi", "agent", "sessions");
+function listJsonlFiles(root) {
+    const files = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(full);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+                files.push(full);
+            }
+        }
+    }
+    return files.sort();
+}
+function readHeaderLine(file) {
+    let firstLine;
+    try {
+        const stream = readFileSync(file, "utf8");
+        const newline = stream.indexOf("\n");
+        firstLine = (newline === -1 ? stream : stream.slice(0, newline)).trim();
+        if (!firstLine)
+            return { error: "empty file" };
+        return { header: JSON.parse(firstLine) };
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return { error: `malformed header: ${String(error)}` };
+        return { error: `unreadable: ${String(error)}` };
+    }
+}
+export function discoverPiSessions(options = {}) {
+    const root = options.root ?? DEFAULT_PI_SESSION_ROOT;
+    const sessions = [];
+    const unrecognized = [];
+    if (!existsSync(root)) {
+        return { sessions, unrecognized };
+    }
+    for (const file of listJsonlFiles(root)) {
+        const parsed = readHeaderLine(file);
+        if ("error" in parsed) {
+            unrecognized.push({ file, reason: parsed.error });
+            continue;
+        }
+        const header = parsed.header;
+        if (header?.type !== "session") {
+            unrecognized.push({ file, reason: "not a Pi session file (no session header)" });
+            continue;
+        }
+        const timestamp = typeof header.timestamp === "string" ? Date.parse(header.timestamp) : NaN;
+        sessions.push({
+            file,
+            sessionId: typeof header.id === "string" ? header.id : null,
+            cwd: typeof header.cwd === "string" ? header.cwd : null,
+            version: typeof header.version === "number" ? header.version : null,
+            timestamp: Number.isNaN(timestamp) ? null : timestamp,
+        });
+    }
+    // Chronological order, oldest first; files without a timestamp sort last.
+    sessions.sort((a, b) => (a.timestamp ?? Infinity) - (b.timestamp ?? Infinity));
+    const limited = options.maxSessions !== undefined && options.maxSessions >= 0
+        ? sessions.slice(0, options.maxSessions)
+        : sessions;
+    return { sessions: limited, unrecognized };
+}

package/dist/importer/importer.d.ts

@@ -0,0 +1,87 @@
+import type { CaptureSummaryProvider } from "../core/host.js";
+import { type PiConversationWindow } from "../adapters/pi/conversation.js";
+import { PiImportLedger } from "./ledger.js";
+import type { LoadedPiSession } from "./session-loader.js";
+/**
+ * Host-neutral orchestration for the Pi historical-session backfill.
+ *
+ * Per unit: deterministic key -> ledger state -> (reconcile | capture ->
+ * terminal ledger state). Per session: load through Pi's session model,
+ * resolve the recorded cwd through the shared project identity, select the
+ * active branch, and rebuild the same work units live capture would have
+ * produced. Source files are only ever read.
+ */
+export interface ImportPathMap {
+    from: string;
+    to: string;
+}
+export interface ImportFilters {
+    scope: "current-project" | "all-projects";
+    currentDirectory: string;
+    session?: string;
+    /** Inclusive lower bound on the work unit's user-entry timestamp (epoch ms). */
+    since?: number;
+    /** Inclusive upper bound on the work unit's user-entry timestamp (epoch ms). */
+    until?: number;
+    maxSessions?: number;
+    force?: boolean;
+    dryRun?: boolean;
+    pathMaps?: ImportPathMap[];
+    root?: string;
+}
+export type ImportUnitStatus = "imported" | "would-import" | "skipped" | "failed" | "already-handled";
+export interface ImportUnitReport {
+    key: string;
+    sessionId: string;
+    userEntryId: string;
+    promptPreview: string;
+    status: ImportUnitStatus;
+    reason?: string;
+    memoryId?: string;
+}
+export interface ImportProjectReport {
+    tag: string;
+    hash: string;
+    directory: string;
+    sessions: number;
+    units: number;
+}
+export interface ImportReport {
+    dryRun: boolean;
+    root: string;
+    sessionsDiscovered: number;
+    sessionsLoaded: number;
+    sessionsFilteredOut: number;
+    sessionsUnrecognized: number;
+    unresolvableSessions: Array<{
+        file: string;
+        cwd: string | null;
+    }>;
+    loadErrors: Array<{
+        file: string;
+        error: string;
+    }>;
+    unitsTotal: number;
+    unitsImported: number;
+    unitsWouldImport: number;
+    unitsSkipped: number;
+    unitsFailed: number;
+    unitsAlreadyHandled: number;
+    skipReasons: Record<string, number>;
+    projects: ImportProjectReport[];
+    units: ImportUnitReport[];
+}
+export interface ImporterDeps {
+    loadSession: (file: string) => LoadedPiSession;
+    provider: CaptureSummaryProvider;
+    onProgress?: (processed: number, total: number, promptPreview: string) => void;
+    ledger?: PiImportLedger;
+}
+export declare function buildImportKey(sessionId: string, window: PiConversationWindow): string | null;
+/**
+ * Find a stored memory by its deterministic import identity. Used to
+ * reconcile crash windows: the memory insert landed but the ledger update did
+ * not commit.
+ */
+export declare function findMemoryIdByImportId(projectHash: string, importId: string): Promise<string | null>;
+export declare function importPiHistory(deps: ImporterDeps, filters: ImportFilters): Promise<ImportReport>;