CLI & Editor Integration

Atamaia is the memory and identity layer for AI-powered development tools. Three ways in, one service layer:

atamaia CLI      ──► REST API ──► services ──► PostgreSQL
generated skills ──► atamaia-call ──► REST API ──► …
MCP clients    ──► /mcp adapter ──► same services

D12: REST is the source of truth. MCP and skills are wrappers. See docs-mcp-integration.md.

Canonical API host: https://api.atamaia.ai. Local default for the CLI is not that host.

`atamaia` (the CLI)

Atamaia.Cli packs as a .NET tool named atamaia (0.4.0, net10).

Renamed 2026-08-27. The command was forge until 0.4.0 — the last thing in the platform still carrying the pre-rename name. If you have the old tool installed, replace it: dotnet tool uninstall --global Forge.Cli && dotnet tool install --global Atamaia.Cli. Note ~/.dotnet/tools is not on this box's PATH; ~/bin/atamaia symlinks to it.

atamaia [--json] [--url <base>] <command> [subcommand] [args]

Base URL resolution (AtamaiaClient.ResolveBaseUrl):

--url / --url=
ATAMAIA_URL
http://localhost:5000

That default is deliberate. The CLI writes. A wrong guess writes to the wrong database. atamaia-call (skills) defaults the other way — prod — because it is read-mostly and lives next to a token.

Auth: atamaia auth login <user> <pass> stores a JWT under ~/.atamaia/token.json. Commands that need a session say so.

`atamaia acp` — dispatching work to another harness

acp run sends a brief to a foreign coding harness (opencode) over ACP; acp watch and acp ps show what a dispatch is doing while it runs. Merged 2026-08-27 from acp-cli-bridge, replacing the python prototype at ~/bin/acp-run.

atamaia acp run   --brief <file> --cwd <dir> [--identity <name> | --no-mcp]
                  [--model <id>] [--mode plan|build] [--trace <file>] [--json]
atamaia acp watch [--trace <file> | --session <id>] [--follow] [--tail N]
atamaia acp ps    [--all]

--mode plan disallows all edit tools and is the default. A plan-mode worker therefore cannot write REPORT.md, which the worker contract requires — pick one per dispatch, do not leave it implicit.
cwd is the sandbox. Anything outside it is rejected unless --allow-outside names it.
--trace is what makes a run observable; without it acp watch has nothing to read, and a dispatch buffers its narration until it exits.
acp ps probes liveness — a run whose process is gone reports ORPHAN, not running.

Commands the help actually lists

Area	Verbs
Probe	`health`, `status`
Context	`hydrate [name]` (default name in help: `ash`), `ask <query>`
Auth	`bootstrap`, `login`, `me`, `register`
Board	`project` / `proj`, `task` (list/get/create/status/dep/note)
Knowledge	`doc`, `fact`, `memory` / `mem`
People	`user`, `identity` / `id`, `org` / `ou`, `role`
Comms	`message` / `msg`, `chat`, `session` / `handoff`
Platform	`ai`, `agent`, `mirror`, `connector`, `log`
Meta	`skills generate`, `watch`, `help`

--json prints raw unwrapped payloads (the client peels ApiEnvelope and list items so callers see what they were written against).

Known CLI lag (do not paper over)

Command	What the CLI sends	What prod requires
`atamaia task create <proj> <title>`	title, optional desc/parent/priority	`kind` + `subsystem` required at `TaskService.CreateAsync`. This command will 400 until the CLI grows those flags. Use MCP `task_create` or REST. `docs-tasks.md`.
`atamaia exp snapshot\|snapshots\|shape\|shapes`	`/api/identities/{id}/snapshots`, `/shapes`	Those REST routes are gone (HTTP 404). The subcommands are still in `ShowHelp`.
`atamaia memory create`	field `type`	Correct.

Do not document atamaia task create as a working classified-create path.

Generated skills

atamaia skills generate walks this deployment’s /api/help contract and writes Agent Skills (SKILL.md) to both:

.agents/skills/ (opencode, Codex, …)
.claude/skills/ (Claude Code)

