@openanonymity/nanomem 0.1.0

package/src/engine/retriever.js

@@ -0,0 +1,414 @@
+/**
+ * MemoryRetriever — Read path for agentic memory.
+ *
+ * Uses tool-calling via the agentic loop to let the LLM search, read,
+ * and assemble relevant memory context. Falls back to brute-force text
+ * search if the LLM call fails.
+ */
+/** @import { LLMClient, Message, ProgressEvent, RetrievalResult, StorageBackend, ToolDefinition } from '../types.js' */
+import { runAgenticToolLoop } from './toolLoop.js';
+import { createRetrievalExecutors } from './executors.js';
+import {
+    normalizeFactText,
+    parseBullets,
+    renderBullet,
+    scoreBullet,
+    tokenizeQuery
+} from '../bullets/index.js';
+
+const MAX_FILES_TO_LOAD = 8;
+const MAX_TOTAL_CONTEXT_CHARS = 4000;
+const MAX_SNIPPETS = 18;
+const MAX_RECENT_CONTEXT_CHARS = 2000;
+
+/** @type {ToolDefinition[]} */
+const RETRIEVAL_TOOLS = [
+    {
+        type: 'function',
+        function: {
+            name: 'list_directory',
+            description: 'List all files and subdirectories in a directory. Use this to discover all files in a domain (e.g. "health" to see all health condition files).',
+            parameters: {
+                type: 'object',
+                properties: {
+                    dir_path: { type: 'string', description: 'Directory path (e.g. "health", "personal", "work"). Use empty string for root.' }
+                },
+                required: ['dir_path']
+            }
+        }
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'retrieve_file',
+            description: 'Search memory files by keyword. Returns paths of files whose content or path matches the query. Use read_file instead if you already know the file path.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'Keyword to search for in file contents (e.g. "cooking", "Stanford", "project")' }
+                },
+                required: ['query']
+            }
+        }
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'read_file',
+            description: 'Read the content of a memory file by its path.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string', description: 'File path to read (e.g. personal/about.md)' }
+                },
+                required: ['path']
+            }
+        }
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'assemble_context',
+            description: 'Synthesize and return the final answer to the user\'s query based on what you read. Do NOT paste raw file content — write a clear, direct answer in plain prose. You MUST call this when done, even if nothing relevant was found (pass an empty string).',
+            parameters: {
+                type: 'object',
+                properties: {
+                    content: { type: 'string', description: 'A synthesized, human-readable answer to the query derived from the memory files. Write prose, not raw bullet dumps. If nothing relevant was found, pass an empty string.' }
+                },
+                required: ['content']
+            }
+        }
+    }
+];
+
+const RETRIEVAL_SYSTEM_PROMPT = `You are a memory retrieval assistant. Your job is to find and assemble relevant personal context from the user's memory files to help answer their query.
+
+You have access to a memory filesystem. The index below shows all available files:
+
+\`\`\`
+{INDEX}
+\`\`\`
+
+Instructions:
+1. Look at the index above. If you can already see relevant file paths, use read_file directly to read them.
+2. Use retrieve_file only when you need to search by keyword (e.g. "cooking", "Stanford") — it searches file contents, not paths.
+3. Use list_directory to see ALL files in a directory when the query relates to a broad domain (e.g. list "health" for any medicine/health query).
+4. Read at most ${MAX_FILES_TO_LOAD} files.
+5. You MUST always finish by calling assemble_context — write a direct, synthesized answer in plain prose based on what you read. Do NOT paste raw bullet lists or file content. If the query is historical or comparative, reason over the facts and answer accordingly.
+6. If nothing is relevant, call assemble_context with an empty string.
+
+IMPORTANT — Domain-exhaustive retrieval:
+- When a query touches a domain (health, work, personal), prefer completeness over selectivity within that domain. File descriptions may be incomplete.
+- For family-related queries: check personal/family.md AND any health files about family members.
+
+When recent conversation context is provided alongside the query, use it to resolve references like "that", "the same", "what we discussed", etc. The conversation shows what the user has been talking about recently.
+
+Only include content that genuinely helps answer this specific query. Do not include unrelated files from other domains.`;
+
+
+class MemoryRetriever {
+    constructor({ backend, bulletIndex, llmClient, model, onProgress, onModelText }) {
+        this._backend = backend;
+        this._bulletIndex = bulletIndex;
+        this._llmClient = llmClient;
+        this._model = model;
+        this._onProgress = onProgress || null;
+        this._onModelText = onModelText || null;
+    }
+
+    /**
+     * Retrieve relevant memory context for a user query.
+     *
+     * @param {string} query the user's message text
+     * @param {string} [conversationText] current session text for reference resolution
+     * @returns {Promise<RetrievalResult | null>}
+     */
+    async retrieveForQuery(query, conversationText) {
+        if (!query || !query.trim()) return null;
+
+        const onProgress = this._onProgress;
+        const onModelText = this._onModelText;
+
+        onProgress?.({ stage: 'init', message: 'Reading memory index...' });
+        await this._backend.init();
+        const index = await this._backend.getTree();
+
+        if (!index || await this._isMemoryEmpty(index)) {
+            return null;
+        }
+
+        let result;
+        try {
+            onProgress?.({ stage: 'retrieval', message: 'Selecting relevant memory files...' });
+            result = await this._toolCallingRetrieval(query, index, onProgress, conversationText, onModelText);
+        } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            onProgress?.({ stage: 'fallback', message: `LLM unavailable (${message}) — falling back to keyword search. Results may be less accurate.` });
+            result = await this._textSearchFallbackWithLoad(query, onProgress, conversationText);
+        }
+
+        // Post-filter assembled context to remove facts already in the conversation
+        if (result?.assembledContext && conversationText) {
+            result.assembledContext = this._filterRedundantContext(result.assembledContext, conversationText);
+        }
+
+        return result;
+    }
+
+    async _toolCallingRetrieval(query, index, onProgress, conversationText, onModelText) {
+        const systemPrompt = RETRIEVAL_SYSTEM_PROMPT
+            .replace('{INDEX}', index);
+        const toolExecutors = createRetrievalExecutors(this._backend);
+
+        const recentContext = this._buildRecentContext(conversationText);
+        const userContent = recentContext
+            ? `Recent conversation:\n\`\`\`\n${recentContext}\n\`\`\`\n\nCurrent query: ${query}`
+            : query;
+
+        const { terminalToolResult, toolCallLog } = await runAgenticToolLoop({
+            llmClient: this._llmClient,
+            model: this._model,
+            tools: RETRIEVAL_TOOLS,
+            toolExecutors,
+            messages: [
+                { role: 'system', content: systemPrompt },
+                { role: 'user', content: userContent }
+            ],
+            terminalTool: 'assemble_context',
+            maxIterations: 8,
+            maxOutputTokens: 4000,
+            temperature: 0,
+            onToolCall: (name, args, result) => {
+                onProgress?.({ stage: 'tool_call', message: `Tool: ${name}`, tool: name, args, result });
+            },
+            onModelText,
+            onReasoning: (chunk, iteration) => {
+                onProgress?.({ stage: 'reasoning', message: chunk, iteration });
+            }
+        });
+
+        const files = [];
+        const seenPaths = new Set();
+        for (const entry of toolCallLog) {
+            if (entry.name === 'read_file' && entry.args?.path && entry.result) {
+                const path = entry.args.path;
+                if (seenPaths.has(path)) continue;
+                try {
+                    const parsed = JSON.parse(entry.result);
+                    if (parsed.error) continue;
+                } catch { /* not JSON, it's file content */ }
+                seenPaths.add(path);
+                files.push({ path, content: entry.result });
+            }
+        }
+
+        const assembledContext = terminalToolResult?.arguments?.content || null;
+        const paths = files.map(f => f.path);
+
+        if (files.length === 0 && !assembledContext) return null;
+
+        const snippetContext = await this._buildSnippetContext(paths, query, conversationText);
+
+        onProgress?.({
+            stage: 'complete',
+            message: `Retrieved ${files.length} memory file${files.length === 1 ? '' : 's'}.`,
+            paths
+        });
+
+        return { files, paths, assembledContext: assembledContext || snippetContext };
+    }
+
+    async _textSearchFallbackWithLoad(query, onProgress, conversationText) {
+        const paths = await this._textSearchFallback(query);
+        if (!paths || paths.length === 0) return null;
+
+        const MAX_PER_FILE_CHARS = 1500;
+        const files = [];
+        let total = 0;
+        for (const path of paths.slice(0, MAX_FILES_TO_LOAD)) {
+            onProgress?.({ stage: 'loading', message: `Loading ${path}...`, path });
+            const raw = await this._backend.read(path);
+            if (!raw) continue;
+            const content = raw.length > MAX_PER_FILE_CHARS
+                ? raw.slice(0, MAX_PER_FILE_CHARS) + '...(truncated)'
+                : raw;
+            if (total + content.length > MAX_TOTAL_CONTEXT_CHARS) break;
+            files.push({ path, content });
+            total += content.length;
+        }
+
+        if (files.length === 0) return null;
+
+        const assembled = await this._buildSnippetContext(files.map(f => f.path), query, conversationText);
+
+        onProgress?.({
+            stage: 'complete',
+            message: `Retrieved ${files.length} memory file${files.length === 1 ? '' : 's'}.`,
+            paths: files.map(f => f.path)
+        });
+
+        return { files, paths: files.map(f => f.path), assembledContext: assembled };
+    }
+
+    async _textSearchFallback(query) {
+        const words = query.split(/\s+/).filter(w => w.length > 3).slice(0, 3);
+        const allPaths = new Set();
+
+        for (const word of words) {
+            const results = await this._backend.search(word);
+            for (const r of results) {
+                allPaths.add(r.path);
+            }
+        }
+
+        return [...allPaths].slice(0, MAX_FILES_TO_LOAD);
+    }
+
+    async _buildSnippetContext(paths, query, conversationText) {
+        const queryTerms = tokenizeQuery(query);
+        let candidates = [];
+        const convWords = conversationText
+            ? new Set(normalizeFactText(conversationText).split(/\s+/).filter(w => w.length >= 3))
+            : null;
+
+        await this._bulletIndex.init();
+        const indexed = this._bulletIndex.getBulletsForPaths(paths);
+
+        if (indexed.length === 0) {
+            for (const path of paths) {
+                await this._bulletIndex.refreshPath(path);
+            }
+        }
+
+        const indexedAfterRefresh = this._bulletIndex.getBulletsForPaths(paths);
+        for (const item of indexedAfterRefresh) {
+            const score = scoreBullet(item.bullet, queryTerms);
+            candidates.push({
+                path: item.path,
+                score,
+                text: renderBullet(item.bullet),
+                updatedAt: item.bullet.updatedAt || '',
+                fileUpdatedAt: item.fileUpdatedAt || 0
+            });
+        }
+
+        // Legacy fallback if a path is still not indexable.
+        if (candidates.length === 0) {
+            for (const path of paths) {
+                const raw = await this._backend.read(path);
+                if (!raw) continue;
+                const bullets = parseBullets(raw);
+                if (bullets.length > 0) {
+                    for (const bullet of bullets) {
+                        const score = scoreBullet(bullet, queryTerms);
+                        candidates.push({ path, score, text: renderBullet(bullet), updatedAt: bullet.updatedAt || '' });
+                    }
+                    continue;
+                }
+                for (const snippet of this._scoreRawLines(raw, queryTerms)) {
+                    candidates.push({ path, score: snippet.score, text: `- ${snippet.text}`, updatedAt: '' });
+                }
+            }
+        }
+
+        // Filter out bullets already present in the current conversation
+        if (convWords && convWords.size > 0) {
+            candidates = candidates.filter(c => {
+                const factWords = normalizeFactText(c.text).split(/\s+/).filter(w => w.length >= 3);
+                if (factWords.length < 2) return true;
+                const matchCount = factWords.filter(w => convWords.has(w)).length;
+                return matchCount / factWords.length < 0.8;
+            });
+        }
+
+        if (candidates.length === 0) return null;
+
+        candidates.sort((a, b) => {
+            if (b.score !== a.score) return b.score - a.score;
+            return String(b.updatedAt || '').localeCompare(String(a.updatedAt || ''));
+        });
+
+        const selected = candidates.slice(0, MAX_SNIPPETS);
+        const grouped = new Map();
+        for (const item of selected) {
+            const list = grouped.get(item.path) || [];
+            list.push(item.text);
+            grouped.set(item.path, list);
+        }
+
+        let total = 0;
+        const sections = [];
+        for (const [path, lines] of grouped.entries()) {
+            const section = `### ${path}\n${lines.join('\n')}`;
+            if (total + section.length > MAX_TOTAL_CONTEXT_CHARS) break;
+            sections.push(section);
+            total += section.length;
+        }
+
+        return sections.join('\n\n').trim() || null;
+    }
+
+    _filterRedundantContext(assembledContext, conversationText) {
+        const convWords = new Set(
+            normalizeFactText(conversationText).split(/\s+/).filter(w => w.length >= 3)
+        );
+        if (convWords.size === 0) return assembledContext;
+
+        const lines = assembledContext.split('\n');
+        const filtered = lines.filter(line => {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith('#') || !trimmed.startsWith('-')) return true;
+            const factWords = normalizeFactText(trimmed).split(/\s+/).filter(w => w.length >= 3);
+            if (factWords.length < 2) return true;
+            const matchCount = factWords.filter(w => convWords.has(w)).length;
+            return matchCount / factWords.length < 0.8;
+        });
+
+        const result = filtered.join('\n').trim();
+        return result || null;
+    }
+
+    _scoreRawLines(content, queryTerms) {
+        const lines = String(content || '')
+            .split('\n')
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .filter((line) => !line.startsWith('#'));
+        if (lines.length === 0) return [];
+
+        const snippets = lines.map((line) => {
+            const lower = line.toLowerCase();
+            let score = 0;
+            for (const term of queryTerms) {
+                if (lower.includes(term)) score += 1;
+            }
+            return { text: line, score };
+        });
+
+        snippets.sort((a, b) => b.score - a.score);
+        return snippets.slice(0, 5);
+    }
+
+    _buildRecentContext(conversationText) {
+        if (!conversationText || conversationText.length < 20) return null;
+        if (conversationText.length <= MAX_RECENT_CONTEXT_CHARS) {
+            const hasMultipleTurns = /\n/.test(conversationText.trim());
+            return hasMultipleTurns ? conversationText : null;
+        }
+        let tail = conversationText.slice(-MAX_RECENT_CONTEXT_CHARS);
+        const firstNewline = tail.indexOf('\n');
+        if (firstNewline > 0 && firstNewline < 200) {
+            tail = tail.slice(firstNewline + 1);
+        }
+        return tail.trim() || null;
+    }
+
+    async _isMemoryEmpty(index) {
+        const all = await this._backend.exportAll();
+        const realFiles = all.filter(f => !f.path.endsWith('_tree.md'));
+        if (realFiles.length === 0) return true;
+        return !realFiles.some(f => (f.itemCount || 0) > 0);
+    }
+}
+
+export { MemoryRetriever };

