# Connect through Auto-Coder Gateway

Give Claude Code, Codex, WorkBuddy and other tools access to Sparse Agent Memory. Use CLI, MCP or a Skill to recall experience, read sources and save confirmed facts in the same project you manage on the website. This connection provides memory operations; your tool continues to run its own code.

## Device authorization (with the updated CLI)

You can sign in without copying a credential:

```sh
sparse-memory auth login
# Optional project suggestion; the browser still verifies your choice:
sparse-memory auth login --project Default
```

Open the printed link in your normal browser, sign in with Auto-Coder.Chat, compare the code and reported hostname, choose an existing project, then allow or deny. Access defaults to read-only and 30 days; choose read/write and 1–365 days when needed. The resulting named credential appears in the same Settings → CLI / MCP list and can be individually revoked.

For an Agent or a two-step flow:

```sh
sparse-memory auth login --no-wait
sparse-memory auth finish --wait 600s
sparse-memory auth status
sparse-memory auth logout
```

Pending expires after ten minutes. A wait timeout exits 7 and keeps pending; Ctrl+C exits 130 and keeps pending. Resume with `auth finish`; denial/expiry clears pending. `auth status` shows the source, account, project, credential name and expiry without secrets. Renew by authorizing again. Existing `login` below keeps its hidden paste prompt.

Both methods use the same existing private config; the latest successful login replaces that profile. The device secret is stored only in `<config-path>.pending` (0600, directory 0700; current-user ACL on Windows), never printed. Stdio MCP reuses the same saved project credential. Global `--config PRIVATE_FILE` / `--url HTTPS_ORIGIN` go before the command; auth subcommands also accept them afterwards. Credential priority is explicit `--config` > `SPARSE_MEMORY_TOKEN` > saved login. `SPARSE_MEMORY_CONFIG` selects the default file. `SPARSE_MEMORY_URL` selects a service origin but cannot send a saved credential to another service. There is no plaintext-token argument.

`auth logout` (also `logout`) revokes the effective server credential and deletes local login/pending. If revocation cannot be confirmed, local deletion still happens, the CLI warns to revoke on the website and exits nonzero. Use `auth logout --local-only` only when intentionally keeping the server credential. Unset any `SPARSE_MEMORY_TOKEN` in the parent shell separately. Website sign-out remains independent.

## 1. Create a scoped credential

