Enum MemoryError 

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),
    InvalidFilter(String),
    InvalidRelation(String),
    ContextBudget {
        budget: u64,
        reserve: u64,
    },
    ContextOverLimit(String),
    SegmentationError(String),
    UnknownHandle(String),
    FragmentIndexOutOfBounds {
        index: usize,
        len: usize,
    },
    FragmentNotFound(u64),
    EmptyWorkingContext,
    WorkingContextCodec(String),
    IngestDisabled,
    IngestOutsideRoots(String),
    IngestPath(String),
    RollbackFailed {
        cause: Box<MemoryError>,
        rollback: Box<MemoryError>,
    },
}

Errors returned by crate::service::MemoryService.

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.

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(String)

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

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 (exactly one of path, content, media is accepted), 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.