@syntesseraai/opencode-feature-factory 0.2.44 → 0.3.0

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

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ */
+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 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;

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

@@ -0,0 +1,71 @@
+/**
+ * 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
+// ────────────────────────────────────────────────────────────
+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.
+ */
+export function initLocalRecall(directory) {
+    _directory = directory;
+    _initialized = true;
+}
+/**
+ * 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;
+    }
+}
+/**
+ * Get the results of the last extraction pass.
+ */
+export function getLastExtractionStats() {
+    return _lastExtraction;
+}
+/**
+ * Shutdown the local-recall system.  Currently a no-op but
+ * provided for lifecycle symmetry and future cleanup needs.
+ */
+export function shutdownLocalRecall() {
+    _initialized = false;
+    _directory = null;
+    _lastExtraction = null;
+}

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

@@ -0,0 +1,90 @@
+/**
+ * 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;
+    args: {
+        title: import("zod").ZodString;
+        description: import("zod").ZodString;
+        category: import("zod").ZodEnum<{
+            pattern: "pattern";
+            decision: "decision";
+            debugging: "debugging";
+            preference: "preference";
+            context: "context";
+            procedure: "procedure";
+        }>;
+        tags: import("zod").ZodArray<import("zod").ZodString>;
+        importance: import("zod").ZodOptional<import("zod").ZodNumber>;
+        content: import("zod").ZodOptional<import("zod").ZodString>;
+        source: import("zod").ZodOptional<import("zod").ZodEnum<{
+            conversation: "conversation";
+            research: "research";
+            implementation: "implementation";
+            review: "review";
+        }>>;
+        relatedMemories: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+        context: import("zod").ZodOptional<import("zod").ZodObject<{
+            project: import("zod").ZodOptional<import("zod").ZodString>;
+            task: import("zod").ZodOptional<import("zod").ZodString>;
+            files: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+        }, import("zod/v4/core").$strip>>;
+    };
+    execute(args: {
+        title: string;
+        description: string;
+        category: "pattern" | "decision" | "debugging" | "preference" | "context" | "procedure";
+        tags: string[];
+        importance?: number | undefined;
+        content?: string | undefined;
+        source?: "conversation" | "research" | "implementation" | "review" | undefined;
+        relatedMemories?: string[] | undefined;
+        context?: {
+            project?: string | undefined;
+            task?: string | undefined;
+            files?: string[] | undefined;
+        } | undefined;
+    }, context: ToolContext): Promise<string>;
+};
+export declare const createLearningSearchTool: () => {
+    description: string;
+    args: {
+        query: import("zod").ZodString;
+        tags: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+        category: import("zod").ZodOptional<import("zod").ZodEnum<{
+            pattern: "pattern";
+            decision: "decision";
+            debugging: "debugging";
+            preference: "preference";
+            context: "context";
+            procedure: "procedure";
+        }>>;
+        limit: import("zod").ZodOptional<import("zod").ZodNumber>;
+        minImportance: import("zod").ZodOptional<import("zod").ZodNumber>;
+    };
+    execute(args: {
+        query: string;
+        tags?: string[] | undefined;
+        category?: "pattern" | "decision" | "debugging" | "preference" | "context" | "procedure" | undefined;
+        limit?: number | undefined;
+        minImportance?: number | undefined;
+    }, context: ToolContext): Promise<string>;
+};
+export declare const createLearningGetTool: () => {
+    description: string;
+    args: {
+        memoryId: import("zod").ZodString;
+    };
+    execute(args: {
+        memoryId: string;
+    }, context: ToolContext): Promise<string>;
+};

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

@@ -0,0 +1,162 @@
+/**
+ * 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 { tool } from '@opencode-ai/plugin/tool';
+import { searchMemories, getMemory } from './memory-service.js';
+import { runExtraction } from './daemon.js';
+// ────────────────────────────────────────────────────────────
+// ff-learning-store  →  triggers extraction + explicit store
+// ────────────────────────────────────────────────────────────
+export const createLearningStoreTool = () => tool({
+    description: 'Store a new learning/memory. Creates a JSON memory file in .feature-factory/local-recall/memories/. ' +
+        'Also triggers extraction from OpenCode session history so that ' +
+        'new memories are automatically captured from recent conversations.',
+    args: {
+        title: tool.schema.string('Title for the memory'),
+        description: tool.schema.string('Brief description of the learning'),
+        category: tool.schema.enum(['pattern', 'decision', 'debugging', 'preference', 'context', 'procedure'], 'Category of memory: pattern (reusable code), decision (arch/design), debugging (error resolution), preference (user pref), context (domain knowledge), procedure (how-to)'),
+        tags: tool.schema.array(tool.schema.string(), 'Tags for categorization'),
+        importance: tool.schema.number('Importance score from 0 to 1').optional(),
+        content: tool.schema.string('Full content/body of the memory').optional(),
+        source: tool.schema.enum(['conversation', 'research', 'implementation', 'review']).optional(),
+        relatedMemories: tool.schema.array(tool.schema.string(), 'Related memory IDs').optional(),
+        context: tool.schema
+            .object({
+            project: tool.schema.string().optional(),
+            task: tool.schema.string().optional(),
+            files: tool.schema.array(tool.schema.string()).optional(),
+        })
+            .optional(),
+    },
+    async execute(args, toolCtx) {
+        try {
+            // Run extraction to ensure latest session data is captured
+            const stats = await runExtraction(toolCtx.directory);
+            // Also store the explicit memory from the agent
+            const { storeMemory } = await import('./memory-service.js');
+            const memory = {
+                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',
+            };
+            const result = await storeMemory(toolCtx.directory, memory);
+            return JSON.stringify({
+                success: true,
+                memoryId: result.id,
+                extractionStats: {
+                    sessionsScanned: stats.sessionsScanned,
+                    newMemories: stats.newMemories,
+                },
+            });
+        }
+        catch (err) {
+            return JSON.stringify({
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    },
+});
+// ────────────────────────────────────────────────────────────
+// ff-learning-search  →  searches local-recall memory store
+// ────────────────────────────────────────────────────────────
+export const createLearningSearchTool = () => tool({
+    description: 'Search for memories by query, tags, or category. Returns matching memory metadata sorted by relevance and importance. ' +
+        'Searches the local-recall memory store which is automatically populated from OpenCode session history.',
+    args: {
+        query: tool.schema.string('Search query to match against memory content'),
+        tags: tool.schema.array(tool.schema.string(), 'Filter by tags').optional(),
+        category: tool.schema
+            .enum(['pattern', 'decision', 'debugging', 'preference', 'context', 'procedure'])
+            .optional(),
+        limit: tool.schema.number('Max results (1-50, default 10)').optional(),
+        minImportance: tool.schema.number('Minimum importance 0-1').optional(),
+    },
+    async execute(args, toolCtx) {
+        try {
+            const results = await searchMemories(toolCtx.directory, {
+                query: args.query,
+                tags: args.tags,
+                category: args.category,
+                minImportance: args.minImportance,
+                limit: Math.min(Math.max(args.limit ?? 10, 1), 50),
+            });
+            return JSON.stringify({
+                count: results.length,
+                memories: results.map((r) => ({
+                    id: r.id,
+                    title: r.title,
+                    category: r.category,
+                    tags: r.tags,
+                    importance: r.importance,
+                    relevance: Math.round(r.relevance * 100) / 100,
+                    createdAt: r.createdAt,
+                    sessionID: r.sessionID,
+                })),
+            });
+        }
+        catch (err) {
+            return JSON.stringify({
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    },
+});
+// ────────────────────────────────────────────────────────────
+// ff-learning-get  →  retrieves a specific memory by ID
+// ────────────────────────────────────────────────────────────
+export const createLearningGetTool = () => tool({
+    description: 'Retrieve the full content of a specific memory by its unique ID. ' +
+        'Returns the complete memory including body text from the local-recall store.',
+    args: {
+        memoryId: tool.schema.string('Unique memory ID to retrieve'),
+    },
+    async execute(args, toolCtx) {
+        try {
+            const memory = await getMemory(toolCtx.directory, args.memoryId);
+            if (!memory) {
+                return JSON.stringify({
+                    success: false,
+                    error: `Memory not found: ${args.memoryId}`,
+                });
+            }
+            return JSON.stringify({
+                success: true,
+                memory: {
+                    id: memory.id,
+                    sessionID: memory.sessionID,
+                    messageID: memory.messageID,
+                    category: memory.category,
+                    title: memory.title,
+                    body: memory.body,
+                    tags: memory.tags,
+                    importance: memory.importance,
+                    createdAt: memory.createdAt,
+                    extractedBy: memory.extractedBy,
+                },
+            });
+        }
+        catch (err) {
+            return JSON.stringify({
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    },
+});

package/dist/local-recall/memory-service.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Memory Service
+ *
+ * MCP-backed memory domain service that stores and retrieves
+ * extracted memories as JSON files in .feature-factory/local-recall/memories/
+ */
+import type { Memory, SearchCriteria, MemorySearchResult } from './types.js';
+/**
+ * Persist a memory to disk.
+ */
+export declare function storeMemory(directory: string, memory: Memory): Promise<{
+    id: string;
+    filePath: string;
+}>;
+/**
+ * Persist multiple memories at once.
+ */
+export declare function storeMemories(directory: string, memories: Memory[]): Promise<void>;
+/**
+ * Read a single memory by ID.
+ */
+export declare function getMemory(directory: string, memoryId: string): Promise<Memory | null>;
+/**
+ * List all stored memories.
+ */
+export declare function listAllMemories(directory: string): Promise<Memory[]>;
+/**
+ * Search memories by criteria.
+ * Returns results sorted by relevance * importance, limited to `limit`.
+ */
+export declare function searchMemories(directory: string, criteria: SearchCriteria): Promise<MemorySearchResult[]>;

