@syntesseraai/opencode-feature-factory 0.3.0 → 0.3.2

package/dist/local-recall/mcp-server.d.ts

@@ -1,38 +1,34 @@
-/**
- * mcp-server.ts — MCP server lifecycle for local-recall.
- *
- * Manages the local-recall extraction daemon lifecycle within the
- * OpenCode plugin.  Provides init / shutdown hooks and exposes
- * the extraction trigger for on-demand use.
- */
-import { type ExtractionStats } from './daemon.js';
-/**
- * Initialize the local-recall system for a project directory.
- * Should be called once during plugin startup.
- */
+import type { ExtractionStats } from './daemon.js';
+import { type DaemonStatus } from './daemon-controller.js';
+import type { Memory, MemoryCategory, MemorySearchResult, SearchCriteria } from './types.js';
+import { OramaMemoryIndex } from './vector/orama-index.js';
+import type { VectorSearchResponse } from './vector/types.js';
+export interface LearningStoreInput {
+    title: string;
+    description: string;
+    category: MemoryCategory;
+    tags: string[];
+    importance?: number;
+    content?: string;
+}
+export interface IndexingStatus {
+    daemon: DaemonStatus;
+    index: ReturnType<OramaMemoryIndex['getStatus']>;
+}
 export declare function initLocalRecall(directory: string): void;
-/**
- * Check if local-recall has been initialized.
- */
 export declare function isInitialized(): boolean;
-/**
- * Get the project directory local-recall is bound to.
- */
 export declare function getDirectory(): string | null;
-/**
- * Trigger an extraction pass. Can be called on-demand (e.g. from
- * the ff-learning-store tool) or at startup.
- *
- * Safe to call multiple times — the processed-log prevents
- * duplicate extraction.
- */
-export declare function triggerExtraction(): Promise<ExtractionStats | null>;
-/**
- * Get the results of the last extraction pass.
- */
+export declare function triggerExtraction(directory?: string): Promise<ExtractionStats | null>;
 export declare function getLastExtractionStats(): ExtractionStats | null;
-/**
- * Shutdown the local-recall system.  Currently a no-op but
- * provided for lifecycle symmetry and future cleanup needs.
- */
 export declare function shutdownLocalRecall(): void;
+export declare function storeLearningMemory(directory: string, args: LearningStoreInput): Promise<{
+    memoryId: string;
+    daemon: DaemonStatus;
+}>;
+export declare function searchLearningMemories(directory: string, criteria: SearchCriteria): Promise<VectorSearchResponse>;
+export declare function getLearningMemory(directory: string, memoryID: string): Promise<Memory | null>;
+export declare function startIndexingDaemon(directory: string, intervalMs?: number): Promise<IndexingStatus>;
+export declare function stopIndexingDaemon(directory: string): Promise<IndexingStatus>;
+export declare function getIndexingStatus(directory: string): Promise<IndexingStatus>;
+export declare function rebuildIndex(directory: string): Promise<IndexingStatus>;
+export declare function listLearningMemories(directory: string, criteria: SearchCriteria): Promise<MemorySearchResult[]>;

package/dist/local-recall/mcp-server.js

@@ -1,71 +1,194 @@
-/**
- * mcp-server.ts — MCP server lifecycle for local-recall.
- *
- * Manages the local-recall extraction daemon lifecycle within the
- * OpenCode plugin.  Provides init / shutdown hooks and exposes
- * the extraction trigger for on-demand use.
- */
-import { runExtraction } from './daemon.js';
-// ────────────────────────────────────────────────────────────
-// State
-// ────────────────────────────────────────────────────────────
+import crypto from 'node:crypto';
+import { LocalRecallDaemonController } from './daemon-controller.js';
+import { getMemory, searchMemories, storeMemory } from './memory-service.js';
+import { createEmbeddingProvider } from './vector/embedding-provider.js';
+import { OramaMemoryIndex } from './vector/orama-index.js';
 let _initialized = false;
 let _directory = null;
