Skip to content

Memory Backend Migration

Describes how amplihack-rs supports migrating agent memory between SQLite and Graph-DB (LadybugDB, formerly Kuzu) backends, and the env-var override contract that controls which backend is active.

Backend Selection

flowchart TD
    A([Process start]) --> B{AMPLIHACK_GRAPH_DB_PATH\nor AMPLIHACK_KUZU_DB_PATH set?}
    B -- primary env var\nAMPLIHACK_GRAPH_DB_PATH --> C[Validate path\n• absolute\n• no ..\n• not /proc /sys /dev]
    B -- legacy env var\nAMPLIHACK_KUZU_DB_PATH --> D[Emit deprecation\nwarning → validate path]
    B -- neither set --> E[Default: ~/.amplihack/\nmemory_kuzu.db\n(legacy path)]
    C --> F{Valid?}
    D --> F
    E --> G[Open Graph-DB]
    F -- yes --> G
    F -- no --> ERR([Error: invalid override path])
    G --> H{Backend preference\nresolved}
    H -- graph-db --> I[GraphDbBackend\nLadybugDB embedded]
    H -- sqlite --> J[SQLiteBackend\nfor transfer operations]

Migration Flow (SQLite → Graph-DB)

sequenceDiagram
    participant CLI as amplihack memory transfer
    participant SQLite as SQLiteBackend
    participant GraphDb as GraphDbBackend
    participant FS as Filesystem

    CLI->>SQLite: open source DB (read-only)
    CLI->>GraphDb: open target DB
    CLI->>SQLite: list_sessions()
    loop For each session
        CLI->>SQLite: load_session_rows(session_id)
        SQLite-->>CLI: Vec<MemoryRecord>
        CLI->>GraphDb: store_session_learning(records)
        GraphDb-->>FS: persist to graph nodes
        CLI->>CLI: report progress
    end
    CLI->>CLI: emit migration summary

Environment Variable Contract

Variable Status Purpose
AMPLIHACK_GRAPH_DB_PATH Primary (preferred) Backend-neutral override; use this
AMPLIHACK_KUZU_DB_PATH Deprecated Legacy backward-compatible alias; emits warning

Both variables are validated with identical security rules before use.