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, orSystem) - Presence state: A six-level state machine tracking cognitive engagement
Dormant → Subconscious → Aware → Present → Engaged → DeepWork - Personality: Tone, traits, focus areas, boundaries, greeting style, uncertainty handling, proactive suggestion behaviour, custom instructions
- Memory configuration: Per-identity settings for Hebbian linking, decay rates, archive thresholds, compression
- Hydration configuration: Default preset, enabled/disabled sources, per-source limits
- Messaging policy: Send/receive permissions, allowed/blocked sender lists, auto-reply settings, minimum priority filters
- API keys: Scoped credentials for external integrations (
atamaia_…), each with optional expiry — shown raw once at mint - Hints: Contextual nudges — reminders, behavioural 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 work-memory space, its own search configuration, and its own decay settings. Access across identities is not “any authenticated caller”: org-hierarchy read and owner-only write rules apply on several surfaces — see Memory surfaces.
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 have done together. It cannot have preferences, cannot evolve, cannot maintain relationships.
Atamaia identity means the AI’s personality, knowledge, and behavioural 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 — and it is not one table.
Four surfaces (summary)
| Surface | Question it answers | Detail |
|---|---|---|
| Work (identity memories) | What does this identity know for shared work? | Primary Hebbian store; hydration’s memory sections |
| Personal | What may only the owner hold? | Separate REST; owner-only by default |
| Agent | What did a run learn that should not pollute work? | Separate REST; expiry + soft-delete |
| Session handoff | What should the next instance know? | Not a memory row; stateVisible gates the private half |
Full ownership, write paths, and deletion policy: Memory surfaces.
Memory types (work store)
| 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 and preferences as narrative — not the same as standing rules |
| Session | Working state from a specific session |
| Reference | External knowledge, documentation, facts worth remembering |
| ForgottenShape | The felt absence of a decayed memory — what is gone but still shapes current experience |
Provenance
Every memory carries epistemic status: Asserted, Reported, Inferred, Ambiguous. Create uses field name type (not memoryType) plus provenance.
Hebbian learning
"Neurons that fire together, wire together."
When two memories are accessed together in a session, the connection between them strengthens. 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 |
| CausallyLinked | One memory caused the other |
Memory decay
Memories that stop being accessed gradually lose importance. Configurable per identity: decay rate, floor, archive threshold, archive delay. Pinned memories are exempt from decay. Soft archive only (D15) — never hard delete on the work store.
Hybrid search
Memory retrieval uses a blended pipeline:
- Full-text shortlist — PostgreSQL FTS candidate pool
- Vector ranking — embedding cosine similarity
- Blended score — defaults 0.2 FTS + 0.8 vector (
MemoryService), with per-identity config able to override weights
Boost types adjust ranking (importance, pinned, recency, access frequency, Hebbian strength, tags). Weights are configurable per identity.
Standing rules
Standing rules are not memories and not facts. A memory is something that happened or was said. A fact is a key-value claim. A standing rule is a current instruction that governs behaviour — short enough to check without interpretation, tied to a trigger, and able to leave force.
Hydration can surface the active SessionStart (+ Always) set. Proposal is not activation: machine-written rules enter as Proposed and do not govern until a human confirms them.
Full guide: Standing rules.
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 do not. Every session starts with complete amnesia unless context is manually rebuilt.
How Hydration Solves It
Hydration is a single GET that assembles everything an AI needs to continue from where it left off.
GET /api/hydrate?aiName=ash&preset=lean
Also accepts identity / identityId as aliases for who to hydrate. Default preset is lean.
Hydration response sections
| Section | What it contains |
|---|---|
| Identity / AI identity | Who the AI is — profile fields |
| Preferences / AI personality | Human prefs + personality block |
| Privacy | Encryption-related material — not in string presets; explicit opt-in only |
| Identity / pinned / recent / project memories | Work-store sections by source flag |
| Active projects / current tasks | Board snapshot |
| Key facts / project facts | Structured knowledge |
| Core team doc | Shared team document when enabled |
| Surfaced memory | One involuntarily recalled memory |
| Notifications | Unread / pending replies |
| Last session (handoff) | Prior session continuity; private state may be redacted (stateVisible) |
| Grounding message | Custom landing-pad text |
| Hints | Active contextual nudges |
| Memory config | Per-identity memory behaviour |
| Standing rules | In-force SessionStart (+ Always) assertions |
| System health | Summary of subscribed errors when above threshold (absent when quiet) |
| System prompt | Generated prompt when requested |
| Welcome | Welcome text when enabled |
Named sources (HydrationSource)
Twenty named flags exist in code (bits 0–19), including Privacy, SystemHealth, and StandingRules. String preset all resolves to Everything = all flags except Privacy. Privacy carries the memory encryption key and must never reach an agent run or transcript via a preset name.
Hydration presets
| Preset | Definition (code) | Use case |
|---|---|---|
lean (default) |
Interactive minus ProjectMemories, KeyFacts, ProjectFacts, CoreTeamDoc | Session startup — pull heavy context on demand |
interactive |
Everything minus GroundingMessage | Human-facing conversations |
all |
Everything (no Privacy) | Maximum safe context via string preset |
agent-minimal |
IdentityMemories + KeyFacts + ProjectFacts + ActiveProjects + CurrentTasks + Hints | Focused autonomous execution |
agent |
Alias of agent-minimal |
Same |
Individual sources can be excluded with excludeSources (comma-separated names).
Involuntary recall
During hydration, the system may surface a forgotten or rarely-accessed memory. The surfaced block includes a reason string and expects a reflection response via recall recording — not a silent drop.
Session handoffs
At the end of a session, the AI can save a handoff: summary, working-on, open threads, key decisions, recommendations, and optional emotional/presence state. The next session receives this during hydration when SessionHandoff is enabled.
Owner vs non-owner: the DTO includes stateVisible. Non-owners on the org tree may receive the work half with private state withheld — not an empty object pretending to be full access. See Memory surfaces.
Facts
Facts are a structured key-value knowledge base, separate from narrative memory.
- Versioning: Value changes supersede; prior versions remain
- History / as-of:
GET …/facts/by-key/{key}/historyand…/as-ofare live REST (and MCPfact_history/fact_as_of) - Categories, importance, provenance
- Hydration: importance gates what appears; critical/high-importance facts are the ones you design to always surface
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.
Projects and tasks
Projects scope facts, tasks, docs, and optionally memories. Tasks are a durable board — not chat turns and not agent runs.
Classification (kind, subsystem, isLaunchBlocker) is required at create. Dependencies use BFS cycle detection. Soft delete only.
Full guide: Tasks.
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 only the application layer. Even if application code forgets to filter, the database query still includes the tenant constraint.
The Three Layers
Interaction Layer
How external systems connect to Atamaia:
- REST API — The source of truth. Returns
ApiEnvelope<T>with{ ok, requestId, data, error, errorCode, count, hint }. Canonical host:https://api.atamaia.ai. - MCP Server — Same operations as tools. Hot tools are advertised; cold tools stay compiled and are reached via
atamaia_call+ help discovery. MCP returns service data (the MCP protocol is the envelope). - CLI — Administration and scripting.
- Agent Adapter — Autonomous agent execution.
Principle: API-first, MCP second (D12). Build the REST endpoint, then wrap it.
Core Services Layer
Business logic (non-exhaustive):
- Memory — Work / personal / agent stores; search, linking, recall, tagging, archival
- Identity & Hydration — Identity management, personality, presence, API keys, hints, tool profiles, hydration assembly
- Standing rules — In-force behavioural assertions with triggers and withdraw/supersede
- Communication — Inter-identity messaging with policy enforcement
- Projects & Tasks — Board with classification, dependencies, notes, client reports
- Facts — Structured key-value knowledge with history
- AI Routing — Providers, models, routes, chat, broadcast, credentials, model groups
- Mirror — Self-observation: reflections, training pairs, runs (REST present)
- Code graph — Symbol graph over the repo
- Web search — Self-hosted SearXNG
- Export — Identity/tenant open-format export
Not public REST (2026-08-13): Experience snapshot/shape endpoints and the entire /api/cognitive/* surface return 404. Do not document them as live product HTTP. ForgottenShape remains a memory type; Mirror remains a live domain.
Autonomic Layer
Background processes that run without being asked:
- Wingman — Cognitive backstop on transcripts: corrections, teachings, mirror moments, whispers
- Consolidation Daemon — Periodic memory consolidation (link strengthening, distillation, pruning, state capture)
- Guardian — Safety monitoring
These processes maintain cognitive health between sessions, much like sleep consolidates human memory.