@polpo-ai/file-stores 0.15.41 → 0.15.42

package/dist/__tests__/file-memory-item-store.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=file-memory-item-store.test.d.ts.map

package/dist/__tests__/file-memory-item-store.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-memory-item-store.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/file-memory-item-store.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/file-memory-item-store.test.js

@@ -0,0 +1,276 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { InMemoryMemoryItemStore, MemoryAuthorizationError, MemoryConflictError, MemoryContractError, createMemoryItem, normalizeMemoryItem, } from "@polpo-ai/core/memory";
+import { FileMemoryItemStore } from "../file-memory-item-store.js";
+function fixture() {
+    const directory = mkdtempSync(join(tmpdir(), "polpo-memory-items-"));
+    return {
+        store: new FileMemoryItemStore(directory),
+        cleanup: () => rmSync(directory, { recursive: true, force: true }),
+    };
+}
+const context = {
+    namespace: "project-a",
+    access: {
+        projectId: "project-a",
+        agentName: "support",
+        externalUserId: "user-a",
+    },
+    surface: "api",
+};
+const otherProjectContext = {
+    namespace: "project-b",
+    access: {
+        orgId: "org-b",
+        projectId: "project-b",
+        agentName: "support",
+        externalUserId: "user-a",
+    },
+    surface: "api",
+};
+function memory(id, content, overrides = {}) {
+    return createMemoryItem({
+        scope: { kind: "agent", agentName: "support" },
+        kind: "fact",
+        content,
+        provenance: { source: "explicit", actor: "user" },
+        ...overrides,
+        id,
+    }, {
+        createId: () => id,
+        now: () => "2026-07-28T10:00:00.000Z",
+    });
+}
+async function withStore(factory, run) {
+    const instance = await factory();
+    try {
+        await run(instance.store);
+    }
+    finally {
+        await instance.store.close?.();
+        await instance.cleanup?.();
+    }
+}
+function memoryItemStoreConformance(name, factory) {
+    it(`${name}: creates, gets, lists, and updates authorized items`, async () => {
+        await withStore(factory, async (store) => {
+            const created = await store.create(memory("memory-1", "Annual billing is enabled."), context);
+            expect(created.id).toBe("memory-1");
+            expect(await store.get("memory-1", context)).toEqual(created);
+            expect(await store.list({}, context)).toEqual([created]);
+            const updated = await store.update("memory-1", {
+                content: "Annual billing is active.",
+                summary: "Billing preference",
+                confidence: 0.9,
+            }, { ...context, now: "2026-07-28T11:00:00.000Z" });
+            expect(updated).toMatchObject({
+                content: "Annual billing is active.",
+                summary: "Billing preference",
+                confidence: 0.9,
+                updatedAt: "2026-07-28T11:00:00.000Z",
+            });
+        });
+    });
+    it(`${name}: isolates identical external users across host namespaces`, async () => {
+        await withStore(factory, async (store) => {
+            const first = memory("memory-user", "Prefers Italian.", {
+                scope: { kind: "user", subjectId: "user-a" },
+                kind: "preference",
+            });
+            await store.create(first, context);
+            expect(await store.get(first.id, otherProjectContext)).toBeUndefined();
+            expect(await store.list({}, otherProjectContext)).toEqual([]);
+            const second = memory("memory-user", "Prefers French.", {
+                scope: { kind: "user", subjectId: "user-a" },
+                kind: "preference",
+            });
+            await expect(store.create(second, otherProjectContext))
+                .resolves.toMatchObject({ content: "Prefers French." });
+        });
+    });
+    it(`${name}: rejects unauthorized writes without revealing reads`, async () => {
+        await withStore(factory, async (store) => {
+            const privateItem = memory("private", "Private note.", {
+                scope: { kind: "user", subjectId: "user-a" },
+            });
+            await store.create(privateItem, context);
+            const wrongUser = {
+                ...context,
+                access: { ...context.access, externalUserId: "user-b" },
+            };
+            expect(await store.get(privateItem.id, wrongUser)).toBeUndefined();
+            expect(await store.update(privateItem.id, { content: "stolen" }, wrongUser)).toBeUndefined();
+            expect(await store.forget(privateItem.id, wrongUser)).toBe(false);
+            await expect(store.create(memory("forbidden", "No.", {
+                scope: { kind: "project", subjectId: "project-b" },
+            }), context)).rejects.toBeInstanceOf(MemoryAuthorizationError);
+        });
+    });
+    it(`${name}: rejects duplicate ids and finds dedupe candidates`, async () => {
+        await withStore(factory, async (store) => {
+            const candidate = memory("dedupe", " Prefers   short answers. ", {
+                scope: { kind: "user", subjectId: "user-a" },
+                kind: "preference",
+            });
+            await store.create(candidate, context);
+            await expect(store.create(candidate, context)).rejects.toBeInstanceOf(MemoryConflictError);
+            expect(await store.findDedupeCandidate({
+                scope: candidate.scope,
+                kind: candidate.kind,
+                content: "prefers short answers.",
+            }, context)).toMatchObject({ id: candidate.id });
+        });
+    });
+    it(`${name}: rejects inactive creates and invalid transitions atomically`, async () => {
+        await withStore(factory, async (store) => {
+            const active = memory("active", "Current value.");
+            await store.create(active, context);
+            const inactive = normalizeMemoryItem({
+                ...memory("inactive", "Old value."),
+                status: "deleted",
+            });
+            await expect(store.create(inactive, context)).rejects.toBeInstanceOf(MemoryContractError);
+            await expect(store.update("active", {
+                status: "pending",
+            }, context)).rejects.toBeInstanceOf(MemoryContractError);
+            expect(await store.get("active", context)).toEqual(active);
+            expect(await store.list({
+                statuses: ["deleted"],
+                includeExpired: true,
+            }, context)).toEqual([]);
+        });
+    });
+    it(`${name}: supersedes atomically and soft-deletes immediately`, async () => {
+        await withStore(factory, async (store) => {
+            await store.create(memory("old", "Uses monthly billing."), context);
+            const result = await store.supersede("old", memory("new", "Uses annual billing."), { ...context, now: "2026-07-28T12:00:00.000Z" });
+            expect(result?.superseded.status).toBe("superseded");
+            expect(result?.replacement.status).toBe("active");
+            expect((await store.search({ query: "billing" }, context))[0]?.item.id)
+                .toBe("new");
+            expect(await store.forget("new", {
+                ...context,
+                now: "2026-07-28T13:00:00.000Z",
+            })).toBe(true);
+            expect(await store.get("new", context)).toBeUndefined();
+            expect(await store.search({ query: "billing" }, context)).toEqual([]);
+            expect(await store.list({
+                statuses: ["deleted"],
+                includeExpired: true,
+            }, context)).toMatchObject([{ id: "new", status: "deleted" }]);
+        });
+    });
+    it(`${name}: rolls back supersede conflicts without changing the original`, async () => {
+        await withStore(factory, async (store) => {
+            await store.create(memory("old", "Old value."), context);
+            await store.create(memory("existing", "Existing value."), context);
+            await expect(store.supersede("old", memory("existing", "Replacement value."), context)).rejects.toBeInstanceOf(MemoryConflictError);
+            expect(await store.get("old", context)).toMatchObject({
+                id: "old",
+                status: "active",
+            });
+        });
+    });
+    it(`${name}: filters expiry and enforces token budgets`, async () => {
+        await withStore(factory, async (store) => {
+            await store.create(memory("a", "Billing invoice reconciliation."), context);
+            await store.create(memory("b", "Billing.", {
+                expiresAt: "2026-07-28T10:30:00.000Z",
+            }), context);
+            await store.create(memory("c", "Billing invoice archive."), context);
+            const results = await store.search({
+                query: "billing invoice",
+                tokenBudget: 10,
+                maxResults: 10,
+                now: "2026-07-28T11:00:00.000Z",
+            }, context);
+            expect(results.map((result) => result.item.id)).toEqual(["a"]);
+            expect(results.reduce((sum, result) => sum + result.estimatedTokens, 0)).toBeLessThanOrEqual(10);
+        });
+    });
+    it(`${name}: records usage without cross-namespace exposure`, async () => {
+        await withStore(factory, async (store) => {
+            await store.create(memory("used", "Used item."), context);
+            await store.appendUsage({
+                id: "usage-1",
+                memoryId: "used",
+                type: "retrieved",
+                at: "2026-07-28T12:00:00.000Z",
+                runId: "run-1",
+            }, context);
+            expect(await store.listUsage("used", context)).toHaveLength(1);
+            expect(await store.listUsage("used", otherProjectContext)).toEqual([]);
+        });
+    });
+}
+memoryItemStoreConformance("InMemoryMemoryItemStore", () => ({
+    store: new InMemoryMemoryItemStore(),
+}));
+memoryItemStoreConformance("FileMemoryItemStore", fixture);
+describe("FileMemoryItemStore durability", () => {
+    it("survives reopen without modifying legacy markdown", async () => {
+        const directory = mkdtempSync(join(tmpdir(), "polpo-memory-items-"));
+        try {
+            const legacyPath = join(directory, "memory.md");
+            writeFileSync(legacyPath, "# Existing legacy memory\n", "utf8");
+            const first = new FileMemoryItemStore(directory);
+            await first.create(createMemoryItem({
+                id: "memory-1",
+                scope: { kind: "agent", agentName: "support" },
+                kind: "fact",
+                content: "Persists.",
+                provenance: { source: "explicit", actor: "system" },
+            }), context);
+            await first.close();
+            const reopened = new FileMemoryItemStore(directory);
+            await expect(reopened.get("memory-1", context))
+                .resolves.toMatchObject({ content: "Persists." });
+            expect(readFileSync(legacyPath, "utf8")).toBe("# Existing legacy memory\n");
+            await reopened.close();
+        }
+        finally {
+            rmSync(directory, { recursive: true, force: true });
+        }
+    });
+    it("serializes concurrent writes without dropping records", async () => {
+        const { store, cleanup } = fixture();
+        try {
+            await Promise.all(Array.from({ length: 50 }, (_, index) => (store.create(createMemoryItem({
+                id: `memory-${index}`,
+                scope: { kind: "agent", agentName: "support" },
+                kind: "fact",
+                content: `Record ${index}`,
+                provenance: { source: "explicit", actor: "system" },
+            }), context))));
+            expect(await store.list({}, context)).toHaveLength(50);
+        }
+        finally {
+            await store.close();
+            cleanup();
+        }
+    });
+    it("fails closed on corrupt persistence and never overwrites it", async () => {
+        const directory = mkdtempSync(join(tmpdir(), "polpo-memory-items-"));
+        try {
+            const path = join(directory, "memory-items.json");
+            writeFileSync(path, "{ definitely-not-json", "utf8");
+            const store = new FileMemoryItemStore(directory);
+            await expect(store.list({}, context)).rejects.toThrow(/corrupt/i);
+            await expect(store.create(createMemoryItem({
+                id: "memory-1",
+                scope: { kind: "agent", agentName: "support" },
+                kind: "fact",
+                content: "Must not overwrite.",
+                provenance: { source: "explicit", actor: "system" },
+            }), context)).rejects.toThrow(/corrupt/i);
+            expect(readFileSync(path, "utf8")).toBe("{ definitely-not-json");
+            expect(existsSync(`${path}.tmp`)).toBe(false);
+        }
+        finally {
+            rmSync(directory, { recursive: true, force: true });
+        }
+    });
+});
+//# sourceMappingURL=file-memory-item-store.test.js.map

