Ultra Memory

Ultra 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.

The core idea:

observe or remember context
-> store a governed memory record with provenance
-> build a task-specific memory capsule
-> run risky actions through a memory firewall
-> show what was used, excluded, and why

Install

Install:

npm install @archoniclabs/ultra-memory

Run the demo:

npx @archoniclabs/ultra-memory demo

For local development:

npm install
npm run build
npm test

Agent Ultra can consume it during development with:

npm install ../ultra-memory

Quickstart

import { UltraMemory } from "@archoniclabs/ultra-memory";

const memory = await UltraMemory.open({
  appId: "agent-ultra",
  storagePath: "/path/to/userData/memory_tree",
  localOnly: true,
  policy: {
    confirmationRequiredActionTypes: ["email.send", "file.delete"]
  }
});

await memory.remember({
  type: "preference",
  text: "User prefers concise technical explanations.",
  scope: { kind: "global" },
  status: "confirmed",
  source: [{ kind: "manual", note: "User confirmed in settings." }]
});

await memory.ingest({
  kind: "conversation",
  conversationId: "thread_123",
  messageId: "msg_1",
  role: "user",
  projectId: "agent-ultra",
  text: "Remember that Maya is a contact from AI Alliance. I prefer concise warm emails."
});

const inbox = await memory.reviewInbox({ projectId: "agent-ultra" });

const capsule = await memory.buildCapsule({
  task: "Draft a follow-up email to Maya from AI Alliance.",
  actionType: "email.draft",
  projectId: "agent-ultra"
});

console.log(capsule.toPrompt());

const decision = await memory.guardAction({
  actionType: "email.send",
  capsule
});

const audit = await memory.listAuditEvents({ maxItems: 10 });

What Makes It Different

• Every memory requires provenance.
• Inferred and confirmed memories are distinct.
• Memories have scope, confidence, sensitivity, and lifecycle fields.
• Capsules explain why each memory was selected.
• Capsules show notable exclusions.
• The firewall prevents memory from silently authorizing risky actions.
• ingest() turns app events into inferred memories for review.
• reviewInbox() lets users confirm or reject inferred memory before it becomes trusted.
• listAuditEvents() shows what memory did, not just what it stored.
• The first store is local JSON, and the store interface is replaceable.

Current API

• UltraMemory.open()
• remember()
• ingest()
• reviewInbox()
• search()
• buildCapsule()
• guardAction()
• listAuditEvents()
• confirm()
• reject()
• forget()
• expire()
• update()
• exportBundle()
• importBundle()

Production Behavior

The 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.

Firewall policy is configurable:

const memory = await UltraMemory.open({
  appId: "agent-ultra",
  storagePath,
  localOnly: true,
  policy: {
    deniedActionTypes: ["payment.send"],
    confirmationRequiredActionTypes: ["email.send", "file.delete", "email.draft"],
    highSensitivityRequiresOptIn: true,
    externalCommunicationRequiresConfirmation: false
  }
});

The 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.

Retrieval Adapters

Ultra 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.

const memory = await UltraMemory.open({
  appId: "my-ai-app",
  storagePath,
  localOnly: true,
  retrievalAdapters: [
    {
      id: "lancedb",
      async search(options) {
        const rows = await searchExistingVectorIndex(options.query, options.maxItems ?? 20);
        return rows.map((row) => ({
          record: mapRowToUltraMemoryRecord(row),
          score: row.score,
          reasons: ["semantic match"]
        }));
      }
    }
  ]
});

This is the intended production layering:

existing retrieval finds candidates
-> Ultra Memory validates governed records
-> buildCapsule() filters by scope/status/sensitivity/action
-> guardAction() blocks unsafe actions

Example

Run:

npm run example

Run tests:

npm test

The example saves:

1. a confirmed email style preference
2. an inferred AI Alliance relationship memory
3. a high-sensitivity unrelated enterprise deal memory

Then it builds an email capsule and blocks email.send unless the user confirms in the current session.

The 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.

Architecture Notes

See docs/architecture.md for the record/capsule/firewall model and the shadow-audit behavior.

Electron Integration Shape

Use the package from the Electron main process:

const memory = await UltraMemory.open({
  appId: "agent-ultra",
  storagePath: path.join(app.getPath("userData"), "memory_tree"),
  localOnly: true
});

ipcMain.handle("memory:buildCapsule", (_event, options) => {
  return memory.buildCapsule(options);
});

ipcMain.handle("memory:guardAction", (_event, options) => {
  return memory.guardAction(options);
});

For chat, ask for actionType: "chat.answer". For external drafts, ask for email.draft. Before sending anything externally, call guardAction() with email.send.