Enum MemoryError 

#[non_exhaustive]
pub enum MemoryError {
    Storage(Error),
    Memory(AgentMemoryError),
    EmptyFact,
    UnknownMemory(u64),
    FactTooLarge {
        bytes: usize,
        max: usize,
    },
    ZeroTtl,
    SelfRelation(u64),
    ReservedKey(String),
    MetadataTooLarge {
        bytes: usize,
        max: usize,
    },
    Embed(EmbedError),
    Extract(ExtractError),
    Rerank(RerankError),
    MigrationCapture(String),
    Unsupported(&'static str),
    InvalidFilter(String),
    InvalidRelation(String),
    ContextBudget {
        budget: u64,
        reserve: u64,
    },
    ContextOverLimit(String),
    SegmentationError(String),
    UnknownHandle(String),
    FragmentIndexOutOfBounds {
        index: usize,
        len: usize,
    },
    FragmentNotFound(u64),
    EmptyWorkingContext,
    WorkingContextCodec {
        detail: String,
        source: Option<Box<Error>>,
    },
    IngestDisabled,
    IngestOutsideRoots(String),
    IngestPath(String),
    RollbackFailed {
        cause: Box<MemoryError>,
        rollback: Box<MemoryError>,
    },
}

Errors returned by crate::service::MemoryService.

non_exhaustive: adapters classify through MemoryError::category, never by variant, so new variants must be a non-event downstream — which is also what lets a variant’s payload gain structure one minor release at a time instead of in one breaking batch.

String payloads are a decision here, not a debt

Every adapter consumes this type through MemoryError::category plus Display; no payload is read programmatically outside this crate. So a variant earns a structured payload only when structure is being lost — a source error flattened out of the source() chain, or an in-crate consumer parsing prose — and Self::WorkingContextCodec is the one that qualified (it had both). The others carry prose on purpose: their messages are heterogeneous narratives written for the person reading them (Self::IngestPath additionally cites the requested path and never the canonical one, a security decision its module documents), and forcing one struct template over them would flatten exactly the nuance they exist to deliver. Re-litigating this per variant is what this paragraph is for.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Storage(Error)

Failure in the underlying VelesDB storage engine.

Memory(AgentMemoryError)

Failure in the Agent Memory SDK. Only constructible with the persistence feature (the native, file-backed store) — a persistence-free backend (e.g. velesdb-wasm’s in-memory one) never touches velesdb-core’s agent module, so this variant can’t arise.

EmptyFact

A fact was empty or whitespace-only.

UnknownMemory(u64)

A remember link or a relate endpoint referenced a memory id that does not exist.

FactTooLarge

A fact was longer than crate::limits::MAX_EMBEDDABLE_TEXT_BYTES, the size an embedding model still accepts. Refused BEFORE the embedder is called, so the caller learns the limit and its own size instead of an opaque backend fault (ollama embeddings call failed).

Fields

bytes: usize

The size of the rejected fact, in bytes.

max: usize

The cap that was exceeded (crate::limits::MAX_EMBEDDABLE_TEXT_BYTES).

ZeroTtl

crate::service::MemoryService::remember_with_ttl was given Some(0). An explicit per-call 0 used to be normalised to “no expiry”, i.e. a caller who meant “expire immediately” silently got a permanent fact — the exact opposite intent, with no signal. A TTL supplied as configuration (with_default_ttl, a compile policy’s source_ttl_seconds) still reads 0 as “no TTL policy”: that is a default, not an intent about one fact.

SelfRelation(u64)

crate::service::MemoryService::relate was asked to link a memory to itself. A self-loop states nothing and is traversed by why like any other edge, so it only adds noise to the evidence trail.

ReservedKey(String)

Caller metadata or a recall filter named a reserved key (content or a _veles_-prefixed system key), which callers may not set or filter on. crate::storage::AUTO_DATE_FIELD is the one documented exception: a caller MAY set it (e.g. to date a fact retroactively), so it never raises this error.

MetadataTooLarge

Caller-supplied metadata (on remember/remember_with_ttl or a context-compiler fragment) exceeded crate::limits::MAX_METADATA_BYTES — a DoS guard, since metadata is a keyed lookup facet, not a payload.

Fields

bytes: usize

The serialized size of the rejected metadata, in bytes.

max: usize

The cap that was exceeded (crate::limits::MAX_METADATA_BYTES).

Embed(EmbedError)

Failure producing a text embedding.

Extract(ExtractError)

Failure extracting facts from raw text in crate::service::MemoryService::remember_extracted.

Rerank(RerankError)

Failure reranking a fused-recall candidate pool in crate::service::MemoryService::recall_fused_reranked.

MigrationCapture(String)

The online-migration observer could not durably classify a mutation. The source write has not run when this error is returned.

Unsupported(&'static str)

The storage backend in use does not support the requested operation. A static description, not prose: the set of refusable operations is closed and known at compile time, and adapters display it verbatim.

InvalidFilter(String)

A fused-recall filter referenced a field name that is not a plain identifier, named a reserved key, or carried a non-scalar value.

InvalidRelation(String)

A relation label supplied to crate::service::MemoryService::relate or a crate::model::Link in crate::service::MemoryService::remember was invalid — empty, too long, or contained non-printable characters.

ContextBudget

A context-compile request carried a token budget that cannot hold any context: zero, or not larger than the response reserve the policy keeps aside for the model’s answer.

Fields

budget: u64

The caller-supplied token budget.

reserve: u64

The response reserve the policy subtracts from the budget.

ContextOverLimit(String)

A context-compile request exceeded a resource cap from crate::limits — too many fragments, or one fragment larger than the per-fragment byte ceiling.

SegmentationError(String)

A transcript segmentation request failed because of the transcript’s FORMAT, not its size — e.g. segmentation.format: "jsonl" forced on a line that does not parse as a {role, content} JSON object (see crate::context::segment::segment_transcript). Deliberately distinct from Self::ContextOverLimit (issue #1516, m2): a parsing failure is not a budget/cap breach, so a caller filtering on the error message no longer sees the misleading “over limit” wording for what is really a malformed-input error. Same ErrorCategory::InvalidInput classification as ContextOverLimit (both map to INVALID_PARAMS over MCP) — only the variant, and the message, differ.

UnknownHandle(String)

A ctx://source/<hash> handle was malformed or nothing is stored under it (the source was never stored, expired, or was forgotten).

FragmentIndexOutOfBounds

crate::service::MemoryService::explain_compilation’s fragment_index named a position beyond request.fragments.

Fields

index: usize

The out-of-bounds index the caller supplied.

len: usize

The actual number of fragments in the request.

FragmentNotFound(u64)

crate::service::MemoryService::explain_compilation found no decision matching the requested fragment_id (and no fragment_index was given, or it selected nothing new to check).

EmptyWorkingContext

crate::service::MemoryService::save_working_context was given a WorkingContext with nothing in it. The write is an idempotent upsert, so an empty save would replace — that is, destroy — the rich state already stored under this project and session. The one tool whose whole job is surviving a context loss must not be able to cause one on a call that carries nothing.

WorkingContextCodec

A persisted working context could not be (de)serialized — the stored payload predates or postdates this crate’s schema.

The one String-payload variant that gained structure, because it is the one that had lost some: half its construction sites flattened a serde_json::Error into prose, destroying the source() chain thiserror exists to preserve — and it is also the only variant matched programmatically (the index reader falls back to an empty index on it rather than failing a load). source is None where the corruption is structural (a marker with no body) rather than a codec refusal.

Fields

detail: String

What was being encoded or decoded, and for which slot.

source: Option<Box<Error>>

The codec’s own refusal, when there is one to preserve.

IngestDisabled

A context fragment carried a path (V2b-1 path ingestion) but no filesystem root is configured (VELESDB_MEMORY_INGEST_ROOTS unset or empty) — the tool is always advertised, but ingestion itself is opt-in. Also the fallback the pure compiler core reports when a path fragment reaches it unresolved (e.g. a binding that has no ingest adapter, such as the WASM build): crate::context never performs I/O itself, so an un-cleared path field always means the adapter that should have resolved or rejected it was skipped.

IngestOutsideRoots(String)

A path-referenced fragment resolved (after following symlinks) to a location outside every configured ingest root. Carries the caller-supplied path VERBATIM, never the canonicalized target — the resolved location may be filesystem structure the caller has no business learning about (e.g. that a symlink escapes).

IngestPath(String)

A path-referenced fragment could not be read for any reason other than escaping the ingest roots: a relative path (an MCP server’s working directory is unpredictable, so only absolute paths are accepted), a path that does not exist or is not a plain file (directories are rejected), a path fragment combined with non-empty content or a media payload (path is exclusive, though content and media may travel together), a fragment carrying none of the three, or a file whose bytes are not valid UTF-8.

RollbackFailed

A remember link failed after the fact was stored AND the compensating rollback delete also failed — unlike every other error from remember, the fact remains stored. Both errors are carried so the caller can see why the write failed and why the cleanup couldn’t undo it.

Neither field is #[source] — deliberately: the Display message already embeds both errors, and a source chain would double-print them in chain-style reports (anyhow, miette). Match on the variant to inspect the two errors programmatically.

Fields

cause: Box<MemoryError>

The link failure that triggered the rollback.

rollback: Box<MemoryError>

The storage failure that prevented the rollback delete.

Implementations

impl MemoryError

pub fn category(&self) -> ErrorCategory

Classify this error into a transport-neutral ErrorCategory. Adapters map the category, not the variant, so the client-facing taxonomy stays identical across the MCP server and every binding.

Trait Implementations

impl Debug for MemoryError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for MemoryError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for MemoryError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<AgentMemoryError> for MemoryError

fn from(source: AgentMemoryError) -> Self

Converts to this type from the input type.

impl From<EmbedError> for MemoryError

fn from(source: EmbedError) -> Self

Converts to this type from the input type.

impl From<Error> for MemoryError

fn from(source: CoreError) -> Self

Converts to this type from the input type.

impl From<ExtractError> for MemoryError

fn from(source: ExtractError) -> Self

Converts to this type from the input type.

impl From<RerankError> for MemoryError

fn from(source: RerankError) -> Self

Converts to this type from the input type.