package/dist/__tests__/file-memory-item-store.test.js.map

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

package/dist/file-memory-item-store.d.ts

@@ -0,0 +1,32 @@
+import { type MemoryDedupeInput, type MemoryGetOptions, type MemoryItem, type MemoryItemPatch, type MemoryItemStore, type MemoryListQuery, type MemorySearchQuery, type MemorySearchResult, type MemoryStoreContext, type MemorySupersedeResult, type MemoryUsageEvent, type MemoryWritePolicy } from "@polpo-ai/core/memory";
+export declare class MemoryStoreCorruptionError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export interface FileMemoryItemStoreOptions {
+    readonly fileName?: string;
+    readonly writePolicy?: MemoryWritePolicy;
+}
+export declare class FileMemoryItemStore implements MemoryItemStore {
+    private readonly path;
+    private readonly memory;
+    private loaded;
+    private loadError;
+    private writes;
+    constructor(polpoDir: string, options?: FileMemoryItemStoreOptions);
+    private load;
+    private persist;
+    private read;
+    private mutate;
+    create(item: MemoryItem, context: MemoryStoreContext): Promise<MemoryItem>;
+    get(id: string, context: MemoryStoreContext, options?: MemoryGetOptions): Promise<MemoryItem | undefined>;
+    list(query: MemoryListQuery, context: MemoryStoreContext): Promise<MemoryItem[]>;
+    update(id: string, patch: MemoryItemPatch, context: MemoryStoreContext): Promise<MemoryItem | undefined>;
+    supersede(id: string, replacement: MemoryItem, context: MemoryStoreContext): Promise<MemorySupersedeResult | undefined>;
+    forget(id: string, context: MemoryStoreContext): Promise<boolean>;
+    search(query: MemorySearchQuery, context: MemoryStoreContext): Promise<MemorySearchResult[]>;
+    findDedupeCandidate(input: MemoryDedupeInput, context: MemoryStoreContext): Promise<MemoryItem | undefined>;
+    appendUsage(event: MemoryUsageEvent, context: MemoryStoreContext): Promise<void>;
+    listUsage(memoryId: string, context: MemoryStoreContext): Promise<MemoryUsageEvent[]>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=file-memory-item-store.d.ts.map

package/dist/file-memory-item-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-memory-item-store.d.ts","sourceRoot":"","sources":["../src/file-memory-item-store.ts"],"names":[],"mappings":"AASA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,eAAe,EAEpB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACvB,MAAM,uBAAuB,CAAC;AAE/B,qBAAa,0BAA2B,SAAQ,KAAK;gBACvC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIpD;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,CAAC;CAC1C;AAED,qBAAa,mBAAoB,YAAW,eAAe;IACzD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAyC;IAC1D,OAAO,CAAC,MAAM,CAAoC;gBAGhD,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,0BAA+B;IAM1C,OAAO,CAAC,IAAI;IAoBZ,OAAO,CAAC,OAAO;YAqBD,IAAI;IAMlB,OAAO,CAAC,MAAM;IAiBd,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC;IAI1E,GAAG,CACD,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAIlC,IAAI,CACF,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,UAAU,EAAE,CAAC;IAIxB,MAAM,CACJ,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAIlC,SAAS,CACP,EAAE,EAAE,MAAM,EACV,WAAW,EAAE,UAAU,EACvB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC;IAQ7C,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAIjE,MAAM,CACJ,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAIhC,mBAAmB,CACjB,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAIlC,WAAW,CACT,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC;IAIhB,SAAS,CACP,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAIxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/file-memory-item-store.js

@@ -0,0 +1,114 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { InMemoryMemoryItemStore, } from "@polpo-ai/core/memory";
+export class MemoryStoreCorruptionError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "MemoryStoreCorruptionError";
+    }
+}
+export class FileMemoryItemStore {
+    path;
+    memory;
+    loaded = false;
+    loadError;
+    writes = Promise.resolve();
+    constructor(polpoDir, options = {}) {
+        this.path = join(polpoDir, options.fileName ?? "memory-items.json");
+        this.memory = new InMemoryMemoryItemStore(options.writePolicy);
+    }
+    load() {
+        if (this.loaded) {
+            if (this.loadError)
+                throw this.loadError;
+            return;
+        }
+        this.loaded = true;
+        if (!existsSync(this.path))
+            return;
+        try {
+            const parsed = JSON.parse(readFileSync(this.path, "utf8"));
+            this.memory.replaceSnapshot(parsed);
+        }
+        catch (error) {
+            this.loadError = new MemoryStoreCorruptionError(`Memory item store is corrupt: ${this.path}`, { cause: error });
+            throw this.loadError;
+        }
+    }
+    persist() {
+        const directory = dirname(this.path);
+        if (!existsSync(directory))
+            mkdirSync(directory, { recursive: true });
+        const temporaryPath = `${this.path}.tmp`;
+        try {
+            writeFileSync(temporaryPath, `${JSON.stringify(this.memory.exportSnapshot(), null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+            renameSync(temporaryPath, this.path);
+        }
+        catch (error) {
+            try {
+                if (existsSync(temporaryPath))
+                    unlinkSync(temporaryPath);
+            }
+            catch {
+                // Preserve the original persistence error.
+            }
+            throw error;
+        }
+    }
+    async read(operation) {
+        await this.writes;
+        this.load();
+        return operation();
+    }
+    mutate(operation) {
+        const result = this.writes.then(async () => {
+            this.load();
+            const before = this.memory.exportSnapshot();
+            try {
+                const value = await operation();
+                this.persist();
+                return value;
+            }
+            catch (error) {
+                this.memory.replaceSnapshot(before);
+                throw error;
+            }
+        });
+        this.writes = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    create(item, context) {
+        return this.mutate(() => this.memory.create(item, context));
+    }
+    get(id, context, options) {
+        return this.read(() => this.memory.get(id, context, options));
+    }
+    list(query, context) {
+        return this.read(() => this.memory.list(query, context));
+    }
+    update(id, patch, context) {
+        return this.mutate(() => this.memory.update(id, patch, context));
+    }
+    supersede(id, replacement, context) {
+        return this.mutate(() => this.memory.supersede(id, replacement, context));
+    }
+    forget(id, context) {
+        return this.mutate(() => this.memory.forget(id, context));
+    }
+    search(query, context) {
+        return this.read(() => this.memory.search(query, context));
+    }
+    findDedupeCandidate(input, context) {
+        return this.read(() => this.memory.findDedupeCandidate(input, context));
+    }
+    appendUsage(event, context) {
+        return this.mutate(() => this.memory.appendUsage(event, context));
+    }
+    listUsage(memoryId, context) {
+        return this.read(() => this.memory.listUsage(memoryId, context));
+    }
+    async close() {
+        await this.writes;
+    }
+}
+//# sourceMappingURL=file-memory-item-store.js.map

package/dist/file-memory-item-store.js.map

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

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { FileTaskStore } from "./file-task-store.js";
 export { FileRunStore } from "./file-run-store.js";
 export { JsonTaskStore } from "./json-task-store.js";
 export { FileMemoryStore } from "./file-memory-store.js";
+export { FileMemoryItemStore, MemoryStoreCorruptionError, } from "./file-memory-item-store.js";
+export type { FileMemoryItemStoreOptions } from "./file-memory-item-store.js";
 export { FileLogStore } from "./file-log-store.js";
 export { FileSessionStore } from "./file-session-store.js";
 export { FileApprovalStore } from "./file-approval-store.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGvD,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAG5E,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEpG,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EACL,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,6BAA6B,CAAC;AACrC,YAAY,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGvD,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAG5E,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEpG,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -2,6 +2,7 @@ export { FileTaskStore } from "./file-task-store.js";
 export { FileRunStore } from "./file-run-store.js";
 export { JsonTaskStore } from "./json-task-store.js";
 export { FileMemoryStore } from "./file-memory-store.js";
+export { FileMemoryItemStore, MemoryStoreCorruptionError, } from "./file-memory-item-store.js";
 export { FileLogStore } from "./file-log-store.js";
 export { FileSessionStore } from "./file-session-store.js";
 export { FileApprovalStore } from "./file-approval-store.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,mDAAmD;AACnD,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE5E,+CAA+C;AAC/C,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEpG,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EACL,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,mDAAmD;AACnD,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE5E,+CAA+C;AAC/C,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEpG,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polpo-ai/file-stores",
-  "version": "0.15.41",
+  "version": "0.15.42",
   "description": "File-based store implementations for Polpo — the default zero-dependency persistence backend (JSON/Markdown files)",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,7 @@
   ],
   "dependencies": {
     "nanoid": "^5.0.9",
-    "@polpo-ai/core": "0.15.41"
+    "@polpo-ai/core": "0.15.42"
   },
   "license": "MIT",
   "repository": {