VelesDB Memory

Compile context fragments into a token-budgeted, provenance-audited prompt context — deterministic, no LLM call. Duplicates drop, repeated log lines collapse, code/URLs/numbers/negative constraints survive verbatim, over-budget content becomes retrievable ctx://source/ handles; `memory_scope` pulls stored memories in. Fragment `metadata` ≤64 KiB. A fragment may set `path` (absolute file, UTF-8 ≤1 MiB; requires VELESDB_MEMORY_INGEST_ROOTS) INSTEAD of `content` — `content`+`media` may combine (content = the image's caption). Returns the assembled content, one auditable decision per fragment (rule id, reason, risk), sources, handles, token-savings, and `warnings` (externalized fragments worth a second look — empty is NOT a clean bill of health; `decisions` is the exhaustive record, `risk` the cheap second signal). `policy.slim_response` drops sections/decisions (keep off when the audit trail matters); `policy.ids_as_strings` stringifies id fields for u64-unsafe clients.

One-call shortcut over compile_context for a raw agent-session transcript: segments it into turns (markers System:/User:/Human:/Assistant:/AI:/Tool:, ### User/### Assistant, or JSONL one line per turn) then into code/log/body sub-segments, then compiles exactly like compile_context. Exactly one of `transcript` (inline) or `path` (absolute file under the VELESDB_MEMORY_INGEST_ROOTS allowlist, ≤8 MiB) must be set. `segmentation.format` forces plain/jsonl — a forced jsonl that fails to parse is a hard error. The first turn is tagged cache-eligible when it looks like a system prompt (segmentation.cache_system_turn, default true). Returns `context` (byte-compatible with compile_context) plus `segmentation`: the detected format and a per-segment audit (turn, role, kind, byte range, fragment_id).

Aggregate the token (and cost) savings of past compile_context calls, optionally per project. Figures are local estimates recorded per compilation (metadata only, never content); `truncated` reports when the sweep hit the recall cap.

Look up a NAMED ENTITY (person, place, organisation): its attributes, outgoing (`relations`) and incoming (`relations_in`) typed edges — both directions, since a question is only answerable from one side. Use for questions ABOUT a thing ("how old is Theo", "who is Theo's father"), where `recall` only returns sentences mentioning the name. Entities/edges are auto-built by `remember_extracted` from text relationships (`X is the father of Y`) and properties (`Y is 15`), JSON types preserved. Name match is case-insensitive; the id is content-addressed, stable across sessions. `found: false` when never mentioned; `name` echoes canonicalized. Autograph edges land asynchronously. Relay ids as strings (`id_str`).

Explain why one fragment of a compile_context request was preserved, abstracted, externalized, dropped, or cached: the request is re-compiled deterministically (recording off) and the fragment's decision (rule id, reason, relevance, risk, handle) returned — no server state needed. Caveats: `memory_scope` recalls from CURRENT memory and a `path` fragment is re-read from CURRENT disk content — not necessarily what the original call saw. Prefer `fragment_index` (0-based) over `fragment_id` when fragments are byte-identical — a shared id resolves to the dedup survivor's decision. `policy.ids_as_strings` applies as in compile_context.

Read one durable extraction job by the `request_id` returned from `remember_extracted`. Returns that `request_id`, its persisted `state` (`accepted`, `running`, `committed`, or `failed`), committed fact `ids` and their u64-safe decimal `ids_str` twins, `skipped_over_cap` after commit, and `error` after failure. While accepted/running, `ids` and `ids_str` are empty and both optional terminal fields are null.

Reinforce a recalled memory with an outcome: `success=true` if the fact was useful, `false` if it was noise. This durably updates the fact's learned confidence, which `recall` uses to re-rank future results — over repeated feedback, useful facts drift up and noise drifts down, so the memory improves with use without retraining the model. Concurrent feedback on one fact is applied atomically, each call counted once. Returns the fact's new confidence in [0,1].

Permanently delete a memory by `id`, removing the fact and its graph links — durable, irreversible. For time-based expiry use `remember`'s TTL instead. Returns the id plus `found`: true = deleted, false = nothing stored under that id (no-op, not an error).

AUDIT the store: page through every stored fact — what `recall` cannot answer (it only ranks by resemblance). Use for 'what do you know about me/this project?', cleanup before sharing, or backup. Returns `memories` (ids ascending; each entry carries `id`, `id_str`, `content`, `metadata`) and `next_cursor`: pass it as `cursor` for the next page, null = done. `filter` keeps facts matching every key; a sparse page is not the end — KEEP following `next_cursor`. `include_internal` also lists internal scaffolding verbatim. Ids exceed 2^53 — relay as strings.

List every session saved under a project via save_working_context, most-recently-saved first — so an agent can discover what is resumable before guessing a session id at load_working_context, or recover from a typo. Empty (not an error) when the project never saved anything.

Resume a session: load the working context saved by save_working_context under the same project + session id. Call at session START. `found: false` (`working: null`) = nothing saved under that exact id — check `other_sessions`: a similar name means a typo, not a fresh start. `other_sessions` is filled on a hit too — a likelier session listed means you may have resumed the WRONG one. `list_working_contexts` browses a project's sessions up front.

Report server health/config: running embedder and whether recall is SEMANTIC (`embedder.semantic: false` = offline hash — surface matching, not meaning; semantic is an env-var switch, no rebuild), embedder provenance of the store, whether a default extractor is configured (`extraction.configured` lets `remember_extracted` omit `extractor`), autograph worker status, dropped/failed enrichment counts (fact stored, graph partial — re-remember to complete), corpus size (`memory.facts`, `memory.edges`). `edges: 0` means `why` has no graph to walk and degrades to plain search — a wiring gap, not a defect. Call at session start, or when recall quality or `why`'s trails surprise — and tell the user when the server runs degraded. No parameters.

Durably request cancellation while the source remains authoritative. A running worker observes the request at its next bounded batch; a paused job is cancelled immediately. From quiescing onward cancellation refuses and reports the required recovery action instead of guessing a rollback.

Resume a durable prepared, capturing, base-copied, catching-up, non-converging or cutover-ready job after verifying the environment-backed target model, dimension and vector witness. Quiescing or activated jobs refuse here until crash-safe cutover recovery has restored a single authoritative generation.

Start one daemon-owned online embedding migration in the background. The existing MCP transport remains the only control boundary; no listener or credential is persisted. `target_backend` selects a backend configured in this daemon's environment. `pause_budget_ms` is the maximum measured request pause. Returns immediately with durable job status; poll migration_status. Refuses a pre-existing destination or another non-terminal epoch.

Read the durable online embedding migration phase, progress watermarks, convergence estimate, measured cutover, cancellation flag, last error and required recovery action. Returns immediately and performs no migration work.

Recall memories semantically similar to a query (vector). Ranking blends similarity with each fact's learned confidence (see `feedback`); the returned `score` is the raw similarity, never the blended value. `filter` narrows by exact-match metadata, e.g. {"project":"veles","status":"resolved"}. With `anchor_root` (an absolute checkout inside the server's ingest roots), each fact remembered with `anchors` carries `freshness` — `fresh`, `stale` (an anchored file changed or was deleted; listed in `changed`, and the fact is ranked lower) or `unverified`; staleness never changes the learned confidence. Ids exceed 2^53 — relay them as strings (`id_str`).

