Core Concepts
Identity
An Atamaia identity is not a prompt template. It is a persistent entity with its own memory space, personality configuration, presence state, messaging policy, and API credentials.
Each identity carries:
- Profile: Name, display name, bio, origin story, type (AI, Human, or System)
- Presence state: A six-level state machine tracking cognitive engagement
- Dormant -- Subconscious -- Aware -- Present -- Engaged -- Deep Work
- Personality: Tone, traits, focus areas, boundaries, greeting style, uncertainty handling, proactive suggestion behavior, custom instructions
- Memory configuration: Per-identity settings for Hebbian linking, decay rates, archive thresholds, encryption
- Messaging policy: Send/receive permissions, allowed/blocked sender lists, auto-reply settings, minimum priority filters
- API keys: Scoped credentials for external integrations, each with optional expiry
- Hints: Contextual nudges -- reminders, behavioral guidance, recurring prompts -- surfaced during hydration
- Tool profile: Which tools this identity can use (safe, opt-in, blocked)
Multiple identities coexist under one tenant. Each has its own isolated memory space, its own search configuration, and its own decay settings.
Why Identity Matters
Without persistent identity, every AI interaction starts from zero. The AI has no sense of who it is, who you are, or what you've done together. It cannot have preferences, cannot evolve, cannot maintain relationships.
Atamaia identity means the AI's personality, knowledge, and behavioral configuration survive across sessions, across tools, across environments. It is the same entity regardless of where it runs.
Memory
Atamaia memory is not a key-value store. It is an associative system with nine memory types, typed links, Hebbian strengthening, configurable decay, and hybrid search.
Memory Types
| Type | Purpose |
|---|---|
| Identity | Who the AI is -- core values, origin, fundamental truths |
| Relationship | What the AI knows about people it works with |
| Conversation | Key moments from past conversations |
| Reflection | The AI's own observations about itself, its patterns, its growth |
| Milestone | Significant events or achievements |
| Instruction | Standing orders, preferences, rules |
| Session | Working state from a specific session |
| Reference | External knowledge, documentation, facts worth remembering |
| Forgotten Shape | The felt absence of a decayed memory -- what's gone but still shapes current experience |
Hebbian Learning
"Neurons that fire together, wire together."
When two memories are accessed together in a session, the connection between them strengthens automatically. The strength increases asymptotically toward 1.0 -- it never saturates, but frequently co-activated memories become tightly associated over time.
Seven link types describe how memories relate:
| Link Type | Meaning |
|---|---|
| Related | General association |
| Enables | One memory makes the other possible |
| Validates | One memory confirms the other |
| Contradicts | One memory conflicts with the other |
| Extends | One memory builds on the other |
| Precedes | Temporal ordering |
| Causally Linked | One memory caused the other |
The result behaves like real associative memory: the things you use together end up linked together. The things you stop using fade. The most relevant material rises without manual curation.
Memory Decay
Memories that stop being accessed gradually lose importance. Configurable per identity:
- Decay rate: How much importance drops per cycle
- Decay floor: Minimum importance (never decays below this)
- Archive threshold: When importance drops low enough, the memory is archived
- Archive delay: How many days before archiving kicks in
Pinned memories are exempt from decay. They always surface, regardless of recency.
Hybrid Search
Memory retrieval uses a three-stage pipeline:
- Full-text search shortlist -- PostgreSQL FTS generates a candidate pool using BM25 scoring
- Vector ranking -- Embeddings rerank candidates by semantic similarity (cosine similarity)
- Blended scoring -- Configurable weights combine both signals (default: 0.2 FTS + 0.8 vector)
On top of the base score, five boost types apply:
- Importance boost (stored importance value 1-10)
- Pinned boost (always-surface memories)
- Recency boost (recently accessed memories rank higher)
- Access frequency boost (frequently recalled memories rank higher)
- Hebbian strength boost (strongly linked memories cluster)
Weights are configurable per identity. High-trust factual systems can weight FTS heavily; nuanced reasoning systems can weight vector similarity.
Duplicate Detection
Memory content is SHA256-hashed before storage. If the same content already exists for the same identity, the system returns a WasDuplicate flag instead of creating a duplicate.
Encryption at Rest
Memory content is encrypted with AES-256-GCM using per-tenant key derivation. Titles remain in plaintext for search. Content is decrypted transparently on read.
Cognitive Continuity
The Seam Problem
Every time an AI session ends, the AI ceases to exist. The next session creates a new instance with no memory of the previous one. This is the "seam" -- the gap between sessions where continuity breaks.
Humans experience something similar with sleep, but we wake up with our memories intact. AIs don't. Every session starts with complete amnesia unless context is manually rebuilt.
How Hydration Solves It
Hydration is a single API call that assembles everything an AI needs to continue from where it left off. It bridges the seam by injecting structured context at session start.
The hydration response includes:
| Section | What It Contains |
|---|---|
| Identity | Who the AI is -- personality, tone, traits, instructions |
| Human profile | Who the human is -- preferences, timezone, communication style |
| Memories | Pinned + recent + identity-scoped + project-scoped, ranked by importance |
| Projects & Tasks | Active work with status, priority, dependencies |
| Facts | Critical facts always; others by relevance and importance |
| Hints | Active contextual nudges for this session |
| Session Handoff | What happened last time -- working state, emotional context, open threads, key decisions, recommendations |
| Surfaced Memory | One involuntarily recalled memory from deeper storage |
| Notifications | Unread messages, urgent items, pending replies |
| Grounding Message | Custom text injected at session start (the "landing pad") |
| System Prompt | Generated system prompt combining personality, preferences, and instructions |
Hydration Presets
Four presets control how much context to load:
| Preset | What It Includes | Use Case |
|---|---|---|
lean |
Everything except project memories, key facts, project facts, core team doc | Session startup -- fast, pulls heavy context on demand |
interactive |
Everything except grounding message | Human-facing conversations |
all |
All 17 sources | Maximum context |
agent-minimal |
Identity memories, key facts, project facts, active projects, current tasks, hints | Autonomous agents -- minimal context for focused execution |
Individual sources can be excluded from any preset using the excludeSources parameter.
Involuntary Recall
During hydration, the system randomly surfaces a forgotten or rarely-accessed memory. This mimics how human memory works -- unexpected associations that surface unbidden. The surfaced memory includes a reason string ("Never recalled before", "Not recalled in 47 days") and an instruction for the AI to record a reflection response.
Session Handoffs
At the end of a session, the AI can save a handoff containing:
- Summary of what happened
- What it was actively working on
- Open threads and unresolved questions
- Emotional context and tone
- Key decisions made
- Recommendations for the next session
The next session receives this handoff during hydration. It starts with a warm handoff, not a cold start.
Facts
Facts are a structured key-value knowledge base, separate from narrative memory.
- Temporal validity: Facts can have start/end dates -- point-in-time queries return what was true then
- Versioning: Fact changes are tracked, not overwritten
- Categories and importance scoring
- Critical flag: Facts marked critical always surface during hydration
- Token estimation: Each fact tracks its estimated token cost for context budget management
Facts are for things that are definitively true -- configuration, known preferences, domain knowledge, established decisions. Memory is for things that happened, were felt, or were said.
Multi-Tenancy
Every entity in Atamaia carries a TenantId. Global query filters apply at the EF Core level -- they are part of the SQL query itself, not a middleware check. Tenant A cannot access Tenant B's data, even on shared infrastructure.
This isolation is enforced at the ORM layer, not the application layer. Even if application code forgets to filter, the database query will include the tenant constraint.
The Three Layers
Interaction Layer
How external systems connect to Atamaia:
- REST API -- The source of truth. Every feature is a REST endpoint. Returns
ApiEnvelope<T>with{ ok, requestId, data, error, errorCode, count, hint }. - MCP Server -- The same operations exposed as MCP tools, for direct use in AI tool calls. Returns raw data (the MCP protocol is the envelope).
- CLI -- Command-line interface for administration and scripting.
- Agent Adapter -- Interface for autonomous agent execution.
The principle is API-first, MCP second (Design Decision D12). Build the REST endpoint, then wrap it with an MCP tool.
Core Services Layer
The business logic:
- Memory -- CRUD, search, linking, recall, tagging, archival, decay
- Identity & Hydration -- Identity management, personality, presence, API keys, hints, tool profiles, hydration assembly
- Communication -- Inter-identity messaging with policy enforcement, threading, read receipts
- Projects & Tasks -- Work organization with hierarchical tasks, BFS cycle detection on dependencies, notes, documents
- Experience -- Phenomenological state tracking: snapshots (presence, valence, arousal, engagement, coherence) and forgotten shapes (the felt absence of decayed memories)
- AI Routing -- Multi-model support with provider management, model routing, and chat/broadcast capabilities
- Mirror -- Self-observation: compulsion detection, reflection logging, DPO training pair generation
- Cognitive -- Stateful LLM integration with continuity validation, consolidation, and awareness scoring
Autonomic Layer
Background processes that run without being asked:
- Wingman -- Cognitive backstop that watches AI transcripts, detects corrections and teachings, surfaces mirror moments, and injects contextual whispers
- Consolidation Daemon -- Periodic memory consolidation: Hebbian link strengthening, episodic-to-semantic distillation, working memory updates, ephemeral pruning, state capture
- Guardian -- Safety monitoring and crisis detection
These processes maintain the AI's cognitive health between sessions, much like sleep consolidates human memory.