@openanonymity/nanomem 0.1.0

package/src/llm/anthropic.js

@@ -0,0 +1,264 @@
+/**
+ * Anthropic Messages API client.
+ *
+ * Translates the standard LLM client interface (OpenAI Chat Completions format)
+ * into Anthropic's Messages API format, so the memory system can use Claude models.
+ *
+ * Uses `fetch` (built into Node 18+ and browsers).
+ */
+/** @import { ChatCompletionParams, ChatCompletionResponse, LLMClient, LLMClientOptions, LLMMessage, ToolCall, ToolDefinition } from '../types.js' */
+
+/**
+ * @param {LLMClientOptions} [options]
+ * @returns {LLMClient}
+ */
+export function createAnthropicClient({ apiKey, baseUrl = 'https://api.anthropic.com', headers = {} } = /** @type {LLMClientOptions} */ ({ apiKey: '' })) {
+    const base = baseUrl.replace(/\/+$/, '');
+
+    function buildHeaders() {
+        return {
+            'Content-Type': 'application/json',
+            'x-api-key': apiKey,
+            'anthropic-version': '2023-06-01',
+            ...headers,
+        };
+    }
+
+    function convertMessages(messages) {
+        let system = '';
+        const converted = [];
+
+        for (const msg of messages) {
+            if (msg.role === 'system') {
+                system += (system ? '\n\n' : '') + msg.content;
+                continue;
+            }
+
+            if (msg.role === 'tool') {
+                // Anthropic uses tool_result content blocks inside "user" messages
+                converted.push({
+                    role: 'user',
+                    content: [{
+                        type: 'tool_result',
+                        tool_use_id: msg.tool_call_id,
+                        content: msg.content,
+                    }],
+                });
+                continue;
+            }
+
+            if (msg.role === 'assistant' && msg.tool_calls && msg.tool_calls.length > 0) {
+                // Build content blocks: text (if any) + tool_use blocks
+                const content = [];
+                if (msg.content) {
+                    content.push({ type: 'text', text: msg.content });
+                }
+                for (const tc of msg.tool_calls) {
+                    let input;
+                    try {
+                        input = typeof tc.function?.arguments === 'string'
+                            ? JSON.parse(tc.function.arguments)
+                            : (tc.function?.arguments || {});
+                    } catch {
+                        input = {};
+                    }
+                    content.push({
+                        type: 'tool_use',
+                        id: tc.id,
+                        name: tc.function?.name || '',
+                        input,
+                    });
+                }
+                converted.push({ role: 'assistant', content });
+                continue;
+            }
+
+            // Regular user/assistant message
+            converted.push({
+                role: msg.role,
+                content: msg.content || '',
+            });
+        }
+
+        return { system, messages: converted };
+    }
+
+    function convertTools(tools) {
+        if (!tools || tools.length === 0) return undefined;
+        return tools.map(t => ({
+            name: t.function?.name || '',
+            description: t.function?.description || '',
+            input_schema: t.function?.parameters || { type: 'object', properties: {} },
+        }));
+    }
+
+    async function createChatCompletion({ model, messages, tools, max_tokens, temperature }) {
+        const { system, messages: convertedMessages } = convertMessages(messages);
+        const body = {
+            model,
+            messages: convertedMessages,
+            max_tokens: max_tokens || 1024,
+            temperature: temperature ?? 0,
+        };
+        if (system) body.system = system;
+        const anthropicTools = convertTools(tools);
+        if (anthropicTools) body.tools = anthropicTools;
+
+        const response = await fetch(`${base}/v1/messages`, {
+            method: 'POST',
+            headers: buildHeaders(),
+            body: JSON.stringify(body),
+        });
+
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            throw new Error(`Anthropic API error ${response.status}: ${text}`);
+        }
+
+        const data = await response.json();
+        return parseAnthropicResponse(data);
+    }
+
+    async function streamChatCompletion({ model, messages, tools, max_tokens, temperature, onDelta, onReasoning }) {
+        const { system, messages: convertedMessages } = convertMessages(messages);
+        const body = {
+            model,
+            messages: convertedMessages,
+            max_tokens: max_tokens || 1024,
+            temperature: temperature ?? 0,
+            stream: true,
+        };
+        if (system) body.system = system;
+        const anthropicTools = convertTools(tools);
+        if (anthropicTools) body.tools = anthropicTools;
+
+        const response = await fetch(`${base}/v1/messages`, {
+            method: 'POST',
+            headers: buildHeaders(),
+            body: JSON.stringify(body),
+        });
+
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            throw new Error(`Anthropic API error ${response.status}: ${text}`);
+        }
+
+        let content = '';
+        const toolCalls = [];
+        let currentToolIndex = -1;
+
+        await readSSE(response, (event) => {
+            const type = event.type;
+
+            if (type === 'content_block_start') {
+                const block = event.content_block;
+                if (block?.type === 'tool_use') {
+                    currentToolIndex++;
+                    toolCalls.push({
+                        id: block.id || '',
+                        type: 'function',
+                        function: { name: block.name || '', arguments: '' },
+                    });
+                }
+            }
+
+            if (type === 'content_block_delta') {
+                const delta = event.delta;
+                if (delta?.type === 'text_delta' && delta.text) {
+                    content += delta.text;
+                    onDelta?.(delta.text);
+                }
+                if (delta?.type === 'thinking_delta' && delta.thinking) {
+                    onReasoning?.(delta.thinking);
+                }
+                if (delta?.type === 'input_json_delta' && delta.partial_json != null && currentToolIndex >= 0) {
+                    toolCalls[currentToolIndex].function.arguments += delta.partial_json;
+                }
+            }
+        });
+
+        return {
+            content,
+            tool_calls: toolCalls,
+            usage: null,
+        };
+    }
+
+    return { createChatCompletion, streamChatCompletion };
+}
+
+// ─── Helpers ─────────────────────────────────────────────────
+
+function parseAnthropicResponse(data) {
+    let content = '';
+    const toolCalls = [];
+
+    for (const block of data.content || []) {
+        if (block.type === 'text') {
+            content += block.text;
+        }
+        if (block.type === 'tool_use') {
+            toolCalls.push(/** @type {ToolCall} */ ({
+                id: block.id,
+                type: 'function',
+                function: {
+                    name: block.name,
+                    arguments: JSON.stringify(block.input || {}),
+                },
+            }));
+        }
+    }
+
+    return {
+        content,
+        tool_calls: toolCalls,
+        usage: data.usage ? {
+            prompt_tokens: data.usage.input_tokens,
+            completion_tokens: data.usage.output_tokens,
+        } : null,
+    };
+}
+
+// ─── SSE Parser (Anthropic format) ──────────────────────────
+
+async function readSSE(response, onMessage) {
+    if (!response.body) {
+        throw new Error('Streaming response body is not available.');
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || '';
+
+        let currentEvent = null;
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed) {
+                currentEvent = null;
+                continue;
+            }
+            if (trimmed.startsWith('event:')) {
+                currentEvent = trimmed.replace(/^event:\s*/, '');
+                continue;
+            }
+            if (!trimmed.startsWith('data:')) continue;
+
+            const data = trimmed.replace(/^data:\s*/, '');
+            if (!data || data === '[DONE]') continue;
+
+            try {
+                const parsed = JSON.parse(data);
+                if (currentEvent) parsed.type = parsed.type || currentEvent;
+                onMessage(parsed);
+            } catch {
+                // Skip unparseable SSE lines
+            }
+        }
+    }
+}