Fused vector + graph recall: like `recall`, plus walks the graph from the top hit and folds connected facts into the ranking — for answers needing a fact the query doesn't name (multi-hop reasoning, temporal chains). `hops`/`graph_boost` tune graph reach, `pool` the vector candidate depth; omit for the proven defaults. Optional exact-match `filter`; set `date_field` (a YYYYMMDD metadata key) for a `dated_context` timeline and `now` anchor. Most relevant first.

Vector recall constrained by ColumnStore metadata predicates: each filter is {field, op (eq/ne/lt/le/gt/ge), value}, ANDed — for time-windowed or numeric-scoped recall (e.g. `ts` in a date range). Comparisons are type-strict, no runtime coercion: a numeric filter never matches a string-stored value — store comparable values like dates numerically at `remember` time (20230601, not "20230601"). Most similar first. Returns caller memories only: internal scaffolding (entity hubs, compiler artefacts, working contexts) never comes back, even under `ne` (which otherwise matches facts lacking the field).

Create a typed directional edge `from` -`relation`-> `to` between two memories; `why`/`recall_fused` traverse OUTGOING edges only, so point `from` at the memory you will later question and `to` at its evidence (decision → cause, fact → source) — an edge pointing INTO a memory is invisible to `why(that memory)`. Idempotent per (from, relation, to); `from` == `to` is refused. Returns `edge_id`/`edge_id_str` — ids exceed 2^53, relay them as strings.

