Skip to content

v0.5: Pluggable MemoryBackend Protocol (SQLite default + memory-hall recommended) #5

@MakiDevelop

Description

@MakiDevelop

Pivot from "Mem0 integration" to "Pluggable MemoryBackend Protocol"

The original framing of this issue was "integrate Mem0 as memory backend." Based on the v0.5 design pass documented in specs/08-memory-architecture.md, the better path is:

  1. Define a MemoryBackend Protocol that any backend can implement
  2. Ship two backends: SQLite (default, current) + memory-hall (recommended for production)
  3. Leave room for community-contributed Mem0 / Letta / Graphiti backends later

Why memory-hall instead of Mem0 as the primary recommendation

Per specs/08-memory-architecture.md:

  • memory-hall has first-class namespaces + agent_ids → matches VirtualMe's multi-role write pattern (extractor / reflector / evaluator / agent)
  • memory-hall has built-in upstream_ids + provenance_tier → matches VirtualMe's triangulation model
  • memory-hall has CJK-native tokenization → meaningful share of VirtualMe users speak Mandarin / Cantonese / Japanese / Korean
  • memory-hall is Apache 2.0, self-hostable, deliberately small (same design ethic as VirtualMe)

Mem0 is excellent for chat-agent accumulating memory, but it's not optimized for "structured persona artifact extraction with explicit provenance." Mem0 backend can be a community contribution later.

v0.5 implementation plan

src/virtualme/storage/
├─ interface.py          # MemoryBackend Protocol
├─ sqlite_backend.py     # Wraps existing db.py (no behavior change)
└─ memhall_backend.py    # HTTP client with HMAC auth

Operator selects via env:

VIRTUALME_BACKEND=sqlite                           # default
# or
VIRTUALME_BACKEND=memory-hall
VIRTUALME_MEMHALL_ENDPOINT=http://localhost:9100
VIRTUALME_MEMHALL_TOKEN_FILE=~/.config/memhall/token

Acceptance criteria

  • MemoryBackend Protocol defined per specs/08-memory-architecture.md §"Integration interface"
  • sqlite_backend.py extracted from existing db.py — zero behavior change for default users
  • memhall_backend.py implemented with HMAC auth + retries + exponential backoff
  • VIRTUALME_BACKEND env var wired
  • Integration test: same process_turn flow runs identically against both backends
  • Documentation: README clarifies SQLite is for trying-on-yourself, memhall is for production pipelines

Out of scope (separate issue)

Estimated effort

2-3 days for the Protocol + memhall backend. L3/L4 logic is a separate larger workstream.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions