# CLI

Your memory in the terminal - plain markdown folders on your disk, searchable and editable offline, served to every AI on your machine over local MCP, and synced to a git remote you control. Everything works offline; the cloud is optional.

## Install

Needs Node 22 or newer. Install with the one-line script, or straight from npm:

**npm**

```bash
npm install -g @agentage/cli
```

**install script**

```bash
curl -fsSL https://agentage.io/install.sh | bash
```

> Everything below works fully offline. Signing in to a cloud account is optional - see [Cloud account](#cloud).

## Quickstart

From nothing to your notes on disk, no sign-in required:

```bash
agentage vault add notes --local            # register a vault at ~/vaults/notes
echo "# My first note" | agentage memory write welcome.md --vault notes
agentage memory list --vault notes
agentage memory search "first" --vault notes
agentage memory read @notes/welcome.md
```

Each vault is a plain folder of `.md` files backed by git; every write commits, so nothing is lost and deletes stay recoverable from history.

## Vaults

A vault is a registered folder of markdown. Add a local folder, or one wired to a git remote you control - the files always live on your disk:

```bash
agentage vault add notes --local             # ~/vaults/notes by default
agentage vault add archive --local ~/archive # or an explicit path
agentage vault add work --git git@github.com:you/memory.git
agentage vault list
agentage vault remove work                   # unregister; files + git history stay on disk
```

Address a document as `@<vault>/<path>`, or as `<path> --vault <name>`; with a single vault (or a `default` set in `vaults.json`) you can drop the vault entirely. `vault remove` only unregisters a vault - your markdown and its git history are left untouched on disk.

## Working with memory

Six verbs over your local vaults - the same operations every connected AI uses. Add `--json` to any verb for machine-readable output.

```bash
agentage memory search <query...>   # search a vault (git grep); --limit <n> (default 20)
agentage memory read <ref>          # print a document
agentage memory write <ref>         # create or overwrite (--body <text>, or stdin)
agentage memory edit <ref>          # --old/--new (str_replace), or --body (--append)
agentage memory list [folder]       # list documents, optionally under a folder
agentage memory delete <ref>        # delete (recoverable from git history)
```

`write` reads the body from `--body`, or from stdin when you pass `--body -` or omit it; add `--frontmatter` to set YAML frontmatter as a JSON object:

```bash
agentage memory write work/plan.md --vault notes --body "Q3 focus is search."
echo "# Draft" | agentage memory write drafts/idea.md --vault notes
agentage memory write pinned.md --vault notes --frontmatter '{"tags":["pinned"]}' --body "Roadmap"
```

`edit` does an exact, unique-substring replace with `--old`/`--new`, or replaces (or appends to) the whole body with `--body` `[--append]`:

```bash
agentage memory edit @notes/work/plan.md --old "search" --new "full-text search"
agentage memory edit @notes/work/plan.md --body "- shipped" --append
```

> **How the engine behaves**
>
> Every vault is a git working copy, so each write is a commit and a `delete` is recoverable from history - nothing is silently lost. Search is `git grep`: literal substring matching, so search one distinctive keyword, not a phrase. Reads clamp at 64 KB, and the engine refuses to store obvious secrets like API keys and tokens.

## Connect your AI (local MCP)

`agentage mcp` serves your local vaults to any AI on this machine over **stdio**, exposing the same frozen six `memory__*` tools as the cloud endpoint. Point a client at it by spawning the command - see the [MCP tools reference](/docs/mcp-tools) for the tool contracts.

**Claude Code**

Register the stdio server in one command:

```bash
claude mcp add agentage-memory -- agentage mcp
```

Any other stdio MCP client works the same way - spawn `agentage mcp`.

**Cursor**

Add the server to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "agentage-memory": {
      "command": "agentage",
      "args": ["mcp"]
    }
  }
}
```

**Any client**

Drop this into your client's MCP config (`.vscode/mcp.json`, a project `.mcp.json`, and the like):

```json
{
  "mcpServers": {
    "agentage-memory": {
      "command": "agentage",
      "args": ["mcp"]
    }
  }
}
```

Clients that speak Streamable HTTP can instead POST to the daemon's local endpoint `http://127.0.0.1:4243/mcp` (stateless; a GET returns 405). The full loopback surface is documented in the [local API](/docs/local-api).

