Spectron’s architecture is described by eight pillars of agent memory and by six experiential memory categories (episodic turns plus identity, knowledge, context, instructions, uncertainty). Curated documents and conversational memory are Authoritative versus Experiential pillars – both are records in the same SurrealDB graph. See Eight pillars and six categories and Unified substrate and authority.
Attribute
A key-value property on an entity, representing a learned or asserted fact. Attributes are versioned: when a value changes, the old attribute is superseded (not deleted) and a new one is created, forming a supersession chain. Attributes carry valid_from and valid_until timestamps for temporal queries.
Authoritative precedence
The precedence rule: Authoritative (curated) content takes precedence over Experiential assertions when they conflict. Disagreements are surfaced via uncertainty records and conflict indicators in state/profile responses — curated records are not silently overwritten. See Authority when pillars meet.
BM25
A keyword-based full-text ranking algorithm used in Spectron's hybrid retrieval. BM25 complements vector search by finding exact-keyword matches that semantic search might miss.
Context
The unit of memory storage and configuration isolation in Spectron. Each Context is bound to a SurrealDB (namespace, database) pair and has its own API keys, model configuration, ontology, and data. Contexts cannot see each other's data. See Contexts and scope.
Decision trace
A decision_trace node records reconciliation outcomes: candidates considered, records created or superseded, confidence and trust, and links to parent traces. Ranked reads emit retrieval_trace; /chat and /reflect emit response_trace. Together they form the graph-resident audit model described in Traces and memory evolution.
Dimensional scope
A set of key-value tags (e.g. {org: "acme", user: "alice"}) that partitions data within a Context. Every piece of data in Spectron carries a scope, and queries filter by scope using subset matching semantics. See Contexts and scope.
Entity
A thing being tracked in experiential memory – a person, company, product, location, or other named object. Entities are identified by a (type, normalised_name) pair and carry attributes and relations. Entities can resolve to knowledge nodes via resolves_to.
Extraction pipeline
The multi-stage process that converts conversational turns into structured experiential records. It operates in three stages: pattern matching (Stage 0), fast LLM (Stage 1), and strong LLM (Stage 2). The pipeline produces entities, attributes, relations, instructions, uncertainties, and invalidations.
Hybrid retrieval
A query mode that combines vector similarity (semantic) and BM25 (keyword) results using Reciprocal Rank Fusion (RRF). The hybrid_graph mode adds keyword graph density and typed knowledge graph scores to the fusion for improved precision.
Instruction
A behavioural directive for the agent, stored separately from factual memory. Instructions are first-class records with active status and can be created, updated, and deactivated. They are included in profile responses and injected into the agent's system context.
Authoritative pillar (curated knowledge)
The Authoritative pillar covers curated artefacts (source.kind = "document", operator upsert): documents, policies, product data, FAQs, structured exports. Higher default trust. Same SurrealDB substrate as experiential records.
Experiential pillar (conversational memory)
The Experiential pillar covers conversational input and derived facts (turn, reflect, elaboration, consolidation, …). It includes the six memory categories: episodic session/turn data plus identity, knowledge, context, instructions, and uncertainty.
MCP (Model Context Protocol)
An open protocol for connecting AI agents to tools and data sources. Spectron exposes an MCP server at /mcp with seven high-level tools for memory and knowledge operations.
Memory category
A classification for experiential data (plus the raw episodic record): identity, knowledge, context, instructions, and uncertainty records, alongside the session/turn stream itself. Instructions and uncertainty use dedicated tables/paths. See Memory categories.
Ontology
An optional per-Context configuration that constrains entity types, attribute keys, and relation labels. When an ontology is configured, the extraction pipeline only creates entities and attributes that conform to the declared types, preventing unbounded schema growth.
Principal
The type of API key making a request. Spectron supports three principal types: management (full control-plane access), agent (read/write within a scope floor), and supervisor (can persist reflections at the supervisor's own scope floor).
Profile
A structured snapshot of the current memory state for a given scope. A profile aggregates identity facts, dynamic context, preferences, and active instructions into a format suitable for injection into an agent's system prompt.
Provenance
The ability to trace every record back to its source (turn, document, or trace). Records carry a structured source object (kind, ref, span, trust, derived_from, …). Some examples use source_turn as shorthand for conversational source.ref. See Provenance and traceability.
Reconciliation
The Reconciliation pillar: integrating newly extracted information with existing beliefs – deduplication, supersession, scope coexistence, and Authoritative precedence. See Eight pillars and six categories.
Reflection
The Reflection pillar: on-demand synthesis (POST /reflect). Insights can be transient or persisted with source.kind = "reflect".
Relation
A typed edge between two entities, representing a fact about their connection. Relations carry a label (e.g. works_at, relocated_to) and temporal validity timestamps.
resolves_to
A link from an experiential-memory entity to a knowledge node under the Authoritative pillar. When set, the agent can combine conversational context with curated facts for the same real-world thing.
Scope floor
The minimum scope dimensions that an API key must include in its requests. A key with scope floor {org: "acme"} cannot make requests at scope {org: "beta"}. The server enforces this at the query level.
Semantic response cache
A per-Context cache keyed on the embedding of the query string. Before falling through to full retrieval, Spectron checks whether a semantically similar query has been answered recently and returns the cached result if the similarity exceeds the threshold.
Session
A first-class conversation record in Spectron. Sessions group turns together and provide the scope context for all memory extracted from those turns. Sessions are durable records – they persist after the conversation ends and can be recalled, diffed, and reflected upon.
Supersession
The versioned replacement of an attribute value. When new information contradicts a stored attribute, the old record is marked with superseded_by and valid_until, and a new record is created with supersedes and valid_from. Both remain in the database, forming a correction history.
Turn
A single message in a session, with a role (user, assistant, system, or tool) and content. Turns are the input to the extraction pipeline and the provenance anchor for all memory produced from them.
Uncertainty
Explicit records for gaps and clashes – part of the Experiential pillar’s six categories and central to the Reconciliation pillar when confidence is insufficient or provenances disagree.
valid_from / valid_until
Temporal validity fields on attributes and relations. valid_from records when a fact became true; valid_until records when it ceased to be true. These fields enable point-in-time queries and historical analysis without deleting old data.