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:

bash

npm install -g @agentage/cli

Everything below works fully offline. Signing in to a cloud account is optional - see Cloud account.

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 for the tool contracts.

bash

claude mcp add agentage-memory -- agentage mcp

Any other stdio MCP client works the same way - spawn agentage 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.

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.

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 and the read-only HTTP surface at api.agentage.io.
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.