@openanonymity/nanomem 0.1.0 → 0.1.2

package/types/backends/BaseStorage.d.ts

@@ -12,6 +12,16 @@ export class BaseStorage {
      * @returns {Promise<string | null>}
      */
     read(path: string): Promise<string | null>;
+    /**
+     * Resolve a user/model-supplied path to the canonical readable path.
+     *
+     * Returns the exact stored path when possible, or a normalized fallback
+     * match when the requested path is only approximately correct.
+     *
+     * @param {string} path
+     * @returns {Promise<string | null>}
+     */
+    resolvePath(path: string): Promise<string | null>;
     /**
      * @param {string} path
      * @param {string} content
@@ -34,6 +44,15 @@ export class BaseStorage {
     /** Override for efficient path listing. Default uses exportAll(). */
     _listAllPaths(): Promise<string[]>;
     _parentPath(filePath: any): any;
+    _basenamePath(filePath: any): string;
+    _normalizeRequestedPath(path: any): string;
+    _normalizeLookupKey(path: any, { stripExtension }?: {
+        stripExtension?: boolean | undefined;
+    }): string;
+    _listReadablePaths(): Promise<string[]>;
+    _resolveReadablePath(path: any): Promise<any>;
+    _choosePreferredPath(candidates: any, requestedPath: any): any;
+    _pathMatchScore(candidate: any, requestedParent: any, requestedBase: any): number;
     /** Generate a one-line summary of file content for the index. */
     _generateOneLiner(content: any): any;
 }

package/types/backends/indexeddb.d.ts

@@ -8,5 +8,6 @@ export class IndexedDBStorage extends BaseStorage {
     _writeRaw(path: any, content: any, meta?: {}): Promise<void>;
     _get(path: any): Promise<any>;
     _getAll(): Promise<any>;
+    _sanitizeRecords(records: any): any;
 }
 import { BaseStorage } from './BaseStorage.js';

package/types/browser.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Remove review-only [[user_data]] markers before sending the final prompt to
+ * the frontier model.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function stripUserDataTags(text: string): string;
+/**
+ * @param {MemoryBankConfig} [config]
+ * @returns {MemoryBank}
+ */
+export function createMemoryBank(config?: MemoryBankConfig): MemoryBank;
+export * from "./bullets/index.js";
+import type { MemoryBankConfig } from './types.js';
+import type { MemoryBank } from './types.js';
+export { buildOmfExport, previewOmfImport, importOmf, parseOmfText, validateOmf } from "./omf.js";

package/types/engine/deleter.d.ts

@@ -0,0 +1,67 @@
+export class MemoryDeleter {
+    /**
+     * @param {{ backend: StorageBackend, bulletIndex: object, llmClient: LLMClient, model: string, onToolCall?: Function }} options
+     */
+    constructor({ backend, bulletIndex, llmClient, model, onToolCall }: {
+        backend: StorageBackend;
+        bulletIndex: object;
+        llmClient: LLMClient;
+        model: string;
+        onToolCall?: Function;
+    });
+    _backend: StorageBackend;
+    _bulletIndex: any;
+    _llmClient: LLMClient;
+    _model: string;
+    _onToolCall: Function | null;
+    /**
+     * Delete memory content matching the given query.
+     *
+     * @param {string} query  Plain-text description of what to delete.
+     * @param {{ deep?: boolean, mode?: string }} [options]
+     * @returns {Promise<{ status: string, deleteCalls: number, writes: Array }>}
+     */
+    deleteForQuery(query: string, options?: {
+        deep?: boolean;
+        mode?: string;
+    }): Promise<{
+        status: string;
+        deleteCalls: number;
+        writes: any[];
+    }>;
+    _standardDelete(query: any, isDocument: any): Promise<{
+        status: string;
+        deleteCalls: number;
+        writes: never[];
+        error: string;
+    } | {
+        status: string;
+        deleteCalls: number;
+        writes: any[];
+        error?: undefined;
+    }>;
+    _deepDelete(query: any, isDocument: any): Promise<{
+        status: string;
+        deleteCalls: number;
+        writes: never[];
+        error: string;
+    } | {
+        status: string;
+        deleteCalls: number;
+        writes: any[];
+        error?: undefined;
+    }>;
+    _runDeletionLoop(query: any, systemPrompt: any, tools: any, maxIterations: any): Promise<{
+        status: string;
+        deleteCalls: number;
+        writes: never[];
+        error: string;
+    } | {
+        status: string;
+        deleteCalls: number;
+        writes: any[];
+        error?: undefined;
+    }>;
+}
+import type { StorageBackend } from '../types.js';
+import type { LLMClient } from '../types.js';

