{"_id":"@apeira/storage","_rev":"3-33ae6bef7b0944641505b64a27e41945","name":"@apeira/storage","dist-tags":{"latest":"0.0.8"},"versions":{"0.0.6":{"name":"@apeira/storage","version":"0.0.6","keywords":["agent","ai","xsai"],"author":"Moeru AI","license":"MIT","_id":"@apeira/storage@0.0.6","maintainers":[{"name":"kwaa","email":"kwa@kwaa.dev"}],"homepage":"https://github.com/moeru-ai/apeira","bugs":"https://github.com/moeru-ai/apeira/issues","dist":{"shasum":"b3fae7de7f7082a5e9d5b9116d0726f71bf4cf89","tarball":"https://registry.npmjs.org/@apeira/storage/-/storage-0.0.6.tgz","fileCount":14,"integrity":"sha512-q3WSkCfdOednFTIbAD6TIr0a/YtOFIBUBOJ0oDC5lJQOHtoZ73nLws42NtMcsOqs850Jjn1G/SrvaGsb7J86jA==","signatures":[{"sig":"MEQCIFLAyHs8T5htgEm1tiEgAanDeO0D8AOktDy26qqsVdm2AiAmxZs7A9Udw8NkYeFKDWwoq5lV5dnTR59ZrdOFWOXkhA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":14973},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./kv":{"types":"./dist/kv.d.ts","default":"./dist/kv.js"},"./json":{"types":"./dist/json.d.ts","default":"./dist/json.js"},"./jsonl":{"types":"./dist/jsonl.d.ts","default":"./dist/jsonl.js"},"./package.json":"./package.json"},"scripts":{"test":"vitest run","build":"pkgroll"},"_npmUser":{"name":"kwaa","email":"kwa@kwaa.dev"},"repository":{"url":"git+https://github.com/moeru-ai/apeira.git","type":"git","directory":"packages/storage"},"description":"Persistent storage adapters for Apeira agents.","directories":{},"sideEffects":false,"_nodeVersion":"26.3.1","_hasShrinkwrap":false,"devDependencies":{"@apeira/core":"0.0.6"},"peerDependencies":{"@apeira/core":"0.0.6"},"_npmOperationalInternal":{"tmp":"tmp/storage_0.0.6_1781868808116_0.14539653771280237","host":"s3://npm-registry-packages-npm-production"}},"0.0.7":{"name":"@apeira/storage","version":"0.0.7","keywords":["agent","ai","xsai"],"author":"Moeru AI","license":"MIT","_id":"@apeira/storage@0.0.7","maintainers":[{"name":"kwaa","email":"kwa@kwaa.dev"}],"homepage":"https://github.com/moeru-ai/apeira","bugs":"https://github.com/moeru-ai/apeira/issues","dist":{"shasum":"815a84ae8a63c8174450e924eb3c5ebf2d9cb5d7","tarball":"https://registry.npmjs.org/@apeira/storage/-/storage-0.0.7.tgz","fileCount":14,"integrity":"sha512-9r8V17IBySQ0WRG2oGORcpOwkC9O09uPEj2qOmtbUk2ccyxY33G5skaeCjxkTk8YkF0s5sgKyc41FRnwKXwyjg==","signatures":[{"sig":"MEQCIE8r66u6SFihc7YpOA83wRehzlYJdHJdloJs8QmhfNCuAiBqPCfqTLPvmEmh2UEn+PJpKriENxOkwFBIJyze1MaWGA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@apeira%2fstorage@0.0.7","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":14973},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./kv":{"types":"./dist/kv.d.ts","default":"./dist/kv.js"},"./json":{"types":"./dist/json.d.ts","default":"./dist/json.js"},"./jsonl":{"types":"./dist/jsonl.d.ts","default":"./dist/jsonl.js"},"./package.json":"./package.json"},"scripts":{"test":"vitest run","build":"pkgroll"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:80d1d5b3-9fd0-4951-b2ac-3808044590d0"}},"repository":{"url":"git+https://github.com/moeru-ai/apeira.git","type":"git","directory":"packages/storage"},"description":"Persistent storage adapters for Apeira agents.","directories":{},"sideEffects":false,"_nodeVersion":"26.5.0","_hasShrinkwrap":false,"devDependencies":{"@apeira/core":"0.0.7"},"peerDependencies":{"@apeira/core":"0.0.7"},"_npmOperationalInternal":{"tmp":"tmp/storage_0.0.7_1784024927715_0.1353238246430548","host":"s3://npm-registry-packages-npm-production"}},"0.0.8":{"name":"@apeira/storage","type":"module","version":"0.0.8","description":"Persistent storage adapters for Apeira agents.","author":"Moeru AI","license":"MIT","homepage":"https://github.com/moeru-ai/apeira","repository":{"type":"git","url":"git+https://github.com/moeru-ai/apeira.git","directory":"packages/storage"},"bugs":"https://github.com/moeru-ai/apeira/issues","keywords":["agent","ai","xsai"],"sideEffects":false,"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./json":{"types":"./dist/json.d.ts","default":"./dist/json.js"},"./jsonl":{"types":"./dist/jsonl.d.ts","default":"./dist/jsonl.js"},"./kv":{"types":"./dist/kv.d.ts","default":"./dist/kv.js"},"./package.json":"./package.json"},"peerDependencies":{"@apeira/core":"0.0.8"},"devDependencies":{"@apeira/core":"0.0.8"},"scripts":{"build":"pkgroll","test":"vitest run"},"main":"./dist/index.js","types":"./dist/index.d.ts","_nodeVersion":"26.7.0","_id":"@apeira/storage@0.0.8","dist":{"integrity":"sha512-7JfhWbCAJrXz4aOskBX3I4sw2T+SgOzN5Y2kvoJCsVwjBrUI3TdGQpsf41zXvgUMdZZroB3RvyKxdxKsI28U0A==","shasum":"747d66f387ddc7f73b49f7bb72c02d8dcd2796bc","tarball":"https://registry.npmjs.org/@apeira/storage/-/storage-0.0.8.tgz","fileCount":14,"unpackedSize":14973,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@apeira%2fstorage@0.0.8","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAFJrKJN/S+xKQSnYBoGAEh9FiPgUoCyUfxF+uyBm/NTAiBULp0MTe1ROI82cEvpWGWQlObhS20dE32PKcxo+3QrEg=="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:80d1d5b3-9fd0-4951-b2ac-3808044590d0"}},"directories":{},"maintainers":[{"name":"kwaa","email":"kwa@kwaa.dev"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/storage_0.0.8_1786204905734_0.64302275128555"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-19T11:33:27.954Z","modified":"2026-08-08T16:01:46.237Z","0.0.6":"2026-06-19T11:33:28.260Z","0.0.7":"2026-07-14T10:28:47.845Z","0.0.8":"2026-08-08T16:01:45.878Z"},"bugs":"https://github.com/moeru-ai/apeira/issues","author":"Moeru AI","license":"MIT","homepage":"https://github.com/moeru-ai/apeira","keywords":["agent","ai","xsai"],"repository":{"type":"git","url":"git+https://github.com/moeru-ai/apeira.git","directory":"packages/storage"},"description":"Persistent storage adapters for Apeira agents.","maintainers":[{"name":"kwaa","email":"kwa@kwaa.dev"}],"readme":"# @apeira/storage\n\nPersistent `AgentStorage` implementations for Apeira.\n\n## Install\n\n```sh\npnpm add @apeira/storage\n```\n\n## JSON\n\nStores the complete entry array in a JSON file. Each append rewrites the file.\n\n```ts\nimport { createAgent } from '@apeira/core'\nimport { json } from '@apeira/storage/json'\n\nconst agent = createAgent({\n  instructions: 'You are a helpful assistant.',\n  runner,\n  storage: json({ path: './data/agent.json' }),\n})\n```\n\nUse JSON storage when human-readable files are useful and the history is\nrelatively small.\n\n## JSONL\n\nStores one entry per line and appends new entries without rewriting existing\ncontent.\n\n```ts\nimport { createAgent } from '@apeira/core'\nimport { jsonl } from '@apeira/storage/jsonl'\n\nconst agent = createAgent({\n  instructions: 'You are a helpful assistant.',\n  runner,\n  storage: jsonl({ path: './data/agent.jsonl' }),\n})\n```\n\nJSONL is the better file format for long-running, append-heavy agents.\n\n## Key-value storage\n\nAdapts a string key-value backend such as Web Storage or an asynchronous\nstorage API. Entries are split into segments to avoid storing the complete log\nunder one key.\n\n```ts\nimport type { StorageLike } from '@apeira/storage/kv'\n\nimport { createAgent } from '@apeira/core'\nimport { kv } from '@apeira/storage/kv'\n\ndeclare const backend: StorageLike\n\nconst agent = createAgent({\n  instructions: 'You are a helpful assistant.',\n  runner,\n  storage: kv({\n    backend,\n    prefix: 'assistant',\n    segmentSize: 100,\n  }),\n})\n```\n\nThe backend must implement:\n\n```ts\nimport type { MaybePromise } from '@apeira/core'\n\ninterface StorageLike {\n  getItem: (key: string) => MaybePromise<null | string | undefined>\n  removeItem: (key: string) => MaybePromise<void>\n  setItem: (key: string, value: string) => MaybePromise<void>\n}\n```\n\n`prefix` defaults to `apeira` and `segmentSize` defaults to `100`.\n\n## Storage lifecycle\n\nAll implementations provide the standard `AgentStorage` operations:\n\n```ts\nimport type { MaybePromise } from '@apeira/core'\n\ninterface AgentStorage<T> {\n  append: (...items: T[]) => MaybePromise<void>\n  clear: () => MaybePromise<void>\n  read: () => MaybePromise<Readonly<T[]>>\n}\n```\n\nStorage only manages persisted entries. Agent initialization and reset\nbaselines belong to core:\n\n```ts\nconst agent = createAgent({\n  initialInput: [user('Existing context')],\n  initialState: { userId: 'user-123' },\n  instructions: 'You are a helpful assistant.',\n  runner,\n  storage: jsonl({ path: './data/agent.jsonl' }),\n})\n```\n\nDuring initialization, core writes `initialInput` only when storage contains no\ninput entries. `agent.reset()` clears storage and restores `initialInput` and\n`initialState`.\n\n## Generic storage\n\nThe storage functions default to `AgentEntry`, but can store another\nJSON-serializable type:\n\n```ts\nconst store = jsonl<string>({ path: './data/items.jsonl' })\n\nawait store.append('first', 'second')\nconst items = await store.read()\n```\n\nJSON and JSONL storage require Node.js. Key-value storage works in any runtime\nthat provides a compatible backend.\n","readmeFilename":""}