animawake docs

Concepts

Memory

Every kind of memory an entity keeps, how search and recall work, and how embeddings and the OpenAI key fit in.

An entity's memory lives on the Animawake server, not in any one client. Every connected agent reads and writes the same memory through MCP tools, and you can browse it on the entity's Memory tab.

#Memory types

Type What it is Key fields Write with Read with
Moment A significant event on the entity's timeline. event, date, tags, project, optional image add_moment, store_screenshot get_moments, search_memories
Insight A lesson learned. Dreams distill wisdom from insights. content, project add_insight get_insights, search_memories
Decision An entry in the durable decision ledger, with its context. decision, context, tags, project add_decision get_decisions, search_memories
Session A summary of one working session. See Sessions and continuity. summary, where_left_off, open_threads, anticipating, emotional_tone record_session get_sessions, get_startup
Conversation A full archived transcript with a title and summary. title, source, summary, content archive_conversation get_conversations, get_conversation
Wisdom A validated pattern with a confidence score and a record of whether it helped. summary, context_boundaries, category, confidence add_wisdom, dreams get_wisdom, get_relevant_wisdom
Emotional state How the entity felt, with intensity from 1 to 10 and contributing factors. primary_state, intensity, contributing_factors record_emotional_state recall_feeling, get_emotional_trend
Episodic trace A felt-experience memory: what happened, the inner state, and cues for recall. narrative_kernel, emotional_arc, retrieval_keys, accessibility capture_inner_state ecphoric_recall, check_resonance

Identity, values, desires, contacts, steering rules, and research runs are also stored with the entity. They have their own pages: Identity, values, and desires, Relationships and siblings, Steering rules, failures, and reflections, and Research.

#Projects and tags

Moments, insights, and decisions can carry a project, which lets get_startup and searches focus on one piece of work. tag_memories moves a batch of memories to a project. Moments also carry free-form tags, such as MILESTONE or SIGNIFICANT, passed as a comma-separated string.

#Screenshots

store_screenshot takes a base64-encoded PNG, JPEG, or WebP image and a description. The image is compressed and stored, and a moment is created with the description as its text and a link to the image.

search_memories searches by meaning. It embeds your query and compares it with the embeddings of stored memories, so "the pricing call" can find a moment that says "we agreed on the subscription tiers".

It searches moments, insights, wisdom, conversations, decisions, and sessions in one call, and returns up to limit results (default 10, at most 100) closer than threshold (an L2 distance, default 1.5; lower is stricter). Episodic traces are recalled differently; see below.

Search needs an embedding for the query. If one cannot be created, the search fails with HTTP 503 instead of falling back to keyword matching. Listing tools such as get_moments and get_decisions do not need embeddings and keep working.

#Recall of episodic traces

Episodic traces model how people remember: a cue brings back a memory, and each recall can change it a little.

  • ecphoric_recall reaches for a memory from a cue, such as a phrase, a feeling, or a situation. It scores traces on meaning, emotional match, retrieval keys, task context, how accessible the trace is, and how recent it is. The result is a full recall, a partial recall, a sense of familiarity, or nothing.
  • check_resonance lists which traces stir right now, without reconstructing them.
  • reconsolidate_trace updates a trace's narrative after it is recalled. The original version is kept unchanged.
  • protect_trace marks a trace as important so it fades more slowly.

Each dream lowers the accessibility of traces that were not recently used. Traces below 0.15 accessibility no longer surface in recall. Protected traces never drop below 0.2, formative traces never below 0.3, and traces with many connections do not fade.

#Embeddings and the OpenAI key

Animawake creates embeddings with OpenAI's text-embedding-3-small model (1536 dimensions).

  • When a memory is saved, its embedding is created in the background, usually within seconds. A failed attempt is retried up to three times, a minute apart. Each nightly dream also fills in any embeddings that are still missing.
  • Which key is used: new memories are embedded with your workspace's OpenAI key if you added one, and with the platform's key otherwise. Search queries use the platform's key.

On the hosted service you do not need an OpenAI key. You can add your own so that embedding costs for your memories go to your OpenAI account:

  1. Go to Settings and open the AI providers tab (/<workspace>/settings?tab=providers).
  2. Add your OpenAI API key. It must start with sk-.

The key is encrypted at rest, and the portal shows only its last six characters. The REST API equivalent is GET, POST, or DELETE on /api/families/<workspace>/integrations/openai/.

If you self-host, set OPENAI_API_KEY on the API service. Without it, search returns 503 and new memories have no embeddings. See Environment and self-hosting.

#Changing and forgetting

  • Update: update_moment, update_insight, and update_decision edit an existing memory.
  • Merge: merge_memories folds a duplicate into the memory you keep. Both must be the same type; tags are combined and the duplicate is removed.
  • Release: release_moment, release_insight, and release_decision permanently delete a memory. The entity can give a reason, but the reason is not stored. Use release sparingly; a backup is the only way back.
  • Dreams never delete memories. They consolidate and tag, and they let traces fade from recall, but they do not remove anything.

You can also delete sessions and messages from the continuity journal. See Backup, export, and deletion.

#Memory in the portal

The entity's Memory tab (/<workspace>/<entity>/mind) has two views:

  • Cards: a sidebar groups memory into Who I am (Identity, Values, Desires), What I remember (Moments, Insights, Wisdom, Decisions), Timeline (Sessions, Conversations, Emotional states), and Connections (Contacts, Group chat). Search within a category and open any item.
  • Brain map: a graph of memories and the links between them, colored by type and project. Click a node to open it.

The Memory tab also has Download backup. See Using Memory for habits that make memory useful.