{"_id":"@agent-smith/tmem","_rev":"5-8c4bfe8697d8a0e6178fb509b420c71f","name":"@agent-smith/tmem","dist-tags":{"latest":"0.0.5"},"versions":{"0.0.1":{"name":"@agent-smith/tmem","version":"0.0.1","license":"MIT","_id":"@agent-smith/tmem@0.0.1","maintainers":[{"name":"synw","email":"synwx@pm.me"}],"homepage":"https://github.com/synw/agent-smith#readme","bugs":{"url":"https://github.com/synw/agent-smith/issues"},"dist":{"shasum":"602a4d792ac04961e556743f5827fdc2d35cb026","tarball":"https://registry.npmjs.org/@agent-smith/tmem/-/tmem-0.0.1.tgz","fileCount":7,"integrity":"sha512-/NiXJKovsQiBpW239f5vpB2IV33wd6kP3bqdG27hsBkla1srzyId8KEdRDGQGqTXeQ8SdWuRGLvurRdSbVPvnA==","signatures":[{"sig":"MEQCIH1eEqoMr1VyHhnO9YoTvV+KxNGuwl/euHAe7km702oFAiA3k1LAjuOaM+ucteku+nIQLzAa6EQgDPyS5UaN87WM3w==","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":3240},"type":"module","types":"./dist/main.d.ts","module":"./dist/main.js","exports":{".":{"import":"./dist/main.js"}},"gitHead":"fbeb4cdbb7fe2deb3a0c108b5e7d6e57cb2df549","scripts":{"docs":"typedoc --entryPointStrategy expand","test":"jest --coverage","build":"rm -rf dist/* && tsc","buildrl":"rm -rf dist/* && rollup -c"},"_npmUser":{"name":"synw","email":"synwx@pm.me"},"repository":{"url":"git+https://github.com/synw/agent-smith.git","type":"git"},"_npmVersion":"10.2.4","description":"An api to ceate human friendly agents: the transient memory module","directories":{},"_nodeVersion":"20.11.0","dependencies":{"localforage":"^1.10.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tslib":"^2.6.2","rollup":"^4.12.0","typedoc":"^0.25.8","typescript":"^5.3.3","@types/node":"^20.11.20","@rollup/plugin-terser":"^0.4.4","typedoc-plugin-markdown":"^3.17.1","markdown-it-replace-link":"^1.2.1","@rollup/plugin-typescript":"^11.1.6","@rollup/plugin-node-resolve":"^15.2.3","typedoc-plugin-rename-defaults":"^0.7.0"},"_npmOperationalInternal":{"tmp":"tmp/tmem_0.0.1_1709748317604_0.11586444122461503","host":"s3://npm-registry-packages"}},"0.0.2":{"name":"@agent-smith/tmem","version":"0.0.2","license":"MIT","_id":"@agent-smith/tmem@0.0.2","maintainers":[{"name":"synw","email":"synwx@pm.me"}],"homepage":"https://github.com/synw/agent-smith#readme","bugs":{"url":"https://github.com/synw/agent-smith/issues"},"dist":{"shasum":"ad0dcd77f02dcc12181ef19d16b395c3047b1f34","tarball":"https://registry.npmjs.org/@agent-smith/tmem/-/tmem-0.0.2.tgz","fileCount":7,"integrity":"sha512-dnoJCddVVQ7GLdma1ryu/M4qQnJvZnWRwkIxmaPMDixzxjdIYjZ3eCrIU+cunXfreQYgEeF5zzndtSjdsMEM0A==","signatures":[{"sig":"MEUCIQD0kmfhDlTm5xBrXbRTaP870SMwQ/X6BiMy1n5PoIJq9QIgVjGTpesp7g6tg7vXI75DlhugC0fMhwmYNAU+44L0+IQ=","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":3273},"type":"module","types":"./dist/main.d.ts","module":"./dist/main.js","exports":{".":{"import":"./dist/main.js"}},"gitHead":"fbeb4cdbb7fe2deb3a0c108b5e7d6e57cb2df549","scripts":{"docs":"typedoc --entryPointStrategy expand","test":"jest --coverage","build":"rm -rf dist/* && tsc","buildrl":"rm -rf dist/* && rollup -c"},"_npmUser":{"name":"synw","email":"synwx@pm.me"},"repository":{"url":"git+https://github.com/synw/agent-smith.git","type":"git"},"_npmVersion":"10.2.4","description":"An api to ceate human friendly agents: the transient memory module","directories":{},"_nodeVersion":"20.11.0","dependencies":{"localforage":"^1.10.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tslib":"^2.6.2","rollup":"^4.12.0","typedoc":"^0.25.8","typescript":"^5.3.3","@types/node":"^20.11.20","@rollup/plugin-terser":"^0.4.4","typedoc-plugin-markdown":"^3.17.1","markdown-it-replace-link":"^1.2.1","@rollup/plugin-typescript":"^11.1.6","@rollup/plugin-node-resolve":"^15.2.3","typedoc-plugin-rename-defaults":"^0.7.0"},"_npmOperationalInternal":{"tmp":"tmp/tmem_0.0.2_1709748923107_0.553122250814502","host":"s3://npm-registry-packages"}},"0.0.3":{"name":"@agent-smith/tmem","version":"0.0.3","license":"MIT","_id":"@agent-smith/tmem@0.0.3","maintainers":[{"name":"synw","email":"synwx@pm.me"}],"homepage":"https://github.com/synw/agent-smith#readme","bugs":{"url":"https://github.com/synw/agent-smith/issues"},"dist":{"shasum":"eccd6664c29539bb79314ed8386d64bb3bbed229","tarball":"https://registry.npmjs.org/@agent-smith/tmem/-/tmem-0.0.3.tgz","fileCount":7,"integrity":"sha512-cJsngN8fU/0shY5cf6xeEix0BDIwYqbdhefLzKuoEg05tbcfelCe3QZlngDPbMfarq+wxoEjV01TAhxYVF0UTA==","signatures":[{"sig":"MEUCIHykHopZfV4K1zFI6z8UeN8+1yaQI7I+borxxbT3b8WOAiEAw4D8az5mtZGvxexfckbLQZTeWHhgFdqkf4jPn619zhU=","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":3273},"type":"module","types":"./dist/main.d.ts","module":"./dist/main.js","exports":{".":{"import":"./dist/main.js"}},"gitHead":"0f482cc33b0a3fb58976ccdede0ca37179c3b7be","scripts":{"docs":"typedoc --entryPointStrategy expand","test":"jest --coverage","build":"rm -rf dist/* && tsc","buildrl":"rm -rf dist/* && rollup -c"},"_npmUser":{"name":"synw","email":"synwx@pm.me"},"repository":{"url":"git+https://github.com/synw/agent-smith.git","type":"git"},"_npmVersion":"10.2.4","description":"An api to ceate human friendly agents: the transient memory module","directories":{},"_nodeVersion":"20.11.0","dependencies":{"localforage":"^1.10.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tslib":"^2.6.2","rollup":"^4.12.0","typedoc":"^0.25.8","typescript":"^5.3.3","@types/node":"^20.11.20","@rollup/plugin-terser":"^0.4.4","typedoc-plugin-markdown":"^3.17.1","markdown-it-replace-link":"^1.2.1","@rollup/plugin-typescript":"^11.1.6","@rollup/plugin-node-resolve":"^15.2.3","typedoc-plugin-rename-defaults":"^0.7.0"},"_npmOperationalInternal":{"tmp":"tmp/tmem_0.0.3_1710248447740_0.5903253756668645","host":"s3://npm-registry-packages"}},"0.0.4":{"name":"@agent-smith/tmem","version":"0.0.4","license":"MIT","_id":"@agent-smith/tmem@0.0.4","maintainers":[{"name":"synw","email":"synwx@pm.me"}],"homepage":"https://github.com/synw/agent-smith#readme","bugs":{"url":"https://github.com/synw/agent-smith/issues"},"dist":{"shasum":"15766ff7648de37ffa7012b8b3773fba7b320670","tarball":"https://registry.npmjs.org/@agent-smith/tmem/-/tmem-0.0.4.tgz","fileCount":7,"integrity":"sha512-DIY/Uuq2QjVS9kKg3BdMnx9rpgD4ymt+Q8eHwpfNG5y72HC52WTiRPVKRVeE9x81oh0xswXxp2HrUxNqqqeGhA==","signatures":[{"sig":"MEYCIQDmf7b9jfadr5zitX+ZhwWNNNgmPquUjll3bHt9Yj3DYgIhAOxny7vyq+MWgvaWbe/vAX03lj+wOLdSZmsIpIN8cCav","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":3270},"type":"module","types":"./dist/main.d.ts","module":"./dist/main.js","exports":{".":{"import":"./dist/main.js"}},"gitHead":"6ec40706152f17054b19129e134e5792d7b0fda8","scripts":{"docs":"typedoc --entryPointStrategy expand","test":"jest --coverage","build":"rm -rf dist/* && tsc","buildrl":"rm -rf dist/* && rollup -c"},"_npmUser":{"name":"synw","email":"synwx@pm.me"},"repository":{"url":"git+https://github.com/synw/agent-smith.git","type":"git"},"_npmVersion":"10.8.2","description":"An api to ceate human friendly agents: the transient memory module","directories":{},"_nodeVersion":"20.11.0","dependencies":{"localforage":"^1.10.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tslib":"^2.7.0","rollup":"^4.22.2","typedoc":"^0.26.7","typescript":"^5.6.2","@types/node":"^22.5.5","@rollup/plugin-terser":"^0.4.4","typedoc-plugin-markdown":"^4.2.7","markdown-it-replace-link":"^1.2.1","@rollup/plugin-typescript":"^11.1.6","@rollup/plugin-node-resolve":"^15.2.3","typedoc-plugin-rename-defaults":"^0.7.1"},"_npmOperationalInternal":{"tmp":"tmp/tmem_0.0.4_1726828887653_0.363520083801808","host":"s3://npm-registry-packages"}},"0.0.5":{"name":"@agent-smith/tmem","version":"0.0.5","description":"An api to ceate human friendly agents: the transient memory module","repository":{"type":"git","url":"git+https://github.com/synw/agent-smith.git"},"scripts":{"buildrl":"rm -rf dist/* && rollup -c","build":"rm -rf dist/* && tsc","test":"jest --coverage","docs":"typedoc --entryPointStrategy expand"},"dependencies":{"localforage":"^1.10.0"},"devDependencies":{"@rollup/plugin-node-resolve":"^16.0.3","@rollup/plugin-terser":"^1.0.0","@rollup/plugin-typescript":"^12.3.0","@types/node":"^25.9.1","markdown-it-replace-link":"^1.2.2","rollup":"^4.61.1","tslib":"^2.8.1","typescript":"^6.0.3"},"module":"./dist/main.js","types":"./dist/main.d.ts","type":"module","exports":{".":{"import":"./dist/main.js"}},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"license":"MIT","gitHead":"d0f8060fc9392f1d1a6aaf85d47cdcb591c56e38","_id":"@agent-smith/tmem@0.0.5","bugs":{"url":"https://github.com/synw/agent-smith/issues"},"homepage":"https://github.com/synw/agent-smith#readme","_nodeVersion":"24.11.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-2R5fkRoZwRAX9VZrMa3Ygu6Efgp+ZEumSGkLsO4MdcxW9ztkEbOeSJWi80j20JHeqrZLLaP9O9jYoZX1eiFmpA==","shasum":"bd63eb51d7dc88eaabb5196f0f2743b08cc048bb","tarball":"https://registry.npmjs.org/@agent-smith/tmem/-/tmem-0.0.5.tgz","fileCount":8,"unpackedSize":10009,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHnMv4JPl6jqKeS+IFV0Ll3f2aTcDcQE4GE/kOWZ3IUYAiAZchEsOujg0FxDxKw9NVSYuXqCYg6OkcUAoNAEQgfiyA=="}]},"_npmUser":{"name":"synw","email":"synwx@protonmail.com"},"directories":{},"maintainers":[{"name":"synw","email":"synwx@protonmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/tmem_0.0.5_1780930686698_0.5941762225217171"},"_hasShrinkwrap":false}},"time":{"created":"2024-03-06T18:05:17.472Z","modified":"2026-06-08T14:58:06.973Z","0.0.1":"2024-03-06T18:05:17.768Z","0.0.2":"2024-03-06T18:15:23.289Z","0.0.3":"2024-03-12T13:00:47.919Z","0.0.4":"2024-09-20T10:41:27.840Z","0.0.5":"2026-06-08T14:58:06.849Z"},"bugs":{"url":"https://github.com/synw/agent-smith/issues"},"license":"MIT","homepage":"https://github.com/synw/agent-smith#readme","repository":{"type":"git","url":"git+https://github.com/synw/agent-smith.git"},"description":"An api to ceate human friendly agents: the transient memory module","maintainers":[{"name":"synw","email":"synwx@protonmail.com"}],"readme":"[![npm version](https://img.shields.io/npm/v/@agent-smith/tmem)](https://www.npmjs.com/package/@agent-smith/tmem)\n\n# @agent-smith/tmem — Transient Memory for AI Agents\n\nA lightweight key-value store wrapping [localForage](https://localforage.github.io/localForage/) (IndexedDB backend) with a simple typed async API. Part of the [Agent Smith toolkit](https://github.com/lynxai-team/agent-smith).\n\n## ✨ Features\n\n- 🗄️ **IndexedDB-backed persistence** — data survives page reloads via localForage\n- 🔤 **TypeScript generics** — typed stores with automatic type inference from keys\n- ⚡ **Simple API** — `init`, `set`, `get`, `del`, `keys`, `all` operations\n- 🌐 **Browser-only** — designed for client-side agent state management\n- 🔄 **Lazy initialization** — initial data populated only when store is empty\n\n## Documentation\n\n### For AI Agents\n- [Codebase Summary](.agents/documentation/codebase-summary.md) — Architecture, key files, and patterns for the transient memory package\n- [Get Started](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/libraries/transient_memory/1.get_started.md) — Installation and quick start\n- [Usage Guide](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/libraries/transient_memory/2.usage.md) — Patterns and examples\n- [API Reference](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/libraries/transient_memory/3.api.md) — Complete API surface\n\n### For Humans\n- [Get Started](https://lynxai-team.github.io/agent-smith/libraries/transient_memory/1.get_started) — Installation and quick start\n- [Usage Guide](https://lynxai-team.github.io/agent-smith/libraries/transient_memory/2.usage) — Patterns and examples\n- [API Reference](https://lynxai-team.github.io/agent-smith/libraries/transient_memory/3.api) — Complete API surface\n\n## 📦 Installation\n\n```bash\nnpm i @agent-smith/tmem\n```\n\n## 🚀 Quick Start\n\n```typescript\nimport { useTmem } from \"@agent-smith/tmem\";\n\nconst store = useTmem(\"myStore\", { greeting: \"hello\", count: 0 });\nawait store.init();\n\n// Write\nawait store.set(\"greeting\", \"world\");\n\n// Read (type inferred from key)\nconst greeting = await store.get(\"greeting\");\nconsole.log(greeting); // \"world\"\n\n// Delete and list\nawait store.del(\"count\");\nconst keys = await store.keys();\nconsole.log(keys); // [\"greeting\"]\n```\n\n## 📝 Usage\n\n### Creating a Store\n\n```typescript\nimport { useTmem } from \"@agent-smith/tmem\";\n\nconst prefs = useTmem(\"userPrefs\", {\n    theme: \"dark\",\n    language: \"en\",\n    fontSize: 14,\n});\n```\n\nThe `initial` object is written only if the store is empty. Subsequent `init()` calls won't overwrite existing data.\n\n### Initialization\n\nAlways call `init()` before any read/write operations:\n\n```typescript\nawait prefs.init();\n```\n\n`init()` waits for IndexedDB readiness and populates initial data if the store is empty.\n\n### Verbose Mode\n\nEnable logging during initialization:\n\n```typescript\nconst prefs = useTmem(\"userPrefs\", { theme: \"dark\" }, true);\nawait prefs.init();\n// Console: Tmem: setting initial data for store userPrefs\n```\n\n### Reading and Writing\n\nAll operations are asynchronous:\n\n```typescript\n// Write\nawait prefs.set(\"theme\", \"light\");\n\n// Read (type inferred from key)\nconst theme = await prefs.get(\"theme\");\nconsole.log(theme); // \"light\"\n\n// Get all values\nconst allPrefs = await prefs.all();\n// { theme: \"light\", language: \"en\", fontSize: 14 }\n```\n\n### Error Handling\n\n`get()` throws if the key doesn't exist:\n\n```typescript\ntry {\n    const value = await prefs.get(\"nonexistent\");\n} catch (e) {\n    console.error(e.message); // \"Key nonexistent not found\"\n}\n```\n\n### Deleting Keys\n\n```typescript\nawait prefs.del(\"fontSize\");\n```\n\n### Accessing the Underlying localForage Instance\n\n```typescript\n// Clear the entire store\nawait prefs.db.clear();\n\n// Iterate over all items\nawait prefs.db.iterate((value, key) => {\n    console.log(key, value);\n});\n```\n\n## 🔧 Complete Example\n\n```typescript\nimport { useTmem } from \"@agent-smith/tmem\";\n\nasync function main() {\n    // 1. Create and initialize\n    const store = useTmem(\"appState\", { version: 1, tokens: [] });\n    await store.init();\n\n    // 2. Write values\n    await store.set(\"version\", 2);\n    await store.set(\"tokens\", [\"abc\", \"def\"]);\n\n    // 3. Read values (types inferred from keys)\n    const version = await store.get(\"version\");\n    const tokens = await store.get(\"tokens\");\n    console.log(`Version: ${version}, Tokens: ${tokens.join(\", \")}`);\n\n    // 4. List all keys\n    const keys = await store.keys();\n    console.log(\"Keys:\", keys); // [\"version\", \"tokens\"]\n\n    // 5. Get everything\n    const allData = await store.all();\n    console.log(allData);\n}\n\nmain();\n```\n\n## 📚 API Reference\n\n### Factory Function: `useTmem`\n\n```typescript\nfunction useTmem<S extends Record<string, any> = Record<string, any>>(\n    name: string,\n    initial: S,\n    verbose?: boolean\n): Tmem<S>\n```\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `name` | `string` | Name of the localForage store (determines IndexedDB object store name) |\n| `initial` | `S` | Initial key-value pairs. Written only if store is empty |\n| `verbose` | `boolean` (optional) | Enable console logging during init. Default: `false` |\n\n### Interface: `Tmem<S>`\n\n```typescript\ninterface Tmem<S extends Record<string, any>> {\n    db: LocalForage;\n    init(): Promise<void>;\n    set<T extends keyof S>(k: T, v: S[T]): Promise<void>;\n    get<T extends keyof S>(k: T): Promise<S[T]>;\n    del<T extends keyof S>(k: T): Promise<void>;\n    keys(): Promise<Array<string>>;\n    all<T = any>(): Promise<Record<string, T>>;\n}\n```\n\n### Method Summary\n\n| Method | Signature | Returns | Description |\n|--------|-----------|---------|-------------|\n| `init()` | `() => Promise<void>` | — | Initialize store with initial data if empty |\n| `set(k, v)` | `(k: keyof S, v: S[keyof S]) => Promise<void>` | — | Store a key-value pair |\n| `get(k)` | `(k: keyof S) => Promise<S[keyof S]>` | Value | Retrieve value by key (throws if missing) |\n| `del(k)` | `(k: keyof S) => Promise<void>` | — | Remove a key from the store |\n| `keys()` | `() => Promise<string[]>` | Array | List all keys in the store |\n| `all()` | `() => Promise<Record<string, any>>` | Object | Get all key-value pairs |\n\n## ⚠️ Important Notes\n\n- **Browser-only**: Uses IndexedDB via localForage — not suitable for Node.js/server-side use\n- **Server alternative**: Use `@agent-smith/smem` (LanceDB) for persistent memory on the server side\n- **Async operations**: All methods return Promises — always use `await`\n- **Type inference**: Generic types are inferred from keys, not provided by the user\n\n## 📄 License\n\nMIT\n","readmeFilename":"README.md"}