Hoppi Memory

Hoppi is OPPi's local-first memory backend and dashboard. It was forked from Hippo and reshaped to be a safe library package: no postinstall automation, no hidden agent windows, no hook/scheduler setup by default, and no Codex/OpenClaw/MCP integration surfaces in the public API.

What Hoppi provides

• side-effect-free TypeScript API for OPPi
• project-scoped local memory storage
• recall, list, update, pin, forget, supersede, consolidate primitives
• OPPi-themed local dashboard with CRUD, project scope, sync setup, manual sync actions, and conflict resolution
• portable sync snapshots for private GitHub repositories
• tombstones for delete convergence across devices
• optional passphrase encryption for sync payloads
• local embedding rebuild support after pulls/imports

Safety model

Installing or importing Hoppi must not:

• install shell hooks
• register schedulers
• start background workers
• spawn Claude/Codex/OpenCode/OpenClaw windows
• wrap CLIs
• mutate agent config files

OPPi owns orchestration and timing. Hoppi exposes explicit storage/dashboard/sync functions only.

Installation

npm install @oppiai/hoppi-memory

OPPi can also install this package on demand into its managed package directory when the user accepts the first-start prompt or chooses the install action from /settings:oppi → Memory.

Library usage

import { createHoppiBackend } from "@oppiai/hoppi-memory";

const hoppi = createHoppiBackend();
await hoppi.init();

const project = { cwd: process.cwd(), displayName: "my-project" };
await hoppi.remember({ project, content: "Durable thing to remember.", tags: ["decision"] });

const recall = await hoppi.recall({ project, query: "durable thing", budget: 1200 });
console.log(recall.contextMarkdown);

Dashboard

const handle = await hoppi.startDashboard({ project, port: 0 });
console.log(handle.url); // http://hoppi.localhost:<port>?projectId=...

The dashboard exposes local APIs for memories, projects, settings, sync status, explicit manual sync, and conflict resolution. Its Sync settings tab includes a private-GitHub setup guide, safe-default checklist, copyable bootstrap commands, optional passphrase settings, and manual pull/push/sync buttons. It also has a built-in demo fallback when opened without a live API.

Sync

Sync stores portable memory records and tombstones, not raw SQLite databases:

import { syncGitRepository, rebuildEmbeddings } from "@oppiai/hoppi-memory";

const result = syncGitRepository(root, repoPath, {
  direction: "both",
  conflictMode: "keep-both",
  passphrase,
});

if (result.embeddingsRebuildRecommended) {
  await rebuildEmbeddings(root);
}

The conservative default is keep-both: conflicting edits are preserved and marked for dashboard resolution rather than silently overwritten. The dashboard Operations panel shows conflict previews and keeps delete-vs-edit conflicts explicit: keep the local edit, accept the remote delete, promote a remote edit, or keep both as separate memories.

Development

npm run build
npm test
npm run build:ui
npm run smoke:pack

The legacy Hippo CLI/source remains in the repository during the fork transition for regression coverage and diagnostics, but the public package entrypoint is intentionally narrow and side-effect-free.