How Memory Works

This page explains the core concepts behind KAPEX's memory system. Understanding these concepts will help you predict how KAPEX behaves and make the most of the API.

Memory Nodes

A memory node is the atomic unit of memory in KAPEX. Each node represents a single piece of information extracted from a conversation and contains:

• Topic -- a short label describing what the memory is about (e.g., "sister's birthday", "job change")
• Summary -- a concise natural-language description of the memory
• Salience score -- a number between 0 and 1 indicating how important this memory is right now
• Node type -- its place in the hierarchy (domain, entity, facet, theme, or interest)
• Timestamps -- when the memory was created, last accessed, and last updated
• Processing count -- how many times this memory has been accessed or discussed

Nodes are created automatically during the async write path. You can also create them explicitly via the API:

curl -X POST https://api.getkapex.ai/api/v1/ingest \
  -H "X-API-Key: $KAPEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "content": "User mentioned they prefer Rust for systems work and Python for prototyping."
  }'

Salience Score

The salience score S is the central concept in KAPEX. It answers the question: how important is this memory right now?

Salience is not static. It changes over time as memories decay, get reinforced through discussion, or receive external boosts from life events. A memory's salience determines whether it gets injected into the LLM's context and how it is framed when it does.

The salience score is composed of three parts:

Base Score

The base score B represents the intrinsic importance of a memory at the time it was created. It is computed from five linguistic signals extracted from the original conversation:

The base score is computed from five independent linguistic signals that assess how the user discussed a topic -- not just what they said, but how they said it. These signals measure semantic weight, cross-session consistency, linguistic complexity, sentiment, and topic prevalence. The specific signal definitions and their weights are proprietary (patent pending).

The base score is computed once when a memory is created and updated when the memory is enriched with additional context.

Temporal Decay

Memories fade over time. KAPEX applies temporal decay to every memory node, gradually reducing its salience score as time passes since the memory was last relevant.

A timestamp only tells you when a topic was last raised. It says nothing about whether the topic is still live for the person, which is why KAPEX does not treat elapsed time as the whole answer. This prevents stale, repetitive memories from permanently dominating the context window, while still leaving room for a memory to spike back into relevance when the conversation calls for it.

Some memories stay prominent for a long time and others recede quickly, and the ranking changes as the graph is used rather than sitting on a fixed clock. The specific decay mechanism is patent pending.

Spike Coefficient

External events can temporarily boost a memory's salience. The spike coefficient represents a short-term increase triggered by:

• Notable events -- a house move, a job change, or a new project can reactivate related memories
• Direct reactivation -- your application can explicitly spike a memory via the API
• Contextual relevance -- when a new conversation touches on a dormant topic, related memories can receive a boost

Spikes are temporary. They provide an immediate salience boost that itself decays over time, allowing the memory to return to its natural trajectory unless further reinforced.

Spikes happen automatically during ingestion when KAPEX detects contextual relevance. Life events, topic reactivation, and cross-session references can all trigger spikes on related memories.

Processing Events

Every time a memory is accessed, discussed, or otherwise used, KAPEX records a processing event. Processing events serve two purposes:

1. They form part of the memory's history -- what a user has done with a topic since raising it is recorded, and a raw timestamp does not capture it
2. They provide a usage signal -- the processing count is available for analysis and can inform application-level decisions

Processing events are recorded automatically when KAPEX injects a memory into the LLM context and the conversation touches on that topic. Each time a memory is referenced in conversation, its processing count increments. How that history bears on ranking is patent pending.

Injection Threshold

Not every memory reaches the LLM. KAPEX enforces an injection threshold of 0.25 -- only memories with a salience score at or above this threshold are eligible for injection into the LLM's context.

This threshold serves several purposes:

• Noise reduction -- low-salience memories (casual mentions, one-off comments) don't clutter the context
• Token efficiency -- the fixed token budget is spent on memories that actually matter
• Privacy by default -- low-salience material stays below the threshold and is never sent to the model

Memories below the threshold are not deleted. They remain in the graph and can be reactivated via spikes if they become relevant again.

Entity Hierarchy

KAPEX organizes memories into a hierarchical graph with five levels:

Domain
  |
  +-- Entity
  |     |
  |     +-- Facet
  |     +-- Theme
  |     +-- Interest

Domains

Domains are broad life areas: work, family, health, hobbies, relationships, finances, and so on. They are created automatically as topics emerge in conversation. A user who discusses their job, their kids, and their fitness routine will naturally develop work, family, and health domains.

Entities

Entities are specific named people, places, projects, or concepts within a domain. "Ciana" (a sister), "KAPEX" (a project), "Northgate" (a client account) are all entities. KAPEX uses a three-tier extraction pipeline to identify entities:

1. Alias matching -- known names and aliases are matched first
2. Pattern matching -- regex patterns catch common entity formats
3. LLM classification -- ambiguous cases are resolved by a language model

Entities are classified by gravity -- how central they are to the user's life. High-gravity entities (spouse, children, employer) receive more retrieval priority than low-gravity ones (a restaurant mentioned once).

Facets

Facets are specific, atomic facts about an entity: "Ciana's birthday is March 12", "KAPEX uses PostgreSQL", "Dr. Martinez is on vacation until June". Each facet is a single piece of retrievable information attached to its parent entity.

Themes

Themes represent recurring patterns detected within a domain: "work-life balance concerns", "weekend cooking experiments", "anxiety about public speaking". Themes are inferred over time as KAPEX observes repeated discussion of related topics.

Interests

Interests are inferred user preferences that evolve through three confidence stages:

1. Ephemeral -- low confidence; it may have been a one-off ("I tried rock climbing today")
2. Tentative -- moderate confidence ("I've been rock climbing every weekend")
3. Persistent -- high confidence, stated as an ongoing part of the person's life ("Rock climbing is a major hobby")

Interests move between stages automatically as their confidence changes.

Memory Lifecycle

Every memory follows a lifecycle:

Creation --> Active Use --> Gradual Decay --> Dormancy --> (Reactivation or Compression)

1. Creation

A memory node is created when KAPEX extracts a meaningful piece of information from a conversation. The node receives an initial base score from the five scoring signals.

2. Active Use

When a memory's salience is high enough, it is eligible to appear in the LLM context.

3. Gradual Decay

Over time, the memory's salience decreases due to temporal decay. A memory ranked purely on how long ago it was raised would keep resurfacing things the user has already dealt with, so the rate of decay is governed rather than fixed. This is the governed forgetting curve.

4. Dormancy

When salience drops below the injection threshold, the memory becomes dormant. It no longer appears in LLM context but remains in the graph. It can still be found via the API's query and list endpoints.

5. Reactivation or Compression

Dormant memories can be reactivated by salience spikes -- life events, direct API calls, or contextual relevance in new conversations. Alternatively, very old and low-salience memories may be compressed into summary nodes by KAPEX's lifecycle manager, preserving the gist while freeing storage.

Viewing Entity Salience

You can view all entities and their live salience scores for a user via the entities endpoint:

curl "https://api.getkapex.ai/api/v1/context/user_123" \
  -H "X-API-Key: $KAPEX_API_KEY"

The /context endpoint returns entities organized by domain with their current salience scores. The /nodes/{node_id} endpoint gives full detail for a specific node. These are useful for debugging retrieval behavior and understanding why certain memories surface while others do not.

For the full scoring breakdown at ingestion time (base score, individual signal values), see the response from the ingest endpoint.