opencode-lcm 0.11.0

package/dist/types.d.ts

@@ -0,0 +1,117 @@
+import type { Message, Part } from '@opencode-ai/sdk';
+export type InteropOptions = {
+    contextMode: boolean;
+    neverOverrideCompactionPrompt: boolean;
+    ignoreToolPrefixes: string[];
+};
+export type ScopeName = 'session' | 'root' | 'worktree' | 'all';
+export type ScopeDefaults = {
+    grep: ScopeName;
+    describe: ScopeName;
+};
+export type ScopeProfile = {
+    worktree: string;
+    grep?: ScopeName;
+    describe?: ScopeName;
+};
+export type RetentionPolicyOptions = {
+    staleSessionDays?: number;
+    deletedSessionDays?: number;
+    orphanBlobDays?: number;
+};
+export type PrivacyOptions = {
+    excludeToolPrefixes: string[];
+    excludePathPatterns: string[];
+    redactPatterns: string[];
+};
+export type AutomaticRetrievalScopeBudgets = {
+    session: number;
+    root: number;
+    worktree: number;
+    all: number;
+};
+export type AutomaticRetrievalStopOptions = {
+    targetHits: number;
+    stopOnFirstScopeWithHits: boolean;
+};
+export type AutomaticRetrievalOptions = {
+    enabled: boolean;
+    maxChars: number;
+    minTokens: number;
+    maxMessageHits: number;
+    maxSummaryHits: number;
+    maxArtifactHits: number;
+    scopeOrder: ScopeName[];
+    scopeBudgets: AutomaticRetrievalScopeBudgets;
+    stop: AutomaticRetrievalStopOptions;
+};
+export type OpencodeLcmOptions = {
+    interop: InteropOptions;
+    scopeDefaults: ScopeDefaults;
+    scopeProfiles: ScopeProfile[];
+    retention: RetentionPolicyOptions;
+    privacy: PrivacyOptions;
+    automaticRetrieval: AutomaticRetrievalOptions;
+    compactContextLimit: number;
+    systemHint: boolean;
+    storeDir?: string;
+    freshTailMessages: number;
+    minMessagesForTransform: number;
+    summaryCharBudget: number;
+    partCharBudget: number;
+    largeContentThreshold: number;
+    artifactPreviewChars: number;
+    artifactViewChars: number;
+    binaryPreviewProviders: string[];
+    previewBytePeek: number;
+};
+export type CapturedEvent = {
+    id: string;
+    type: string;
+    sessionID?: string;
+    timestamp: number;
+    payload: unknown;
+};
+export type SearchResult = {
+    id: string;
+    type: string;
+    sessionID?: string;
+    timestamp: number;
+    snippet: string;
+};
+export type StoreStats = {
+    schemaVersion: number;
+    totalEvents: number;
+    sessionCount: number;
+    latestEventAt?: number;
+    eventTypes: Record<string, number>;
+    summaryNodeCount: number;
+    summaryStateCount: number;
+    rootSessionCount: number;
+    branchedSessionCount: number;
+    artifactCount: number;
+    artifactBlobCount: number;
+    sharedArtifactBlobCount: number;
+    orphanArtifactBlobCount: number;
+    worktreeCount: number;
+    pinnedSessionCount: number;
+};
+export type ConversationMessage = {
+    info: Message;
+    parts: Part[];
+};
+export type NormalizedSession = {
+    sessionID: string;
+    title?: string;
+    directory?: string;
+    parentSessionID?: string;
+    rootSessionID?: string;
+    lineageDepth?: number;
+    pinned?: boolean;
+    pinReason?: string;
+    updatedAt: number;
+    compactedAt?: number;
+    deleted?: boolean;
+    eventCount: number;
+    messages: ConversationMessage[];
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared pure utility functions used across the LCM codebase.
+ * These functions have no dependencies on store internals or external types.
+ */
+export declare function asRecord(value: unknown): Record<string, unknown> | undefined;
+export declare function firstFiniteNumber(value: unknown): number | undefined;
+export declare function truncate(text: string, limit: number): string;
+export declare function shortNodeID(nodeID: string): string;
+export declare function parseJson<T>(value: string): T;
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function hashContent(content: string): string;
+export declare function tokenizeQuery(query: string): string[];
+/** FTS5 reserved words that would be interpreted as operators/syntax inside MATCH. */
+export declare const FTS5_RESERVED: Set<string>;
+/** Drop FTS5-reserved words and too-short tokens to keep MATCH queries safe. */
+export declare function sanitizeFtsTokens(tokens: string[]): string[];
+export declare function buildSnippet(content: string, query?: string, limit?: number): string;
+export declare function sanitizeAutomaticRetrievalSourceText(text: string): string;
+export declare function isAutomaticRetrievalNoise(text: string): boolean;
+/**
+ * Fast-path filter: drops only grammatical function words.
+ * Corpus-aware TF-IDF weighting should be applied downstream for full filtering.
+ */
+export declare function filterIntentTokens(tokens: string[]): string[];
+/**
+ * Returns the minimal grammatical stoplist for use in TF-IDF scoring.
+ * Tokens in this set are always dropped without hitting the FTS index.
+ */
+export declare function getGrammaticalStopwords(): Set<string>;
+export declare function shouldSuppressLowSignalAutomaticRetrievalAnchor(anchorText: string, anchorSignalCount: number, minTokens: number, anchorFileCount: number): boolean;
+export declare function inferUrlScheme(url?: string): string | undefined;
+export declare function inferFileExtension(file?: string): string | undefined;
+export declare function classifyFileCategory(mime?: string, extension?: string): string;
+export declare function formatMetadataValue(value: unknown): string | undefined;
+export declare function formatRetentionDays(value?: number): string;

package/dist/utils.js

@@ -0,0 +1,414 @@
+import { createHash } from 'node:crypto';
+/**
+ * Shared pure utility functions used across the LCM codebase.
+ * These functions have no dependencies on store internals or external types.
+ */
+// --- Type guards ---
+export function asRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    return value;
+}
+export function firstFiniteNumber(value) {
+    const record = asRecord(value);
+    if (!record)
+        return undefined;
+    for (const entry of Object.values(record)) {
+        if (typeof entry === 'number' && Number.isFinite(entry))
+            return entry;
+    }
+    return undefined;
+}
+// --- String utilities ---
+export function truncate(text, limit) {
+    return text.length <= limit ? text : `${text.slice(0, Math.max(0, limit - 3))}...`;
+}
+export function shortNodeID(nodeID) {
+    return nodeID.length <= 32 ? nodeID : `${nodeID.slice(0, 20)}...${nodeID.slice(-8)}`;
+}
+export function parseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to parse JSON: ${message}\nInput: ${value.slice(0, 120)}${value.length > 120 ? '...' : ''}`);
+    }
+}
+// --- Number utilities ---
+export function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+// --- Hashing ---
+export function hashContent(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+// --- Query tokenization ---
+export function tokenizeQuery(query) {
+    return [...new Set(query.toLowerCase().match(/[a-z0-9_]+/g) ?? [])];
+}
+/** FTS5 reserved words that would be interpreted as operators/syntax inside MATCH. */
+export const FTS5_RESERVED = new Set([
+    'and',
+    'or',
+    'not',
+    'near',
+    'order',
+    'by',
+    'asc',
+    'desc',
+    'limit',
+    'offset',
+    'match',
+    'rank',
+    'rowid',
+    'bm25',
+    'highlight',
+    'snippet',
+    'replace',
+    'delete',
+    'insert',
+    'update',
+    'select',
+    'from',
+    'where',
+    'group',
+    'having',
+]);
+/** Drop FTS5-reserved words and too-short tokens to keep MATCH queries safe. */
+export function sanitizeFtsTokens(tokens) {
+    return tokens.filter((t) => t.length >= 2 && !FTS5_RESERVED.has(t));
+}
+// --- Snippet extraction ---
+export function buildSnippet(content, query, limit = 280) {
+    const normalized = content.replace(/\s+/g, ' ').trim();
+    if (!normalized)
+        return '';
+    if (!query)
+        return truncate(normalized, limit);
+    const lower = normalized.toLowerCase();
+    const exact = query.toLowerCase();
+    let index = lower.indexOf(exact);
+    if (index < 0) {
+        for (const token of tokenizeQuery(query)) {
+            index = lower.indexOf(token);
+            if (index >= 0)
+                break;
+        }
+    }
+    if (index < 0)
+        return truncate(normalized, limit);
+    const start = Math.max(0, index - 90);
+    const end = Math.min(normalized.length, index + Math.max(exact.length, 32) + 150);
+    return truncate(normalized.slice(start, end), limit);
+}
+// --- Automatic retrieval text sanitization ---
+const AUTOMATIC_RETRIEVAL_NOISE_PATTERNS = [
+    /<system-reminder>/i,
+    /system[-\s[\]]*reminder/i,
+    /\[archived by opencode-lcm:/i,
+    /archived hits:/i,
+    /summary roots:/i,
+    /\b(?:message|summary|artifact) session=[^\s]+ id=[^\s]+/i,
+    /\bsum_[a-f0-9]{12}_l\d+_p\d+:/i,
+    /recall telemetry:/i,
+    /recalled context:/i,
+    /your operational mode has changed/i,
+    /opencode-lcm automatically recalled/i,
+    /recalled \d+ archived hit/i,
+    /compacted \d+ older conversation turn/i,
+    /treat recalled archive as supporting context/i,
+    /use lcm_(describe|grep|resume|expand|artifact)/i,
+];
+/**
+ * Minimal grammatical stoplist — function words and common verbs that are almost never
+ * informative for retrieval. Corpus-aware TF-IDF weighting handles the rest in store.ts.
+ * This list exists purely to avoid a DB round-trip for obvious determiners/pronouns/verbs.
+ */
+const GRAMMATICAL_STOPWORDS = new Set([
+    // Determiners/articles
+    'a',
+    'an',
+    'the',
+    // Pronouns
+    'i',
+    'me',
+    'my',
+    'we',
+    'us',
+    'our',
+    'you',
+    'your',
+    'it',
+    'its',
+    'this',
+    'that',
+    'these',
+    'those',
+    // Copula/auxiliary verbs
+    'is',
+    'are',
+    'was',
+    'were',
+    'be',
+    'been',
+    'am',
+    'do',
+    'does',
+    'did',
+    'has',
+    'have',
+    'had',
+    'can',
+    'could',
+    'will',
+    'would',
+    'shall',
+    'should',
+    'may',
+    'might',
+    'must',
+    // Common verbs that are rarely informative for retrieval
+    'say',
+    'said',
+    'tell',
+    'told',
+    'show',
+    'shown',
+    'get',
+    'got',
+    'give',
+    'gave',
+    'make',
+    'made',
+    'take',
+    'took',
+    'come',
+    'came',
+    'go',
+    'went',
+    'see',
+    'saw',
+    'know',
+    'knew',
+    'think',
+    'thought',
+    'want',
+    'need',
+    'use',
+    'used',
+    // Prepositions/conjunctions
+    'in',
+    'on',
+    'at',
+    'to',
+    'for',
+    'from',
+    'by',
+    'with',
+    'about',
+    'into',
+    'and',
+    'or',
+    'but',
+    'so',
+    'if',
+    'then',
+    'than',
+    'as',
+    'of',
+    // Adverbs/misc
+    'just',
+    'only',
+    'also',
+    'still',
+    'already',
+    'even',
+    'very',
+    'yes',
+    'no',
+    'ok',
+    'okay',
+    'not',
+    'again',
+    'more',
+    'some',
+    'any',
+    'all',
+    'every',
+    'each',
+    // Retrieval-specific noise
+    'recall',
+    'remind',
+    'reply',
+    'mention',
+    'mentioned',
+    'where',
+    'when',
+    'what',
+    'which',
+    'who',
+    'how',
+    'why',
+]);
+export function sanitizeAutomaticRetrievalSourceText(text) {
+    return text
+        .replace(/<system-reminder>[\s\S]*?<\/system-reminder>/gi, ' ')
+        .replace(/<system-reminder>/gi, ' ')
+        .replace(/<\/system-reminder>/gi, ' ')
+        .replace(/\[Archived by opencode-lcm:[^\]]*\]/gi, ' ')
+        .replace(/Archived hits:[^\n]*/gi, ' ')
+        .replace(/Summary roots:[^\n]*/gi, ' ')
+        .replace(/Recall telemetry:[^\n]*/gi, ' ')
+        .replace(/Recalled context:/gi, ' ')
+        .replace(/Archived roots:/gi, ' ')
+        .replace(/Treat recalled archive as supporting context[^\n]*/gi, ' ')
+        .replace(/Use lcm_(describe|grep|resume|expand|artifact)[^\n]*/gi, ' ')
+        .replace(/opencode-lcm automatically recalled[^\n]*/gi, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+export function isAutomaticRetrievalNoise(text) {
+    return AUTOMATIC_RETRIEVAL_NOISE_PATTERNS.some((pattern) => pattern.test(text));
+}
+/**
+ * Fast-path filter: drops only grammatical function words.
+ * Corpus-aware TF-IDF weighting should be applied downstream for full filtering.
+ */
+export function filterIntentTokens(tokens) {
+    return tokens.filter((token) => {
+        if (GRAMMATICAL_STOPWORDS.has(token))
+            return false;
+        if (token.length >= 3)
+            return true;
+        return /\d/.test(token) || token.includes('_');
+    });
+}
+/**
+ * Returns the minimal grammatical stoplist for use in TF-IDF scoring.
+ * Tokens in this set are always dropped without hitting the FTS index.
+ */
+export function getGrammaticalStopwords() {
+    return GRAMMATICAL_STOPWORDS;
+}
+export function shouldSuppressLowSignalAutomaticRetrievalAnchor(anchorText, anchorSignalCount, minTokens, anchorFileCount) {
+    if (anchorSignalCount >= minTokens)
+        return false;
+    if (anchorFileCount > 0)
+        return false;
+    if (anchorText.includes('?'))
+        return false;
+    const rawTokenCount = tokenizeQuery(anchorText).length;
+    return rawTokenCount <= 4;
+}
+// --- URL and file utilities ---
+export function inferUrlScheme(url) {
+    if (!url)
+        return undefined;
+    const index = url.indexOf(':');
+    if (index <= 0)
+        return undefined;
+    return url.slice(0, index).toLowerCase();
+}
+export function inferFileExtension(file) {
+    if (!file)
+        return undefined;
+    const cleaned = file.replace(/\\/g, '/').split('/').pop() ?? file;
+    const index = cleaned.lastIndexOf('.');
+    if (index <= 0 || index === cleaned.length - 1)
+        return undefined;
+    return cleaned.slice(index + 1).toLowerCase();
+}
+export function classifyFileCategory(mime, extension) {
+    const kind = mime?.toLowerCase() ?? '';
+    const ext = extension?.toLowerCase() ?? '';
+    if (kind.startsWith('image/'))
+        return 'image';
+    if (kind === 'application/pdf' || ext === 'pdf')
+        return 'pdf';
+    if (kind.startsWith('audio/'))
+        return 'audio';
+    if (kind.startsWith('video/'))
+        return 'video';
+    if (kind.includes('zip') ||
+        kind.includes('tar') ||
+        kind.includes('gzip') ||
+        ['zip', 'tar', 'gz', 'tgz', 'rar', '7z'].includes(ext))
+        return 'archive';
+    if (kind.includes('spreadsheet') || ['xls', 'xlsx', 'ods', 'csv', 'tsv'].includes(ext))
+        return 'spreadsheet';
+    if (kind.includes('presentation') || ['ppt', 'pptx', 'odp', 'key'].includes(ext))
+        return 'presentation';
+    if (kind.includes('word') ||
+        kind.includes('document') ||
+        ['doc', 'docx', 'odt', 'rtf'].includes(ext))
+        return 'document';
+    if (kind.startsWith('text/') || ['txt', 'md', 'rst', 'log'].includes(ext))
+        return 'text';
+    if ([
+        'ts',
+        'tsx',
+        'js',
+        'jsx',
+        'py',
+        'rb',
+        'go',
+        'rs',
+        'java',
+        'kt',
+        'c',
+        'cpp',
+        'h',
+        'hpp',
+        'cs',
+        'php',
+        'swift',
+        'scala',
+        'pl',
+        'pm',
+        'sh',
+        'bash',
+        'zsh',
+        'fish',
+        'ps1',
+        'bat',
+        'cmd',
+    ].includes(ext))
+        return 'code';
+    if ([
+        'html',
+        'htm',
+        'xml',
+        'json',
+        'yaml',
+        'yml',
+        'toml',
+        'ini',
+        'cfg',
+        'conf',
+        'env',
+        'sql',
+        'graphql',
+        'gql',
+    ].includes(ext))
+        return 'structured-data';
+    return 'binary';
+}
+// --- Formatting utilities ---
+export function formatMetadataValue(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (Array.isArray(value)) {
+        const items = value.map((item) => formatMetadataValue(item)).filter(Boolean);
+        return items.length > 0 ? items.join(', ') : undefined;
+    }
+    if (value && typeof value === 'object') {
+        return JSON.stringify(value);
+    }
+    return undefined;
+}
+export function formatRetentionDays(value) {
+    return value === undefined ? 'disabled' : String(value);
+}

package/dist/workspace-path.d.ts

@@ -0,0 +1 @@
+export declare function resolveWorkspacePath(workspaceDirectory: string, inputPath: string): string;

package/dist/workspace-path.js

@@ -0,0 +1,15 @@
+import path from 'node:path';
+export function resolveWorkspacePath(workspaceDirectory, inputPath) {
+    const workspaceRoot = path.resolve(workspaceDirectory);
+    const resolvedPath = path.isAbsolute(inputPath)
+        ? path.normalize(inputPath)
+        : path.resolve(workspaceRoot, inputPath);
+    const relativePath = path.relative(workspaceRoot, resolvedPath);
+    const escapesWorkspace = relativePath === '..' ||
+        relativePath.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relativePath);
+    if (!escapesWorkspace) {
+        return resolvedPath;
+    }
+    throw new Error(`Path must stay within the workspace: ${inputPath}`);
+}

package/dist/worktree-key.d.ts

@@ -0,0 +1 @@
+export declare function normalizeWorktreeKey(directory?: string): string | undefined;

package/dist/worktree-key.js

@@ -0,0 +1,6 @@
+export function normalizeWorktreeKey(directory) {
+    if (!directory)
+        return undefined;
+    const normalized = directory.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+    return normalized || undefined;
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "opencode-lcm",
+  "version": "0.11.0",
+  "description": "Long-memory plugin for OpenCode with context-mode interop",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "author": "Isaac Grumberg",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Plutarch01/opencode-lcm.git"
+  },
+  "homepage": "https://github.com/Plutarch01/opencode-lcm#readme",
+  "bugs": {
+    "url": "https://github.com/Plutarch01/opencode-lcm/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "memory",
+    "sqlite",
+    "context-mode",
+    "lcm"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.json",
+    "lint": "biome check src tests",
+    "format": "biome format --write src tests",
+    "test": "npm run build && tsc -p tests/tsconfig.json && node --test tests/*.test.mjs dist-tests/*.test.js",
+    "perf:archive": "npm run build && node scripts/perf-archive.mjs",
+    "dogfood:opencode": "npm run build && node scripts/dogfood-opencode.mjs",
+    "prepublishOnly": "npm run typecheck && npm run lint && npm run test"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.10",
+    "@opencode-ai/plugin": "^1.3.3",
+    "@types/node": "^25.5.0",
+    "typescript": "^5.8.3"
+  }
+}