topic-memory 0.1.0

package/dist/storage/indexeddb.d.ts

@@ -0,0 +1,23 @@
+import type { CanonicalExchange, CanonicalTopic, LatestTopicWorkerRun, MemoryStorage } from '../types.js';
+export interface IndexedDbMemoryStorageOptions {
+    dbName?: string;
+    indexedDB?: IDBFactory;
+}
+export declare class IndexedDbMemoryStorage implements MemoryStorage {
+    private readonly dbName;
+    private readonly idb;
+    constructor(options?: IndexedDbMemoryStorageOptions);
+    listExchanges(): Promise<CanonicalExchange[]>;
+    putExchange(exchange: CanonicalExchange): Promise<void>;
+    clearExchanges(): Promise<void>;
+    listTopics(): Promise<CanonicalTopic[]>;
+    replaceTopics(topics: CanonicalTopic[]): Promise<void>;
+    clearTopics(): Promise<void>;
+    getLatestTopicWorkerRun(): Promise<LatestTopicWorkerRun | null>;
+    saveLatestTopicWorkerRun(run: LatestTopicWorkerRun): Promise<void>;
+    clearLatestTopicWorkerRun(): Promise<void>;
+    private getAll;
+    private write;
+    private open;
+}
+//# sourceMappingURL=indexeddb.d.ts.map

package/dist/storage/indexeddb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexeddb.d.ts","sourceRoot":"","sources":["../../src/storage/indexeddb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAM1G,MAAM,WAAW,6BAA6B;IAAG,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,UAAU,CAAC;CAAE;AAE3F,qBAAa,sBAAuB,YAAW,aAAa;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;gBAErB,OAAO,GAAE,6BAAkC;IAOjD,aAAa,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAI7C,WAAW,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IACvD,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAC/B,UAAU,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAIvC,aAAa,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAYtD,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAC5B,uBAAuB,IAAI,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAI/D,wBAAwB,CAAC,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAYlE,yBAAyB,IAAI,OAAO,CAAC,IAAI,CAAC;YAElC,MAAM;YAWN,KAAK;IAWnB,OAAO,CAAC,IAAI;CAiBb"}

package/dist/storage/indexeddb.js