package/dist/local-recall/memory-service.js

@@ -0,0 +1,156 @@
+/**
+ * Memory Service
+ *
+ * MCP-backed memory domain service that stores and retrieves
+ * extracted memories as JSON files in .feature-factory/local-recall/memories/
+ */
+import { readFile, writeFile, readdir, mkdir } from 'fs/promises';
+import path from 'path';
+const { join, resolve } = path;
+/** Only allow IDs that are safe for filenames: alphanumeric, hyphens, underscores. */
+const SAFE_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+function getMemoriesDir(directory) {
+    return join(directory, '.feature-factory', 'local-recall', 'memories');
+}
+/**
+ * Validate a memory ID and resolve its file path with containment check.
+ * Throws if the ID is invalid or the resolved path escapes the memories directory.
+ */
+function resolveMemoryPath(memoriesDir, memoryId) {
+    if (!SAFE_ID_PATTERN.test(memoryId)) {
+        throw new Error(`Invalid memory ID: ${memoryId}`);
+    }
+    const resolved = resolve(memoriesDir, `${memoryId}.json`);
+    const canonicalDir = resolve(memoriesDir);
+    const relative = path.relative(canonicalDir, resolved);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error(`Memory ID escapes storage directory: ${memoryId}`);
+    }
+    return resolved;
+}
+// ── Store ───────────────────────────────────────────────────────
+/**
+ * Persist a memory to disk.
+ */
+export async function storeMemory(directory, memory) {
+    const memoriesDir = getMemoriesDir(directory);
+    await mkdir(memoriesDir, { recursive: true });
+    const filePath = resolveMemoryPath(memoriesDir, memory.id);
+    await writeFile(filePath, JSON.stringify(memory, null, 2), 'utf-8');
+    return { id: memory.id, filePath };
+}
+/**
+ * Persist multiple memories at once.
+ */
+export async function storeMemories(directory, memories) {
+    for (const memory of memories) {
+        await storeMemory(directory, memory);
+    }
+}
+// ── Retrieve ────────────────────────────────────────────────────
+/**
+ * Read a single memory by ID.
+ */
+export async function getMemory(directory, memoryId) {
+    try {
+        const filePath = resolveMemoryPath(getMemoriesDir(directory), memoryId);
+        const raw = await readFile(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * List all stored memories.
+ */
+export async function listAllMemories(directory) {
+    const memoriesDir = getMemoriesDir(directory);
+    try {
+        const files = await readdir(memoriesDir);
+        const jsonFiles = files.filter((f) => f.endsWith('.json'));
+        const memories = [];
+        for (const file of jsonFiles) {
+            try {
+                const raw = await readFile(join(memoriesDir, file), 'utf-8');
+                memories.push(JSON.parse(raw));
+            }
+            catch {
+                // Skip malformed files
+            }
+        }
+        return memories;
+    }
+    catch {
+        return [];
+    }
+}
+// ── Search ──────────────────────────────────────────────────────
+/**
+ * Compute a simple relevance score between a query and a memory.
+ * Uses term-frequency matching on title, body, and tags.
+ */
+function computeRelevance(query, memory) {
+    const queryTerms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    if (queryTerms.length === 0)
+        return 0;
+    const searchable = [
+        memory.title.toLowerCase(),
+        memory.body.toLowerCase(),
+        ...memory.tags.map((t) => t.toLowerCase()),
+    ].join(' ');
+    let matchCount = 0;
+    for (const term of queryTerms) {
+        if (searchable.includes(term)) {
+            matchCount++;
+        }
+    }
+    return matchCount / queryTerms.length;
+}
+/**
+ * Search memories by criteria.
+ * Returns results sorted by relevance * importance, limited to `limit`.
+ */
+export async function searchMemories(directory, criteria) {
+    const allMemories = await listAllMemories(directory);
+    const limit = criteria.limit ?? 10;
+    let filtered = allMemories;
+    // Filter by category
+    if (criteria.category) {
+        filtered = filtered.filter((m) => m.category === criteria.category);
+    }
+    // Filter by session
+    if (criteria.sessionID) {
+        filtered = filtered.filter((m) => m.sessionID === criteria.sessionID);
+    }
+    // Filter by minimum importance
+    if (criteria.minImportance !== undefined) {
+        filtered = filtered.filter((m) => m.importance >= criteria.minImportance);
+    }
+    // Filter by tags (any match)
+    if (criteria.tags && criteria.tags.length > 0) {
+        const tagSet = new Set(criteria.tags.map((t) => t.toLowerCase()));
+        filtered = filtered.filter((m) => m.tags.some((t) => tagSet.has(t.toLowerCase())));
+    }
+    // Score and rank
+    const scored = filtered.map((m) => {
+        const relevance = computeRelevance(criteria.query, m);
+        return {
+            id: m.id,
+            sessionID: m.sessionID,
+            category: m.category,
+            title: m.title,
+            tags: m.tags,
+            importance: m.importance,
+            createdAt: m.createdAt,
+            relevance,
+        };
+    });
+    // Sort by combined score (relevance * importance)
+    scored.sort((a, b) => {
+        const scoreA = a.relevance * a.importance;
+        const scoreB = b.relevance * b.importance;
+        return scoreB - scoreA;
+    });
+    return scored.slice(0, limit);
+}

package/dist/local-recall/model-router.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Model Router
+ *
+ * Determines which AI model to use for memory extraction.
+ * Maintains an allowlist of cheap/fast models suitable for extraction work.
+ */
+import type { AllowedModel } from './types.js';
+/**
+ * Check if a model is in the extraction allowlist.
+ */
+export declare function isAllowedModel(providerID: string, modelID: string): boolean;
+/**
+ * Get the preferred extraction model from the allowlist.
+ */
+export declare function getPreferredModel(): AllowedModel;
+/**
+ * Get all allowed models sorted by priority.
+ */
+export declare function getAllowedModels(): AllowedModel[];
+/**
+ * Find the best allowed model given a set of available provider IDs.
+ */
+export declare function selectModel(availableProviders: string[]): AllowedModel | null;

package/dist/local-recall/model-router.js

@@ -0,0 +1,41 @@
+/**
+ * Model Router
+ *
+ * Determines which AI model to use for memory extraction.
+ * Maintains an allowlist of cheap/fast models suitable for extraction work.
+ */
+/**
+ * Allowlist of models eligible for extraction.
+ * Ordered by priority (lower = preferred).
+ */
+const ALLOWED_MODELS = [
+    { providerID: 'anthropic', modelID: 'claude-haiku-4-5', priority: 1 },
+    { providerID: 'openai', modelID: 'gpt-5-mini', priority: 2 },
+    { providerID: 'moonshot', modelID: 'kimi-k2.5', priority: 3 },
+    { providerID: 'google', modelID: 'gemini-2.0-flash', priority: 4 },
+];
+/**
+ * Check if a model is in the extraction allowlist.
+ */
+export function isAllowedModel(providerID, modelID) {
+    return ALLOWED_MODELS.some((m) => m.providerID === providerID && m.modelID === modelID);
+}
+/**
+ * Get the preferred extraction model from the allowlist.
+ */
+export function getPreferredModel() {
+    return ALLOWED_MODELS[0];
+}
+/**
+ * Get all allowed models sorted by priority.
+ */
+export function getAllowedModels() {
+    return [...ALLOWED_MODELS];
+}
+/**
+ * Find the best allowed model given a set of available provider IDs.
+ */
+export function selectModel(availableProviders) {
+    const providerSet = new Set(availableProviders);
+    return ALLOWED_MODELS.find((m) => providerSet.has(m.providerID)) ?? null;
+}

package/dist/local-recall/processed-log.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Processed Log
+ *
+ * Tracks which messages have already been processed for memory extraction.
+ * Uses content-hash based idempotency: each processed entry stores a
+ * hash derived from the message content so re-extractions with identical
+ * content are skipped even if message IDs change.
+ *
+ * Stored as a JSON file at .feature-factory/local-recall/processed.json
+ */
+import type { ProcessedEntry } from './types.js';
+/**
+ * Create a SHA-256 content hash from one or more text fragments.
+ * Used to de-duplicate extraction across re-processes / message edits.
+ */
+export declare function contentHash(...fragments: string[]): string;
+/**
+ * Read all processed entries from the log.
+ */
+export declare function readProcessedLog(directory: string): Promise<ProcessedEntry[]>;
+/**
+ * Check if a specific message has already been processed (by message ID).
+ */
+export declare function isProcessed(directory: string, messageID: string): Promise<boolean>;
+/**
+ * Check if a content hash has already been processed.
+ * This catches duplicate content even if message IDs differ.
+ */
+export declare function isContentProcessed(directory: string, hash: string): Promise<boolean>;
+/**
+ * Mark messages as processed by appending entries to the log.
+ */
+export declare function markProcessed(directory: string, entries: ProcessedEntry[]): Promise<void>;
+/**
+ * Get the set of already-processed message IDs for fast lookup.
+ */
+export declare function getProcessedMessageIDs(log: ProcessedEntry[]): Set<string>;
+/**
+ * Get the set of already-processed content hashes for fast lookup.
+ */
+export declare function getProcessedHashes(log: ProcessedEntry[]): Set<string>;