> **Local routing, no auth**
>
> On this machine the tools address vaults directly: a `@<vault>/` prefix routes to that vault, and `memory__list` at the root shows each vault as a top-level folder. The loopback socket has no auth - it is bound to `127.0.0.1` and never exposed to the network. For AI outside this machine, use the cloud endpoint `memory.agentage.io/mcp`.

## Git sync

A `--git` vault is a local working copy wired to a remote you control. The daemon commits and pushes your changes and pulls remote ones on an interval - `interval` seconds per origin (default 300; `0` = manual only). Trigger a round yourself with `vault sync`:

```bash
agentage vault add work --git git@github.com:you/memory.git
agentage vault sync            # sync every git-backed vault now
agentage vault sync work       # just one
```

Your local write is always saved first: an unreachable remote never blocks a read or write, and a conflicting remote edit lands beside yours as `<file>.conflict.md` instead of overwriting it - no write is ever lost.

By default `.obsidian/` and `data.json` are kept out of sync. Set `interval` and an `ignore` list per origin in `vaults.json`; a set `ignore` **replaces** those defaults (gitignore syntax), and an empty list syncs everything:

```json
{
  "version": 1,
  "vaults": {
    "work": {
      "path": "~/vaults/work",
      "origin": [
        {
          "remote": "git@github.com:you/memory.git",
          "interval": 900,
          "ignore": [".obsidian/", "*.tmp"]
        }
      ]
    }
  }
}
```

_~/.agentage/vaults.json_

## The daemon

One small background process (loopback only, `http://127.0.0.1:4243` by default) owns the engine so vault writes are serialized and git sync runs in the background. It autostarts on the first memory verb and restarts itself after an update; you rarely touch it directly.

```bash
agentage daemon status         # pid, uptime, version, per-vault sync state
agentage daemon start          # start it explicitly (idempotent)
agentage daemon stop           # stop it
```

To skip the daemon and run verbs in-process, pass `--no-daemon` or set `AGENTAGE_NO_DAEMON=1`. It also serves a JSON HTTP API on the same port for local scripts and tools - see the [local API](/docs/local-api).

## Cloud account

Optionally sign in to connect this machine to your agentage account over OAuth 2.1 (PKCE) - no password touches the terminal, no API key to copy. Every memory verb above works fully offline without it.

```bash
agentage setup                 # browser OAuth sign-in, then prints status
agentage setup --no-browser    # print the sign-in URL instead of opening a browser
agentage setup --reauth        # force a fresh sign-in
agentage setup --disconnect    # sign out and remove local credentials
agentage status                # CLI version, target, sign-in state (--json)
```

Tokens are stored in `~/.agentage/auth.json` (mode `0600`).

## Staying current

```bash
agentage update                # install the latest published version
agentage update --check        # report whether an update is available
```

`status` also surfaces a passive hint, at most once an hour, when a newer version is available.

## Environment

Override the defaults with environment variables:

| Variable | Purpose | Default |
| --- | --- | --- |
| `AGENTAGE_CONFIG_DIR` | Config + credentials dir (`auth.json`, `vaults.json`, daemon state) | `~/.agentage` |
| `AGENTAGE_DAEMON_PORT` | Local daemon port | `4243` |
| `AGENTAGE_NO_DAEMON` | Set to `1` to run memory verbs in-process | unset |
| `AGENTAGE_SITE_FQDN` | Cloud target host | `agentage.io` |

## What it is not

- Not a cloud client - reads and writes hit local files first; the cloud MCP endpoint is at [memory.agentage.io/mcp](/docs/mcp-server) and the read-only HTTP surface at [api.agentage.io](/docs/rest-api).
- Not another database - vaults are ordinary folders; uninstall the CLI and your markdown is still there.
- No API keys - one optional sign-in, the same account as every other agentage surface.