Glossary

Short definitions of the terms Engrava uses, each linking to the page that explains it in depth. New to Engrava? Read Core Concepts first — this page is a quick reference, not a tutorial.

Thought

The unit of memory — one idea, fact, observation, or message, stored as a frozen (immutable) ThoughtRecord. You don’t mutate a thought in place; you create_thought() it and update_thought() to get a new version. See Core Concepts → Thought.

Essence

The compact, canonical, prompt-facing one-liner of a thought (1–200 characters, enforced) — the text you inject into an LLM prompt when the memory is retrieved. Think headline. See Core Concepts → essence vs content.

Content

The full source text of a thought, retained for full-text search and provenance. Think article (to the essence’s headline). See Core Concepts → essence vs content.

Edge

A typed, weighted, directional link between two thoughts — what makes Engrava a graph rather than a flat table. The EdgeType set is ASSOCIATED, DEPENDS_ON, DERIVED_FROM, MESSAGE_OF, BRIDGE, CONSOLIDATED_FROM, and CONTESTED_BY; weight (0.0–1.0) expresses how strong the relation is. See Core Concepts → Edge.

Embedding

The vector representation of a thought that powers semantic (meaning-based) search. Embeddings are optional — without a provider or an explicit query_vector, vector retrieval is skipped and search falls back to the lexical (FTS5) index; a caller-supplied query_vector still activates vector retrieval without a provider. See the Embeddings guide.

Reflection

A higher-order summary thought (ThoughtType.REFLECTION). A reflection that dreaming creates is centroid-embedded and carries lineage edges: Engrava clusters semantically related thoughts and writes a centroid-embedded summary node, linked back to its members by CONSOLIDATED_FROM edges. Callers may also create a REFLECTION thought directly; generic creation does not require an embedding or a lineage edge. See Core Concepts → Reflection and Dreaming.

Dreaming

The periodic, off-the-hot-path consolidation process you invoke with run_consolidation(): it evaluates eligible candidates and may promote important ones, link related ones with edges, and cluster them into reflections when the corresponding gates, thresholds, caps, embeddings, and feature settings permit. Built-in dreaming involves no LLM and its synthesis is purely structural; a caller-supplied DreamingSignalProtocol implementation is your code and may call one. See Dreaming.

Consolidation

Another name for what dreaming does in a single pass — evaluating candidates and conditionally producing promotions, edges, and reflections via run_consolidation(). See Dreaming.

Forgetting

The subtractive counterpart to dreaming — the two halves of memory maintenance. An opt-in loop (mechanism: Memory Hygiene) that lets cold, low-signal thoughts fade by archiving them — the default action, and reversible — and, as a separately opted-in step, garbage-collects archived rows after cycle + wall-clock restore windows; garbage collection is destructive and is not reversible through lifecycle transitions. Built-in scoring and the default hooks make no LLM calls; a configured on_retrieve or decay_function hook may itself call an LLM or other external service. OFF by default. See Forgetting (Memory Hygiene).

Memory Hygiene

The mechanism name for Forgetting: the run_hygiene() loop configured under hygiene_policy. Passing a fixed now fixes the inactivity, archive-stamp, and GC-window boundaries for a given store, configuration, and cycle, but candidate expiry filtering still reads real wall time on every page of the underlying scan, so a fixed now alone does not guarantee identical candidate selection across two runs. “Forgetting” is the public concept, “Memory Hygiene” is the mechanism, and hygiene is the API name — the same concept-over-mechanism layering as Dreaming over consolidate(). See Forgetting (Memory Hygiene).

Promotion

The act, during consolidation, of marking an important thought by setting its priority to P1. With a positive priority weight, P1 gives an already-retrieved candidate the largest priority boost in hybrid search — priority does not itself add a thought to the candidate set. Whether a candidate is promoted depends on the gates and the promote_threshold. See Dreaming.

Cycle

A logical clock — a monotonically increasing integer tick that you own and advance (typically one cycle per agent turn). It is not wall-clock time and not a stored row; Engrava never increments it for you. It drives the recency signal and dreaming’s age gates. With no explicit recency reference and no configured cycle provider, recency is inactive; an explicit recency_now instead selects transaction-time recency. Freezing a cognitive cycle at a constant makes that axis useless: it stops cycle-based age and recency from advancing and may stop cadence-based run_if_due() calls from becoming due, though a direct consolidation call can still execute and mutate memory. See Core Concepts → Cycle.

Valid time

One of Engrava’s three time axes: when a fact is true in the world, as opposed to transaction time (when Engrava recorded it — created_at / updated_at) and the consumer-owned cognitive cycle. Valid time is carried by two optional, nullable ISO-8601 fields, valid_from and valid_until, on both ThoughtRecord and EdgeRecord. They describe a half-open interval (valid_until is exclusive); a None bound means open (±∞) for the NULL-tolerant predicates valid_now, valid_at, and valid_within, so an un-annotated record is “valid for all time” under those — valid_between is the exception: it requires a real (non-None) value on both stored bounds and excludes a record where either is open. Queried through the valid_now / valid_at / valid_within / valid_between MindQL predicates. See The Bi-temporal Model.

Transaction time

When Engrava recorded or last changed a fact — the created_at / updated_at bookkeeping timestamps Engrava supplies when you omit them. Callers may also supply or update these timestamps explicitly, and nothing enforces that updated_at moves forward; contrast with valid time (the real-world axis you set) and the cycle (the logical agent clock). See The Bi-temporal Model.

Signal

One scoring component that hybrid search computes for a candidate and fuses into the final rank. Engrava has five: FTS5 keyword, vector similarity, recency, priority, and graph. A signal whose prerequisite is missing (e.g. no embeddings) is skipped rather than erroring. See Search.

Gate

A cheap boolean check in dreaming that a candidate must pass to be promoted — e.g. min_age_cycles (the thought must be old enough) and the confirmation gate; dreaming scores a candidate before checking its gates, so failing a gate blocks promotion, not scoring. Gates filter out clearly ineligible thoughts. See Dreaming → Gates.

Priority

A thought’s importance level, P1 (highest) to P4 (lowest). It is one of the hybrid-search signals: when priority weighting is enabled and positive, higher priority increases the score of an already-retrieved candidate; dreaming promotes thoughts to P1. See Core Concepts → Priority.

Lifecycle

The small state machine a thought moves through (evolve() enforces transitions when given a LifecycleStatus member; a plain string skips that check): CREATED → ACTIVE, ACTIVE → DONE, ACTIVE → ARCHIVED, DONE → ARCHIVED, and ARCHIVED → ACTIVE; a caller may also construct a record with an initial lifecycle value directly rather than starting at CREATED. ARCHIVED is a soft-retired state — the row and its content remain until garbage-collected, but an archived thought is excluded from default ranked retrieval (reversible via restore_thought / include_archived). See Core Concepts → Lifecycle and Data Lifecycle.

Provenance

Where a memory came from. source is a free-form identifier and source_type is the KnowledgeSource enum. The optional, typed ProvenanceContext records caller-supplied write-time context such as session, actor, retrieval query, and retrieved thought ids. These values are untrusted lineage hints, not identity, authorization, or proof that a claim is true. Semantic evidence and the hash-chain mutation journal are separate provenance layers. See Core Concepts → Provenance and Evidence and conflicts.

Conflict

A caller-detected tension between claims. Engrava lets incompatible thoughts coexist and provides the directional CONTESTED_BY edge label, valid-time bounds, metadata, and provenance needed to represent the tension. It does not resolve entities, infer a contradiction, choose the true claim, or create a clarification task. See Evidence and conflicts.

Confirmation

confirmation_count — a counter that increments on each deduplication hash hit (via deduplicate=True) or your own logic; Engrava does not establish that a hit is an independent re-encounter. Distinct from confidence, a caller-assigned belief-strength field that may be supplied at creation and changed later — it is not static. Dreaming reads them as separate signals. See Core Concepts → confidence vs confirmation_count.

Visibility

ThoughtVisibility — whether a thought may surface in the agent’s outer speech: private (internal only), selective (shared on request — the default), or public (may appear in output). Engrava stores the level; honouring it is your application’s responsibility. See Core Concepts → Visibility.

search_hybrid() — retrieval that fuses up to five signals (FTS5 keyword, vector, recency, priority, graph) into one ranked result, rather than relying on vector similarity alone. See Search.

Graph signal

The fifth hybrid-search signal: a 1-hop-weighted neighbour boost where a candidate gains score if its graph neighbours also match the query. The graph-ranking signal is disabled by default (default_graph_weight = 0.0), but graph expansion — which follows CONSOLIDATED_FROM edges to widen the candidate pool — is enabled by default and runs whenever a top-ranked REFLECTION candidate is present in the fused pool. See Search.

Percept

In the agent loop, an incoming observation (e.g. a user message) stored as an OBSERVATION thought, typically tagged with the percept(...) helper. It is what the agent takes in. See Building a memory-backed agent.

Utterance

In the agent loop, the agent’s own outgoing reply, typically stored as an OUTPUT_DRAFT thought. It is what the agent produces. See Building a memory-backed agent.

For the exhaustive package reference, see the OSS glossary.md docs.