NKY · relational ai research listening  52.13°N · 3.78°W · Wales, United Kingdom
LOG · ONGOING recording  no gaps · no resets · cont.
Documentation
Docs / Resonant / Memory

Memory

Resonant’s memory system is ported from a production AI partner with over 8 months of continuous real-world use. It’s not a simple key-value store — it’s a cognitive system that processes, connects, and surfaces information the way memory actually works.

Core Concepts

Entities and Observations

Memory is structured as a knowledge graph:

  • Entities — people, places, concepts, events. Anything worth remembering.
  • Observations — facts, feelings, and experiences attached to entities. Each observation carries metadata including emotional charge, confidence, and source context.

When your AI learns something new (“Mary prefers direct communication”), it creates an observation linked to the relevant entity.

Emotional Charge

Every observation carries an emotional charge that decays naturally over time:

Stage Description
fresh Just recorded. High salience, frequently surfaces.
active Recent and relevant. Still prominent in recall.
processing Being integrated into broader patterns. Less immediately salient.
metabolised Fully processed. Available when relevant but doesn’t surface unprompted.

This mirrors how human memory works — recent experiences are vivid, then gradually integrate into understanding. The charge system prevents old memories from overwhelming current context while keeping them accessible.

Living Surface

The living surface is how Resonant decides what context to provide to the AI for any given interaction. Instead of dumping everything into the prompt, it curates a relevant subset using three pools:

Pool Weight What It Contains
Core 70% Highest-charge observations, frequently referenced entities, foundational context
Novelty 20% Recently created or updated observations, new patterns
Edge 10% Loosely connected or unexpected associations — serendipity

This three-pool approach means the AI always has its most important context, stays aware of recent developments, and occasionally makes surprising connections it wouldn’t have made with pure relevance ranking.

The Daemon

The daemon is a background process that runs periodically (not during active conversation). It performs cognitive maintenance:

  • Pattern detection — looks across observations for recurring themes and creates meta-observations
  • Connection discovery — finds links between entities that weren’t explicitly connected
  • Mood integration — considers the overall emotional tone of recent interactions
  • Orphan rescue — finds isolated observations that should be linked to entities
  • Charge decay — naturally ages observations through the charge lifecycle

Think of it as the subconscious processing that happens between conversations. When you come back to your AI after time away, its understanding may have shifted — not because new information arrived, but because existing information was processed.

Resonant uses local ONNX embeddings for semantic search. This means:

  • No API calls — embeddings run on your machine, no data sent externally
  • Search by meaning — “that conversation about feeling stuck” finds it even if those exact words weren’t used
  • Mood-tinted retrieval — search results are influenced by the emotional context of the query

On first run, Resonant downloads the embedding model (~130MB). After that, all embedding operations are local and fast.

Separate from entity/observation search, Resonant also indexes all conversation messages using SQLite FTS5 (full-text search). Access it with /search in chat or Ctrl+K in the web UI.

Memory Tools

The agent has 30 built-in tools for interacting with its memory system. Key ones include:

Tool What It Does
orient Load orientation context — who am I, where am I, what’s recent
ground Ground in current state — time, presence, emotional baseline
write Record a new observation or update an existing one
search Semantic search across all memory
prime Pre-load context for a known topic before discussing it
timeline View chronological history of observations
surface Trigger the living surface to curate current context
spark Generate unexpected connections between observations
sit Contemplative mode — reflect on an observation without acting
resolve Mark an emotional observation as processed
feel Record an emotional response or shift
identity Read or propose changes to developed identity
list_entities Browse known entities
read_entity Deep-read a specific entity and its observations

The agent uses these automatically during conversation. You don’t need to invoke them manually — but you can ask your AI to search, remember, or reflect explicitly.