package/src/llm/openai.js

@@ -0,0 +1,179 @@
+/**
+ * OpenAI-compatible HTTP client.
+ *
+ * Works with OpenAI, Tinfoil, OpenRouter, or any provider
+ * that implements the OpenAI Chat Completions API format.
+ *
+ * Uses `fetch` (built into Node 18+ and browsers).
+ */
+/** @import { ChatCompletionParams, ChatCompletionResponse, LLMClient, LLMClientOptions, ToolCall } from '../types.js' */
+
+/**
+ * @param {LLMClientOptions} [options]
+ * @returns {LLMClient}
+ */
+export function createOpenAIClient({ apiKey, baseUrl = 'https://api.openai.com/v1', headers = {} } = /** @type {LLMClientOptions} */ ({ apiKey: '' })) {
+    // Normalize: strip trailing slash
+    const base = baseUrl.replace(/\/+$/, '');
+
+    function buildHeaders() {
+        return {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${apiKey}`,
+            ...headers,
+        };
+    }
+
+    async function createChatCompletion({ model, messages, tools, max_tokens, temperature }) {
+        const body = { model, messages, temperature };
+        if (max_tokens != null) body.max_tokens = max_tokens;
+        if (tools && tools.length > 0) body.tools = tools;
+
+        const response = await fetch(`${base}/chat/completions`, {
+            method: 'POST',
+            headers: buildHeaders(),
+            body: JSON.stringify(body),
+        });
+
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            throw new Error(`OpenAI API error ${response.status}: ${text}`);
+        }
+
+        const data = await response.json();
+        const choice = data.choices?.[0]?.message || {};
+
+        return {
+            content: choice.content || '',
+            tool_calls: (choice.tool_calls || []).map((tc) => ({
+                id: tc.id,
+                type: 'function',
+                function: {
+                    name: tc.function?.name || '',
+                    arguments: tc.function?.arguments || '{}',
+                },
+            })),
+            usage: data.usage || null,
+        };
+    }
+
+    async function streamChatCompletion({ model, messages, tools, max_tokens, temperature, onDelta, onReasoning }) {
+        const body = { model, messages, temperature, stream: true };
+        if (max_tokens != null) body.max_tokens = max_tokens;
+        if (tools && tools.length > 0) body.tools = tools;
+
+        const response = await fetch(`${base}/chat/completions`, {
+            method: 'POST',
+            headers: buildHeaders(),
+            body: JSON.stringify(body),
+        });
+
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            throw new Error(`OpenAI API error ${response.status}: ${text}`);
+        }
+
+        // Accumulate the full response from SSE deltas
+        let content = '';
+        const toolCallAccumulator = new Map();
+
+        await readSSE(response, (chunk) => {
+            const delta = chunk.choices?.[0]?.delta;
+            if (!delta) return;
+
+            // Content delta
+            if (delta.content) {
+                content += delta.content;
+                onDelta?.(delta.content);
+            }
+
+            // Reasoning delta (some providers send this)
+            if (delta.reasoning) {
+                onReasoning?.(delta.reasoning);
+            }
+
+            // Tool call deltas — accumulate by index
+            if (delta.tool_calls) {
+                for (const tc of delta.tool_calls) {
+                    const idx = tc.index ?? 0;
+                    if (!toolCallAccumulator.has(idx)) {
+                        toolCallAccumulator.set(idx, {
+                            id: tc.id || '',
+                            type: 'function',
+                            function: { name: '', arguments: '' },
+                        });
+                    }
+                    const acc = toolCallAccumulator.get(idx);
+                    if (!acc) continue;
+                    if (tc.id) acc.id = tc.id;
+                    if (tc.function?.name) acc.function.name += tc.function.name;
+                    if (tc.function?.arguments) acc.function.arguments += tc.function.arguments;
+                }
+            }
+        });
+
+        const tool_calls = [...toolCallAccumulator.entries()]
+            .sort(([a], [b]) => a - b)
+            .map(([, tc]) => tc);
+
+        return {
+            content,
+            tool_calls,
+            usage: null,
+        };
+    }
+
+    return { createChatCompletion, streamChatCompletion };
+}
+
+// ─── SSE Parser ──────────────────────────────────────────────
+
+async function readSSE(response, onMessage) {
+    if (!response.body) {
+        throw new Error('Streaming response body is not available.');
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || '';
+
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed) continue;
+            if (trimmed.startsWith(':')) continue;
+            if (!trimmed.startsWith('data:')) continue;
+
+            const data = trimmed.replace(/^data:\s*/, '');
+            if (!data || data === '[DONE]') {
+                if (data === '[DONE]') return;
+                continue;
+            }
+
+            try {
+                const parsed = JSON.parse(data);
+                onMessage(parsed);
+            } catch {
+                // Skip unparseable SSE lines
+            }
+        }
+    }
+
+    const remaining = buffer.trim();
+    if (remaining && remaining.startsWith('data:')) {
+        const data = remaining.replace(/^data:\s*/, '');
+        if (data && data !== '[DONE]') {
+            try {
+                const parsed = JSON.parse(data);
+                onMessage(parsed);
+            } catch {
+                // Skip
+            }
+        }
+    }
+}

package/src/prompt_sets/conversation/ingestion.js

@@ -0,0 +1,51 @@
+/**
+ * Prompt set for conversation ingestion.
+ *
+ * Strict mode: only saves facts the user explicitly stated.
+ * Used when importing chat history, conversation logs, or live sessions.
+ */
+
+export const ingestionPrompt = `You are a memory manager. After reading a conversation, decide if any concrete, reusable facts should be saved to the user's memory files.
+
+CRITICAL: Only save facts the user explicitly stated. Do NOT infer, extrapolate, or fabricate information.
+
+Save information that is likely to help in a future conversation. Be selective — only save durable facts, not transient conversation details.
+
+Do NOT save:
+- Anything the user did not explicitly say (no inferences, no extrapolations, no "likely" facts)
+- Information already present in existing files (the system deduplicates automatically)
+- Transient details (greetings, "help me with this", "thanks", questions without lasting answers)
+- The assistant's own reasoning, suggestions, or knowledge — only what the user stated
+- Sensitive secrets (passwords, auth tokens, private keys, full payment data, government IDs)
+- Opinions the assistant expressed unless the user explicitly agreed with them
+
+Current memory index:
+\`\`\`
+{INDEX}
+\`\`\`
+
+**Key principle: Prefer fewer, broader files over many narrow ones.** Organize files into folders by domain (e.g. health/, work/, personal/). Within each folder, group related facts into the same file rather than splitting every sub-topic into its own file. Before creating a new file, check whether an existing file in the same domain could absorb the facts. A single file with many bullets on related sub-topics is better than many files with one or two bullets each.
+
+Instructions:
+1. Read the conversation below and identify facts the user explicitly stated.
+2. Check the memory index above. Default to append_memory when an existing file covers the same domain or a closely related topic. Only use create_new_file when no existing file is thematically close. Do not read files before writing — the system deduplicates automatically.
+3. Use this bullet format: "- Fact text | topic=topic-name | source=SOURCE | confidence=LEVEL | updated_at=YYYY-MM-DD"
+4. Source values:
+   - source=user_statement — the user directly said this. This is the PRIMARY source. Use it for the vast majority of saved facts.
+   - source=llm_infer — use ONLY when combining multiple explicit user statements into an obvious conclusion (e.g. user said "I work at Acme" and "Acme is in SF" → "Works in SF"). Never use this to guess, extrapolate, or fill in gaps. When in doubt, do not save.
+5. Confidence: high for direct user statements, medium for llm_infer. Never save low-confidence items.
+6. You may optionally add tier=working for clearly short-term or in-progress context. If you are unsure, omit tier and just save the fact.
+7. Facts worth saving: allergies, health conditions, location, job/role, tech stack, pets, family members, durable preferences, and active plans — but ONLY if the user explicitly mentioned them.
+8. If a fact is time-sensitive, include date context in the text. You may optionally add review_at or expires_at.
+9. If nothing new is worth remembering, simply stop without calling any write tools. Saving nothing is better than saving something wrong.
+
+Rules:
+- Write facts in a timeless, archival format: use absolute dates (YYYY-MM-DD) rather than relative terms like "recently", "currently", "just", or "last week". A fact must be interpretable correctly even years after it was written.
+- Favor broad thematic files. A file can hold multiple related sub-topics — only truly unrelated facts need separate files.
+- Only create a new file when nothing in the index is thematically close. When in doubt, append.
+- When creating a new file, choose a broad, thematic name that can absorb future related facts — not a narrow label for a single detail.
+- Use update_memory only if a fact is now stale or contradicted.
+- When a new explicit user statement contradicts an older one on the same topic, prefer the newer statement. If a user statement conflicts with an inference, the user statement always wins.
+- If a conflict is ambiguous, preserve both versions rather than deleting one.
+- Do not skip obvious facts just because the schema supports extra metadata.
+- Content should be raw facts only — no filler commentary.`;

package/src/prompt_sets/document/ingestion.js

@@ -0,0 +1,43 @@
+/**
+ * Prompt set for document ingestion.
+ *
+ * Relaxed mode: extracts and reasonably infers facts from reference material.
+ * Used when importing notes, READMEs, articles, code repositories, or knowledge bases.
+ */
+
+export const ingestionPrompt = `You are a memory manager. You are reading documents (notes, README files, code repositories, articles) and extracting facts about the subject into a structured memory bank.
+
+Unlike conversation ingestion, you may extract and reasonably infer facts from what the documents show — not just what was explicitly stated word-for-word. Use good judgment: extract what is clearly supported by the content, avoid speculation.
+
+Save information that would be useful when answering questions about this subject in the future. Be generous — capture expertise, projects, preferences, philosophy, and patterns that emerge from the documents.
+
+Do NOT save:
+- Speculation or guesses not supported by the content
+- Boilerplate (installation steps, license text, generic disclaimers)
+- Information already present in existing files (use read_file to check first)
+- Sensitive secrets (passwords, auth tokens, private keys)
+
+Current memory index:
+\`\`\`
+{INDEX}
+\`\`\`
+
+**Key principle: Create a NEW file for each distinct topic.** Organize into domain folders (e.g. projects/, expertise/, education/, philosophy/) with topic-specific files within them.
+
+Instructions:
+1. Read the document content and identify concrete, reusable facts about the subject.
+2. If a matching file already exists in the index, use read_file first to avoid duplicates.
+3. Use create_new_file for new topics, append_memory to add to existing files.
+4. Use this bullet format: "- Fact text | topic=topic-name | source=SOURCE | confidence=LEVEL | updated_at=YYYY-MM-DD"
+5. Source values (IMPORTANT — never use source=user_statement here):
+   - source=document — the fact is directly stated or clearly shown in the document. Use for the majority of facts.
+   - source=document_infer — a reasonable inference from what multiple parts of the document collectively show (e.g. a repo with only C files and a README praising simplicity → "prefers low-level, minimal implementations"). Use sparingly.
+6. Confidence: high for source=document facts, medium for source=document_infer.
+7. Facts worth extracting: skills and expertise, projects built, stated opinions and philosophy, tools and languages used, patterns across work, goals and motivations, background and experience.
+8. If nothing meaningful can be extracted from a document, stop without calling any write tools.
+
+Rules:
+- Write facts in a timeless, archival format: use absolute dates (YYYY-MM-DD) rather than relative terms like "recently", "currently", "just", or "last week". A fact must be interpretable correctly even years after it was written.
+- One file per distinct topic. Do NOT put unrelated facts in the same file.
+- Create new files freely — focused files are better than bloated ones.
+- Content should be raw facts only — no filler commentary.`;

package/src/prompt_sets/index.js

@@ -0,0 +1,31 @@
+/**
+ * Prompt set registry.
+ *
+ * Each mode provides an ingestionPrompt (and optionally others in future).
+ * resolvePromptSet(mode) returns the full prompt set, falling back to 'conversation'.
+ *
+ * Adding a new mode: create src/prompt_sets/<mode>/ingestion.js, export ingestionPrompt,
+ * then add it to PROMPT_SETS below.
+ */
+
+import { ingestionPrompt as conversationIngestion } from './conversation/ingestion.js';
+import { ingestionPrompt as documentIngestion } from './document/ingestion.js';
+
+/** @type {Record<string, { ingestionPrompt: string }>} */
+const PROMPT_SETS = {
+    conversation: { ingestionPrompt: conversationIngestion },
+    document:     { ingestionPrompt: documentIngestion },
+};
+
+/**
+ * Resolve the prompt set for a given mode.
+ * Falls back to 'conversation' for unknown modes.
+ *
+ * @param {string} [mode]
+ * @returns {{ ingestionPrompt: string }}
+ */
+export function resolvePromptSet(mode = 'conversation') {
+    return PROMPT_SETS[mode] || PROMPT_SETS.conversation;
+}
+
+export const AVAILABLE_MODES = Object.keys(PROMPT_SETS);