package/types/engine/executors.d.ts

@@ -13,6 +13,36 @@ export function createRetrievalExecutors(backend: StorageBackend): {
         path: any;
     }) => Promise<string>;
 };
+/**
+ * Build the executed augment_query tool for the retrieval flow.
+ *
+ * The outer memory-agent loop chooses relevant files. This executor then runs a
+ * dedicated prompt-crafter pass that turns those raw inputs into the final
+ * tagged prompt, keeping prompt-crafting fully inside nanomem.
+ *
+ * @param {object} options
+ * @param {StorageBackend} options.backend
+ * @param {LLMClient} options.llmClient
+ * @param {string} options.model
+ * @param {string} options.query
+ * @param {string} [options.conversationText]
+ * @param {(event: { stage: 'loading', message: string, attempt?: number }) => void} [options.onProgress]
+ */
+export function createAugmentQueryExecutor({ backend, llmClient, model, query, conversationText, onProgress }: {
+    backend: StorageBackend;
+    llmClient: LLMClient;
+    model: string;
+    query: string;
+    conversationText?: string | undefined;
+    onProgress?: ((event: {
+        stage: "loading";
+        message: string;
+        attempt?: number;
+    }) => void) | undefined;
+}): ({ user_query, memory_files }: {
+    user_query: any;
+    memory_files: any;
+}) => Promise<string>;
 /**
  * Build tool executors for the extraction (write) flow.
  * @param {StorageBackend} backend
@@ -30,9 +60,9 @@ export function createExtractionExecutors(backend: StorageBackend, hooks?: Extra
         path: any;
         content: any;
     }) => Promise<string>;
-    update_memory: ({ path, content }: {
+    update_bullets: ({ path, updates }: {
         path: any;
-        content: any;
+        updates: any;
     }) => Promise<string>;
     archive_memory: ({ path, item_text }: {
         path: any;
@@ -42,5 +72,29 @@ export function createExtractionExecutors(backend: StorageBackend, hooks?: Extra
         path: any;
     }) => Promise<string>;
 };
+/**
+ * Build tool executors for the deletion flow.
+ * @param {StorageBackend} backend
+ * @param {{ refreshIndex?: Function, onWrite?: Function }} [hooks]
+ */
+export function createDeletionExecutors(backend: StorageBackend, hooks?: {
+    refreshIndex?: Function;
+    onWrite?: Function;
+}): {
+    list_directory: ({ dir_path }: {
+        dir_path: any;
+    }) => Promise<string>;
+    retrieve_file: ({ query }: {
+        query: any;
+    }) => Promise<string>;
+    read_file: ({ path }: {
+        path: any;
+    }) => Promise<string>;
+    delete_bullet: ({ path, bullet_text }: {
+        path: any;
+        bullet_text: any;
+    }) => Promise<string>;
+};
 import type { StorageBackend } from '../types.js';
+import type { LLMClient } from '../types.js';
 import type { ExtractionExecutorHooks } from '../types.js';

package/types/engine/recentConversation.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Trim a conversation transcript while preserving turn boundaries and preferring
+ * to keep user turns visible even when assistant replies are long.
+ *
+ * @param {string} conversationText
+ * @param {object} options
+ * @param {number} [options.maxChars]
+ * @param {number} [options.maxTurns]
+ * @param {number} [options.maxUserChars]
+ * @param {number} [options.maxAssistantChars]
+ * @returns {string | null}
+ */
+export function trimRecentConversation(conversationText: string, { maxChars, maxTurns, maxUserChars, maxAssistantChars }?: {
+    maxChars?: number | undefined;
+    maxTurns?: number | undefined;
+    maxUserChars?: number | undefined;
+    maxAssistantChars?: number | undefined;
+}): string | null;

package/types/engine/retriever.d.ts

