Unified Memory Hub

The problem of continuity

How can multiple AI workspaces retrieve durable, inspectable project context across sessions while keeping private data under local control?

Local-first memory layer

I built a dual-backend memory layer: portable JSON records for durability, with SQLite/FTS5 for fast local retrieval. Hybrid semantic and full-text search, an embedding cache, incremental ingestion, and a mem CLI make project context usable across agent sessions. A local dashboard and file watcher expose ingestion, search, and system health instead of hiding the system behind a vector-store API.

Cloud backup

The local database remains the source of truth. New, updated, and deleted records enter a durable outbox, then Firestore receives merge writes after a short debounce. This automatic path is push-only: it never reads from or imports cloud records, and localOnly memories never leave the machine.

Cloud reconciliation is a separate, explicit action. When requested, mem sync reads only records changed since its saved watermark and reconciles newer local or remote versions without treating Firestore as a real-time replica. Locks, deterministic document IDs, retries, and visible provider health keep that process bounded and inspectable.

Retrieval with provenance

Memory Hub is designed to return context that is both relevant and traceable. Each record keeps its source, timestamps, tags, and—when it can be determined—its project, contributing agent, original file path, and document section. That allows a query to answer both “what seems useful here?” and “where did this come from?”

Retrieval combines embedding-based semantic similarity with SQLite FTS5/BM25 keyword ranking. Semantic search helps surface related ideas; keyword ranking protects exact technical details such as function names, URLs, error messages, and project-specific language. Results can also be narrowed by project, agent, source, or tag.

For information that changes over time, the CLI supports keyed upserts. A stable source + key identifies one fact, so a corrected preference, decision, or project status replaces its earlier version instead of creating a second, contradictory record. The system keeps the record’s identity, refreshes its content and embedding when needed, merges its tags and metadata, and queues the newest version for backup.

Design constraints

The system had to preserve continuity without making personal context dependent on a hosted service or opaque automation. Retrieved memories needed enough provenance to be checked, not simply trusted, and routine cloud behavior needed to stay bounded on free-tier infrastructure. Those constraints led to explicit reconciliation, push-only backup, local control of private data, and visible failure states rather than silent fallback behavior.

Visual walkthrough

This page will later carry an architecture diagram and a synthetic query flow.