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

use std::collections::BTreeMap;
use std::path::{Path, PathBuf};

use super::{
    execute::journal_workspace, fingerprint, query_error, CollectionProgress, MigrationLock,
    MigrationState, Phase, AGENT_COLLECTIONS, STATE_FORMAT_VERSION,
};

pub(crate) fn prepare_live_switch(
    source: &Path,
    destination: &Path,
    target_model: &str,
    target_dimension: usize,
    target_witness: &str,
) -> Result<PathBuf, crate::MemoryError> {
    verify_target_provenance(destination, target_model, target_dimension)?;
    let source = source
        .canonicalize()
        .map_err(|err| query_error(format!("cannot resolve live source: {err}")))?;
    let source_fingerprint = fingerprint(&source)?;
    let workspace = journal_workspace(destination)?;
    let lock = MigrationLock::acquire(&workspace, "migrate-live-prepare").map_err(query_error)?;
    let result = prepare_locked(
        &workspace,
        &lock,
        source,
        source_fingerprint,
        target_model,
        target_dimension,
        target_witness,
    );
    super::execute::reconcile(result, lock.release())?;
    Ok(workspace)
}

fn prepare_locked(
    workspace: &Path,
    lock: &MigrationLock,
    source_path: PathBuf,
    source_fingerprint: String,
    target_model: &str,
    target_dimension: usize,
    target_witness: &str,
) -> Result<(), crate::MemoryError> {
    if let Some(existing) = MigrationState::read(workspace).map_err(query_error)? {
        existing
            .may_resume(
                &source_path,
                &source_fingerprint,
                target_model,
                target_dimension,
            )
            .map_err(query_error)?;
        if existing.embedder_witness.as_deref() != Some(target_witness) {
            return Err(query_error(
                "live switch target embedder witness changed; start a fresh migration",
            ));
        }
        return require_validated(existing.phase);
    }
    let mut state = new_state(
        source_path,
        source_fingerprint,
        target_model,
        target_dimension,
        target_witness,
    );
    state.write(workspace, lock).map_err(query_error)?;
    state.phase = Phase::DestinationValidated;
    state.write(workspace, lock).map_err(query_error)
}

fn new_state(
    source_path: PathBuf,
    source_fingerprint: String,
    target_model: &str,
    target_dimension: usize,
    target_witness: &str,
) -> MigrationState {
    let progress = AGENT_COLLECTIONS
        .iter()
        .map(|name| ((*name).to_owned(), CollectionProgress::Complete))
        .collect::<BTreeMap<_, _>>();
    MigrationState {
        format_version: STATE_FORMAT_VERSION,
        phase: Phase::Prepared,
        source_path,
        source_fingerprint,
        target_model: target_model.to_owned(),
        target_dimension,
        progress,
        embedder_witness: Some(target_witness.to_owned()),
    }
}

fn require_validated(phase: Phase) -> Result<(), crate::MemoryError> {
    if phase == Phase::DestinationValidated {
        return Ok(());
    }
    Err(query_error(format!(
        "live switch preparation found journal phase {phase:?}; recovery must finish first"
    )))
}

fn verify_target_provenance(
    destination: &Path,
    target_model: &str,
    target_dimension: usize,
) -> Result<(), crate::MemoryError> {
    let recorded = crate::embedding_provenance::read(destination).map_err(query_error)?;
    crate::embedding_provenance::check(recorded.as_ref(), target_model, target_dimension)
        .map_err(query_error)
}