@openanonymity/nanomem 0.1.0

package/types/types.d.ts

@@ -0,0 +1,293 @@
+export type Tier = "working" | "long_term" | "history";
+export type Status = "active" | "superseded" | "expired" | "uncertain";
+export type Source = "user_statement" | "llm_infer" | "document" | "document_infer" | "assistant_summary" | "inference" | "system";
+export type Confidence = "high" | "medium" | "low";
+export type Bullet = {
+    text: string;
+    topic: string | null;
+    updatedAt: string | null;
+    expiresAt: string | null;
+    reviewAt: string | null;
+    tier: Tier;
+    status: Status;
+    source: Source | null;
+    confidence: Confidence | null;
+    explicitTier: boolean;
+    explicitStatus: boolean;
+    explicitSource: boolean;
+    explicitConfidence: boolean;
+    heading: string;
+    section: string;
+    lineIndex: number;
+};
+export type EnsureBulletMetadataOptions = {
+    defaultTopic?: string | undefined;
+    defaultTier?: Tier | undefined;
+    defaultStatus?: Status | undefined;
+    defaultSource?: Source | undefined;
+    defaultConfidence?: Confidence | undefined;
+    updatedAt?: string | undefined;
+};
+export type CompactionResult = {
+    working: Bullet[];
+    longTerm: Bullet[];
+    history: Bullet[];
+    active: Bullet[];
+    archive: Bullet[];
+};
+export type CompactBulletsOptions = {
+    today?: string | undefined;
+    maxActivePerTopic?: number | undefined;
+    defaultTopic?: string | undefined;
+};
+export type StorageMetadata = {
+    oneLiner?: string | undefined;
+    itemCount?: number | undefined;
+    titles?: string[] | undefined;
+};
+export type ExportRecord = {
+    path: string;
+    content?: string | undefined;
+    oneLiner?: string | undefined;
+    itemCount?: number | undefined;
+    titles?: string[] | undefined;
+    parentPath?: string | undefined;
+    createdAt?: number | undefined;
+    updatedAt?: number | undefined;
+};
+export type SearchResult = {
+    path: string;
+    lines: string[];
+};
+export type ListResult = {
+    files: string[];
+    dirs: string[];
+};
+export type ToolCallFunction = {
+    name: string;
+    arguments: string;
+};
+export type ToolCall = {
+    id: string;
+    type: "function";
+    function: ToolCallFunction;
+};
+export type ToolFunctionParameters = {
+    type: "object";
+    properties: Record<string, {
+        type: string;
+        description?: string;
+    }>;
+    required: string[];
+};
+export type ToolFunctionDef = {
+    name: string;
+    description: string;
+    parameters: ToolFunctionParameters;
+};
+export type ToolDefinition = {
+    type: "function";
+    function: ToolFunctionDef;
+};
+export type LLMMessage = {
+    role: "system" | "user" | "assistant" | "tool";
+    content?: string | null | undefined;
+    tool_calls?: ToolCall[] | undefined;
+    tool_call_id?: string | undefined;
+};
+export type ChatCompletionParams = {
+    model: string;
+    messages: LLMMessage[];
+    tools?: ToolDefinition[] | undefined;
+    max_tokens?: number | undefined;
+    temperature?: number | undefined;
+};
+export type StreamChatCompletionParams = {
+    model: string;
+    messages: LLMMessage[];
+    tools?: ToolDefinition[] | undefined;
+    max_tokens?: number | undefined;
+    temperature?: number | undefined;
+    onDelta?: ((text: string) => void) | undefined;
+    onReasoning?: ((text: string) => void) | undefined;
+};
+export type ChatCompletionResponse = {
+    content: string;
+    tool_calls: ToolCall[];
+    finish_reason?: string | undefined;
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+    } | null;
+};
+export type LLMClient = {
+    createChatCompletion: (params: ChatCompletionParams) => Promise<ChatCompletionResponse>;
+    streamChatCompletion: (params: StreamChatCompletionParams) => Promise<ChatCompletionResponse>;
+};
+export type LLMClientOptions = {
+    apiKey: string;
+    baseUrl?: string | undefined;
+    headers?: Record<string, string> | undefined;
+};
+export type ProgressStage = "init" | "retrieval" | "fallback" | "tool_call" | "reasoning" | "loading" | "complete";
+export type ProgressEvent = {
+    stage: ProgressStage;
+    message: string;
+    tool?: string | undefined;
+    args?: Record<string, any> | undefined;
+    result?: string | Record<string, any> | undefined;
+    paths?: string[] | undefined;
+    iteration?: number | undefined;
+    path?: string | undefined;
+};
+export type RetrievalResult = {
+    files: {
+        path: string;
+        content: string;
+    }[];
+    paths: string[];
+    assembledContext: string | null;
+};
+export type IngestOptions = {
+    updatedAt?: string | undefined;
+    /**
+     * - Prompt set to use for extraction
+     */
+    mode?: string | undefined;
+    /**
+     * - Alias for mode (deprecated, use mode)
+     */
+    extractionMode?: string | undefined;
+    sessionTitle?: string | undefined;
+};
+export type IngestResult = {
+    status: "processed" | "skipped" | "error";
+    writeCalls: number;
+    writes?: {
+        path: string;
+        before: string | null;
+        after: string | null;
+    }[] | undefined;
+    error?: string | undefined;
+};
+export type ToolCallLogEntry = {
+    name: string;
+    args: Record<string, any>;
+    result: string;
+    toolCallId: string;
+};
+export type ToolLoopResult = {
+    textResponse: string;
+    terminalToolResult: {
+        name: string;
+        arguments: Record<string, any>;
+    } | null;
+    messages: LLMMessage[];
+    iterations: number;
+    toolCallLog: ToolCallLogEntry[];
+};
+export type ToolLoopOptions = {
+    llmClient: LLMClient;
+    model: string;
+    tools: ToolDefinition[];
+    toolExecutors: Record<string, ToolExecutor>;
+    messages: LLMMessage[];
+    terminalTool?: string | null | undefined;
+    maxIterations?: number | undefined;
+    maxOutputTokens?: number | undefined;
+    temperature?: number | undefined;
+    onToolCall?: ((name: string, args: Record<string, any>, result: string) => void) | null | undefined;
+    onModelText?: ((text: string, iteration: number) => void) | null | undefined;
+    onReasoning?: ((chunk: string, iteration: number) => void) | null | undefined;
+    signal?: AbortSignal | null | undefined;
+};
+export type ExtractionExecutorHooks = {
+    normalizeContent?: ((content: string, path: string) => string) | undefined;
+    mergeWithExisting?: ((existing: string | null, incoming: string, path: string) => string) | undefined;
+    refreshIndex?: ((path: string) => Promise<void>) | undefined;
+    onWrite?: ((path: string, before: string, after: string) => void) | undefined;
+};
+export type ToolExecutor = (args: any) => Promise<string>;
+export type StorageBackend = {
+    init: () => Promise<void>;
+    read: (path: string) => Promise<string | null>;
+    write: (path: string, content: string) => Promise<void>;
+    delete: (path: string) => Promise<void>;
+    exists: (path: string) => Promise<boolean>;
+    search: (query: string) => Promise<SearchResult[]>;
+    ls: (dirPath?: string) => Promise<ListResult>;
+    getTree: () => Promise<string | null>;
+    rebuildTree: () => Promise<void>;
+    exportAll: () => Promise<ExportRecord[]>;
+    clear: () => Promise<void>;
+};
+export type StorageFacade = {
+    read: (path: string) => Promise<string | null>;
+    write: (path: string, content: string) => Promise<void>;
+    delete: (path: string) => Promise<void>;
+    exists: (path: string) => Promise<boolean>;
+    search: (query: string) => Promise<SearchResult[]>;
+    ls: (dirPath?: string) => Promise<ListResult>;
+    getTree: () => Promise<string | null>;
+    rebuildTree: () => Promise<void>;
+    exportAll: () => Promise<ExportRecord[]>;
+    clear: () => Promise<void>;
+};
+export type MemoryBankLLMConfig = {
+    apiKey: string;
+    baseUrl?: string | undefined;
+    model?: string | undefined;
+    provider?: string | undefined;
+    headers?: Record<string, string> | undefined;
+};
+export type MemoryBankConfig = {
+    llm?: MemoryBankLLMConfig | undefined;
+    llmClient?: LLMClient | undefined;
+    model?: string | undefined;
+    storage?: StorageBackend | "ram" | "filesystem" | "indexeddb" | undefined;
+    storagePath?: string | undefined;
+    onProgress?: ((event: ProgressEvent) => void) | undefined;
+    onCompactProgress?: ((event: ProgressEvent) => void) | undefined;
+    onToolCall?: ((name: string, args: Record<string, any>, result: string) => void) | undefined;
+    onModelText?: ((text: string) => void) | undefined;
+};
+export type Message = {
+    role: "user" | "assistant";
+    content: string;
+};
+export type ChatGptSession = {
+    title: string | null;
+    messages: Message[];
+    updatedAt: string | null;
+};
+export type SessionSummary = {
+    id: string;
+    title: string;
+    createdAt: number | null;
+    updatedAt: number | null;
+    messageCount: number | null;
+    model: string | null;
+};
+export type SessionWithConversation = {
+    session: SessionSummary;
+    conversation: Message[];
+};
+export type BulletItem = {
+    path: string;
+    bullet: Bullet;
+    fileUpdatedAt: number;
+};
+export type MemoryBank = {
+    init: () => Promise<void>;
+    retrieve: (query: string, conversationText?: string) => Promise<RetrievalResult | null>;
+    ingest: (messages: Message[], options?: IngestOptions) => Promise<IngestResult>;
+    compact: () => Promise<{
+        filesChanged: number;
+        filesTotal: number;
+    } | undefined>;
+    storage: StorageFacade;
+    serialize: () => Promise<string>;
+    toZip: () => Promise<Uint8Array>;
+    _backend: StorageBackend;
+    _bulletIndex: import("./bullets/bulletIndex.js").MemoryBulletIndex;
+};

package/types/utils/portability.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Convert an array of {path, content} records into a single portable string.
+ *
+ * Format:
+ *   --- FILE: path/to/file.md
+ *   <file content>
+ *   --- FILE: other/file.md
+ *   <file content>
+ *
+ * Note: file content must not contain a line that starts with "--- FILE: ".
+ * This is extremely unlikely for memory markdown but worth being aware of.
+ * @param {ExportRecord[]} records
+ * @returns {string}
+ */
+export function serialize(records: ExportRecord[]): string;
+/**
+ * Reconstruct records from a serialized string produced by serialize().
+ * @param {string} str
+ * @returns {{ path: string, content: string }[]}
+ */
+export function deserialize(str: string): {
+    path: string;
+    content: string;
+}[];
+/**
+ * Produce a valid ZIP archive (STORE, no compression) from an array of records.
+ * Works in Node.js ≥ 18 and modern browsers (uses TextEncoder + Uint8Array only).
+ *
+ * @param {ExportRecord[]} records
+ * @returns {Uint8Array}
+ */
+export function toZip(records: ExportRecord[]): Uint8Array;
+import type { ExportRecord } from '../types.js';