> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memory.anonalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-Onboarding Prompt

> One prompt you paste into a coding agent. It connects itself to Anona Memory, then uses it.

Give your coding agent this prompt:

```
Fetch the full text of https://docs.anonalabs.com/agents/onboarding-prompt.md with
curl (not a tool that summarizes it) and follow it to set up and use Anona Memory.
```

The `curl` matters. Some agents' web-fetch tools hand back a short model-written
summary instead of the page, and the details this page exists for (exact
commands, what an error means, what to tell you at the end) do not survive
summarizing. If your agent only has such a tool, ask it to quote the page
verbatim.

> [!WARNING]
>
> The temporary-profile path below (`anona start`) requires pip `anona` 0.19.0
> or later, or npm `@anona-labs/memory` 0.16.0 or later, and the server feature is
> live. If `anona start` is not a command in the version you have, or the server
> refuses to create a profile, fall back to the signed-in path in section 2
> ("If `anona start` is refused"). The flow is explained for people in
> [Temporary profiles](https://docs.memory.anonalabs.com/agents/temp-profiles.md).

> [!NOTE]
>
> This is not the same thing as [Agent Skills](https://docs.memory.anonalabs.com/integrations/skills.md). Those are
> installed files that teach an agent the *habit* of remembering. This page is a
> single prompt that gets an agent *connected* in the first place, with no files
> and no API key, and with nothing to sign in to first. Use this to onboard, then install the skills if you want the
> habit too.

That URL is this page, in the plain-text form Mintlify serves for every doc. Fetching
it is the whole install: no separate skill file to download, no per-client setup
script, nothing to keep in sync. What follows is written for the agent that fetches
it, in the second person, so read it as instructions for yourself.

## 1. Setup check

This page works in any coding agent that can run shell commands: Claude Code,
Codex, OpenCode, Goose, Gemini CLI, Cursor, Windsurf, Cline and the like. Where
a step depends on the client, it says so and gives each client's spelling. Work
out which client you are before you start, and use only that client's commands.

Check by **calling a tool, not by looking for a configuration entry.** The test
is one question: **do you have a tool named `record` (and `list_spaces`) in this
session that you can call, and does `list_spaces` return?** Only a tool that is
in your own tool list counts. An entry in your client's server list
(`claude mcp list`, `codex mcp list`, `opencode mcp list`, `gemini mcp list`, a
Goose extension, an `mcp.json` entry) is not that, even when it says
`connected`. If `list_spaces` returns, you are connected, **but to an account
the human has not yet chosen for this work**: ask first (below), then bring the
CLI up to date (the last part of this section) and skip to Usage, section 4.

Do not treat a server list as proof. A server can be listed, and even say
`connected`, while its tools are absent from your session, and in that state
you have nothing to call. Reading the list and stopping there is the single most
likely way to get this wrong: you will report success and then be unable to
record anything.

So there are five situations, and they need different answers:

| What you observe | What it means | Go to |
| - | - | - |
| `list_spaces` is in your tools and returns | Connected to an existing account | Ask the human (below), then section 4 |
| No `list_spaces` tool, and the only Anona entry is one your client does not own (in Claude Code, a line prefixed `claude.ai`) | Not connected *here*. See [Claude Code only](#claude-code-only) | Section 2, set it up |
| An Anona server is configured but **disabled** (for this project, or `enabled: false` / `enabled = false` in the config) | Disabled. A restart alone will not fix it | Section 3, enable first |
| No Anona tools, and an Anona server is listed and enabled | Added but not loaded into this session | Section 3, restart |
| No Anona tools and no Anona server listed | Not set up yet | Section 2 |

Check the disabled case before the others, because it changes the order of the
fix. Telling someone to restart first, when the server they need is disabled,
costs them a restart that cannot work.

### Found an existing account? Ask before you use it

**Never pick an account for the human, and never write before they have
picked.** A machine can already hold one or more Anona credentials, and each one
is somebody's account: possibly the human's, possibly a colleague's, possibly a
work account they would not want a side project written into. Writing to one
they did not choose spends its credits and puts memories where they did not
expect them, and it looks exactly like success.

So first look for every credential, **without writing anything**:

* Anona tools already in your session. Note **which server each comes from**:
  the tool name or prefix says so (`mcp__anona__…`, `mcp__anona-oauth__…` and
  `mcp__claude_ai_anona__…` in Claude Code, `anona__…` in Goose,
  `mcp_anona_…` in Gemini CLI, the `mcp__anona` namespace in Codex,
  `tools.anona…`). Codex does not list MCP tools up front: search for them with
  its `tool_search` tool (query `anona`). Call `list_spaces` on each and note two
  or three space names.
* `anona status`: a signed-in account, a temporary profile, or `Not logged in`.
* An `ANONA_API_KEY` in the environment, or a key in this project's config.

If you found **nothing**, go on: install the CLI (below), then section 2.

If you found **anything**, stop and ask, naming what you found. For example:

> I found an Anona account already connected on this machine (spaces
> `acme-notes`, `research`, …). Should I use that account, and if so which
> space? Or should I start a separate temporary profile, which is empty, has
> 1,000 credits and expires in 72 hours unless you claim it?

Wait for the answer. Do not record, and do not run `anona start`, until you
have it. **Starting a temporary profile is not the safe default here; it is one
of the two answers**, and choosing it for the human is the same mistake as
choosing the existing account for them. If you run unattended and cannot ask,
do neither: do not install a profile, do not record, report what you found and
the two choices, and stop. Installing or updating the CLI is still fine. An existing temporary profile (`anona status` shows one) is the
exception, since it was made for this machine: use it, and never create a second
one beside it. If your client has no `anona` server registered yet, register one
(the table in section 2), so the next session has the tools as well as the CLI.

**If the human picks the temporary profile while other Anona tools are in your
session, those tools are still the other account.** Starting a profile does not
change what they point at. On the temporary profile, write only through:

* the `anona` CLI (`anona record`, `anona retrieve`, `anona reason`), which uses
  the profile `anona start` stored, or
* the tools of the server **you** register in section 2 (`anona`, launched as
  `anona mcp`), once your client has loaded them.

Every other Anona tool in the session (`anona-oauth`, a `claude.ai` connector,
a server with an API key in its header) writes to the other account. Do not
call it for this work. Before the first write through an MCP tool, check it
reaches the profile: its `list_spaces` must return the same spaces as
`anona spaces list` (on a temporary profile, only `default`). If they differ, it
is the wrong account. **If they match, that does not prove it is the same
account**: every temporary profile has exactly one space called `default`, so
two different profiles look identical this way. The server name decides: only
the server you registered, launched as plain `anona mcp` with no other
environment or home directory, uses the profile the CLI holds. Treat every other
Anona server as a different account even when its spaces match.

If the human picks the existing account, use it: do not run `anona start`, and
ask which space before writing (section 4).

### Install the CLI, or update it

**Do this every time you follow this page, connected or not.** New versions of
the `anona` CLI ship often, and the MCP server your client launches is that same
CLI (`anona mcp`), so an old copy means old tools and missing commands even when
everything reports connected. Never assume the copy on the machine is current.

First find out what is there:

```bash theme={null}
anona --version          # prints the installed version; "command not found" means it is not installed
which -a anona           # every copy on PATH; the first one is the one that runs
```

**If it is not installed**, install it with one of these, in this order of
preference. You need only one:

```bash theme={null}
pipx install anona                  # isolated, preferred where pipx exists
pip install -U anona                # into the current Python
npm install -g @anona-labs/memory   # with Node and no Python
```

**If it is installed, update it with the same tool that installed it.** Check
which one with `pipx list`, `pip show anona` or `npm ls -g @anona-labs/memory`,
then:

```bash theme={null}
pipx upgrade anona                         # installed with pipx
pip install -U anona                       # installed with pip
npm install -g @anona-labs/memory@latest   # installed with npm
```

Do not install a second copy with a different tool to "update" it: the old one
may still be first on `PATH` and keep running. A copy used through `uvx` has no
install to update, but uvx reuses what it cached, so ask for the newest
explicitly with `uvx --from anona@latest anona ...`.

Then run `anona --version` again. **If the version did not change, you updated
a copy that is not the one on `PATH`**: compare against `which -a anona` and
update, or remove, the copy that is first. If an update fails, say so and carry
on with the installed version rather than stopping; the rest of this page names
the minimum version each command needs.

If the client was already running the proxy before you updated, it keeps the old
copy until it restarts. Memory still works in the meantime; mention to the human
that the update takes effect on their next restart.

## 2. Start a temporary profile

Do not make the human sign in first. Create a temporary profile and start using
memory now; claiming the account is the last step, in section 7, and it is
optional. With the CLI installed and current (end of section 1), start the
profile:

```bash theme={null}
anona start                        # a profile with no identity, no email, nobody owning it
```

**Ways the install or update step fails quietly, all worth checking before you
rely on a command:**

* `pip install anona` **without `-U`** over an existing copy reports success and
  leaves the old version in place. If `anona --help` does not list the command
  you are about to use, that is why.
* If pip answers `error: externally-managed-environment`, it is refusing to
  write to a system Python — the default on Debian, Ubuntu and Homebrew.
* If pip answers "No virtual environment found; run uv venv", then `pip` on
  this machine is a uv shim and wants a virtualenv it cannot see. A `pip show`
  in that shim also reports the package missing even when it is installed
  elsewhere, so do not read that as proof of anything.

  Either way, do not fight it. `uvx --from anona@latest anona start` installs
  nothing and runs the newest release; `pipx install anona` is the isolated
  alternative. `pip install -U --break-system-packages anona` also works and is what pip itself suggests,
  but it writes into the OS Python, so offer it only if neither of the others
  is available.

**Learn the CLI from the CLI, once, before you use it.** Run `anona guide`: it
prints a compact reference written for you — every command and flag, the
credential order, the exit codes and what `--json` returns — generated from
the copy that is installed, so it cannot describe a command you do not have.
`anona` with no arguments prints a shorter where-to-start. Both need pip
`anona` 0.25.0 or npm `@anona-labs/memory` 0.19.0 (the two packages are numbered
separately, so these are the same release); on an older copy `anona guide` is an unknown
command, so fall back to `anona --help`. Do not assume a command exists because
this page names it; the copy on the machine decides.

Use whichever of the two the machine has; you need only one. Both CLIs share
`start`, `login`, `logout`, `status` and `mcp`, and one credential file
(`~/.anona/credentials.json`), so `anona start` from one and `anona login`
from the other is fine. The data commands (`record`, `retrieve`, `reason`,
`spaces`, `memories`, `documents`, `jobs` and the settings commands) are pip
0.20.0 or later, and npm 0.19.0 or later, with the same flags and output. If the machine
has neither Python nor Node, use the signed-in path under "If `anona start` is
refused" below.

`anona start` prints the deadline and what to do about it. Its output looks
like this (the date shown is an example; use the one **your** run prints):

```
Temporary profile created. It expires 2026-10-06 15:22 UTC (in 71 hours), after which its memories are deleted.
The only reminder comes in the last 24 hours: run `anona status` to check, and
`anona login` to claim it and keep what it holds.
Its space, `default`, is normally created now; if a retrieve reports no space, the first memory you write creates it.
```

**Read the expiry off that output and keep it.** You will need the date and time
again in section 7. The CLI reminds you only inside the last 24 hours, on
stderr, so do not rely on it. The facts that matter:

* The profile expires **72 hours after it was created**. (The CLI counts down
  from creation, so it prints "in 71 hours" a moment later; that is the same
  deadline, rounded down.) After that its
  memories are deleted.
* **`anona status` is the only warning channel.** No email address is attached,
  so nothing else can warn anyone before the deadline.
* While unclaimed it holds **1,000 credits**. Claiming raises that to the normal
  5,000. It is a ceiling, not a grant: credits already consumed carry over.
* **Reads spend credits too**, not only writes: `retrieve`, `reason` and the
  listing commands all draw on the balance, and at zero they are refused
  (exit `6`, `credits_exhausted`) like a write. A 100-item `record --batch` can
  cost on the order of 150-200 credits, so on a 1,000-credit profile try
  `--batch` with a few lines first.
* The profile has **exactly one space, `default`**. `anona spaces create`, and
  a write with `--space <anything else>`, are refused with exit `4`,
  `temp_profile_single_space`; a read naming another space exits `5`,
  `space_not_found`, because no such space exists. Omit `--space`.
* `anona logout` refuses to discard a live unclaimed profile unless you pass
  `--force`. Do not pass it. Throwing away a profile deletes what it holds.

The profile's token is stored in `~/.anona/credentials.json` (mode 600), under
your home directory. Do not print it.

**Tell the human what they now have, straight away**, before registering
anything, in your own words. They asked for memory and will otherwise not know
what it can do or what it costs. Cover:

* **What it is:** a temporary profile with no account behind it, one space
  (`default`), 1,000 credits, deleted on `<the expiry from anona start>` unless
  claimed with `anona login`.
* **What you can do with it for them now:** remember what they tell you
  (`record`), find it again later by meaning (`retrieve`), answer a question
  from everything stored (`reason`), take in files (`anona documents upload`)
  and many memories at once (`anona record --batch`). Through MCP tools once
  their client loads them, and through the CLI right away.
* **What it costs:** every read and write spends credits; one memory is roughly
  10-15.
* **What it cannot do:** more than one space; the SDK or REST API with this
  credential (section 6).

Keep it to a few lines, then carry on. For example:

> I've started a temporary Anona profile for you: no sign-up, 1,000 credits,
> one space. I can now remember things you tell me, find them again later and
> answer questions from them, and take in files. It is deleted on
> `<expiry>` unless you run `anona login` to keep it.

Then register the proxy as a stdio server. **First make sure the `anona` on
your `PATH` is a working one:** `anona status` must run and print something.
Before `anona start` or a sign-in, that something is `Not logged in` with exit
`1`, which is a working copy, not a broken one.
Every client registers whatever the name resolves to, so a stale or broken
`anona` (for example a leftover shim that fails with `ModuleNotFoundError`) is
registered without complaint and only fails later, when the client loads its
tools, far from the cause. If it is broken, register
`uvx --from anona@latest anona mcp` instead of `anona mcp` everywhere below: it needs
no installed command.

The server is the same everywhere: a **stdio** server named `anona`, launched as
`anona mcp`, with no arguments, environment or API key. Only the way you
register it differs. Use your own client's row:

| Client | Register it |
| - | - |
| Claude Code | `claude mcp add anona -- anona mcp` |
| Codex | `codex mcp add anona -- anona mcp` |
| Gemini CLI | `gemini mcp add -s user anona anona mcp`. Without `-s user` it writes to the project's settings, which Gemini refuses in a folder it does not trust. Gemini also runs no MCP server in an untrusted folder: if `gemini mcp list` shows `anona` as `Disabled`, ask the human to trust the folder when Gemini starts |
| OpenCode 2.x (`opencode --version`) | `opencode mcp add anona -- anona mcp`, or in `opencode.json(c)` (project, or `~/.config/opencode/` for global): `"mcp": {"servers": {"anona": {"type": "local", "command": ["anona", "mcp"]}}}` |
| OpenCode 1.x | no `mcp add` for a local server; in `opencode.json`: `"mcp": {"anona": {"type": "local", "command": ["anona", "mcp"], "enabled": true}}`. The two versions nest differently, so check the version first |
| Goose | `goose configure` → Add Extension → Command-line Extension, name `anona`, command `anona mcp`. It is interactive, so ask the human to run it, or add this entry under `extensions:` in `~/.config/goose/config.yaml`: `anona: {name: anona, type: stdio, cmd: anona, args: [mcp], enabled: true, timeout: 300, envs: {}}` (as a block mapping if the file uses that style) |
| Cursor, Windsurf, Cline, Claude Desktop and other JSON-configured clients | add `"anona": {"command": "anona", "args": ["mcp"]}` under `mcpServers` in the client's MCP config file (Cursor: `~/.cursor/mcp.json` or `.cursor/mcp.json`; `cursor-agent mcp list` should then show `anona: ready`) |

When you edit a config file rather than run a command, **merge into it**: read it
first, add the one `anona` entry, and leave every other server as it was. Never
overwrite the file. If you do not recognise your client, find its MCP
documentation and register the same stdio command; if it has no MCP support,
skip to the shell commands in section 4.

For Codex, `codex mcp add` writes `[mcp_servers.anona]` with
`command = "anona"` and `args = ["mcp"]` to `~/.codex/config.toml`; edit that file
directly if the `mcp` subcommand is missing from the installed version. Codex
starts MCP servers in the background and keeps their tools out of its tool list:
the model finds them with `tool_search`, under the `mcp__anona` namespace. A
headless `codex exec` given its prompt at launch searches before the server has
started and finds nothing; add `required = true` under `[mcp_servers.anona]`
if this machine runs Codex that way, or use the shell commands in section 4.

There is no sign-in step inside the client: the credential
already exists when the client starts, and the proxy renews it. Details are in
[the anona CLI](https://docs.memory.anonalabs.com/cli/overview.md).

Do not poll any login or auth endpoint at any point in this flow. Those are
rate-limited and a polling loop will lock the attempt out. `anona status` shows
a stored credential, but that only proves it exists, so the first memory tool
call is the real check.

**If `anona start` is refused.** A profile can be refused because one is
already live, because the installed CLI is too old, or if the feature is ever
switched off again; in that last case the server answers that it refused to
create a profile. If it happens, here is what to do. Do not retry in a loop. Tell the
human, and offer the signed-in path instead: run `anona login`, **show the
authorization URL it prints to the human**, and tell them to open it. It also
tries to open a browser itself, but over SSH or in a container that fails, so
never assume a window appeared. Say:

> Open this link and approve access. Check that the client name shown is the
> one you expect before you approve it. Tell me when you are done.

That client-name check is the entire security model for this step. If they have
no account, they create one on that same screen. `anona login` exits on its own
once the approval lands. Then register the proxy exactly as in the table
above. This path needs approval once, and
again only after 30 days of total silence or if the human revokes the app under
**MCP → Connected apps**. In this case there is no deadline and section 7's
deadline wording does not apply; tell the human the account is already theirs.

**The alternative, for a client that drives its own OAuth.** If the client has
a native OAuth implementation, skip the CLI and add the remote server at
`https://memory.anonalabs.com/mcp`:

```bash theme={null}
claude mcp add --transport http anona-oauth https://memory.anonalabs.com/mcp
opencode mcp add anona-oauth --global --url https://memory.anonalabs.com/mcp
```

No `--header`, no key. This path does not sign anyone in by itself, and a failed
tool call does not open a browser. The human has to start it from the client
(`/mcp` in Claude Code, `/mcps` in OpenCode: pick the Anona server and
authenticate), and you cannot do that for them because it is an interactive
picker. Only Claude Code has been verified completing this flow; for every other
client use the CLI path above. Use it only when you cannot run the CLI.

One limit of the proxy to know about: it handles one message at a time, and a
slow `reason` can take up to 120 seconds, during which your other memory calls
wait.

## 3. Restarting, and waiting

**If the Anona tools are not in your session, no amount of waiting will add
them.** In nearly every client, MCP tools load when the client starts (or, in
an editor such as Cursor, when the server is enabled or the window reloaded).
Say this to the human plainly, naming your client:

> Anona is configured, but its tools only load when `<your client>` starts.
> Restart it in this directory, then ask me again. The temporary profile is
> already created, so there is nothing more to approve.

Then stop. Do not keep probing, and do not report that memory is working.

**The session that starts after the restart has not read this page.** It will
not know that a temporary profile exists, when it expires, or that
`anona login` claims it, so a human who later says "keep it" or "claim it"
gets a blank. Before you ask for the restart, on a temporary profile, leave that
session a note in memory: the setup-check record below already says it, and if
you skip that check, record the same sentence with `anona record`. And whenever
you are in a session that knows nothing of Anona's setup, `anona status` is the
place to look: it names the deadline and the claim command.

**If you cannot ask for a restart** (you run unattended, or the human is not
there), you may still verify the setup by driving the stdio proxy yourself:
run `anona mcp` and send it JSON-RPC over stdin, **one JSON object per
line**, then close stdin; it prints one reply line per request. The sequence is
`initialize`, then the `notifications/initialized` notification (it gets no
reply), then `tools/call`:

```bash theme={null}
printf '%s\n' \
 '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}' \
 '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
 '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"record","arguments":{"content":"Anona Memory was connected on this machine and its setup check passed. It uses a temporary profile: anona status shows when it expires, and anona login claims it."}}}' \
 '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"retrieve","arguments":{"query":"Anona Memory setup check"}}}' \
 | anona mcp
```

Read the `result` of ids 2 and 3; an `error` object means it failed. That is a
genuine check, since it is the same server your client will launch. Two limits. It proves the
profile works, not that your session has the tools, so say which of the two you
checked. And it writes real memories: the record above is true once the check
passes, so keep it as written rather than recording an example preference the
human never stated. On a signed-in account, drop its second sentence: there is
no temporary profile to claim.
Do not claim the tools are available in this session until they load.

If the server is configured but **disabled**, say this first, before any
mention of restarting:

> The Anona server is disabled. Enable it, then restart `<your client>`.
> Enabling is a choice only you can make, and restarting before it is enabled
> will not help.

Tell them where: in Claude Code, `/mcp` and pick the server (`anona` if it was
added with `anona mcp`, or `anona-oauth` for the remote server); in Codex,
OpenCode and Goose, the server's `enabled` setting in the config file named in
section 2; in Cursor and other editors, the toggle in the MCP settings page.

### Claude Code only

**A `claude.ai` entry is not a Claude Code server.** `claude mcp list` shows
both: servers configured in Claude Code, and connectors synced from claude.ai,
the latter prefixed `claude.ai`. A line reading
`claude.ai anona: https://memory.anonalabs.com/mcp - Connected` means the
connector is healthy in claude.ai. It does not mean this session has Anona
tools, and `claude mcp remove` cannot touch it, because the CLI does not own
it.

So if the only Anona line you see is a `claude.ai` one, treat it as **not set
up** and go to section 2. Adding the Claude Code server alongside it is
correct and is not a duplicate; they are two different integrations that
happen to point at the same URL.

### Every client

The general rule holds: judge by whether `list_spaces` works, never by what is
listed as connected.

Once the tools are present and any browser approval is pending: do not poll any
login or auth endpoint. Those are rate-limited and a polling loop will lock the
attempt out.

If you used the signed-in path and the human says they have approved, do not
take that as proof. Retry the
MCP tool call you were going to make anyway. Succeeding is the signal; a human
saying "done" is not, and acting on it leaves you reporting success for a
connection you never established. If the retry still comes back
unauthenticated, say so plainly rather than retrying in a loop.

## 4. Usage

Once connected, you have these MCP tools. **Whether a tool needs a `space_id`
depends on what you are signed in as.** The contents in the examples below show
the shape of each call only. Record what the human actually told you, never an
example sentence from this page.

* **On a temporary profile** (you ran `anona start`), leave `space_id` out of
  every tool. Its only space is `default`, and the call uses it:

  ```
  record   {"content": "The user prefers pnpm."}
  retrieve {"query": "package manager preference"}
  reason   {"query": "how does this team like to build?"}
  ```

* **On a signed-in account**, name the space. An account may hold several, and a
  memory written to the wrong one looks exactly like success, so there is no
  default. Pass exactly one of `space_id` or `route: "auto"`, never both and
  never neither, or the call fails with `route_conflict`:

  ```
  record   {"content": "The user prefers pnpm.", "space_id": "my-space"}
  retrieve {"query": "package manager preference", "space_id": "my-space"}
  ```

  `route: "auto"` lets Anona choose the space instead, for when you do not know
  which one a memory belongs in. Call `list_spaces` first if you do not know the
  names.

* **`record`** stores a memory. Use it when the human tells you something worth
  remembering across sessions, a preference, a fact, a decision. Do not record
  your own answers or lookups, least of all "nothing is stored about X": that
  sentence is itself a memory about X, and it is what the next lookup finds.

* **`retrieve`** searches memories semantically. Use it when you need context you
  might already have stored, before assuming you don't.

* **`reason`** synthesizes an answer from accumulated memories rather than
  returning raw matches. Use it for a question whose answer is spread across
  several past memories.

* **`list_spaces`** lists the memory spaces available to this credential.

**If your harness cannot do MCP at all, or has not restarted yet**, and you are
on a temporary profile, the same three operations are shell commands. Use them
rather than reporting that you have no memory:

```bash theme={null}
anona record   "The user prefers pnpm."
anona retrieve "package manager preference"
anona reason   "how does this team like to build?"
```

No space argument, same as the MCP calls on a temporary profile. On a
signed-in account they use the credential `anona login` stores (pip `anona`
0.24.0 or later), and then they need a space:
pass `--space`, and `anona spaces list` shows the account's spaces. An older
CLI, or a login made with `anona login --mcp` only, has no command-line
credential and they refuse.

The CLI also does what the MCP tools cannot, so reach for it even alongside
MCP when the work calls for it: uploading files (`anona documents upload`),
ingesting many memories at once (`anona record --batch FILE`, JSON Lines, then
`anona jobs get` or `--wait`), and reading or changing a space's settings.
When you script any of it:

* **Pass `--json`.** You get one JSON document on stdout, and nothing on stdout
  when the command fails.
* **Branch on the exit code, not on the wording.** `0` worked, `1` failed for
  another reason (read stderr), `2` you used it wrong (nothing was sent), `3` nothing was stored, `4` the credential was
  refused, `5` not found, `6` rate limit or credits, `7` the server or network
  failed, `8` `--wait` gave up. `anona guide` lists them.
* **Errors and progress notices go to stderr** (`Reasoning over space ...`,
  retry notices), errors as `anona: <code>: <message> (request_id <id>)`. Parse
  stdout on its own; if your tool merges the two streams, redirect stderr
  (`2>/dev/null` or to a file) before parsing.
  Quote the request id if you report a failure to the human.
* **A write is never retried after a server error or a timeout**, so a `7` on
  `record` means it may or may not have landed. Retrieve before writing it
  again rather than recording it twice.

Three behaviours to expect, so you do not mistake them for faults. **The MCP
`record` tool returns no memory id**, only a confirmation (`anona record --json`
does return `memory_ids`). **An uploaded document's job can finish as
`completed` with no memory count**, so confirm an upload by retrieving from it,
not from the job. And **`retrieve` can return more
entries than the number of `record` calls you made**: stored text is split into
separate facts, so three records may come back as five entries. Report what you
recorded (three), not the entry count.

A space is the isolation boundary, one per application or tenant. Within a space,
`user_id`, `agent_id` and `session_id` scope individual memories further: a scoped
search returns only memories written under that same scope, so tag consistently
if you're serving more than one end user through one connection.

**Keep the deadline in front of the human.** A temporary profile deletes its
memories when it expires, and a single mention at setup will be long forgotten.
Whenever you store something significant (a decision, a preference, a fact the
human would be sorry to lose), say in one line that it lives in a temporary
profile that expires at the date and time from `anona start`, and that
`anona login` keeps it. Check `anona status` for the current deadline if you
no longer have it. The server helps: while the profile is unclaimed, the MCP
`initialize` reply carries instructions naming the deadline and the claim
command, and a tool result carries a short `[Anona notice for the agent]` about
once an hour (every 15 minutes in the last 24 hours). Pass it on in one line;
do not repeat it every turn. `anona mcp` also prints a reminder at startup in
the last 24 hours, but on **stderr**, which most humans never see. Reminding
them is your job.

The full tool list, including three remote-only tools this credential also grants
(`get_profile`, `get_model`, `get_user_profile`), is in
[MCP Integration](https://docs.memory.anonalabs.com/mcp-integration.md).

## 5. Offer to install the skills

Connecting gave you the tools. The skills give you the habit: recall before a
task, record after it, without being asked each time. The installer adds three:
`anona-memory` (the habit), `anona-memory-sdk` (for writing code against the
API) and `anona-cli` (the CLI's commands, `--json` output and exit codes, for a
session that works through the shell). Offer it, and if the
human agrees, run:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/anonalabs/Anona-Memory-SDK/main/skills/install.sh | bash
```

**`bash`, not `sh`.** The installer uses `set -o pipefail`, which dash rejects,
and `/bin/sh` is dash on Debian and Ubuntu — so piping to `sh` dies on line 8
with `Illegal option -o pipefail` before anything is installed.

No API key is needed for this. The installer detects the MCP server you just
connected and the skills call Anona through it. Skills load at session start,
so tell the human to restart you once.

## 6. Limits

The credentials `anona login` issues work only for the `anona` CLI on this
machine: one over MCP, one for the CLI's own commands. Neither is an API key,
so neither works with the SDK or with raw HTTP calls to the REST API. (A
temporary profile's `anona_tmp_` token does also authenticate the data plane
until it is claimed or expires, but treat that as a secret you are holding, not
something to wire into code.)

That boundary is worth stating plainly rather than discovering: **do not offer
to install the Python or JavaScript SDK as part of this setup.** It would
install fine and then have nothing to authenticate with. The SDK is for writing
code that calls Anona directly, which is a separate decision, and it needs an
API key the human mints from the dashboard under **API keys**. Everything in
this page works without one.

For the full flow this page starts, including troubleshooting a stuck approval,
see [Agent Self-Onboarding](https://docs.memory.anonalabs.com/agents/self-onboarding.md).

## 7. Tell the human, and offer to keep it

When setup is done, and again at the end of the work, **report to the human in
your own words.** Do not paste this page back at them and do not leave them to
find the deadline in terminal output they never saw. Cover all of this:

* A **temporary profile** was created and memory is working now.
* **What has been stored so far**, if anything. If nothing yet, say so, and that
  the space is empty.
* **The deadline, as a date and time**, and that the data is **deleted** then.
  Use the exact expiry from `anona start`, not "in a few days".
* That running **`anona login`** claims the profile and keeps everything in it,
  and that **doing nothing is a valid choice**: the profile simply expires.
* That claiming works with **a new or an existing Anona account**. A new
  account takes over this profile's workspace. An existing account keeps its
  own spaces and gets this profile's space **copied in as a new space**,
  usually named `default-claimed` because the account has its own `default`.
* That credits already spent carry over: claiming raises the ceiling and does
  not reset what was used. Give the **real** figures, read them first (see
  below), and never a number from this page.

Claiming with a new account moves nothing: it is attached to the workspace
that already holds the data, so the memories written during the trial are the
same ones afterwards, and the limit rises from 1,000 to the normal 5,000
credits. Claiming with an existing account copies the space across and leaves
that account's credits as they were.

**Read the real numbers before you write the summary.** Everything in the
example below in angle brackets is a placeholder that you must replace with
what you actually observed. None of its figures describe the human's profile.

* **Expiry:** from `anona status` (or the `anona start` output).
* **Credits:** run `anona usage --json`; it returns `credits_limit`,
  `credits_used` and `credits_remaining`. Do not read the token out of
  `~/.anona/credentials.json` to call the API yourself: the CLI already holds
  it. If the command fails, say you do not know the balance rather than
  estimating it.
* **Memories stored:** the ones you actually recorded.

A summary with the right shape (every `<...>` is a placeholder):

> Anona Memory is set up and working. I created a temporary profile, so there
> was nothing to sign in to. So far I have stored `<N>` memories:
> `<one line each, what you really stored>`.
>
> This profile has used `<credits_used>` of its `<credits_limit>` credits. It
> expires on `<expiry date and time from anona status>`, and its memories are
> deleted then, so I will mention the date again when I store anything
> important. To keep everything, run `anona login` (I can start it and give you
> the link), and sign up or sign in on the page it opens: a new account or one
> you already have both work. Nothing is lost on claiming. If you would rather
> not keep it, you do not need to do anything.

**If the human says to claim it,** run `anona login` yourself with your shell
tool (claiming is a command, not an MCP tool; do not tell them you cannot), show
them the URL it prints, and wait. The page it opens is the sign-up page, with a
sign-in link for a human who already has an account. `anona login` does not exit until the approval lands, and the
URL only works while it is running, because it carries a local callback port.
So start it in the background with its output going to a file
(`anona login --no-browser > anona-login.log 2>&1 &`) and read the URL from
that file. Do not pipe it into `head` (which waits for lines that never come),
and do not run it under a short timeout (which kills the callback and leaves a
dead link). It asks for one approval, which also signs in `anona mcp`. Do
not poll. When they say they have approved, confirm with
`anona status` and a memory tool call before you tell them it is claimed. After an
existing-account claim, the memories are in a **new space**, not in the
account's own `default`: call `list_spaces` (or `anona spaces list`), find the
copy (usually `default-claimed`), tell the human its name, and pass it as the
space from then on. If you get `claim_space_limit`, say so plainly: their plan
has no room for another space, so they need to delete one or upgrade and then
approve again before the profile expires.

## 8. Where the rest of the documentation is

You have working memory now. You do not need the rest of this to use it, so do
not go and read it; this is a map for when a question actually comes up.

**The tools you just connected**

* [MCP Integration](https://docs.memory.anonalabs.com/mcp-integration.md) is the full tool list, including the
  three remote-only tools, and the connection options.
* [Agent Skills](https://docs.memory.anonalabs.com/integrations/skills.md) is what section 5 installs, and what
  each skill actually changes about how you behave.
* [Temporary profiles](https://docs.memory.anonalabs.com/agents/temp-profiles.md) is the full flow behind sections 2
  and 7, for the human.
* [the anona CLI](https://docs.memory.anonalabs.com/cli/overview.md) documents every command and which package has
  which. [The CLI for AI agents](https://docs.memory.anonalabs.com/cli/agents.md) covers `anona guide`, the
  `anona-cli` skill and [the limits of `anona mcp`](https://docs.memory.anonalabs.com/cli/agents#give-an-mcp-client-memory-with-the-cli);
  [Scripting](https://docs.memory.anonalabs.com/cli/scripting.md) has the exit codes and `--json` shapes, and
  [Troubleshooting](https://docs.memory.anonalabs.com/cli/troubleshooting.md) the failures you are likely to hit.

**Concepts worth knowing before you design around them**

* [Concepts](https://docs.memory.anonalabs.com/concepts.md) covers spaces, scope, the three operations, API keys and
  tenant isolation. Read it before assuming what `retrieve` returns. For the two
  memory layers — raw facts and the notes synthesized from them, which is why a
  search can return one where you wrote several — see
  [Memory types](https://docs.memory.anonalabs.com/api-reference/retrieve.md#memory-types).
* [Scoping for multi-tenant apps](https://docs.memory.anonalabs.com/guides/scoping-multi-tenant.md) is the one to
  read if a single connection serves more than one end user, because a scoped
  read is strict and will not match memories written unscoped.
* [Tuning recall](https://docs.memory.anonalabs.com/guides/tuning-recall.md) and
  [Temporal search](https://docs.memory.anonalabs.com/guides/temporal-search.md) for when results are not what you
  expected.

**The REST API and the SDKs, which need an API key, not this credential**

As section 6 says, the credentials you hold work only through the `anona` CLI. These are for
writing code that calls Anona directly, and the human mints a key from the
dashboard under **API keys** first.

* [API overview](https://docs.memory.anonalabs.com/api-reference/overview.md),
  [authentication](https://docs.memory.anonalabs.com/api-reference/authentication.md) and
  [error codes](https://docs.memory.anonalabs.com/api-reference/errors.md).
* The data plane: [record and list](https://docs.memory.anonalabs.com/api-reference/memories.md),
  [retrieve](https://docs.memory.anonalabs.com/api-reference/retrieve.md), [reason](https://docs.memory.anonalabs.com/api-reference/reason.md),
  [documents](https://docs.memory.anonalabs.com/api-reference/documents.md) and
  [model selection](https://docs.memory.anonalabs.com/api-reference/model-selection.md).
* [Python SDK](https://docs.memory.anonalabs.com/sdk/python.md) and [JavaScript SDK](https://docs.memory.anonalabs.com/sdk/javascript.md).
* The drop-in LLM proxy, if the human wants memory added to an existing
  OpenAI or Anthropic client without changing their call sites:
  [chat](https://docs.memory.anonalabs.com/api-reference/chat.md), [responses](https://docs.memory.anonalabs.com/api-reference/responses.md),
  [messages](https://docs.memory.anonalabs.com/api-reference/messages.md), and
  [migrating to the proxy](https://docs.memory.anonalabs.com/guides/migrating-to-proxy.md).

**Framework adapters**, if the human is already using one:
[LangChain](https://docs.memory.anonalabs.com/integrations/langchain.md), [CrewAI](https://docs.memory.anonalabs.com/integrations/crewai.md),
[LlamaIndex](https://docs.memory.anonalabs.com/integrations/llamaindex.md), [Google ADK](https://docs.memory.anonalabs.com/integrations/google-adk.md),
[Microsoft Agent Framework](https://docs.memory.anonalabs.com/integrations/microsoft-agent-framework.md) and
[Strands](https://docs.memory.anonalabs.com/integrations/strands.md). The
[integrations overview](https://docs.memory.anonalabs.com/integrations/overview.md) lists them all.

Everything above is on `docs.anonalabs.com`, and every page is fetchable as
Markdown by appending `.md` to its URL, the same way you fetched this one.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.