{"_id":"0g-memory-sdk","_rev":"3-8ad7f17e2b28d7ab8d25559515117cd3","name":"0g-memory-sdk","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"0g-memory-sdk","version":"0.1.0","keywords":["ai-agents","agent-memory","0g-network","decentralized-storage","web3","autonomous-agents","blockchain","llm"],"author":{"name":"0G-Memory Contributors"},"license":"MIT","_id":"0g-memory-sdk@0.1.0","maintainers":[{"name":"alphataco","email":"alphataco2004@gmail.com"}],"homepage":"https://github.com/anbusan19/0g-memory-sdk#readme","bugs":{"url":"https://github.com/anbusan19/0g-memory-sdk/issues"},"dist":{"shasum":"4e0fa8fd684d6c4f0465a7fcb943adbfd9bce3a1","tarball":"https://registry.npmjs.org/0g-memory-sdk/-/0g-memory-sdk-0.1.0.tgz","fileCount":11,"integrity":"sha512-Tn1f3sxzUbz1enuAlAgAuhemg4UurWpWmJwDnK4H/C+JildVl79v6hyrHk8QQrmT2819bIqVg4f8HuES914QKQ==","signatures":[{"sig":"MEUCIC5ZzHrx8wOehY6Tis+ONrr9Jz+Yp2fSbOYMEemKWQytAiEAxUv6A9mRdCm9Fy7HkXNcaZlxD9VGNh8P6D/hdA3+GzU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":55839},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"167af7ec81e3a85cc1c8e014c67bac3cc06b7343","scripts":{"dev":"tsup --watch","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"alphataco","email":"alphataco2004@gmail.com"},"repository":{"url":"git+https://github.com/anbusan19/0g-memory-sdk.git","type":"git"},"_npmVersion":"11.6.1","description":"Persistent, verifiable memory for AI agents — backed by 0G Storage (KV + Log) and 0G Chain","directories":{},"_nodeVersion":"24.6.0","dependencies":{"ethers":"6.13.1","@0gfoundation/0g-storage-ts-sdk":"^1.2.9"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","typescript":"^5.0.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/0g-memory-sdk_0.1.0_1778942978364_0.5378379819897356","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"0g-memory-sdk","version":"0.1.1","keywords":["ai-agents","agent-memory","0g-network","decentralized-storage","web3","autonomous-agents","blockchain","llm"],"author":{"name":"0G-Memory Contributors"},"license":"MIT","_id":"0g-memory-sdk@0.1.1","maintainers":[{"name":"alphataco","email":"alphataco2004@gmail.com"}],"homepage":"https://github.com/anbusan19/0g-memory-sdk#readme","bugs":{"url":"https://github.com/anbusan19/0g-memory-sdk/issues"},"dist":{"shasum":"4a2c21c4337b09b2d9026b827a43bbfea12c7817","tarball":"https://registry.npmjs.org/0g-memory-sdk/-/0g-memory-sdk-0.1.1.tgz","fileCount":12,"integrity":"sha512-9vu5h29Ed0Nua6Jg+inj1n8lDwV1epdhikgoh9UJPVtnVn3Rw/tUractrCpOqCNf2R+MqbTqA6MZ2QMXhdVvmQ==","signatures":[{"sig":"MEQCIAdcWEshP0RcXrHQ/ZsmS5hK6JOOQAPVChVvtCo+WH+tAiAbiOpIxN2v/s/S+ubng4Kfyy7/yVSAxW7/d+r6irzBEQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":62621},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"167af7ec81e3a85cc1c8e014c67bac3cc06b7343","scripts":{"dev":"tsup --watch","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"alphataco","email":"alphataco2004@gmail.com"},"repository":{"url":"git+https://github.com/anbusan19/0g-memory-sdk.git","type":"git"},"_npmVersion":"11.6.1","description":"Persistent, verifiable memory for AI agents — backed by 0G Storage (KV + Log) and 0G Chain","directories":{},"_nodeVersion":"24.6.0","dependencies":{"ethers":"6.13.1","@0gfoundation/0g-storage-ts-sdk":"^1.2.9"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","typescript":"^5.0.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/0g-memory-sdk_0.1.1_1778943325479_0.41818813827842294","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"0g-memory-sdk","publishConfig":{"access":"public"},"version":"0.1.2","description":"Persistent, verifiable memory for AI agents — backed by 0G Storage (KV + Log) and 0G Chain","keywords":["ai-agents","agent-memory","0g-network","decentralized-storage","web3","autonomous-agents","blockchain","llm"],"license":"MIT","author":{"name":"0G-Memory Contributors"},"repository":{"type":"git","url":"git+https://github.com/anbusan19/0g-memory-sdk.git"},"main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit"},"dependencies":{"@0gfoundation/0g-storage-ts-sdk":"^1.2.9","ethers":"6.13.1"},"devDependencies":{"@types/node":"^22.0.0","tsup":"^8.5.1","typescript":"^5.0.0"},"engines":{"node":">=18"},"gitHead":"167af7ec81e3a85cc1c8e014c67bac3cc06b7343","_id":"0g-memory-sdk@0.1.2","bugs":{"url":"https://github.com/anbusan19/0g-memory-sdk/issues"},"homepage":"https://github.com/anbusan19/0g-memory-sdk#readme","_nodeVersion":"24.6.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-FO2x/mQZqMt5XlkBXdUfrWC8mXoZmJHryFDFbp/w7plAwyXdIcD5k00VAnVrw/oGkY3NQzGid4/D7OH++EURNA==","shasum":"c6d826ed4f95bce905ea4717bf4d72c1b63419fe","tarball":"https://registry.npmjs.org/0g-memory-sdk/-/0g-memory-sdk-0.1.2.tgz","fileCount":12,"unpackedSize":70010,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCozO41lGKLAXDg5/ZyPsg8xS7TnrbmtF4d57IfYAn8vAIhAJqB1fKaTjog/VFr0Sz6QEGRugWDJNePsC8JP/E83yBo"}]},"_npmUser":{"name":"alphataco","email":"alphataco2004@gmail.com"},"directories":{},"maintainers":[{"name":"alphataco","email":"alphataco2004@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/0g-memory-sdk_0.1.2_1778948502921_0.7024685130765327"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-16T14:49:38.277Z","modified":"2026-05-16T16:21:43.173Z","0.1.0":"2026-05-16T14:49:38.509Z","0.1.1":"2026-05-16T14:55:25.632Z","0.1.2":"2026-05-16T16:21:43.058Z"},"bugs":{"url":"https://github.com/anbusan19/0g-memory-sdk/issues"},"author":{"name":"0G-Memory Contributors"},"license":"MIT","homepage":"https://github.com/anbusan19/0g-memory-sdk#readme","keywords":["ai-agents","agent-memory","0g-network","decentralized-storage","web3","autonomous-agents","blockchain","llm"],"repository":{"type":"git","url":"git+https://github.com/anbusan19/0g-memory-sdk.git"},"description":"Persistent, verifiable memory for AI agents — backed by 0G Storage (KV + Log) and 0G Chain","maintainers":[{"name":"alphataco","email":"alphataco2004@gmail.com"}],"readme":"![0G-Memory](../../readmebanner.png)\n\n# 0G-Memory SDK\n\n[![npm version](https://img.shields.io/npm/v/0g-memory-sdk)](https://www.npmjs.com/package/0g-memory-sdk)\n[![license](https://img.shields.io/npm/l/0g-memory-sdk)](./LICENSE)\n\nPersistent, verifiable memory for AI agents — backed by [0G Storage](https://0g.ai) (KV + Log layers) and 0G Chain.\n\nAgents built with this SDK remember clients, context, and history across sessions — from any machine, without a database.\n\n```bash\nnpm install 0g-memory-sdk\n```\n\n---\n\n## Why\n\nAI agents forget everything when a session ends. Context lives in RAM, databases owned by third parties, or not at all. There is no cryptographic proof that stored data was not modified.\n\n`0g-memory-sdk` gives any agent three primitives that run entirely on the 0G decentralized network:\n\n| Method | What it does |\n|---|---|\n| `remember(key, value)` | Writes permanently to 0G Log (immutable, Merkle-provable) and registers a `key → rootHash` pointer in 0G KV so it is retrievable from any machine |\n| `recall(key)` | Resolves the key via the KV index, fetches the value from the Log layer |\n| `archive(record)` | Writes typed business records and returns a [StorageScan](https://storagescan-newton.0g.ai) URL as a verifiable on-chain proof |\n\nBecause the key index lives on 0G — not on disk — any agent instance with the same private key and `agentId` gets full memory across machines, restarts, and serverless deployments.\n\n---\n\n## Quick start\n\n```ts\nimport { ZeroGMemory, deriveAgentId } from '0g-memory-sdk';\n\nconst { agentId } = deriveAgentId('my-agent', process.env.PRIVATE_KEY!);\n\nconst memory = new ZeroGMemory({\n  agentId,\n  privateKey: process.env.PRIVATE_KEY!,\n  rpcUrl:     'https://evmrpc-testnet.0g.ai',\n  indexerRpc: 'https://indexer-storage-testnet-standard.0g.ai',\n});\n\n// Store something\nconst rootHash = await memory.remember('user:alice', { plan: 'pro', credits: 42 });\n\n// Retrieve later — from any machine\nconst data = await memory.recall('user:alice');\n// → { plan: 'pro', credits: 42 }\n\n// Or retrieve immediately by root hash (before KV index settles on-chain)\nconst same = await memory.recallByHash(rootHash);\n```\n\n> **Testnet tokens:** Get OG from the [0G faucet](https://faucet.0g.ai) to pay for storage transactions.\n\n---\n\n## API\n\n### `new ZeroGMemory(config)`\n\n```ts\nconst memory = new ZeroGMemory({\n  agentId:    string,  // unique agent identifier — use deriveAgentId()\n  privateKey: string,  // wallet private key, pays for 0G storage txs\n  rpcUrl:     string,  // 0G chain RPC endpoint\n  indexerRpc: string,  // 0G storage indexer endpoint\n});\n```\n\n`ChainMemory` is exported as an alias of `ZeroGMemory` for backward compatibility.\n\n---\n\n### `memory.remember(key, value) → Promise<string>`\n\nWrites `value` to the 0G Log layer (permanent, content-addressed) and fires a concurrent KV write to register `key → rootHash` in the distributed index. Returns the root hash.\n\n```ts\nconst rootHash = await memory.remember('session:xyz', {\n  messages: [...],\n  summary: 'User asked about pricing.',\n});\n```\n\nThe KV index write settles within a few 0G blocks. Use `recallByHash(rootHash)` for same-request access before it settles.\n\n---\n\n### `memory.recall(key) → Promise<unknown | null>`\n\nLooks up `key` in the 0G KV index, then fetches the value from the Log layer. Returns `null` if the key was never written or the KV index has not yet settled.\n\nFalls back automatically to the legacy local-file index (`.chainmemory/`) for data written by earlier SDK versions, and migrates those entries to KV on first access.\n\n```ts\nconst context = await memory.recall('session:xyz');\nif (context) {\n  // resume where the agent left off\n}\n```\n\n---\n\n### `memory.recallByHash(rootHash) → Promise<unknown | null>`\n\nFetches a value directly from the 0G Log layer by its root hash, bypassing the KV index entirely. Use this immediately after `remember()` when you cannot wait for the index to settle.\n\n```ts\nconst rootHash = await memory.remember('key', data);\nconst same     = await memory.recallByHash(rootHash); // always consistent\n```\n\n---\n\n### `memory.archive(record) → Promise<{ rootHash, storageScanUrl }>`\n\nWrites a typed, permanent record to the 0G Log layer. Returns the content-address root hash and a [StorageScan](https://storagescan-newton.0g.ai) explorer URL that anyone can use to verify the data was not modified.\n\n```ts\nconst { rootHash, storageScanUrl } = await memory.archive({\n  type: 'invoice',   // 'invoice' | 'payment' | 'interaction' | 'custom'\n  data: invoice,\n});\n\nconsole.log(storageScanUrl);\n// https://storagescan-newton.0g.ai/tx/0xabc...\n```\n\n---\n\n### `memory.updateClientContext(clientName, context) → Promise<string>`\n\nConvenience wrapper that normalises `clientName` to a key (`client:<name>`) and calls `remember()`. Designed for agents that serve multiple clients and need per-client persistent state. Returns the root hash.\n\n```ts\nconst rootHash = await memory.updateClientContext('Alice Johnson', {\n  totalInvoiced: 4200,\n  invoiceCount:  3,\n  lastJobDescription: 'Frontend redesign — 40 hrs at $120/hr',\n});\n\n// Recall in a future session:\nconst alice = await memory.recall('client:alice_johnson');\n```\n\n---\n\n### `deriveAgentId(name, privateKey) → AgentIdentity`\n\nDerives a deterministic, collision-resistant agent ID from a human-readable name and a wallet private key. Format: `<name>:<first-8-hex-chars-of-address>`.\n\n```ts\nimport { deriveAgentId } from '0g-memory-sdk';\n\nconst { agentId, walletAddress } = deriveAgentId('billing-agent', process.env.PRIVATE_KEY!);\n// agentId:       \"billing-agent:a3f8c201\"\n// walletAddress: \"0xA3F8...\"\n```\n\n### `isValidAgentId(agentId) → boolean`\n\nValidates that a string matches the `<name>:<8-hex-chars>` format.\n\n---\n\n## Configuration reference\n\n| Field | Description | Testnet value |\n|---|---|---|\n| `agentId` | Unique agent identifier | `deriveAgentId('my-agent', privateKey).agentId` |\n| `privateKey` | Wallet private key — pays gas and storage fees | Your Galileo testnet key |\n| `rpcUrl` | 0G chain JSON-RPC endpoint | `https://evmrpc-testnet.0g.ai` |\n| `indexerRpc` | 0G storage indexer endpoint | `https://indexer-storage-testnet-standard.0g.ai` |\n\n---\n\n## Patterns\n\n### Session memory across restarts\n\n```ts\nasync function chat(sessionId: string, userMessage: string) {\n  const history = (await memory.recall(`session:${sessionId}`)) as Message[] ?? [];\n\n  const reply = await llm.complete([\n    ...history,\n    { role: 'user', content: userMessage },\n  ]);\n\n  await memory.remember(`session:${sessionId}`, [\n    ...history,\n    { role: 'user',      content: userMessage },\n    { role: 'assistant', content: reply },\n  ]);\n\n  return reply;\n}\n```\n\n### Returning-client detection\n\n```ts\nasync function greet(clientName: string) {\n  const ctx = await memory.recall(`client:${clientName.toLowerCase()}`);\n  return ctx\n    ? `Welcome back — you've invoiced $${ctx.totalInvoiced} across ${ctx.invoiceCount} jobs.`\n    : `Welcome! Let's set up your first invoice.`;\n}\n```\n\n### Verifiable audit trail\n\n```ts\nconst { rootHash, storageScanUrl } = await memory.archive({\n  type: 'invoice',\n  data: { id: 'INV-042', client: 'Acme Corp', total: 6000, currency: 'USD' },\n});\n\n// Share storageScanUrl — anyone can verify the invoice was not tampered with\n```\n\n### LangChain / agent framework integration\n\n```ts\nimport { ZeroGMemory, deriveAgentId } from '0g-memory-sdk';\n\nconst { agentId } = deriveAgentId('langchain-agent', process.env.PRIVATE_KEY!);\nconst memory = new ZeroGMemory({ agentId, privateKey: ..., rpcUrl: ..., indexerRpc: ... });\n\n// Use as a custom memory store\nconst loadMemory = async (key: string) => memory.recall(key);\nconst saveMemory = async (key: string, value: unknown) => memory.remember(key, value);\n```\n\n---\n\n## Consistency model\n\n| Pattern | Consistency | When to use |\n|---|---|---|\n| `remember()` → `recallByHash()` | Immediate | Same request, same session |\n| `remember()` → `recall()` | Eventual (few blocks, ~seconds) | Cross-session, cross-machine |\n| `archive()` | Write-once, permanent | Invoices, audit trails, proof records |\n\n`recall()` automatically falls back to the local `.chainmemory/` index for data written by older SDK versions and migrates those entries to the KV layer transparently.\n\n---\n\n## Reference application\n\n**AgentBill** is the reference implementation — an autonomous invoicing agent built with this SDK on the full 0G stack:\n\n- **0G Compute** — Qwen-2.5-7B parses natural-language job descriptions into structured invoices\n- **0G Memory** — per-client context recalled across sessions via `recall()` / `updateClientContext()`\n- **0G Storage** — each invoice archived permanently via `archive()`, root hash returned as proof\n- **0G Chain** — invoice registered and paid on-chain via an escrow smart contract\n\nSource: [github.com/anbusan19/0g-memory](https://github.com/anbusan19/0g-memory)\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}