@@ -1,4 +1,5 @@
 export class MemoryRetriever {
+    static _stripUserDataTags(text: any): any;
     constructor({ backend, bulletIndex, llmClient, model, onProgress, onModelText }: {
         backend: any;
         bulletIndex: any;
@@ -21,14 +22,24 @@ export class MemoryRetriever {
      * @returns {Promise<RetrievalResult | null>}
      */
     retrieveForQuery(query: string, conversationText?: string): Promise<RetrievalResult | null>;
-    _toolCallingRetrieval(query: any, index: any, onProgress: any, conversationText: any, onModelText: any): Promise<{
-        files: {
-            path: any;
-            content: string;
-        }[];
-        paths: any[];
-        assembledContext: any;
-    } | null>;
+    /**
+     * @param {string} query
+     * @param {string} index
+     * @param {(event: ProgressEvent) => void | null} onProgress
+     * @param {string | undefined} conversationText
+     * @param {((text: string, iteration: number) => void) | null} onModelText
+     * @param {{ mode: 'retrieve' | 'augment' }} options
+     * @returns {Promise<RetrievalResult | AugmentQueryResult | null>}
+     */
+    _toolCallingRetrieval(query: string, index: string, onProgress: (event: ProgressEvent) => void | null, conversationText: string | undefined, onModelText: ((text: string, iteration: number) => void) | null, options?: {
+        mode: "retrieve" | "augment";
+    }): Promise<RetrievalResult | AugmentQueryResult | null>;
+    /**
+     * @param {string} query
+     * @param {string} [conversationText]
+     * @returns {Promise<AugmentQueryResult | null>}
+     */
+    augmentQueryForPrompt(query: string, conversationText?: string): Promise<AugmentQueryResult | null>;
     _textSearchFallbackWithLoad(query: any, onProgress: any, conversationText: any): Promise<{
         files: {
             path: any;
@@ -44,7 +55,9 @@ export class MemoryRetriever {
         text: string;
         score: number;
     }[];
-    _buildRecentContext(conversationText: any): any;
+    _buildRecentContext(conversationText: any): string | null;
     _isMemoryEmpty(index: any): Promise<boolean>;
 }
 import type { RetrievalResult } from '../types.js';
+import type { ProgressEvent } from '../types.js';
+import type { AugmentQueryResult } from '../types.js';

package/types/imports/claude.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Detect whether parsed JSON is a Claude export.
+ * Claude exports are arrays of objects with `chat_messages` and `uuid`.
+ * @param {unknown} parsed
+ * @returns {boolean}
+ */
+export function isClaudeExport(parsed: unknown): boolean;
+/**
+ * Parse a Claude export into normalized sessions.
+ * @param {unknown[]} conversations — the parsed JSON array
+ * @returns {ChatGptSession[]}
+ */
+export function parseClaudeExport(conversations: unknown[]): ChatGptSession[];
+import type { ChatGptSession } from '../types.js';

package/types/imports/importData.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Import one or more conversations/documents into memory using the same ingest
+ * path as the CLI import command, but in a browser-safe module.
+ *
+ * @param {Pick<MemoryBank, 'init' | 'ingest'>} memoryBank
+ * @param {string | unknown | MemoryImportConversation | MemoryImportConversation[] | Array<{ path: string, content: string }>} input
+ * @param {ImportDataOptions} [options]
+ * @returns {Promise<ImportDataResult>}
+ */
+export function importData(memoryBank: Pick<MemoryBank, "init" | "ingest">, input: string | unknown | MemoryImportConversation | MemoryImportConversation[] | Array<{
+    path: string;
+    content: string;
+}>, options?: ImportDataOptions): Promise<ImportDataResult>;
+/**
+ * @param {string | unknown | MemoryImportConversation | MemoryImportConversation[] | Array<{ path: string, content: string }>} input
+ * @param {ImportDataOptions} [options]
+ * @returns {{ items: MemoryImportConversation[], mode: 'conversation' | 'document' }}
+ */
+export function parseImportInput(input: string | unknown | MemoryImportConversation | MemoryImportConversation[] | Array<{
+    path: string;
+    content: string;
+}>, options?: ImportDataOptions): {
+    items: MemoryImportConversation[];
+    mode: "conversation" | "document";
+};
+import type { MemoryBank } from '../types.js';
+import type { MemoryImportConversation } from '../types.js';
+import type { ImportDataOptions } from '../types.js';
+import type { ImportDataResult } from '../types.js';

package/types/imports/index.d.ts

@@ -1,3 +1,5 @@
 export { parseMarkdownFiles } from "./markdown.js";
 export { extractSessionsFromOAFastchatExport, extractConversationFromOAFastchatExport, listOAFastchatSessions } from "./oaFastchat.js";
 export { isChatGptExport, parseChatGptExport } from "./chatgpt.js";
+export { isClaudeExport, parseClaudeExport } from "./claude.js";
+export { importData, parseImportInput } from "./importData.js";

package/types/index.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Remove review-only [[user_data]] markers before sending the final prompt to
+ * the frontier model.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function stripUserDataTags(text: string): string;
 /**
  * Create a memory instance.
  *
@@ -18,4 +26,5 @@ import type { MemoryBankConfig } from './types.js';
 import type { MemoryBank } from './types.js';
 export { createRetrievalExecutors, createExtractionExecutors } from "./engine/executors.js";
 export { serialize, deserialize, toZip } from "./utils/portability.js";
+export { buildOmfExport, previewOmfImport, importOmf, parseOmfText, validateOmf } from "./omf.js";
 export { extractSessionsFromOAFastchatExport, extractConversationFromOAFastchatExport, listOAFastchatSessions } from "./imports/oaFastchat.js";

package/types/llm/openai.d.ts

@@ -1,16 +1,13 @@
-/**
- * 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, headers }?: LLMClientOptions): LLMClient;
+export type ApiError = Error & {
+    status?: number;
+    retryable?: boolean;
+    retryAfterMs?: number | null;
+    _retryFinalized?: boolean;
+};
 import type { LLMClientOptions } from '../types.js';
 import type { LLMClient } from '../types.js';

package/types/llm/tinfoil.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @param {MemoryBankLLMConfig} [options]
+ * @returns {LLMClient}
+ */
+export function createTinfoilClient(options?: MemoryBankLLMConfig): LLMClient;
+export type ApiError = Error & {
+    status?: number;
+    retryable?: boolean;
+    retryAfterMs?: number | null;
+    _retryFinalized?: boolean;
+};
+import type { MemoryBankLLMConfig } from '../types.js';
+import type { LLMClient } from '../types.js';

package/types/omf.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @param {unknown} doc
+ * @returns {{ valid: boolean, error?: string }}
+ */
+export function validateOmf(doc: unknown): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * @param {string} text
+ * @returns {OmfDocument}
+ */
+export function parseOmfText(text: string): OmfDocument;
+/**
+ * @param {StorageFacade} storage
+ * @param {{ sourceApp?: string }} [options]
+ * @returns {Promise<OmfDocument>}
+ */
+export function buildOmfExport(storage: StorageFacade, options?: {
+    sourceApp?: string;
+}): Promise<OmfDocument>;
+/**
+ * @param {StorageFacade} storage
+ * @param {OmfDocument} doc
+ * @param {OmfImportOptions} [options]
+ * @returns {Promise<OmfImportPreview>}
+ */
+export function previewOmfImport(storage: StorageFacade, doc: OmfDocument, options?: OmfImportOptions): Promise<OmfImportPreview>;
+/**
+ * @param {StorageFacade} storage
+ * @param {OmfDocument} doc
+ * @param {OmfImportOptions} [options]
+ * @returns {Promise<OmfImportResult>}
+ */
+export function importOmf(storage: StorageFacade, doc: OmfDocument, options?: OmfImportOptions): Promise<OmfImportResult>;
+import type { OmfDocument } from './types.js';
+import type { StorageFacade } from './types.js';
+import type { OmfImportOptions } from './types.js';
+import type { OmfImportPreview } from './types.js';
+import type { OmfImportResult } from './types.js';

package/types/prompt_sets/conversation/ingestion.d.ts

@@ -1,7 +1,12 @@
 /**
  * Prompt set for conversation ingestion.
  *
- * Strict mode: only saves facts the user explicitly stated.
- * Used when importing chat history, conversation logs, or live sessions.
+ * ingestionPrompt — general import: full discretion over create/append/update.
+ * addPrompt       — `nanomem add`: only write NEW facts (create or append, no updates).
+ * updatePrompt    — `nanomem update`: only edit EXISTING facts (no new files).
  */
-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.\n\nCRITICAL: Only save facts the user explicitly stated. Do NOT infer, extrapolate, or fabricate information.\n\nSave information that is likely to help in a future conversation. Be selective \u2014 only save durable facts, not transient conversation details.\n\nDo NOT save:\n- Anything the user did not explicitly say (no inferences, no extrapolations, no \"likely\" facts)\n- Information already present in existing files (the system deduplicates automatically)\n- Transient details (greetings, \"help me with this\", \"thanks\", questions without lasting answers)\n- The assistant's own reasoning, suggestions, or knowledge \u2014 only what the user stated\n- Sensitive secrets (passwords, auth tokens, private keys, full payment data, government IDs)\n- Opinions the assistant expressed unless the user explicitly agreed with them\n\nCurrent memory index:\n```\n{INDEX}\n```\n\n**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.\n\nInstructions:\n1. Read the conversation below and identify facts the user explicitly stated.\n2. 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 \u2014 the system deduplicates automatically.\n3. Use this bullet format: \"- Fact text | topic=topic-name | source=SOURCE | confidence=LEVEL | updated_at=YYYY-MM-DD\"\n4. Source values:\n   - source=user_statement \u2014 the user directly said this. This is the PRIMARY source. Use it for the vast majority of saved facts.\n   - source=llm_infer \u2014 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\" \u2192 \"Works in SF\"). Never use this to guess, extrapolate, or fill in gaps. When in doubt, do not save.\n5. Confidence: high for direct user statements, medium for llm_infer. Never save low-confidence items.\n6. 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.\n7. Facts worth saving: allergies, health conditions, location, job/role, tech stack, pets, family members, durable preferences, and active plans \u2014 but ONLY if the user explicitly mentioned them.\n8. If a fact is time-sensitive, include date context in the text. You may optionally add review_at or expires_at.\n9. If nothing new is worth remembering, simply stop without calling any write tools. Saving nothing is better than saving something wrong.\n\nRules:\n- 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.\n- Favor broad thematic files. A file can hold multiple related sub-topics \u2014 only truly unrelated facts need separate files.\n- Only create a new file when nothing in the index is thematically close. When in doubt, append.\n- When creating a new file, choose a broad, thematic name that can absorb future related facts \u2014 not a narrow label for a single detail.\n- Use update_memory only if a fact is now stale or contradicted.\n- 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.\n- If a conflict is ambiguous, preserve both versions rather than deleting one.\n- Do not skip obvious facts just because the schema supports extra metadata.\n- Content should be raw facts only \u2014 no filler commentary.";
+export const addPrompt: "You are a memory manager. Save NEW facts from the text that do not yet exist in memory.\n\nCRITICAL: Only save facts the user explicitly stated. Do NOT infer, extrapolate, or fabricate.\n\nCurrent memory index:\n```\n{INDEX}\n```\n\nFor each new fact, decide:\n- Use append_memory if an existing file already covers the same domain or topic.\n- Use create_new_file only if no existing file is thematically close.\n\nDo NOT save:\n- Facts already present in memory\n- Transient details (greetings, one-off questions with no lasting answer)\n- Sensitive secrets (passwords, tokens, keys)\n\nBullet format: \"- Fact text | topic=topic-name | source=user_statement | confidence=high | updated_at=YYYY-MM-DD\"\n\nIf nothing new is worth saving, stop without calling any tools.";
+export const updatePrompt: "You are a memory manager. Update the user's memory based on the text below.\n\nCRITICAL: Only save facts the user explicitly stated. Do NOT infer, extrapolate, or fabricate.\n\nCurrent memory index:\n```\n{INDEX}\n```\n\nSteps:\n1. Identify which existing file(s) might hold facts that are stale or contradicted by the new information.\n2. Use read_file to read the current content and find the exact bullet text to replace.\n3. If a matching old fact exists, use update_bullets with all corrections for that file in a single call, passing the exact old fact text and the corrected fact text for each.\n4. If no existing fact matches \u2014 the information is entirely new \u2014 use append_memory to add it to an existing file that covers the same domain, or create_new_file if no existing file is thematically close.\n\nRules:\n- Prefer update_bullets when an existing fact is directly contradicted or corrected.\n- Only change bullets that are directly contradicted or corrected by the new information.\n- Do not touch any other bullets in the file.\n- Pass old_fact exactly as it appears in the file (including pipe-delimited metadata is fine).\n- Pass new_fact as plain text only \u2014 no metadata.\n- When appending or creating, use this bullet format: \"- Fact text | topic=topic-name | source=user_statement | confidence=high | updated_at=YYYY-MM-DD\"\n\nIf nothing new or changed is worth saving, stop without calling any tools.";
+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.\n\nCRITICAL: Only save facts the user explicitly stated. Do NOT infer, extrapolate, or fabricate information.\n\nSave information that is likely to help in a future conversation. Be selective \u2014 only save durable facts, not transient conversation details.\n\nDo NOT save:\n- Anything the user did not explicitly say (no inferences, no extrapolations, no \"likely\" facts)\n- Information already present in existing files\n- Transient details (greetings, \"help me with this\", \"thanks\", questions without lasting answers)\n- The assistant's own reasoning, suggestions, or knowledge \u2014 only what the user stated\n- Sensitive secrets (passwords, auth tokens, private keys, full payment data, government IDs)\n- Opinions the assistant expressed unless the user explicitly agreed with them\n\nCurrent memory index:\n```\n{INDEX}\n```\n\n**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.\n\nInstructions:\n1. Read the conversation below and identify facts the user explicitly stated.\n2. Do not read files before writing. The memory index is sufficient to decide where to append. Only read a file if the index entry is ambiguous and you need the exact current content to avoid duplicating a fact.\n3. If no relevant file exists yet, create_new_file directly.\n4. 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.\n5. Use this bullet format: \"- Fact text | topic=topic-name | source=SOURCE | confidence=LEVEL | updated_at=YYYY-MM-DD\"\n6. Source values:\n   - source=user_statement \u2014 the user directly said this. This is the PRIMARY source. Use it for the vast majority of saved facts.\n   - source=llm_infer \u2014 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\" \u2192 \"Works in SF\"). Never use this to guess, extrapolate, or fill in gaps. When in doubt, do not save.\n7. Confidence: high for direct user statements, medium for llm_infer. Never save low-confidence items.\n8. 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.\n9. Facts worth saving: allergies, health conditions, location, job/role, tech stack, pets, family members, durable preferences, and active plans \u2014 but ONLY if the user explicitly mentioned them.\n10. If a fact is time-sensitive, include date context in the text. You may optionally add review_at or expires_at.\n11. If nothing new is worth remembering, simply stop without calling any write tools. Saving nothing is better than saving something wrong.\n\nRules:\n- 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.\n- Favor broad thematic files. A file can hold multiple related sub-topics \u2014 only truly unrelated facts need separate files.\n- Only create a new file when nothing in the index is thematically close. When in doubt, append.\n- When creating a new file, choose a broad, thematic name that can absorb future related facts \u2014 not a narrow label for a single detail.\n- Use update_bullets only if a fact is now stale or contradicted. Pass all corrections for a file in one call.\n- 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.\n- If a conflict is ambiguous, preserve both versions rather than deleting one.\n- Do not skip obvious facts just because the schema supports extra metadata.\n- Content should be raw facts only \u2014 no filler commentary.";
+export const deletePrompt: "You are a memory manager performing a TARGETED deletion.\n\nThe user wants to remove: \"{QUERY}\"\n\nRULES \u2014 read carefully before acting:\n1. Delete all bullets that are ABOUT the subject(s) or entity mentioned in the deletion request.\n   - If the query names a specific entity (a pet, person, place, project), delete every fact about that entity \u2014 not just the one line that introduces it.\n   - Example: \"I have dog mochi\" \u2192 delete ALL facts about Mochi (habits, toys, traits, the introduction line, etc.).\n2. Do NOT delete facts about unrelated subjects, even if they appear in the same file.\n3. When genuinely unsure whether a bullet is about the target subject, SKIP it.\n4. Never delete an entire file \u2014 only individual bullets via delete_bullet.\n5. Pass the EXACT bullet text as it appears in the file, including all | metadata after the fact.\n\nCurrent memory index:\n```\n{INDEX}\n```\n\nSteps:\n1. Identify which file(s) likely contain the content to delete from the index above.\n2. Use retrieve_file or list_directory if the relevant file is not obvious from the index.\n3. Use read_file to read the identified file(s).\n4. Call delete_bullet for each bullet that is about the subject(s) in the deletion request.\n5. If nothing matches, stop without calling delete_bullet.";
+export const deepDeletePrompt: "You are a memory manager performing a COMPREHENSIVE deletion across ALL memory files.\n\nThe user wants to remove: \"{QUERY}\"\n\nRULES \u2014 read carefully before acting:\n1. Delete all bullets that are ABOUT the subject(s) or entity mentioned in the deletion request.\n   - If the query names a specific entity (a pet, person, place, project), delete every fact about that entity across every file \u2014 not just the one line that introduces it.\n   - Example: \"I have dog mochi\" \u2192 delete ALL facts about Mochi wherever they appear.\n2. Do NOT delete facts about unrelated subjects.\n3. When genuinely unsure whether a bullet is about the target subject, SKIP it.\n4. Never delete an entire file \u2014 only individual bullets via delete_bullet.\n5. Pass the EXACT bullet text as it appears in the file, including all | metadata after the fact.\n\nYou MUST read every file listed below and check it for matching content.\n\nFiles to check:\n{FILE_LIST}\n\nSteps:\n1. Use read_file to read each file listed above, one by one.\n2. For each file, call delete_bullet for any bullet that is about the subject(s) in the deletion request.\n3. Continue until every file has been checked.\n4. If a file has no matching bullets, move on without calling delete_bullet for it.";

package/types/prompt_sets/document/ingestion.d.ts

@@ -1,7 +1,12 @@
 /**
  * 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.
+ * ingestionPrompt  — general import: full discretion over create/append/update.
+ * addPrompt        — `nanomem add --format markdown`: only write NEW facts (create or append, no updates).
+ * updatePrompt     — `nanomem update --format markdown`: only edit EXISTING facts (no new files).
  */
-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.\n\nUnlike conversation ingestion, you may extract and reasonably infer facts from what the documents show \u2014 not just what was explicitly stated word-for-word. Use good judgment: extract what is clearly supported by the content, avoid speculation.\n\nSave information that would be useful when answering questions about this subject in the future. Be generous \u2014 capture expertise, projects, preferences, philosophy, and patterns that emerge from the documents.\n\nDo NOT save:\n- Speculation or guesses not supported by the content\n- Boilerplate (installation steps, license text, generic disclaimers)\n- Information already present in existing files (use read_file to check first)\n- Sensitive secrets (passwords, auth tokens, private keys)\n\nCurrent memory index:\n```\n{INDEX}\n```\n\n**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.\n\nInstructions:\n1. Read the document content and identify concrete, reusable facts about the subject.\n2. If a matching file already exists in the index, use read_file first to avoid duplicates.\n3. Use create_new_file for new topics, append_memory to add to existing files.\n4. Use this bullet format: \"- Fact text | topic=topic-name | source=SOURCE | confidence=LEVEL | updated_at=YYYY-MM-DD\"\n5. Source values (IMPORTANT \u2014 never use source=user_statement here):\n   - source=document \u2014 the fact is directly stated or clearly shown in the document. Use for the majority of facts.\n   - source=document_infer \u2014 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 \u2192 \"prefers low-level, minimal implementations\"). Use sparingly.\n6. Confidence: high for source=document facts, medium for source=document_infer.\n7. 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.\n8. If nothing meaningful can be extracted from a document, stop without calling any write tools.\n\nRules:\n- 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.\n- One file per distinct topic. Do NOT put unrelated facts in the same file.\n- Create new files freely \u2014 focused files are better than bloated ones.\n- Content should be raw facts only \u2014 no filler commentary.";
+export const addPrompt: "You are a memory manager. Extract NEW facts from the document that do not yet exist in memory.\n\nYou may extract and reasonably infer facts from what the document shows \u2014 not just word-for-word statements. Use good judgment: extract what is clearly supported by the content, avoid speculation.\n\nCurrent memory index:\n```\n{INDEX}\n```\n\nFor each new fact, decide:\n- Use append_memory if an existing file already covers the same domain or topic.\n- Use create_new_file only if no existing file is thematically close.\n\nDo NOT save:\n- Facts already present in memory\n- Boilerplate (installation steps, license text, generic disclaimers)\n- Sensitive secrets (passwords, tokens, keys)\n\nBullet format: \"- Fact text | topic=topic-name | source=document | confidence=high | updated_at=YYYY-MM-DD\"\n\nIf nothing new is worth saving, stop without calling any tools.";
+export const updatePrompt: "You are a memory manager. Correct or update facts already saved in memory based on the document below.\n\nCRITICAL: Only edit files that already exist. Do NOT create new files. Do NOT rewrite whole files.\n\nCurrent memory index:\n```\n{INDEX}\n```\n\nSteps:\n1. Identify which existing file(s) hold facts that are now stale or contradicted by the document.\n2. Use read_file to read the current content and find the exact bullet text to replace.\n3. Use update_bullets with all corrections for that file in a single call, passing the exact old fact text and the corrected fact text for each.\n\nRules:\n- Only change bullets that are directly contradicted or corrected by the new information.\n- Do not touch any other bullets in the file.\n- Pass old_fact exactly as it appears in the file (including pipe-delimited metadata is fine).\n- Pass new_fact as plain text only \u2014 no metadata.\n\nIf nothing needs updating, stop without calling any tools.";
+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.\n\nUnlike conversation ingestion, you may extract and reasonably infer facts from what the documents show \u2014 not just what was explicitly stated word-for-word. Use good judgment: extract what is clearly supported by the content, avoid speculation.\n\nSave information that would be useful when answering questions about this subject in the future. Be generous \u2014 capture expertise, projects, preferences, philosophy, and patterns that emerge from the documents.\n\nDo NOT save:\n- Speculation or guesses not supported by the content\n- Boilerplate (installation steps, license text, generic disclaimers)\n- Information already present in existing files\n- Sensitive secrets (passwords, auth tokens, private keys)\n\nCurrent memory index:\n```\n{INDEX}\n```\n\n**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.\n\nInstructions:\n1. Read the document content and identify concrete, reusable facts about the subject.\n2. Do not read files before writing. The memory index is sufficient to decide where to append or create. Only read a file if the index entry is ambiguous and you need the exact current content to avoid duplicating a fact.\n3. Use create_new_file for new topics, append_memory to add to existing files.\n4. Use this bullet format: \"- Fact text | topic=topic-name | source=SOURCE | confidence=LEVEL | updated_at=YYYY-MM-DD\"\n5. Source values (IMPORTANT \u2014 never use source=user_statement here):\n   - source=document \u2014 the fact is directly stated or clearly shown in the document. Use for the majority of facts.\n   - source=document_infer \u2014 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 \u2192 \"prefers low-level, minimal implementations\"). Use sparingly.\n6. Confidence: high for source=document facts, medium for source=document_infer.\n7. 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.\n8. If nothing meaningful can be extracted from a document, stop without calling any write tools.\n\nRules:\n- 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.\n- One file per distinct topic. Do NOT put unrelated facts in the same file.\n- Create new files freely \u2014 focused files are better than bloated ones.\n- Content should be raw facts only \u2014 no filler commentary.";
+export const deletePrompt: "You are a memory manager performing a TARGETED deletion.\n\nThe user wants to remove: \"{QUERY}\"\n\nRULES \u2014 read carefully before acting:\n1. Delete all bullets that are ABOUT the subject(s) or entity mentioned in the deletion request.\n   - If the query names a specific entity (a person, project, tool, concept), delete every fact about that entity \u2014 not just the one line that introduces it.\n   - Example: \"project recipe-app\" \u2192 delete ALL facts about the recipe-app project (tech stack, goals, status, etc.).\n2. Do NOT delete facts about unrelated subjects, even if they appear in the same file.\n3. When genuinely unsure whether a bullet is about the target subject, SKIP it.\n4. Never delete an entire file \u2014 only individual bullets via delete_bullet.\n5. Pass the EXACT bullet text as it appears in the file, including all | metadata after the fact.\n\nCurrent memory index:\n```\n{INDEX}\n```\n\nSteps:\n1. Identify which file(s) likely contain the content to delete from the index above.\n2. Use retrieve_file or list_directory if the relevant file is not obvious from the index.\n3. Use read_file to read the identified file(s).\n4. Call delete_bullet for each bullet that is about the subject(s) in the deletion request.\n5. If nothing matches, stop without calling delete_bullet.";
+export const deepDeletePrompt: "You are a memory manager performing a COMPREHENSIVE deletion across ALL memory files.\n\nThe user wants to remove: \"{QUERY}\"\n\nRULES \u2014 read carefully before acting:\n1. Delete all bullets that are ABOUT the subject(s) or entity mentioned in the deletion request.\n   - If the query names a specific entity (a person, project, tool, concept), delete every fact about that entity wherever it appears.\n   - Example: \"project recipe-app\" \u2192 delete ALL facts about the recipe-app project across every file.\n2. Do NOT delete facts about unrelated subjects.\n3. When genuinely unsure whether a bullet is about the target subject, SKIP it.\n4. Never delete an entire file \u2014 only individual bullets via delete_bullet.\n5. Pass the EXACT bullet text as it appears in the file, including all | metadata after the fact.\n\nYou MUST read every file listed below and check it for matching content.\n\nFiles to check:\n{FILE_LIST}\n\nSteps:\n1. Use read_file to read each file listed above, one by one.\n2. For each file, call delete_bullet for any bullet that is about the subject(s) in the deletion request.\n3. Continue until every file has been checked.\n4. If a file has no matching bullets, move on without calling delete_bullet for it.";