velesdb-memory 0.11.6

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
144

#![deny(unsafe_code)]
//! # VelesDB-memory
//!
//! Local-first **memory** layer for AI agents, exposed through a single MCP
//! server. This crate is the domain core: it maps nine memory operations onto
//! `VelesDB`'s in-core Agent Memory SDK.
//!
//! | Operation           | Meaning                                            |
//! |--------------------|-----------------------------------------------------|
//! | `remember`          | store a fact (+ optional links to other memories)  |
//! | `recall`            | semantic retrieval of similar facts                |
//! | `recall_where`      | semantic retrieval filtered by metadata            |
//! | `recall_fused`      | vector + graph fused retrieval                     |
//! | `relate`            | create a typed edge between two memories           |
//! | `forget`            | delete a memory                                    |
//! | `why`               | recall + multi-hop graph traversal                 |
//! | `feedback`          | reinforce or penalize a memory after use           |
//! | `remember_extracted`| extract facts from raw text and auto-wire the graph|
//!
//! ## License boundary (non-negotiable)
//!
//! This crate exposes **memory semantics only** (results), never raw database
//! capabilities (`query(velesql)`, `create_collection`, `upsert(vectors)`,
//! `traverse(graph)`). Exposing the raw engine would constitute a "Substantial
//! Set" of the Software's features and breach the `VelesDB` Core License 1.0
//! (§1, No Hosted or Managed Service). See `VISION.md` §5 and `PLAN.md` Phase 4A.

/// Wall-clock "today" as a `YYYYMMDD` integer, read only by `remember`'s
/// auto-date stamping (see [`storage::AUTO_DATE_FIELD`]) — never by the
/// context compiler, which stays clock-free and deterministic. Internal:
/// nothing outside the crate needs to read the clock directly.
mod clock;
/// The optional TOML configuration file: one place to set every knob, with
/// `command line > environment > file > default` precedence. Native-only —
/// it reads the filesystem.
#[cfg(not(target_arch = "wasm32"))]
pub mod config;
/// The deterministic context compiler (EPIC-P-070): classify, dedup, and pack
/// caller-supplied context fragments under a token budget — no LLM, no cloud,
/// every decision auditable. Gated behind the default `context` feature.
#[cfg(feature = "context")]
pub mod context;
/// Format recalled facts as a chronological, date-prefixed timeline with a
/// "now" anchor — the dated-context representation measured to lift temporal
/// question answering, shipped as product behavior rather than a harness prompt.
pub mod dated_context;
pub mod embedder;
pub mod error;
pub mod extract;
/// Vector+graph score fusion — the ranking layer behind
/// [`service::MemoryService::recall_fused`]. Internal: callers reach it only
/// through that method.
mod fusion;
/// The streamable-HTTP transport (multi-client mode): lets several MCP
/// clients share ONE `velesdb-memory` process instead of each spawning its
/// own stdio process and fighting over the store's single-writer `flock`.
/// Gated behind the (non-default) `http` feature — see the module docs and
/// the crate README's "HTTP transport (multi-client)" section.
#[cfg(feature = "http")]
pub mod http;
/// Content-addressed memory ids — internal; ids surface through the service API.
pub(crate) mod id;
/// Resource caps (DoS limits) shared by every adapter — the single source of
/// truth for fact size, recall limit, and `why` hop depth.
pub mod limits;
/// The MCP server transport. Gated behind the default `mcp` feature so library
/// consumers (e.g. the language bindings) can depend on the memory core without
/// pulling the `rmcp`/`tokio` server stack.
#[cfg(feature = "mcp")]
pub mod mcp;
/// The domain data model — the value types the memory layer exchanges
/// (`Link`, `Recollection`, `ColumnFilter`, `Explanation`, …), separate from the
/// service that computes them.
pub mod model;
/// Synchronous retry + actionable failure reporting shared by the two blocking
/// Ollama call sites ([`embedder`] and [`extract`]). Internal: it exists to make
/// those two backends resilient, not to be a general-purpose retry API.
#[cfg(any(feature = "ollama", feature = "extract"))]
mod ollama_retry;
/// Optional second-stage re-scoring of a fused recall pool (bring your own
/// cross-encoder/LLM). Never wired in by default — see [`rerank::Reranker`].
pub mod rerank;
/// Shared JSON Schema post-processing (strips `schemars`' non-standard integer
/// `format` keywords so strict MCP clients don't warn on every id field).
mod schema;
pub mod service;
/// The storage backend abstraction — [`storage::MemoryStore`] and the
/// default, file-backed [`storage::NativeStore`]. Implement `MemoryStore` to
/// run the wedge over a different backend (e.g. an in-memory one for WASM).
pub mod storage;
/// Locally-generated TLS material (a cached self-signed CA + short-lived
/// leaf certs) for the streamable-HTTP transport's HTTPS-by-default
/// listener — see the module docs for the full design rationale. Gated
/// behind `http` since it exists only to serve that transport.
#[cfg(feature = "http")]
pub mod tls;

/// Default embedding dimension — the single source of truth, taken from the
/// SDK's own default so the server, library, and tests never restate the
/// value. `velesdb_core::agent` (where the canonical constant lives) is
/// itself `persistence`-gated, so a `persistence`-free build (e.g.
/// `velesdb-wasm`) falls back to `FALLBACK_DIMENSION`.
#[cfg(feature = "persistence")]
pub const DEFAULT_DIMENSION: usize = velesdb_core::agent::DEFAULT_DIMENSION;
#[cfg(not(feature = "persistence"))]
pub const DEFAULT_DIMENSION: usize = FALLBACK_DIMENSION;

/// The hand-written value the `persistence`-free arm of
/// [`DEFAULT_DIMENSION`] falls back to (the canonical constant's module is
/// feature-gated away there). The `persistence` build — CI's default —
/// statically asserts it still equals the canonical value, so drift fails
/// to compile instead of silently splitting the wasm default dimension
/// from the native one.
const FALLBACK_DIMENSION: usize = 384;
#[cfg(feature = "persistence")]
const _: () = assert!(
    FALLBACK_DIMENSION == velesdb_core::agent::DEFAULT_DIMENSION,
    "update FALLBACK_DIMENSION to match velesdb_core::agent::DEFAULT_DIMENSION"
);

#[cfg(feature = "context")]
pub use context::ContextCompiler;
pub use dated_context::{format_dated_context, DatedContext};
pub use embedder::{DynEmbedder, EmbedError, Embedder, HashEmbedder};
#[cfg(feature = "ollama")]
pub use embedder::{OllamaEmbedder, DEFAULT_OLLAMA_MODEL, DEFAULT_OLLAMA_URL};
pub use error::{ErrorCategory, MemoryError};
#[cfg(feature = "extract")]
pub use extract::OllamaExtractor;
pub use extract::{
    DynExtractor, ExtractError, ExtractedAttribute, ExtractedFact, ExtractedRelation, Extraction,
    Extractor,
};
#[cfg(feature = "mcp")]
pub use mcp::McpServer;
pub use model::{
    ColumnFilter, ColumnOp, EntityProfile, EntityRelation, Explanation, FusionOptions, Link,
    MemoryEdge, MemoryNode, Recollection, UnrelateOutcome,
};
pub use rerank::{DynReranker, RerankError, Reranker};
pub use service::{MemoryService, Metadata};
#[cfg(feature = "persistence")]
pub use storage::NativeStore;
pub use storage::{MemoryStore, AUTO_DATE_FIELD};