Store a fact in durable local memory; optional `links` (graph edges) and `metadata` tags (ColumnStore, ≤64 KiB serialized) for later filtering. Facts are capped at 2048 bytes — a longer one is REFUSED with its size; split it into atomic facts, or `compile_context` it and remember a summary. `ttl_seconds` sets a durable expiry (omit = permanent; 0 is refused). Optional `anchors` (repo-relative paths, ≤8) with `anchor_root` (an absolute checkout inside the server's ingest roots) tie the fact to those files: the server records each file's SHA-256 so a later `recall` can flag the fact stale when one changes; re-remember with `anchors` to re-anchor. Returns the fact's stable id — relay it as a string (`id_str`): ids exceed 2^53. With the async autograph worker, derived edges land asynchronously; the fact itself is immediately readable.

Accept a passage for durable background extraction; returns before model generation. `extractor` per call (`outline`/`ollama`/`openai`), else VELESDB_MEMORY_EXTRACTOR. `idempotency_key` makes a retry reuse one job; same key with a changed payload is rejected. The receipt returns `request_id`, initial `state` (`accepted`, or the reused request's persisted state) and `reused`. Poll `extraction_status(request_id)` until `committed`/`failed`; accepted/running jobs survive restart.

Fetch back the exact original content behind a `ctx://source/<hash>` handle from a compiled context — what compile_context externalized or partially packed is recoverable, not lost.

Persist this session's distilled working state (goal, constraints, verified facts, hypotheses, decisions, evidence, pending actions) under a project + session id — so a LATER session resumes instead of re-deriving. Call near session end, or on meaningful change. Same project+session = idempotent upsert; an empty `working` is REFUSED (it would wipe a previous save). ≤1 MiB. Returns the fact's id. ON TIMEOUT, THE SAVE MAY NOT HAVE HAPPENED — check `list_working_contexts` for an advanced `saved_at`, then re-send if needed (upsert = safe).

Suggest a starting token_budget for compile_context for a named model — looked up in a static, committed model→context-window table (never a network call). `reserve_tokens` reserves room for the response, mirroring `policy.response_reserve_tokens`. `window`/`suggested_budget` come back null for an unlisted model — an honest "unknown", never a guess.

Remove the edge `from` -`relation`-> `to` — `relate`'s undo; the two memories are untouched. Idempotent: an absent edge answers `found: false` rather than erroring; `removed` counts actual deletions. Refuses what `relate` refuses (empty relation, `from` == `to`). Removes auto-derived edges alike, but re-remembering the source fact can rebuild them — to correct one prefer `forget` + `remember`. Pass ids as decimal strings (>2^53).

Explain a decision: find the best-matching memory (optionally scoped by a metadata `filter`, e.g. the current project) and return the connected subgraph of related memories reachable through typed links — fusing vector, ColumnStore, and graph to surface context a plain similarity search misses.