velesdb-memory 0.14.1

VelesDB-memory: local-first MCP memory server for AI agents (remember/recall/relate/forget/why + deterministic context compiler).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

use std::path::Path;

use super::{
    activate_destination, advance, archive_source, entry_state, journal_workspace, late_activation,
    outcome, query_error, rename_durably, require_journalled_fingerprint, unrecognised_disk,
    MigrationLock, MigrationState, Phase, Slots, SwitchOutcome, SwitchState,
};

pub(crate) fn stage_live_switch(
    store: &Path,
    destination: &Path,
) -> Result<SwitchOutcome, crate::MemoryError> {
    run_live_action(store, destination, stage_locked, false)
}

pub(crate) fn rollback_staged_live_switch(
    store: &Path,
    destination: &Path,
) -> Result<SwitchOutcome, crate::MemoryError> {
    run_live_action(store, destination, rollback_locked, false)
}

pub(crate) fn finalize_staged_live_switch(
    store: &Path,
    destination: &Path,
) -> Result<SwitchOutcome, crate::MemoryError> {
    run_live_action(store, destination, finalize_locked, true)
}

type LiveAction =
    fn(&Slots, &mut MigrationState, &Path, &MigrationLock) -> Result<(), crate::MemoryError>;

fn run_live_action(
    store: &Path,
    destination: &Path,
    action: LiveAction,
    allow_completed: bool,
) -> Result<SwitchOutcome, crate::MemoryError> {
    let workspace = journal_workspace(destination)?;
    let lock = MigrationLock::acquire(&workspace, "migrate-live-switch").map_err(query_error)?;
    let result = live_action_locked(
        store,
        destination,
        &workspace,
        &lock,
        action,
        allow_completed,
    );
    crate::migration::execute::reconcile(result, lock.release())
}

fn live_action_locked(
    store: &Path,
    destination: &Path,
    workspace: &Path,
    lock: &MigrationLock,
    action: LiveAction,
    allow_completed: bool,
) -> Result<SwitchOutcome, crate::MemoryError> {
    let mut state = entry_state(workspace, allow_completed)?;
    let slots = Slots::resolve(store, &state, destination)?;
    action(&slots, &mut state, workspace, lock)?;
    Ok(outcome(&slots))
}

fn stage_locked(
    slots: &Slots,
    state: &mut MigrationState,
    _workspace: &Path,
    _lock: &MigrationLock,
) -> Result<(), crate::MemoryError> {
    require_phase(state.phase, Phase::DestinationValidated, "stage")?;
    archive_source(slots, state)?;
    activate_destination(slots, state)
}

fn rollback_locked(
    slots: &Slots,
    state: &mut MigrationState,
    _workspace: &Path,
    _lock: &MigrationLock,
) -> Result<(), crate::MemoryError> {
    require_phase(state.phase, Phase::DestinationValidated, "roll back")?;
    match slots.on_disk() {
        SwitchState {
            source: true,
            archive: false,
            destination: true,
        } => Ok(()),
        SwitchState {
            source: false,
            archive: true,
            destination: true,
        } => restore_first_rename(slots, state),
        SwitchState {
            source: true,
            archive: true,
            destination: false,
        } => restore_both_renames(slots, state),
        other => Err(unrecognised_disk(other, Phase::DestinationValidated)),
    }
}

fn restore_first_rename(slots: &Slots, state: &MigrationState) -> Result<(), crate::MemoryError> {
    require_journalled_fingerprint(&slots.archive, state, "archive")?;
    rename_durably(&slots.archive, &slots.source)
}

fn restore_both_renames(slots: &Slots, state: &MigrationState) -> Result<(), crate::MemoryError> {
    late_activation(slots, state)?;
    rename_durably(&slots.source, &slots.destination)?;
    rename_durably(&slots.archive, &slots.source)
}

fn finalize_locked(
    slots: &Slots,
    state: &mut MigrationState,
    workspace: &Path,
    lock: &MigrationLock,
) -> Result<(), crate::MemoryError> {
    if state.phase == Phase::Committed {
        return Ok(());
    }
    late_activation(slots, state)?;
    if state.phase == Phase::DestinationValidated {
        advance(state, Phase::SourceArchived, workspace, lock)?;
    }
    require_phase(state.phase, Phase::SourceArchived, "finalize")?;
    advance(state, Phase::DestinationActivated, workspace, lock)
}

fn require_phase(
    actual: Phase,
    expected: Phase,
    operation: &str,
) -> Result<(), crate::MemoryError> {
    if actual == expected {
        return Ok(());
    }
    Err(query_error(format!(
        "cannot {operation} live switch from journal phase {actual:?}; expected {expected:?}"
    )))
}