Sign in, choose or create a project, then open [Settings → CLI / MCP](/#/settings/clients). Create a separate credential for each tool, with one project, read-only or read/write access, and an expiry. The credential is shown once. Paste it into the terminal login prompt. It cannot grant administrator or invitation privileges.

Existing projects work directly. Invitations are disabled by default, so new users register after verifying their Chat identity. First-time users need an invitation only when an administrator enables that policy. Configure a query model under Settings → Query service before using model-based retrieval.

### Use shared Team memory

Create or join a Team on the website, then select `Team · name` as the credential target. Read-only credentials access approved memories. Read/write credentials can submit proposals; by default the Owner must approve them on the website before publication. A response with `state: pending` and `published: false` is awaiting review. Use the Team page for updates, deletions and reviews.

CLI 1.1.0 also submits updates with `sparse-memory save --action update --entry-id entry_ID --expected-version 1 --text "Updated content"`. For deletion use `--action delete` with the same ID and version options. These operations still follow the review policy; they cannot approve proposals.

Leaving or removal revokes that member’s Team credentials and withdraws pending proposals. Rejoining requires new credentials. Personal-project credentials do not gain Team access automatically.

## 2. Install the CLI

macOS Apple Silicon, Linux x64 / ARM64 and Windows x64 use **1.2.0**, including device authorization. Intel Macs retain **1.1.0** and the existing `sparse-memory login` credential prompt. New macOS releases support Apple Silicon only. See the [platform release index](/downloads/releases.json) and the retained [Intel Mac 1.1.0 checksums](/downloads/1.1.0/SHA256SUMS).

macOS / Linux:

```sh
curl -fsS https://memory.sparse-agent.com/install.sh -o /tmp/sparse-memory-install.sh
sh /tmp/sparse-memory-install.sh --client all
```

Windows PowerShell:

```powershell
Invoke-WebRequest https://memory.sparse-agent.com/install.ps1 -OutFile "$env:TEMP\sparse-memory-install.ps1"
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:TEMP\sparse-memory-install.ps1" -Client all
```

The installer verifies SHA-256, installs in your user directory and keeps an existing binary as `.previous`. Available for macOS Intel / Apple Silicon, Linux x64 / ARM64 and Windows x64. Open a new terminal:

```sh
sparse-memory --help
sparse-memory login
sparse-memory projects
sparse-memory query "What are this project's deployment conventions?"
sparse-memory save --kind decision --title "Deployment convention" --text "Confirmed: validate in an isolated environment before publishing."
```

`login` hides credential input and stores it in `sparse-memory/config.json` under your system user configuration directory, with Unix mode 0600 or a current-user Windows ACL. Set `SPARSE_MEMORY_CONFIG` to use a separate configuration path. Never put credentials in arguments, project files or chat.

For manual installation choose your platform in the [release manifest](/downloads/releases.json), verify [SHA256SUMS](/downloads/1.2.0/SHA256SUMS), extract the archive and add the executable to PATH.

## 3. Connect MCP

The recommended local stdio connection reuses the CLI's private login. Client configuration contains no token.

Claude Code:

```sh
claude mcp add --transport stdio sparse-memory -- sparse-memory mcp
```

Codex:

```sh
codex mcp add sparse-memory -- sparse-memory mcp
```

In WorkBuddy or another stdio client, add an MCP server with command `sparse-memory` and argument `mcp`. If a desktop client cannot resolve PATH, use the installed executable's absolute path. Confirm five tools are listed: `memory_projects`, `memory_query`, `memory_read`, `memory_save`, `memory_status`.

Clients supporting remote Streamable HTTP can also use `https://memory.sparse-agent.com/mcp` with a Bearer credential in their private authentication settings. This endpoint uses independent credentials. Clients that require OAuth discovery should use stdio instead. Never place credentials in URLs.

## 4. Teach your client with a Skill

```sh
sparse-memory integrate --client codex
sparse-memory integrate --client claude
sparse-memory integrate --client workbuddy
```

Codex uses `~/.agents/skills/sparse-memory/SKILL.md`; Claude Code uses `~/.claude/skills/sparse-memory/SKILL.md`. For WorkBuddy the command creates an import ZIP and prints its path. Import and enable it in your version's Skills UI, then start a new task. You can also download the [WorkBuddy Skill ZIP](/downloads/1.2.0/workbuddy-sparse-memory.zip). Use `--skills-dir DIR` only with a confirmed Skills directory. `--client all` prepares all three clients. A differing existing Skill is preserved and reported as a conflict. Installing Skills does not register MCP configuration automatically.

The Skill teaches tools to query first, read relevant sources, then save confirmed experience. Conversations and private client histories are not uploaded automatically.

## 5. Read, save and revoke

Read relative paths returned by queries with `sparse-memory read "relative/path"`. Continue long sources with `read --offset N "relative/path"`, using `next_offset`. Preserve incomplete or failed query status rather than claiming exhaustive recall.

Save kinds are `intent`, `change`, `howto`, `incident`, `decision`. Each fact allows 16000 UTF-8 bytes; `save --file note.txt` reads a text file. Saves append to the selected project, preserve existing content and deduplicate identical kind and text. Concurrent saves merge on the server. At capacity, export and organize the project on the website or choose another project.

`sparse-memory logout` revokes the selected credential and removes this machine's login. Signing out of the website does not revoke independent tool credentials. You can also revoke a credential in Settings → CLI / MCP to invalidate every copy. Expired or revoked credentials and disabled accounts are denied. Read-only credentials cannot save. Credentials cannot access other projects, accounts, host files or management APIs.

If the command is missing, open a new terminal or use its absolute path. For 401, create a new credential and log in. For 403, check permissions and account status. For retrieval failures, check query model settings. Do not save credentials, passwords, private conversations or unconfirmed information as shared memory.

[Full memory guide](/docs/memory?lang=en)

When a connection closes early, the CLI retries within its original timeout. Save retries reuse the identical input and remain deduplicated by the server.