Skip to content

Concepts & Glossary

A quick tour through the vocabulary you will encounter across the semvec docs. None of the entries replace the primary references (whitepaper, patent-pending application) — they give you enough shared language to read the rest of the site confidently.

The name

  • PSS — Persistent Semantic State. The algorithm that semvec implements. You will still see "pss" in source paths, tests, and class deprecation aliases because semvec was originally developed and published as the pss Python package (EP 25 188 105.8, CIP in progress). semvec is the same engine rewritten in Rust with PEP 8-compliant names.
  • Semvec — The productised name; the shipping library. It stands for semantic vector.

The relationship is: Semvec is the product, PSS is the algorithm.

Core state-update quantities

These are the numbers SemvecState.update() returns on every turn. Each one is also exposed as a rolling history on the state object (beta_history, similarity_history, …).

Metric Symbol What it means Typical range
similarity sim(t) Cosine similarity between the new input embedding and the current semantic state, measured before the update. [-1, 1] (normalised inputs)
beta (β) β Adaptive momentum — how much of the previous state survives. β = 1 freezes the state; β = 0 replaces it fully with the new input. [beta_basis, beta_max_default] ≈ [0.05, 0.95]
pattern_strength α_pat How strongly the retrieved memories pull the new state toward their centroid. Computed from the attention-weighted memory similarities. [0, ~1.5]
norm ‖S‖ L2 norm of the new semantic state vector after adaptive normalisation. Bounded so the state never blows up. [0, 1.2]
FSM Field Stability Metric Smoothed "how stable is the state oscillating?" indicator driven by the norm + similarity histories. Feeds phase detection. Computed on demand via state.calculate_fsm(...) (≥ 0.2.0a1) — license-bound, see licensing. [0, 1]
topic_switch — Magnitude of a detected topic switch (0 when no switch). Non-zero values boost the next turn's novelty scoring. [0, 1]
novelty_score — How surprising the new input is versus the system-vector history (state-history novelty amplification, feature delta 20). [0, 1]

The 6 conversation phases

Phase detection is a hybrid Markov × rule-based FSM on top of the core metrics. Every update may emit a phase transition; the current phase is exposed as phase_detector.current_phase and echoed in the update result.

Phase Emitted when
initialization first N turns, state still warming up
exploration high novelty + low resonance — new topic
convergence similarity rising, beta rising, memories aligning
resonance stable alignment; most inputs short-circuit against memory
stability long steady resonance without drift
instability phase oscillation; drift anchors trigger realignment

Memory tiers

SemvecState.memory is a three-tier MultiResolutionMemory:

  • Short-term (default 20 slots) — every turn lands here.
  • Medium-term (default 100) — promoted on access + importance.
  • Long-term (default 500) — k-means++ consolidated clusters.

Eviction is selective forgetting: a composite score (0.4 · importance + 0.35 · recency + 0.25 · access_count) picks the victim, not FIFO.

Drift, anchors, resonance triggers

  • Drift — when the semantic state migrates away from a set of reference embeddings. Measured as cosine against the drift anchors you registered via add_anchor(embedding). When the score falls below drift_threshold the state is gradually realigned (gradient over several turns, not a snap).
  • Anchor score — the mean cosine between the current state and all registered anchors.
  • Resonance trigger — a keyword or embedding that, when matched, forces β = beta_basis for that turn and pins importance = 1.0, making the state absorb the input aggressively (feature delta 19).

Embedding interface

Every API that takes an embedder= parameter expects an object exposing two methods:

embedder.get_embedding(text: str) -> np.ndarray    # shape (dimension,), preferably L2-normalised
embedder.get_dimension() -> int                    # must match SemvecConfig.dimension

See the embedders guide for ready-made wrappers (SentenceTransformers, OpenAI, ONNX int8).

The feature deltas

"Feature deltas 16-26" and "feature deltas 27, 29, 30" are the numbered feature additions in the underlying patent-pending application (EP 25 188 105.8, CIP in progress). They are exposed 1:1 over the REST API and under the SemvecState method surface. The short-form catalogue:

Δ Feature Where it shows up
16 Fisher-protected memory — EMA-weighted protection_score on retrieved units MemoryUnit.protection_score, SessionManager.get_metrics
17 K-means++ long-term consolidation MultiResolutionMemory internals
18 Self-learning retrieval projection (W_down / W_up) SemvecState.set_retrieval_projection_weights
19 Semantically-triggered resonance ResonanceTrigger + POST /v1/session/{id}/trigger
20 State-history novelty amplification automatic; novelty_score in the update dict
21 Persistent operator state vector SemvecState.operator_state_vector
22 State serialisation + SHA-256 consistency verification to_dict / from_dict + POST /v1/session/{id}/verify
23 Long-term semantic drift detection + realignment add_anchor + anchor_score + automatic realignment
24 Template-based pre-initialisation SemvecConfig.template_vectors
25 Multi-level input isolation filter IsolationLevel + PUT /v1/session/{id}/isolation
26 Policy-vector compliance modulation PolicyVector + POST /v1/session/create with policy_vectors=[…]
27 Semantic delta-vector transfer POST /v1/network/transfer
28 Synthetic memory injection POST /v1/session/{id}/memory
29 User-isolated instance partitioning POST /v1/network/users/switch
30 Trust-based consensus protocol POST /v1/network/consensus
31 Three-factor instance influence weighting SemvecCortexService._calculate_influence

Deltas 1–15 are the base feature claims (PSS equation, multi- resolution memory, phase detection, attention retrieval, query cache, MetaPSS). They are not numbered individually in the API surface because they are the library.

Further reading