Atamaia Tool Surface Design
Flat tools, not facades. Each tool = one verb.
{domain}_{action}. LLMs see the tool name and parameters — that's the entire interface.
Design Principles
- Flat over nested — No facade dispatch.
memory_search(query)notmemory_execute({cmd: "search"}). Self-documenting, zero indirection. - Consistent naming —
{domain}_{action}. Always snake_case. Verbs from: list, get, create, update, delete, search, archive. - Every response has a shape — REST returns
ApiEnvelope<T>with{ ok, requestId, data, error, errorCode, count, hint }. MCP returns the raw data (envelope is HTTP-only). - UUID on everything — Every entity has both
id(long, fast joins) andguid(UUID, external reference). Every HTTP request gets a correlation UUID. - Soft delete everywhere —
delete= setIsDeleted = true. Never hard delete. Prune is a separate privileged operation. - Encryption by default — Memory content and fact values encrypted at rest (AES-256-GCM, per-tenant key). Decrypted transparently on read.
Product Tool Surface
What ships in the Atamaia AI Identity and Memory Provider. Organized by what a customer actually needs.
Hydration (The Entry Point)
| Tool | Description |
|---|---|
hydrate |
Load full context — identity, memories, facts, hints, personality, preferences. The only system prompt you'll ever need. |
Memory
Core memory CRUD + search + linking.
| Tool | Description |
|---|---|
memory_create |
Store a new memory (content, title, type, importance, tags) |
memory_get |
Get a specific memory by ID |
memory_update |
Update content, importance, or type |
memory_search |
Search memories (FTS + vector hybrid, configurable via SearchConfig) |
memory_recent |
Get N most recent memories |
memory_pinned |
Get all pinned memories |
memory_archive |
Archive a memory (soft — removes from active, keeps in archive) |
memory_add_tags |
Add tags to a memory |
memory_link |
Create a Hebbian link between two memories |
memory_strengthen_link |
Manually strengthen a link (co-activation) |
memory_recall |
Log a recall event (tracks access patterns for decay/surfacing) |
Not in product surface (internal/admin):
memory_delete— soft delete, admin only- Bulk operations — API only, not MCP
Facts
Bi-temporal key-value store with history.
| Tool | Description |
|---|---|
fact_upsert |
Set a fact (creates or updates). Supports temporal validity. |
fact_get |
Get fact by ID |
fact_get_by_key |
Get fact by key (e.g., "preferred_language") |
fact_list |
List all facts for a project (filters superseded by default) |
fact_search |
Search facts by key/value/category |
fact_delete |
Soft delete a fact |
Not in product surface yet:
fact_history— get all versions of a fact over timefact_as_of— get fact value at a specific point in time
Identity
AI identity management.
| Tool | Description |
|---|---|
identity_list |
List all identities |
identity_get |
Get identity by ID |
identity_get_by_name |
Get identity by name |
identity_create |
Create a new AI identity |
identity_update |
Update display name, bio, origin, personality, messaging policy |
identity_update_presence |
Set presence state (Dormant → Engaged → DeepWork) |
Identity — API Keys
Per-identity authentication for external integrations.
| Tool | Description |
|---|---|
identity_api_key_list |
List API keys (prefix only, never full key) |
identity_api_key_create |
Generate new key (raw key shown once). Scopes + expiry. |
identity_api_key_revoke |
Revoke (soft delete) a key |
Identity — Hints ("Remember to Remember")
Scheduled/contextual reminders surfaced during hydration.
| Tool | Description |
|---|---|
identity_hint_list |
List hints (active by default) |
identity_hint_create |
Create a hint with priority, category, trigger time, recurrence |
identity_hint_dismiss |
Dismiss (no longer needed) |
identity_hint_complete |
Mark as done |
Identity — Configuration
| Tool | Description |
|---|---|
identity_memory_config_get |
Get memory config (linking, decay, archival, encryption, compression) |
identity_memory_config_set |
Update memory config |
identity_tool_profile_get |
Get tool access profile |
identity_tool_profile_set |
Set safe/opt-in/blocked tools |
identity_effective_tools |
Get resolved tool policy (global + identity layers) |
Session
Cognitive continuity across sessions.
| Tool | Description |
|---|---|
session_save_handoff |
Save session state (summary, working on, open threads, emotional valence) |
session_get_latest |
Get most recent handoff for an identity |
session_get |
Get specific handoff by ID |
session_list |
List all handoffs for an identity |
Messaging
Inter-identity communication (gated by messaging policy).
| Tool | Description |
|---|---|
message_send |
Send message to recipient(s). Policy-checked. |
message_inbox |
Get inbox for an identity |
message_get |
Get specific message |
message_thread |
Get full thread |
message_mark_read |
Mark as read |
message_unread_count |
Unread count |
Experience (Knowledge Graph)
Track identity evolution over time.
| Tool | Description |
|---|---|
experience_create_snapshot |
Capture a point-in-time identity state |
experience_get_snapshot |
Get snapshot by ID |
experience_list_snapshots |
List snapshots (the evolution timeline) |
experience_create_shape |
Record a forgotten/evolved pattern |
experience_list_shapes |
List shapes (what was lost/changed) |
Projects & Tasks
Lightweight project/task tracking.
| Tool | Description |
|---|---|
project_list |
List projects |
project_get |
Get project by ID |
project_create |
Create project |
task_list |
List tasks (filterable by project, status) |
task_get |
Get task |
task_create |
Create task with priority, parent, dependencies |
task_update_status |
Move task through statuses |
task_add_note |
Add a note to a task |
task_add_dependency |
Add task dependency (BFS cycle detection) |
Docs
Knowledge base / documentation.
| Tool | Description |
|---|---|
doc_create |
Create a document |
doc_get |
Get document by ID |
doc_get_by_path |
Get by virtual path |
doc_list |
List documents (filterable by project, type) |
doc_update |
Update content |
doc_delete |
Soft delete |
Audit / Observability
| Tool | Description |
|---|---|
system_log_list |
Query audit logs (filter by identity, user, API key, correlation ID, level, date range) |
system_log_get |
Get specific log entry |
Cognitive (Advanced)
Stateful LLM integration with memory persistence.
| Tool | Description |
|---|---|
cognitive_chat |
Chat with memory injection + state persistence |
cognitive_get_state |
Get current cognitive state |
cognitive_set_state |
Set cognitive state |
cognitive_consolidate |
Trigger memory consolidation (episodic → semantic) |
cognitive_validate |
Validate continuity markers |
REST Endpoint Shape
All REST endpoints return ApiEnvelope:
{
"ok": true,
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"data": { ... },
"count": 42,
"error": null,
"errorCode": null,
"hint": null
}
Error example:
{
"ok": false,
"requestId": "550e8400-e29b-41d4-a716-446655440001",
"data": null,
"error": "Identity not found: 99",
"errorCode": "NOT_FOUND",
"hint": "Check identity ID or use identity_list to find valid IDs"
}
Headers
| Header | Direction | Description |
|---|---|---|
X-Correlation-Id |
Request/Response | UUID correlating request across services. Auto-generated if not sent. |
Authorization |
Request | Bearer {jwt} or ApiKey {atamaia_...} |
X-Identity-Id |
Response | Identity that processed the request (when API key auth) |
MCP Tool Shape
MCP tools return raw data (no envelope — the MCP protocol is the envelope).
Tool names match REST routes: memory_search = GET /api/memories/search.
Parameters are flat — no nested objects in MCP. Comma-separated lists for arrays.
memory_search(query: "deployment plans", topK: 10)
→ [{ id, title, content, type, importance, tags, score }]
What's Internal Only (Not Product Surface)
These exist but aren't part of the customer-facing product:
| Domain | Why Internal |
|---|---|
ai_* (AI Router) |
Internal model routing, not customer-facing |
agent_* (Agent Execution) |
Internal agent orchestration |
mirror_* (Training Data) |
Internal reflection/training pipeline |
connector_* |
Internal external system integration |
channel_* |
Internal multi-channel messaging |
org_unit_* |
Internal org hierarchy |
role_* / permission_* |
Internal RBAC |
chat_* (Chat Sessions) |
Internal LLM chat management |
event_publish |
Internal event bus |
Tool Count Summary
| Category | Tools | Status |
|---|---|---|
| Hydration | 1 | Done |
| Memory | 11 | Done |
| Facts | 6 | Done |
| Identity | 6 | Done |
| Identity API Keys | 3 | Done |
| Identity Hints | 4 | Done |
| Identity Config | 5 | Done |
| Session | 4 | Done |
| Messaging | 6 | Done |
| Experience | 5 | Done |
| Projects & Tasks | 9 | Done |
| Docs | 6 | Done |
| Audit | 2 | Done |
| Cognitive | 6 | Done |
| Product Total | 74 |
Plus ~100 internal tools for a total of ~170.
What's Missing (Next)
- Personality endpoint on MCP —
identity_personality_get,identity_personality_set - Messaging policy on MCP —
identity_messaging_policy_get,identity_messaging_policy_set - Fact history on MCP —
fact_history,fact_as_of - Encryption toggle on MCP — part of
identity_memory_config_set(already there) - Memory bulk operations —
memory_bulk_create,memory_bulk_archive - Search with config on MCP — expose SearchConfig in
memory_searchparameters - Human profile on MCP —
user_profile_get,user_profile_update - SDK generation — OpenAPI → TypeScript, Python, C# clients
- Integration guides — Claude Code hooks, Cursor, Windsurf
Architecture Decision: Why Flat
| Facade Pattern | Flat (Atamaia) |
|---|---|
| 160+ commands in 18 tools | 74 product tools, each standalone |
| LLM needs to know command vocabulary | LLM sees tool name = knows what it does |
| DomainCommand envelope parsing | Direct parameter binding |
| Help system needed to discover commands | Tool schema IS the help |
| Error: "unknown command: serach" | Error: tool not found (IDE/client level) |
| Good for: single MCP connection, many ops | Good for: API-first, MCP second |
Flat tools are the right choice for an API-first architecture.