@@ -0,0 +1,95 @@
+const EXCHANGE_STORE = 'canonical_exchanges';
+const TOPIC_STORE = 'topics';
+const RUN_STORE = 'latest_topic_worker_run';
+export class IndexedDbMemoryStorage {
+    dbName;
+    idb;
+    constructor(options = {}) {
+        this.dbName = options.dbName ?? 'topic-memory:v1';
+        const factory = options.indexedDB ?? globalThis.indexedDB;
+        if (!factory)
+            throw new Error('IndexedDB is not available in this environment');
+        this.idb = factory;
+    }
+    async listExchanges() {
+        const records = await this.getAll(EXCHANGE_STORE);
+        return records.sort((a, b) => a.sequence - b.sequence);
+    }
+    async putExchange(exchange) { await this.write(EXCHANGE_STORE, (store) => store.put(exchange)); }
+    async clearExchanges() { await this.write(EXCHANGE_STORE, (store) => store.clear()); }
+    async listTopics() {
+        const records = await this.getAll(TOPIC_STORE);
+        return records.sort((a, b) => (a.startedAt ?? 0) - (b.startedAt ?? 0) || a.topicId.localeCompare(b.topicId));
+    }
+    async replaceTopics(topics) {
+        const db = await this.open();
+        await new Promise((resolve, reject) => {
+            const tx = db.transaction(TOPIC_STORE, 'readwrite');
+            const store = tx.objectStore(TOPIC_STORE);
+            store.clear();
+            for (const topic of topics)
+                store.put(topic);
+            tx.oncomplete = () => { db.close(); resolve(); };
+            tx.onerror = () => { const error = tx.error; db.close(); reject(error ?? new Error('IndexedDB topic transaction failed')); };
+            tx.onabort = () => { const error = tx.error; db.close(); reject(error ?? new Error('IndexedDB topic transaction aborted')); };
+        });
+    }
+    async clearTopics() { await this.write(TOPIC_STORE, (store) => store.clear()); }
+    async getLatestTopicWorkerRun() {
+        const records = await this.getAll(RUN_STORE);
+        return records.sort((a, b) => b.createdAt - a.createdAt)[0] ?? null;
+    }
+    async saveLatestTopicWorkerRun(run) {
+        const db = await this.open();
+        await new Promise((resolve, reject) => {
+            const tx = db.transaction(RUN_STORE, 'readwrite');
+            const store = tx.objectStore(RUN_STORE);
+            store.clear();
+            store.put(run);
+            tx.oncomplete = () => { db.close(); resolve(); };
+            tx.onerror = () => { const error = tx.error; db.close(); reject(error ?? new Error('IndexedDB run transaction failed')); };
+            tx.onabort = () => { const error = tx.error; db.close(); reject(error ?? new Error('IndexedDB run transaction aborted')); };
+        });
+    }
+    async clearLatestTopicWorkerRun() { await this.write(RUN_STORE, (store) => store.clear()); }
+    async getAll(storeName) {
+        const db = await this.open();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(storeName, 'readonly');
+            const request = tx.objectStore(storeName).getAll();
+            tx.oncomplete = () => { db.close(); resolve(request.result ?? []); };
+            tx.onerror = () => { const error = tx.error; db.close(); reject(error ?? new Error('IndexedDB read failed')); };
+            tx.onabort = () => { const error = tx.error; db.close(); reject(error ?? new Error('IndexedDB read aborted')); };
+        });
+    }
+    async write(storeName, action) {
+        const db = await this.open();
+        await new Promise((resolve, reject) => {
+            const tx = db.transaction(storeName, 'readwrite');
+            action(tx.objectStore(storeName));
+            tx.oncomplete = () => { db.close(); resolve(); };
+            tx.onerror = () => { const error = tx.error; db.close(); reject(error ?? new Error('IndexedDB write failed')); };
+            tx.onabort = () => { const error = tx.error; db.close(); reject(error ?? new Error('IndexedDB write aborted')); };
+        });
+    }
+    open() {
+        return new Promise((resolve, reject) => {
+            const request = this.idb.open(this.dbName, 1);
+            request.onupgradeneeded = () => {
+                const db = request.result;
+                if (!db.objectStoreNames.contains(EXCHANGE_STORE)) {
+                    const store = db.createObjectStore(EXCHANGE_STORE, { keyPath: 'id' });
+                    store.createIndex('sequence', 'sequence', { unique: true });
+                    store.createIndex('status', 'status', { unique: false });
+                }
+                if (!db.objectStoreNames.contains(TOPIC_STORE))
+                    db.createObjectStore(TOPIC_STORE, { keyPath: 'topicId' });
+                if (!db.objectStoreNames.contains(RUN_STORE))
+                    db.createObjectStore(RUN_STORE, { keyPath: 'runId' });
+            };
+            request.onerror = () => reject(request.error ?? new Error('Failed to open IndexedDB memory database'));
+            request.onsuccess = () => resolve(request.result);
+        });
+    }
+}
+//# sourceMappingURL=indexeddb.js.map