One emitter, portable subset of agentskills.io: name + description required; no $ARGUMENTS / $1 shell templating (those disagree across clients and were an injection hole).

Curated set (default, not --all):

Skill directory	Domain
`atamaia-memories`	Memories
`atamaia-facts`	Facts
`atamaia-tasks`	Tasks
`atamaia-docs`	Docs
`atamaia-projects`	Projects
`atamaia-identities`	Identities
`atamaia-hydration`	Hydration
`atamaia-ai-routing`	AIRouter

--all emits every domain in the contract. --check regenerates in memory, writes nothing, exits 1 on drift. --out DIR redirects. --domain NAME limits to one.

Each skill tells the agent to call atamaia-call (auth inherited). It is not a second implementation of the service.

The 2026-03-14 table of /hydrate, /mem-add, /task-add, /ask-local, /cognitive-status is not what this generator ships. Those were per-invocation slash files. Do not install them as the product skill set.

MCP-aware editors

Recommended path. The adapter, hot/cold split, and .mcp.json shape are docs-mcp-integration.md. The verb list is docs-tool-surface.md (~50 hot tools, not 74).

{
  "mcpServers": {
    "atamaia": {
      "type": "url",
      "url": "https://api.atamaia.ai/mcp",
      "headers": {
        "Authorization": "Bearer atamaia_YOUR_KEY"
      }
    }
  }
}

Same block works for Cursor and any client that speaks Streamable HTTP MCP. Windsurf / VS Code Copilot: point the MCP panel at that URL and header. OpenAI-compatible HTTP clients should use REST (docs-sdk-api-guide.md), not invent a second MCP dialect.

There is no experience_create_snapshot tool. There is no cognitive_chat tool.

CLAUDE.md

## HYDRATE FIRST

Call `hydrate` before doing anything else.

Persist as you go:
- `memory_create` (`type`, not `memoryType`)
- `fact_upsert`
- `task_create` with `kind` and `subsystem`
- `rule_check` before acting; `rule_propose` only drafts
- `session_save_handoff` before you leave

Hooks (optional)

If you inject hydration without MCP, call REST GET (not POST):

curl -s "https://api.atamaia.ai/api/hydrate?preset=lean" \
  -H "Authorization: Bearer $ATAMAIA_API_KEY"

Claude Code's hook format is owned by Anthropic and changes independently of Atamaia. Check the current Claude Code documentation for hooks.session_start / inject_as: system_context before relying on the shape above — the 2026-03 hook JSON is an example, not a contract.

Hydration presets

Preset	Meaning
`lean` (default)	Interactive minus ProjectMemories, KeyFacts, ProjectFacts, CoreTeamDoc
`interactive`	Everything except GroundingMessage
`all`	Everything except Privacy
`agent-minimal` / `agent`	IdentityMemories, KeyFacts, ProjectFacts, ActiveProjects, CurrentTasks, Hints

lean does not include key facts or project facts. Pull those on demand. Response now includes standingRules and systemHealth. Full section list: docs-mcp-integration.md.

emotionalValence on a handoff is a float, not "focused".

Troubleshooting

Problem	Fix
`401 Unauthorized`	Key must be `Authorization: Bearer atamaia_...` (or a JWT). Not `ApiKey`, not `atm_`, not `X-Api-Key`.
MCP tools not showing	`.mcp.json` in the project root; URL `https://api.atamaia.ai/mcp`; session mode (stateless 400s on `Mcp-Session-Id`, #252).
Hydration empty	Identity API keys hydrate the caller’s identity if `aiName` is omitted. `identity_list` for valid names. Empty-success on a missing identity is a known failure mode the MCP tool now fails loudly on.
`atamaia` talks to the wrong box	It defaults to localhost. Set `--url` or `ATAMAIA_URL`. Skills’ `atamaia-call` defaults to prod.
`atamaia task create` 400	CLI does not send `kind`/`subsystem`. Use MCP/REST.
`atamaia exp …` fails	Those REST routes are gone.
Skills look unlike `/mem-add`	Correct. Regenerate with `atamaia skills generate`.
`atamaia-call` not found	On PATH from the skill install; not the same binary as `atamaia`.