-let _lastExtraction = null;
-// ────────────────────────────────────────────────────────────
-// Public API
-// ────────────────────────────────────────────────────────────
-/**
- * Initialize the local-recall system for a project directory.
- * Should be called once during plugin startup.
- */
+let _runtime = null;
+let _initPromise = null;
+function parseBoolean(value, fallback) {
+    if (value === undefined) {
+        return fallback;
+    }
+    const normalized = value.trim().toLowerCase();
+    return !['0', 'false', 'off', 'no'].includes(normalized);
+}
+function parseInterval(value, fallback) {
+    if (!value) {
+        return fallback;
+    }
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return fallback;
+    }
+    return Math.round(parsed);
+}
+function createRuntime(directory) {
+    const provider = (() => {
+        try {
+            return createEmbeddingProvider();
+        }
+        catch {
+            return createEmbeddingProvider({
+                ...process.env,
+                FF_LOCAL_RECALL_EMBEDDING_PROVIDER: 'ollama',
+            });
+        }
+    })();
+    const index = new OramaMemoryIndex(directory, provider);
+    const daemon = new LocalRecallDaemonController({
+        directory,
+        index,
+        intervalMs: parseInterval(process.env.FF_LOCAL_RECALL_INDEX_INTERVAL_MS, 15_000),
+        extractionEnabled: parseBoolean(process.env.FF_LOCAL_RECALL_EXTRACTION_ENABLED, true),
+    });
+    return index.initialize().then(() => {
+        const autoStart = parseBoolean(process.env.FF_LOCAL_RECALL_DAEMON_AUTOSTART, true);
+        if (autoStart) {
+            daemon.start();
+        }
+        else {
+            daemon.requestRun('startup');
+        }
+        return {
+            directory,
+            index,
+            daemon,
+        };
+    });
+}
+async function ensureRuntime(directory) {
+    if (directory && directory !== _directory) {
+        initLocalRecall(directory);
+    }
+    if (!_initialized || !_directory) {
+        throw new Error('local-recall is not initialized');
+    }
+    if (!_initPromise) {
+        _initPromise = createRuntime(_directory).then((runtime) => {
+            _runtime = runtime;
+        });
+    }
+    await _initPromise;
+    if (!_runtime) {
+        throw new Error('local-recall runtime failed to initialize');
+    }
+    return _runtime;
+}
 export function initLocalRecall(directory) {
-    _directory = directory;
+    if (_directory === directory && _initialized) {
+        return;
+    }
+    if (_runtime) {
+        _runtime.daemon.stop();
+    }
     _initialized = true;
+    _directory = directory;
+    _runtime = null;
+    _initPromise = createRuntime(directory).then((runtime) => {
+        _runtime = runtime;
+    });
 }
-/**
- * Check if local-recall has been initialized.
- */
 export function isInitialized() {
     return _initialized;
 }
-/**
- * Get the project directory local-recall is bound to.
- */
 export function getDirectory() {
     return _directory;
 }