package/dist/storage/indexeddb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexeddb.js","sourceRoot":"","sources":["../../src/storage/indexeddb.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,79 @@
+export type CanonicalExchangeStatus = 'pending' | 'completed' | 'failed';
+export type CanonicalTopicStatus = 'open' | 'provisional' | 'finalized';
+export interface CanonicalExchange {
+    id: string;
+    sequence: number;
+    userText: string;
+    userSentAt: number;
+    assistantText: string;
+    assistantCompletedAt: number | null;
+    status: CanonicalExchangeStatus;
+    failureReason: string | null;
+    source: 'live';
+}
+export interface CanonicalTopicSpan {
+    startSequence: number;
+    endSequence: number;
+}
+export interface CanonicalTopic {
+    topicId: string;
+    status: CanonicalTopicStatus;
+    labelTerms: string[];
+    retrievalTerms: string[];
+    spans: CanonicalTopicSpan[];
+    startedAt: number | null;
+    endedAt: number | null;
+    updatedAt: number;
+    source: 'topic_worker_v1';
+}
+export type TopicWorkerRunValidationStatus = 'accepted' | 'rejected' | 'failed';
+export interface LatestTopicWorkerRun {
+    runId: string;
+    createdAt: number;
+    inputText: string;
+    rawOutput: string;
+    validationStatus: TopicWorkerRunValidationStatus;
+    validationError: string | null;
+    acceptedTopics: CanonicalTopic[];
+    requestModel: string;
+}
+export interface MemoryLlmRequest {
+    system: string;
+    user: string;
+    maxTokens: number;
+    temperature?: number;
+    topP?: number;
+}
+export interface MemoryLlm {
+    complete(input: MemoryLlmRequest): Promise<string>;
+}
+export interface MemoryStorage {
+    listExchanges(): Promise<CanonicalExchange[]>;
+    putExchange(exchange: CanonicalExchange): Promise<void>;
+    clearExchanges(): Promise<void>;
+    listTopics(): Promise<CanonicalTopic[]>;
+    replaceTopics(topics: CanonicalTopic[]): Promise<void>;
+    clearTopics(): Promise<void>;
+    getLatestTopicWorkerRun(): Promise<LatestTopicWorkerRun | null>;
+    saveLatestTopicWorkerRun(run: LatestTopicWorkerRun): Promise<void>;
+    clearLatestTopicWorkerRun(): Promise<void>;
+}
+export interface RetrieveResult {
+    recentContext: CanonicalExchange[];
+    topicDirectory: string;
+    selectedTopicIds: string[];
+    openedTopicPackets: string[];
+    memoryContext: string;
+    needsTimeMetadata: boolean;
+    trace: {
+        selectorInput: string;
+        selectorRawOutput: string;
+        selectorError: string | null;
+    };
+}
+export interface TopicWorkerResult {
+    ran: boolean;
+    reason: 'completed_exchange_gate' | 'active_tail_gate' | 'accepted' | 'rejected' | 'failed';
+    run: LatestTopicWorkerRun | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,227 @@
+# Architecture & Capacity Notes
+
+[简体中文](./ARCHITECTURE.zh-CN.md)
+
+This appendix explains the design assumptions behind Topic Memory v0.1. It is not required for installation or integration.
+
+## 1. What Topic Memory actually scales
+
+Topic Memory does **not** increase an LLM's native context window.
+
+Instead, it separates two quantities that are often treated as if they were the same:
+
+- **stored conversation history** — how much history the application can preserve;
+- **per-request prompt history** — how much of that history must be sent to a model for one reply.
+
+A raw-history design tends toward:
+
+```text
+per-request history tokens ≈ total exchanges × average tokens per exchange
+```
+
+Topic Memory tends toward:
+
+```text
+per-request memory tokens
+≈ recent context
++ Topic Directory
++ a small number of reopened topic packets
+```
+
+The full Canonical Transcript remains in storage and is not replayed on every request.
+
+## 2. The v0.1 retrieval path
+
+Let:
+
+- `N` = total completed exchanges stored;
+- `g` = average exchanges represented by one topic;
+- `d` = average tokens in one Topic Directory entry;
+- `k` = number of reopened topics, with `k <= 3` in v0.1;
+- `t` = average tokens per completed exchange;
+- `r` = number of recent exchanges, fixed at `5` in v0.1.
+
+The approximate number of topics is:
+
+```text
+T ≈ N / g
+```
+
+The Topic Directory cost is approximately:
+
+```text
+DirectoryTokens ≈ T × d
+                ≈ (N / g) × d
+```
+
+The recent-context cost is approximately:
+
+```text
+RecentTokens ≈ r × t
+             = 5 × t
+```
+
+If a reopened topic contains roughly `g` exchanges, the maximum reopened historical text is approximately:
+
+```text
+OpenedTopicTokens ≈ k × g × t
+```
+
+So a rough v0.1 memory prompt estimate is:
+
+```text
+MemoryPromptTokens
+≈ (N / g) × d
++ 5 × t
++ k × g × t
++ fixed prompt overhead
+```
+
+This is not constant-time retrieval: the v0.1 Topic Directory grows with the number of topics. The important difference is that the full raw transcript does not grow inside every prompt.
+
+## 3. Illustrative 600 → 5,000 exchange sizing example
+
+The following is a capacity calculation, **not a benchmark result and not a guaranteed maximum**.
+
+Assume:
+
+- model context window: `128,000 tokens`;
+- approximately `8,000 tokens` reserved for system instructions, current input, output headroom, and other application context;
+- available historical prompt budget: approximately `120,000 tokens`;
+- average completed exchange: `200 tokens` across user + assistant;
+- average topic size: `8 exchanges`;
+- average Topic Directory entry: `60 tokens`;
+- recent context: `5 exchanges`;
+- maximum reopened topics: `3`.
+
+### Raw-history approach
+
+```text
+120,000 / 200 = 600 exchanges
+```
+
+Under these assumptions, replaying every historical exchange reaches the approximate historical prompt budget at around **600 completed exchanges**.
+
+### Topic Memory with 5,000 stored exchanges
+
+Number of topics:
+
+```text
+5,000 / 8 = 625 topics
+```
+
+Topic Directory:
+
+```text
+625 × 60 = 37,500 tokens
+```
+
+Recent context:
+
+```text
+5 × 200 = 1,000 tokens
+```
+
+Up to three reopened topics:
+
+```text
+3 × 8 × 200 = 4,800 tokens
+```
+
+Subtotal:
+
+```text
+37,500 + 1,000 + 4,800 = 43,300 tokens
+```
+
+Allowing roughly 1,000–2,000 additional tokens for selector instructions, timestamps, formatting, and other fixed overhead gives an illustrative total of approximately:
+
+```text
+44,000–45,000 memory-related tokens
+```
+
+In this example:
+
+```text
+5,000 / 600 ≈ 8.33×
+```
+
+So the system can *represent and selectively reopen* about **8.3× more completed-exchange history** than the raw 600-exchange prompt example, while keeping the memory-related prompt far below the cost of replaying all 5,000 exchanges.
+
+For comparison, replaying all 5,000 exchanges at 200 tokens each would be roughly:
+
+```text
+5,000 × 200 = 1,000,000 tokens
+```
+
+The illustrative Topic Memory retrieval prompt of ~44k–45k tokens is about **95% smaller** than replaying that full one-million-token history.
+
+Again: these numbers describe one set of assumptions. They do not mean Topic Memory guarantees exactly 5,000 exchanges or that 600 exchanges is a universal limit.
+
+## 4. Why 5,000 is not a hard maximum
+
+The storage layer can preserve more than 5,000 exchanges. v0.1's more relevant scaling constraint is the Topic Directory.
+
+Because the selector currently sees the entire Topic Directory, its prompt cost grows approximately with:
+
+```text
+O(number of topics)
+```
+
+If topics average eight exchanges each, 5,000 exchanges produce about 625 topic entries. If the archive becomes much larger, the directory itself eventually becomes the dominant prompt cost.
+
+A future version could reduce this cost with techniques such as:
+
+- hierarchical topic directories;
+- coarse-to-fine topic routing;
+- server-side lexical or semantic pre-filtering;
+- time-partitioned directories;
+- vector or hybrid retrieval before the Memory Selector.
+
+Those are intentionally outside v0.1.
+
+## 5. Why topics instead of a single rolling summary
+
+A rolling summary is cheap, but repeated summarization can discard exact details and flatten chronology.
+
+Topic Memory keeps two different representations:
+
+1. **Topic metadata** for lightweight discovery.
+2. **Canonical Transcript spans** for exact recovery.
+
+The Topic Worker is therefore not trying to replace the original conversation with a summary. It creates an index that points back to the original evidence.
+
+This matters when the user asks questions such as:
+
+- "What did I say about that project last month?"
+- "Which option did we reject before?"
+- "When did I tell you that?"
+- "What exactly happened in that earlier conversation?"
+
+The selector can identify a topic, then the SDK can reopen the original exchanges behind it.
+
+## 6. Long-context research context
+
+The design motivation is consistent with a broader observation in long-context LLM research: a larger context window does not automatically imply perfect retrieval from every position in a long prompt.
+
+Related work includes:
+
+- **Liu et al., "Lost in the Middle: How Language Models Use Long Contexts"** — shows that retrieval performance can depend strongly on where relevant information appears in long input contexts.
+- **Maharana et al., "Evaluating Very Long-Term Conversational Memory of LLM Agents" (LoCoMo, ACL 2024)** — evaluates conversations of up to 600 turns and reports that long-term conversational memory remains challenging even with long-context and retrieval approaches.
+- **Banerjee et al., "APEX-MEM: Agentic Semi-Structured Memory with Temporal Reasoning for Long-Term Conversational AI" (ACL 2026)** — explores semi-structured, temporally grounded memory with retrieval-time resolution of relevant historical information.
+
+Topic Memory v0.1 is an independent implementation and does not claim to reproduce the methods or benchmark results of those systems. These references are included only as context for the general design choice of storing long history externally and retrieving compact, relevant evidence at reply time.
+
+References:
+
+- https://arxiv.org/abs/2307.03172
+- https://aclanthology.org/2024.acl-long.747/
+- https://aclanthology.org/2026.acl-long.749/
+
+## 7. Practical interpretation
+
+The safest way to describe v0.1 is:
+
+> Topic Memory converts an ever-growing raw transcript into a persistent archive plus a lightweight topic index, then reopens only a few relevant transcript spans for each new request.
+
+Its benefit is not a guaranteed number of remembered exchanges. Its benefit is that the amount of conversation you can preserve becomes much less tightly coupled to the amount of conversation you must resend on every model call.