velesdb_memory/
lib.rs

1#![deny(unsafe_code)]
2//! # VelesDB-memory
3//!
4//! Local-first **memory** layer for AI agents, exposed through a single MCP
5//! server. This crate is the domain core: it maps five memory operations onto
6//! `VelesDB`'s in-core Agent Memory SDK.
7//!
8//! | Operation  | Meaning                                            |
9//! |------------|----------------------------------------------------|
10//! | `remember` | store a fact (+ optional links to other memories)  |
11//! | `recall`   | semantic retrieval of similar facts                |
12//! | `relate`   | create a typed edge between two memories           |
13//! | `forget`   | delete a memory                                    |
14//! | `why`      | recall + multi-hop graph traversal                 |
15//!
16//! ## License boundary (non-negotiable)
17//!
18//! This crate exposes **memory semantics only** (results), never raw database
19//! capabilities (`query(velesql)`, `create_collection`, `upsert(vectors)`,
20//! `traverse(graph)`). Exposing the raw engine would constitute a "Substantial
21//! Set" of the Software's features and breach the `VelesDB` Core License 1.0
22//! (§1, No Hosted or Managed Service). See `VISION.md` §5 and `PLAN.md` Phase 4A.
23
24pub mod embedder;
25pub mod error;
26pub mod extract;
27/// Vector+graph score fusion — the ranking layer behind
28/// [`service::MemoryService::recall_fused`]. Internal: callers reach it only
29/// through that method.
30mod fusion;
31/// Content-addressed memory ids — internal; ids surface through the service API.
32pub(crate) mod id;
33/// Resource caps (DoS limits) shared by every adapter — the single source of
34/// truth for fact size, recall limit, and `why` hop depth.
35pub mod limits;
36/// The MCP server transport. Gated behind the default `mcp` feature so library
37/// consumers (e.g. the language bindings) can depend on the memory core without
38/// pulling the `rmcp`/`tokio` server stack.
39#[cfg(feature = "mcp")]
40pub mod mcp;
41/// The domain data model — the value types the memory layer exchanges
42/// (`Link`, `Recollection`, `ColumnFilter`, `Explanation`, …), separate from the
43/// service that computes them.
44pub mod model;
45/// Optional second-stage re-scoring of a fused recall pool (bring your own
46/// cross-encoder/LLM). Never wired in by default — see [`rerank::Reranker`].
47pub mod rerank;
48/// Shared JSON Schema post-processing (strips `schemars`' non-standard integer
49/// `format` keywords so strict MCP clients don't warn on every id field).
50mod schema;
51pub mod service;
52/// The storage backend abstraction — [`storage::MemoryStore`] and the
53/// default, file-backed [`storage::NativeStore`]. Implement `MemoryStore` to
54/// run the wedge over a different backend (e.g. an in-memory one for WASM).
55pub mod storage;
56
57/// Default embedding dimension — the single source of truth, taken from the
58/// SDK's own default so the server, library, and tests never restate the
59/// value. `velesdb_core::agent` (where the canonical constant lives) is
60/// itself `persistence`-gated, so a `persistence`-free build (e.g.
61/// `velesdb-wasm`) falls back to [`FALLBACK_DIMENSION`].
62#[cfg(feature = "persistence")]
63pub const DEFAULT_DIMENSION: usize = velesdb_core::agent::DEFAULT_DIMENSION;
64#[cfg(not(feature = "persistence"))]
65pub const DEFAULT_DIMENSION: usize = FALLBACK_DIMENSION;
66
67/// The hand-written value the `persistence`-free arm of
68/// [`DEFAULT_DIMENSION`] falls back to (the canonical constant's module is
69/// feature-gated away there). The `persistence` build — CI's default —
70/// statically asserts it still equals the canonical value, so drift fails
71/// to compile instead of silently splitting the wasm default dimension
72/// from the native one.
73const FALLBACK_DIMENSION: usize = 384;
74#[cfg(feature = "persistence")]
75const _: () = assert!(
76    FALLBACK_DIMENSION == velesdb_core::agent::DEFAULT_DIMENSION,
77    "update FALLBACK_DIMENSION to match velesdb_core::agent::DEFAULT_DIMENSION"
78);
79
80pub use embedder::{DynEmbedder, EmbedError, Embedder, HashEmbedder};
81#[cfg(feature = "ollama")]
82pub use embedder::{OllamaEmbedder, DEFAULT_OLLAMA_MODEL, DEFAULT_OLLAMA_URL};
83pub use error::{ErrorCategory, MemoryError};
84#[cfg(feature = "extract")]
85pub use extract::OllamaExtractor;
86pub use extract::{DynExtractor, ExtractError, ExtractedFact, Extractor};
87#[cfg(feature = "mcp")]
88pub use mcp::McpServer;
89pub use model::{
90    ColumnFilter, ColumnOp, Explanation, FusionOptions, Link, MemoryEdge, MemoryNode, Recollection,
91};
92pub use rerank::{DynReranker, RerankError, Reranker};
93pub use service::{MemoryService, Metadata};
94pub use storage::MemoryStore;
95#[cfg(feature = "persistence")]
96pub use storage::NativeStore;
velesdb_memory/lib.rs

velesdb_memory/
lib.rs