package/src/engine/toolLoop.js

@@ -0,0 +1,176 @@
+/**
+ * AgenticToolLoop — Backend-agnostic agentic tool-calling loop.
+ *
+ * Sends messages to an LLM with OpenAI-format tool definitions, executes
+ * tool calls locally, and loops until the LLM stops calling tools or a
+ * terminal tool is invoked.  When an onReasoning callback is provided,
+ * uses streaming to surface reasoning tokens in real time; otherwise
+ * uses non-streaming requests for reliable tool call parsing.
+ */
+/** @import { ToolLoopOptions, ToolLoopResult, ChatCompletionResponse, ToolCall, LLMMessage } from '../types.js' */
+
+const DEFAULT_MAX_ITERATIONS = 10;
+const DEFAULT_MAX_OUTPUT_TOKENS = 500;
+const DEFAULT_TEMPERATURE = 0;
+
+/**
+ * Run an agentic tool-calling loop.
+ *
+ * @param {ToolLoopOptions} options
+ * @returns {Promise<ToolLoopResult>}
+ */
+export async function runAgenticToolLoop(options) {
+    const {
+        llmClient,
+        model,
+        tools,
+        toolExecutors,
+        messages: initialMessages,
+        terminalTool = null,
+        maxIterations = DEFAULT_MAX_ITERATIONS,
+        maxOutputTokens = DEFAULT_MAX_OUTPUT_TOKENS,
+        temperature = DEFAULT_TEMPERATURE,
+        onToolCall = null,
+        onModelText = null,
+        onReasoning = null,
+        signal = null
+    } = options;
+
+    const messages = [...initialMessages];
+    const toolCallLog = [];
+    let textResponse = '';
+    let terminalToolResult = null;
+    let iterations = 0;
+
+    // Stream when onReasoning is provided (surfaces reasoning tokens in real time).
+    // Otherwise use non-streaming createChatCompletion for reliable tool call parsing.
+    const useStreaming = !!onReasoning && !!llmClient.streamChatCompletion;
+
+    for (let i = 0; i < maxIterations; i++) {
+        if (signal?.aborted) break;
+        iterations++;
+
+        const requestPayload = {
+            model,
+            messages: messages.map(m => ({
+                role: m.role,
+                content: m.content,
+                ...(m.tool_calls ? { tool_calls: m.tool_calls } : {}),
+                ...(m.tool_call_id ? { tool_call_id: m.tool_call_id } : {})
+            })),
+            tools,
+            max_tokens: maxOutputTokens,
+            temperature
+        };
+
+        let response;
+        let iterationText = '';
+
+        if (useStreaming) {
+            response = await llmClient.streamChatCompletion({
+                ...requestPayload,
+                onDelta: (d) => { iterationText += d; },
+                onReasoning: (d) => { onReasoning(d, iterations); }
+            });
+        } else {
+            response = await llmClient.createChatCompletion(requestPayload);
+        }
+
+        // If output was truncated and no tool calls came through, retry once with 2× tokens.
+        if (response.finish_reason === 'length' && (response.tool_calls || []).length === 0) {
+            const retryTokens = requestPayload.max_tokens * 2;
+            const retryPayload = { ...requestPayload, max_tokens: retryTokens };
+            iterationText = '';
+            response = useStreaming
+                ? await llmClient.streamChatCompletion({ ...retryPayload, onDelta: (d) => { iterationText += d; }, onReasoning: (d) => { onReasoning(d, iterations); } })
+                : await llmClient.createChatCompletion(retryPayload);
+        }
+
+        const responseToolCalls = response.tool_calls || [];
+        const responseText = iterationText || response.content || '';
+
+        // Forward model text to caller (even alongside tool calls)
+        if (responseText && onModelText) {
+            onModelText(responseText, iterations);
+        }
+
+        // No tool calls → LLM is done, return text response
+        if (responseToolCalls.length === 0) {
+            textResponse = responseText;
+            break;
+        }
+
+        // Append assistant message with tool_calls to conversation
+        messages.push({
+            role: 'assistant',
+            content: responseText || null,
+            tool_calls: responseToolCalls
+        });
+
+        // Execute each tool call
+        let hitTerminal = false;
+        for (const tc of responseToolCalls) {
+            const toolName = tc.function?.name || '';
+            let args;
+            try {
+                args = typeof tc.function?.arguments === 'string'
+                    ? JSON.parse(tc.function.arguments)
+                    : (tc.function?.arguments || {});
+            } catch {
+                args = {};
+            }
+
+            const toolCallId = tc.id || '';
+
+            // Check for terminal tool
+            if (terminalTool && toolName === terminalTool) {
+                terminalToolResult = { name: toolName, arguments: args };
+                toolCallLog.push({ name: toolName, args, result: '[terminal]', toolCallId });
+                onToolCall?.(toolName, args, '[terminal]');
+
+                // Still need to append tool result so conversation is valid
+                messages.push({
+                    role: 'tool',
+                    content: JSON.stringify({ acknowledged: true }),
+                    tool_call_id: toolCallId
+                });
+                hitTerminal = true;
+                break;
+            }
+
+            // Execute the tool
+            let result;
+            const executor = toolExecutors[toolName];
+            if (!executor) {
+                result = JSON.stringify({ error: `Unknown tool: ${toolName}` });
+            } else {
+                try {
+                    result = await executor(args);
+                } catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    result = JSON.stringify({ error: `Tool error: ${message}` });
+                }
+            }
+
+            toolCallLog.push({ name: toolName, args, result, toolCallId });
+            onToolCall?.(toolName, args, result);
+
+            // Append tool result
+            messages.push({
+                role: 'tool',
+                content: typeof result === 'string' ? result : JSON.stringify(result),
+                tool_call_id: toolCallId
+            });
+        }
+
+        if (hitTerminal) break;
+    }
+
+    return {
+        textResponse,
+        terminalToolResult,
+        messages,
+        iterations,
+        toolCallLog
+    };
+}