-/**
- * Trigger an extraction pass. Can be called on-demand (e.g. from
- * the ff-learning-store tool) or at startup.
- *
- * Safe to call multiple times — the processed-log prevents
- * duplicate extraction.
- */
-export async function triggerExtraction() {
-    if (!_initialized || !_directory) {
-        return null;
-    }
-    try {
-        _lastExtraction = await runExtraction(_directory);
-        return _lastExtraction;
-    }
-    catch {
-        return null;
-    }
+export async function triggerExtraction(directory) {
+    const runtime = await ensureRuntime(directory);
+    const status = await runtime.daemon.runNow('trigger-extraction');
+    return status.lastRun?.extraction ?? null;
 }
-/**
- * Get the results of the last extraction pass.
- */
 export function getLastExtractionStats() {
-    return _lastExtraction;
+    return _runtime?.daemon.getStatus().lastRun?.extraction ?? null;
 }
-/**
- * Shutdown the local-recall system.  Currently a no-op but
- * provided for lifecycle symmetry and future cleanup needs.
- */
 export function shutdownLocalRecall() {
+    _runtime?.daemon.stop();
     _initialized = false;
     _directory = null;
-    _lastExtraction = null;
+    _runtime = null;
+    _initPromise = null;
+}
+function toMemory(args) {
+    return {
+        id: crypto.randomUUID(),
+        sessionID: 'agent-explicit',
+        messageID: 'agent-explicit',
+        category: args.category,
+        title: args.title,
+        body: args.content ?? args.description,
+        tags: args.tags,
+        importance: args.importance ?? 0.7,
+        createdAt: Date.now(),
+        extractedBy: 'agent-explicit',
+    };
+}
+export async function storeLearningMemory(directory, args) {
+    const runtime = await ensureRuntime(directory);
+    const memory = toMemory(args);
+    await storeMemory(runtime.directory, memory);
+    runtime.daemon.requestRun('store');
+    return {
+        memoryId: memory.id,
+        daemon: runtime.daemon.getStatus(),
+    };
+}
+export async function searchLearningMemories(directory, criteria) {
+    const runtime = await ensureRuntime(directory);
+    try {
+        const vectorResults = await runtime.index.search(criteria);
+        return {
+            backend: 'vector',
+            results: vectorResults,
+        };
+    }
+    catch (error) {
+        const lexicalResults = await searchMemories(runtime.directory, criteria);
+        return {
+            backend: 'lexical',
+            results: lexicalResults,
+            fallbackReason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export async function getLearningMemory(directory, memoryID) {
+    await ensureRuntime(directory);
+    return getMemory(directory, memoryID);
+}
+export async function startIndexingDaemon(directory, intervalMs) {
+    const runtime = await ensureRuntime(directory);
+    const daemon = runtime.daemon.start(intervalMs);
+    return {
+        daemon,
+        index: runtime.index.getStatus(),
+    };
+}
+export async function stopIndexingDaemon(directory) {
+    const runtime = await ensureRuntime(directory);
+    const daemon = runtime.daemon.stop();
+    return {
+        daemon,
+        index: runtime.index.getStatus(),
+    };
+}
+export async function getIndexingStatus(directory) {
+    const runtime = await ensureRuntime(directory);
+    return {
+        daemon: runtime.daemon.getStatus(),
+        index: runtime.index.getStatus(),
+    };
+}
+export async function rebuildIndex(directory) {
+    const runtime = await ensureRuntime(directory);
+    const daemon = await runtime.daemon.rebuild();
+    return {
+        daemon,
+        index: runtime.index.getStatus(),
+    };
+}
+export async function listLearningMemories(directory, criteria) {
+    const searchResults = await searchLearningMemories(directory, criteria);
+    return searchResults.results;
 }

package/dist/local-recall/mcp-stdio-server.d.ts

@@ -0,0 +1,4 @@
+export interface LocalRecallMCPServerOptions {
+    directory?: string;
+}
+export declare function runLocalRecallMCPServer(options?: LocalRecallMCPServerOptions): Promise<void>;

package/dist/local-recall/mcp-stdio-server.js

@@ -0,0 +1,225 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { getIndexingStatus, getLearningMemory, rebuildIndex, searchLearningMemories, shutdownLocalRecall, startIndexingDaemon, stopIndexingDaemon, storeLearningMemory, initLocalRecall, } from './mcp-server.js';
+const CATEGORIES = [
+    'pattern',
+    'decision',
+    'debugging',
+    'preference',
+    'context',
+    'procedure',
+];
+function toCallResult(payload, isError = false) {
+    return {
+        isError,
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(payload),
+            },
+        ],
+    };
+}
+function asObject(value) {
+    if (!value || typeof value !== 'object') {
+        return {};
+    }
+    return value;
+}
+function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function asNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function asStringArray(value) {
+    if (!Array.isArray(value) || !value.every((item) => typeof item === 'string')) {
+        return undefined;
+    }
+    return value;
+}
+export async function runLocalRecallMCPServer(options = {}) {
+    const directory = options.directory ?? process.env.FF_LOCAL_RECALL_DIRECTORY ?? process.cwd();
+    initLocalRecall(directory);
+    const server = new Server({
+        name: 'ff-local-recall',
+        version: '1.0.0',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            {
+                name: 'local_recall.search',
+                description: 'Search local-recall memories with vector retrieval and lexical fallback.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        query: { type: 'string' },
+                        category: { type: 'string', enum: CATEGORIES },
+                        tags: { type: 'array', items: { type: 'string' } },
+                        minImportance: { type: 'number' },
+                        limit: { type: 'number' },
+                    },
+                    required: ['query'],
+                },
+            },
+            {
+                name: 'local_recall.get',
+                description: 'Get a memory by unique ID.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        memoryId: { type: 'string' },
+                    },
+                    required: ['memoryId'],
+                },
+            },
+            {
+                name: 'local_recall.store',
+                description: 'Store a memory and enqueue async indexing.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        title: { type: 'string' },
+                        description: { type: 'string' },
+                        category: { type: 'string', enum: CATEGORIES },
+                        tags: { type: 'array', items: { type: 'string' } },
+                        importance: { type: 'number' },
+                        content: { type: 'string' },
+                    },
+                    required: ['title', 'description', 'category', 'tags'],
+                },
+            },
+            {
+                name: 'local_recall.index.start',
+                description: 'Start the local-recall daemon.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        intervalMs: { type: 'number' },
+                    },
+                },
+            },
+            {
+                name: 'local_recall.index.status',
+                description: 'Get local-recall daemon status.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            },
+            {
+                name: 'local_recall.index.stop',
+                description: 'Stop local-recall daemon.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            },
+            {
+                name: 'local_recall.index.rebuild',
+                description: 'Perform a full rebuild of the local-recall index.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            },
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const toolName = request.params.name;
+        const args = asObject(request.params.arguments);
+        try {
+            switch (toolName) {
+                case 'local_recall.search': {
+                    const query = asString(args.query);
+                    if (!query) {
+                        return toCallResult({ error: 'query is required' }, true);
+                    }
+                    const result = await searchLearningMemories(directory, {
+                        query,
+                        category: asString(args.category),
+                        tags: asStringArray(args.tags),
+                        minImportance: asNumber(args.minImportance),
+                        limit: asNumber(args.limit),
+                    });
+                    return toCallResult(result);
+                }
+                case 'local_recall.get': {
+                    const memoryId = asString(args.memoryId);
+                    if (!memoryId) {
+                        return toCallResult({ error: 'memoryId is required' }, true);
+                    }
+                    const memory = await getLearningMemory(directory, memoryId);
+                    if (!memory) {
+                        return toCallResult({ error: `Memory not found: ${memoryId}` }, true);
+                    }
+                    return toCallResult({ success: true, memory });
+                }
+                case 'local_recall.store': {
+                    const title = asString(args.title);
+                    const description = asString(args.description);
+                    const category = asString(args.category);
+                    const tags = asStringArray(args.tags);
+                    if (!title || !description || !category || !tags) {
+                        return toCallResult({
+                            error: 'title, description, category, and tags are required',
+                        }, true);
+                    }
+                    if (!CATEGORIES.includes(category)) {
+                        return toCallResult({
+                            error: `Invalid category: ${category}`,
+                        }, true);
+                    }
+                    const result = await storeLearningMemory(directory, {
+                        title,
+                        description,
+                        category: category,
+                        tags,
+                        importance: asNumber(args.importance),
+                        content: asString(args.content),
+                    });
+                    return toCallResult({
+                        success: true,
+                        memoryId: result.memoryId,
+                        daemon: result.daemon,
+                    });
+                }
+                case 'local_recall.index.start': {
+                    const result = await startIndexingDaemon(directory, asNumber(args.intervalMs));
+                    return toCallResult({ success: true, ...result });
+                }
+                case 'local_recall.index.status': {
+                    const result = await getIndexingStatus(directory);
+                    return toCallResult({ success: true, ...result });
+                }
+                case 'local_recall.index.stop': {
+                    const result = await stopIndexingDaemon(directory);
+                    return toCallResult({ success: true, ...result });
+                }
+                case 'local_recall.index.rebuild': {
+                    const result = await rebuildIndex(directory);
+                    return toCallResult({ success: true, ...result });
+                }
+                default:
+                    return toCallResult({ error: `Unknown tool: ${toolName}` }, true);
+            }
+        }
+        catch (error) {
+            return toCallResult({
+                error: error instanceof Error ? error.message : String(error),
+            }, true);
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    const shutdown = () => {
+        shutdownLocalRecall();
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}

package/dist/local-recall/mcp-tools.d.ts

@@ -1,14 +1,3 @@
-/**
- * mcp-tools.ts — OpenCode plugin tool definitions for local-recall.
- *
- * Replaces the legacy ff-learning-{store,search,get} plugins with
- * MCP-backed tools that read from OpenCode's session storage and
- * expose the local-recall memory system.
- *
- * Public contract uses the native MemoryCategory taxonomy
- * (pattern, decision, debugging, preference, context, procedure).
- * The public contract exposes only category-based MCP tools.
- */
 import type { ToolContext } from '@opencode-ai/plugin/tool';
 export declare const createLearningStoreTool: () => {
     description: string;
@@ -88,3 +77,27 @@ export declare const createLearningGetTool: () => {
         memoryId: string;
     }, context: ToolContext): Promise<string>;
 };
+export declare const createLearningIndexStartTool: () => {
+    description: string;
+    args: {
+        intervalMs: import("zod").ZodOptional<import("zod").ZodNumber>;
+    };
+    execute(args: {
+        intervalMs?: number | undefined;
+    }, context: ToolContext): Promise<string>;
+};
+export declare const createLearningIndexStatusTool: () => {
+    description: string;
+    args: {};
+    execute(args: Record<string, never>, context: ToolContext): Promise<string>;
+};
+export declare const createLearningIndexStopTool: () => {
+    description: string;
+    args: {};
+    execute(args: Record<string, never>, context: ToolContext): Promise<string>;
+};
+export declare const createLearningIndexRebuildTool: () => {
+    description: string;
+    args: {};
+    execute(args: Record<string, never>, context: ToolContext): Promise<string>;
+};