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 nine 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//! | `recall_where`      | semantic retrieval filtered by metadata            |
13//! | `recall_fused`      | vector + graph fused retrieval                     |
14//! | `relate`            | create a typed edge between two memories           |
15//! | `forget`            | delete a memory                                    |
16//! | `why`               | recall + multi-hop graph traversal                 |
17//! | `feedback`          | reinforce or penalize a memory after use           |
18//! | `remember_extracted`| extract facts from raw text and auto-wire the graph|
19//!
20//! ## License boundary (non-negotiable)
21//!
22//! This crate exposes **memory semantics only** (results), never raw database
23//! capabilities (`query(velesql)`, `create_collection`, `upsert(vectors)`,
24//! `traverse(graph)`). Exposing the raw engine would constitute a "Substantial
25//! Set" of the Software's features and breach the `VelesDB` Core License 1.0
26//! (§1, No Hosted or Managed Service). See `VISION.md` §5 and `PLAN.md` Phase 4A.
27
28/// Wall-clock "today" as a `YYYYMMDD` integer, read only by `remember`'s
29/// auto-date stamping (see [`storage::AUTO_DATE_FIELD`]) — never by the
30/// context compiler, which stays clock-free and deterministic. Internal:
31/// nothing outside the crate needs to read the clock directly.
32mod clock;
33/// The optional TOML configuration file: one place to set every knob, with
34/// `command line > environment > file > default` precedence. Native-only —
35/// it reads the filesystem.
36#[cfg(not(target_arch = "wasm32"))]
37pub mod config;
38/// The deterministic context compiler (EPIC-P-070): classify, dedup, and pack
39/// caller-supplied context fragments under a token budget — no LLM, no cloud,
40/// every decision auditable. Gated behind the default `context` feature.
41#[cfg(feature = "context")]
42pub mod context;
43/// Format recalled facts as a chronological, date-prefixed timeline with a
44/// "now" anchor — the dated-context representation measured to lift temporal
45/// question answering, shipped as product behavior rather than a harness prompt.
46pub mod dated_context;
47pub mod embedder;
48pub mod error;
49pub mod extract;
50/// Vector+graph score fusion — the ranking layer behind
51/// [`service::MemoryService::recall_fused`]. Internal: callers reach it only
52/// through that method.
53mod fusion;
54/// The streamable-HTTP transport (multi-client mode): lets several MCP
55/// clients share ONE `velesdb-memory` process instead of each spawning its
56/// own stdio process and fighting over the store's single-writer `flock`.
57/// Gated behind the (non-default) `http` feature — see the module docs and
58/// the crate README's "HTTP transport (multi-client)" section.
59#[cfg(feature = "http")]
60pub mod http;
61/// Content-addressed memory ids — internal; ids surface through the service API.
62pub(crate) mod id;
63/// Resource caps (DoS limits) shared by every adapter — the single source of
64/// truth for fact size, recall limit, and `why` hop depth.
65pub mod limits;
66/// The MCP server transport. Gated behind the default `mcp` feature so library
67/// consumers (e.g. the language bindings) can depend on the memory core without
68/// pulling the `rmcp`/`tokio` server stack.
69#[cfg(feature = "mcp")]
70pub mod mcp;
71/// The domain data model — the value types the memory layer exchanges
72/// (`Link`, `Recollection`, `ColumnFilter`, `Explanation`, …), separate from the
73/// service that computes them.
74pub mod model;
75/// Synchronous retry + actionable failure reporting shared by the two blocking
76/// Ollama call sites ([`embedder`] and [`extract`]). Internal: it exists to make
77/// those two backends resilient, not to be a general-purpose retry API.
78#[cfg(any(feature = "ollama", feature = "extract"))]
79mod ollama_retry;
80/// Optional second-stage re-scoring of a fused recall pool (bring your own
81/// cross-encoder/LLM). Never wired in by default — see [`rerank::Reranker`].
82pub mod rerank;
83/// Shared JSON Schema post-processing (strips `schemars`' non-standard integer
84/// `format` keywords so strict MCP clients don't warn on every id field).
85mod schema;
86pub mod service;
87/// The storage backend abstraction — [`storage::MemoryStore`] and the
88/// default, file-backed [`storage::NativeStore`]. Implement `MemoryStore` to
89/// run the wedge over a different backend (e.g. an in-memory one for WASM).
90pub mod storage;
91/// Locally-generated TLS material (a cached self-signed CA + short-lived
92/// leaf certs) for the streamable-HTTP transport's HTTPS-by-default
93/// listener — see the module docs for the full design rationale. Gated
94/// behind `http` since it exists only to serve that transport.
95#[cfg(feature = "http")]
96pub mod tls;
97
98/// Default embedding dimension — the single source of truth, taken from the
99/// SDK's own default so the server, library, and tests never restate the
100/// value. `velesdb_core::agent` (where the canonical constant lives) is
101/// itself `persistence`-gated, so a `persistence`-free build (e.g.
102/// `velesdb-wasm`) falls back to `FALLBACK_DIMENSION`.
103#[cfg(feature = "persistence")]
104pub const DEFAULT_DIMENSION: usize = velesdb_core::agent::DEFAULT_DIMENSION;
105#[cfg(not(feature = "persistence"))]
106pub const DEFAULT_DIMENSION: usize = FALLBACK_DIMENSION;
107
108/// The hand-written value the `persistence`-free arm of
109/// [`DEFAULT_DIMENSION`] falls back to (the canonical constant's module is
110/// feature-gated away there). The `persistence` build — CI's default —
111/// statically asserts it still equals the canonical value, so drift fails
112/// to compile instead of silently splitting the wasm default dimension
113/// from the native one.
114const FALLBACK_DIMENSION: usize = 384;
115#[cfg(feature = "persistence")]
116const _: () = assert!(
117    FALLBACK_DIMENSION == velesdb_core::agent::DEFAULT_DIMENSION,
118    "update FALLBACK_DIMENSION to match velesdb_core::agent::DEFAULT_DIMENSION"
119);
120
121#[cfg(feature = "context")]
122pub use context::ContextCompiler;
123pub use dated_context::{format_dated_context, DatedContext};
124pub use embedder::{DynEmbedder, EmbedError, Embedder, HashEmbedder};
125#[cfg(feature = "ollama")]
126pub use embedder::{OllamaEmbedder, DEFAULT_OLLAMA_MODEL, DEFAULT_OLLAMA_URL};
127pub use error::{ErrorCategory, MemoryError};
128#[cfg(feature = "extract")]
129pub use extract::OllamaExtractor;
130pub use extract::{
131    DynExtractor, ExtractError, ExtractedAttribute, ExtractedFact, ExtractedRelation, Extraction,
132    Extractor,
133};
134#[cfg(feature = "mcp")]
135pub use mcp::McpServer;
136pub use model::{
137    ColumnFilter, ColumnOp, EntityProfile, EntityRelation, Explanation, FusionOptions, Link,
138    MemoryEdge, MemoryNode, Recollection,
139};
140pub use rerank::{DynReranker, RerankError, Reranker};
141pub use service::{MemoryService, Metadata};
142#[cfg(feature = "persistence")]
143pub use storage::NativeStore;
144pub use storage::{MemoryStore, AUTO_DATE_FIELD};
velesdb_memory/lib.rs

velesdb_memory/
lib.rs
