{"_id":"@archoniclabs/ultra-memory","_rev":"2-265ce95a942b5f2e55012d5394301175","name":"@archoniclabs/ultra-memory","dist-tags":{"alpha":"0.1.0-alpha.0","latest":"1.0.0"},"versions":{"0.1.0-alpha.0":{"name":"@archoniclabs/ultra-memory","version":"0.1.0-alpha.0","keywords":["ai","memory","local-first","agent","provenance"],"license":"Apache-2.0","_id":"@archoniclabs/ultra-memory@0.1.0-alpha.0","maintainers":[{"name":"archoniclabs","email":"akshaypadamata06@gmail.com"}],"dist":{"shasum":"216af79b075e5b5aff822770a4cb175d48574b59","tarball":"https://registry.npmjs.org/@archoniclabs/ultra-memory/-/ultra-memory-0.1.0-alpha.0.tgz","fileCount":23,"integrity":"sha512-/4Sxb52SWvWwDbLxPNS/jiEewaGzyZe6fL1ToXZORL6130AbnZ2yA6nXucdHduQDCHToRQPNFscdGciwl/jNSg==","signatures":[{"sig":"MEUCIQC1JnHKM//9g23d6TIb892H8CsnJAWcDiJzF/OPA7q2cQIgcNOaZRLZEHe7CKOHzaELtOfbxKZYZHnyKqkFGZZVXM0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":53672},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"npm run build && node --test tests/*.test.mjs","build":"tsc -p tsconfig.json","example":"npm run build && node examples/email-firewall.mjs","prepack":"npm run build","typecheck":"tsc -p tsconfig.json --noEmit","prepublishOnly":"npm run typecheck && npm test"},"_npmUser":{"name":"archoniclabs","email":"akshaypadamata06@gmail.com"},"_npmVersion":"11.6.2","description":"Local-first governed memory layer for AI apps.","directories":{},"_nodeVersion":"24.11.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.5.4","@types/node":"^26.0.0"},"_npmOperationalInternal":{"tmp":"tmp/ultra-memory_0.1.0-alpha.0_1781901542148_0.5124479120511389","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@archoniclabs/ultra-memory","version":"1.0.0","description":"Local-first governed memory layer for AI apps.","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"bin":{"ultra-memory":"dist/cli.js"},"publishConfig":{"access":"public"},"scripts":{"build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit","test":"npm run build && node --test tests/*.test.mjs","prepack":"npm run build","prepublishOnly":"npm run typecheck && npm test","example":"npm run build && node examples/email-firewall.mjs"},"keywords":["ai","memory","local-first","agent","provenance"],"license":"Apache-2.0","devDependencies":{"@types/node":"^26.0.0","typescript":"^5.5.4"},"engines":{"node":">=20"},"_id":"@archoniclabs/ultra-memory@1.0.0","_nodeVersion":"24.11.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-TseFRctZ7YbLj6E1d19O7hQit90Z+90VYIRGc/c6m65pSxIiojdUSbyc+J5D2VYfclR7DW9WcL/74G1QG83A5g==","shasum":"f2612675a68e643523407678a516673c29998d90","tarball":"https://registry.npmjs.org/@archoniclabs/ultra-memory/-/ultra-memory-1.0.0.tgz","fileCount":27,"unpackedSize":76805,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDqMutOjhGw5wN6uVUFofzr4TAM914EVo+2C/+Hh4zbjAIhANeZgq6+eZi1uz0kd+/yy/eged/qEdChxXUvQbNuEcFP"}]},"_npmUser":{"name":"archoniclabs","email":"akshaypadamata06@gmail.com"},"directories":{},"maintainers":[{"name":"archoniclabs","email":"akshaypadamata06@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ultra-memory_1.0.0_1781903859190_0.4586823497240218"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-19T20:39:02.053Z","modified":"2026-06-19T21:17:39.497Z","0.1.0-alpha.0":"2026-06-19T20:39:02.287Z","1.0.0":"2026-06-19T21:17:39.373Z"},"license":"Apache-2.0","keywords":["ai","memory","local-first","agent","provenance"],"description":"Local-first governed memory layer for AI apps.","maintainers":[{"name":"archoniclabs","email":"akshaypadamata06@gmail.com"}],"readme":"# Ultra Memory\n\nUltra Memory is a local-first governed memory layer for AI apps. It is not trying to be another vector database. It sits above retrieval and decides which memories are safe, relevant, and explainable enough to influence an answer or action.\n\nThe core idea:\n\n```txt\nobserve or remember context\n-> store a governed memory record with provenance\n-> build a task-specific memory capsule\n-> run risky actions through a memory firewall\n-> show what was used, excluded, and why\n```\n\n## Install\n\nInstall:\n\n```bash\nnpm install @archoniclabs/ultra-memory\n```\n\nRun the demo:\n\n```bash\nnpx @archoniclabs/ultra-memory demo\n```\n\nFor local development:\n\n```bash\nnpm install\nnpm run build\nnpm test\n```\n\nAgent Ultra can consume it during development with:\n\n```bash\nnpm install ../ultra-memory\n```\n\n## Quickstart\n\n```ts\nimport { UltraMemory } from \"@archoniclabs/ultra-memory\";\n\nconst memory = await UltraMemory.open({\n  appId: \"agent-ultra\",\n  storagePath: \"/path/to/userData/memory_tree\",\n  localOnly: true,\n  policy: {\n    confirmationRequiredActionTypes: [\"email.send\", \"file.delete\"]\n  }\n});\n\nawait memory.remember({\n  type: \"preference\",\n  text: \"User prefers concise technical explanations.\",\n  scope: { kind: \"global\" },\n  status: \"confirmed\",\n  source: [{ kind: \"manual\", note: \"User confirmed in settings.\" }]\n});\n\nawait memory.ingest({\n  kind: \"conversation\",\n  conversationId: \"thread_123\",\n  messageId: \"msg_1\",\n  role: \"user\",\n  projectId: \"agent-ultra\",\n  text: \"Remember that Maya is a contact from AI Alliance. I prefer concise warm emails.\"\n});\n\nconst inbox = await memory.reviewInbox({ projectId: \"agent-ultra\" });\n\nconst capsule = await memory.buildCapsule({\n  task: \"Draft a follow-up email to Maya from AI Alliance.\",\n  actionType: \"email.draft\",\n  projectId: \"agent-ultra\"\n});\n\nconsole.log(capsule.toPrompt());\n\nconst decision = await memory.guardAction({\n  actionType: \"email.send\",\n  capsule\n});\n\nconst audit = await memory.listAuditEvents({ maxItems: 10 });\n```\n\n## What Makes It Different\n\n- Every memory requires provenance.\n- Inferred and confirmed memories are distinct.\n- Memories have scope, confidence, sensitivity, and lifecycle fields.\n- Capsules explain why each memory was selected.\n- Capsules show notable exclusions.\n- The firewall prevents memory from silently authorizing risky actions.\n- `ingest()` turns app events into inferred memories for review.\n- `reviewInbox()` lets users confirm or reject inferred memory before it becomes trusted.\n- `listAuditEvents()` shows what memory did, not just what it stored.\n- The first store is local JSON, and the store interface is replaceable.\n\n## Current API\n\n- `UltraMemory.open()`\n- `remember()`\n- `ingest()`\n- `reviewInbox()`\n- `search()`\n- `buildCapsule()`\n- `guardAction()`\n- `listAuditEvents()`\n- `confirm()`\n- `reject()`\n- `forget()`\n- `expire()`\n- `update()`\n- `exportBundle()`\n- `importBundle()`\n\n## Production Behavior\n\nThe framework includes runtime validation. Memories are rejected if they have invalid type/status/sensitivity fields, missing text, missing project/app scope IDs, invalid dates, or no provenance source.\n\nFirewall policy is configurable:\n\n```ts\nconst memory = await UltraMemory.open({\n  appId: \"agent-ultra\",\n  storagePath,\n  localOnly: true,\n  policy: {\n    deniedActionTypes: [\"payment.send\"],\n    confirmationRequiredActionTypes: [\"email.send\", \"file.delete\", \"email.draft\"],\n    highSensitivityRequiresOptIn: true,\n    externalCommunicationRequiresConfirmation: false\n  }\n});\n```\n\nThe defaults still deny memory authorization for payments, require confirmation for email sends and file deletes, and require explicit opt-in before high-sensitivity memories can influence actions.\n\n## Retrieval Adapters\n\nUltra Memory can sit above an existing memory backend. Retrieval adapters provide candidate records from LanceDB, SQLite, full-text search, app-specific chunk stores, or any other retrieval system. Ultra Memory still owns governance, capsule filtering, action safety, and audit.\n\n```ts\nconst memory = await UltraMemory.open({\n  appId: \"my-ai-app\",\n  storagePath,\n  localOnly: true,\n  retrievalAdapters: [\n    {\n      id: \"lancedb\",\n      async search(options) {\n        const rows = await searchExistingVectorIndex(options.query, options.maxItems ?? 20);\n        return rows.map((row) => ({\n          record: mapRowToUltraMemoryRecord(row),\n          score: row.score,\n          reasons: [\"semantic match\"]\n        }));\n      }\n    }\n  ]\n});\n```\n\nThis is the intended production layering:\n\n```txt\nexisting retrieval finds candidates\n-> Ultra Memory validates governed records\n-> buildCapsule() filters by scope/status/sensitivity/action\n-> guardAction() blocks unsafe actions\n```\n\n## Example\n\nRun:\n\n```bash\nnpm run example\n```\n\nRun tests:\n\n```bash\nnpm test\n```\n\nThe example saves:\n\n1. a confirmed email style preference\n2. an inferred AI Alliance relationship memory\n3. a high-sensitivity unrelated enterprise deal memory\n\nThen it builds an email capsule and blocks `email.send` unless the user confirms in the current session.\n\nThe capsule also performs a shadow audit: nearby memories that share task terms but fail governance checks are shown as excluded. This is designed to catch cases where unrelated deal context might otherwise leak into an external email.\n\n## Architecture Notes\n\nSee [docs/architecture.md](docs/architecture.md) for the record/capsule/firewall model and the shadow-audit behavior.\n\n## Electron Integration Shape\n\nUse the package from the Electron main process:\n\n```ts\nconst memory = await UltraMemory.open({\n  appId: \"agent-ultra\",\n  storagePath: path.join(app.getPath(\"userData\"), \"memory_tree\"),\n  localOnly: true\n});\n\nipcMain.handle(\"memory:buildCapsule\", (_event, options) => {\n  return memory.buildCapsule(options);\n});\n\nipcMain.handle(\"memory:guardAction\", (_event, options) => {\n  return memory.guardAction(options);\n});\n```\n\nFor chat, ask for `actionType: \"chat.answer\"`. For external drafts, ask for `email.draft`. Before sending anything externally, call `guardAction()` with `email.send`.\n","readmeFilename":"README.md"}