Developers

Quick setup

Install, set up, then launch your agent. Choose a local install for one machine or follow the shared-server steps for a team.

Just me My team Check that it works

Just me

Install one binary, let it start one local server, then launch your agent. The server binds to 127.0.0.1:49374, so nothing outside this machine can reach it. A fresh install keeps its token in an owner-only file that the hooks and the CLI read, so you type none.

1
Install the binary
The script downloads the release for your OS and chip, checks it against the published .sha256 file and refuses to install without a match. It links ~/.local/bin/ai-memory and needs no root.
Terminal
```
curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/install.sh | sh
```
2
Set it up
setup creates the data directory and token, starts a per-user service and wires the agents you select. Use setup --plan to preview without changes, or setup --web to choose agents in a local browser page.
Terminal
```
ai-memory setup
```
3
Launch your agent through it
Restart your agents once. Launching claude directly keeps working afterwards.
Terminal
```
ai-memory run claude
```

1
Install the binary
mise downloads the release archive for your OS and chip and checks it against the published .sha256 file. It needs no Rust toolchain and no Docker.
Terminal
```
mise use -g github:akitaonrails/ai-memory
```
2
Create the data directory and start the server
init creates the data directory and its token file. serve has to stay running, so give it its own terminal. It listens on this machine only, and the hooks and the CLI read the token from the data directory.
Terminal
```
ai-memory init
ai-memory serve --transport http --bind 127.0.0.1:49374
```
3
Launch your agent through it
The first launch of a harness installs its hooks and MCP entry if they are missing. Launching claude directly keeps working afterwards.
Terminal
```
ai-memory run claude
```

1
Install the package
The -bin package is a prebuilt x86_64 or aarch64 binary. Both packages ship a user unit and a system unit for systemd.
Terminal
```
yay -S ai-memory-bin    # prebuilt Linux x86_64/aarch64 binary
yay -S ai-memory        # builds from source
```

Create the data directory

Terminal

mkdir -p ~/.config/ai-memory ~/.local/share/ai-memory
ai-memory --data-dir ~/.local/share/ai-memory \
  --config ~/.config/ai-memory/config.toml init

3
Start the user service
It needs no sudo, and all state stays in your home directory. The services section covers the system unit and running after logout.
Terminal
```
systemctl --user enable --now ai-memory.service
```
4
Launch your agent through it
Terminal
```
ai-memory run claude
```

1
Install the package
Download the x86_64 or aarch64 RPM from the release page. It carries the binary, the hook sources and the systemd units.
Terminal
```
sudo dnf install ./ai-memory-*.rpm
```

Create the data directory

Terminal

mkdir -p ~/.config/ai-memory ~/.local/share/ai-memory
ai-memory --data-dir ~/.local/share/ai-memory \
  --config ~/.config/ai-memory/config.toml init

3
Start the user service
It needs no sudo, and all state stays in your home directory. The services section covers the system unit and running after logout.
Terminal
```
systemctl --user enable --now ai-memory.service
```
4
Launch your agent through it
Terminal
```
ai-memory run claude
```

Download and extract

This archive is for Apple Silicon. On an Intel Mac, replace aarch64 with x86_64. A browser download needs xattr -d com.apple.quarantine ./ai-memory once. A curl download does not.

Terminal

mkdir -p ~/Applications/ai-memory && cd ~/Applications/ai-memory
curl -fsSL -O https://github.com/akitaonrails/ai-memory/releases/latest/download/ai-memory-macos-aarch64.tar.gz
tar -xzf ai-memory-macos-aarch64.tar.gz

2
Create the data directory and start the server
Leave serve running in this terminal. The launchd agent starts it at login instead.
Terminal
```
./ai-memory init
./ai-memory serve --transport http --bind 127.0.0.1:49374
```
3
Launch your agent through it
Keep the extracted binary where it is, because the hooks the first launch installs point at that path.
Terminal
```
cd ~/Applications/ai-memory
./ai-memory run claude
```

Install the wrapper script
The wrapper is a small shell script that lands in ~/.local/bin/ai-memory. The README has the install script, which checks the download against its SHA-256 file before installing it. Copy it from there.

Start the server

The image covers linux/amd64 and linux/arm64. On a Podman host, replace docker with podman. The wrapper uses rootless Podman on its own when Docker is not installed.

Terminal

docker run -d --name ai-memory \
    --restart unless-stopped \
    -p 127.0.0.1:49374:49374 \
    -v ai-memory-data:/data \
    docker.io/akitaonrails/ai-memory:latest

3
Launch your agent through it
The first launch wires hooks and MCP. On Linux/macOS the wrapper uses a verified native host client for normal hook installation. Explicit legacy shell-script hooks do not enforce per-repository capture exclusions.
Terminal
```
ai-memory run claude
```

1
Install in PowerShell
Native Windows remains experimental. The script verifies the release zip’s checksum, installs under %LOCALAPPDATA%\Programs\ai-memory and adds it to your user PATH, without administrator rights. For an agent inside WSL2, use the Linux steps inside that distro instead. Windows guide. Scoop installs the same zip from the maintainer's bucket; the download page has the two commands.
Terminal
```
irm https://github.com/akitaonrails/ai-memory/releases/latest/download/install.ps1 | iex
```
2
Set it up
setup creates the data directory and token, wires detected agents and starts a hidden server now and at each logon. It runs while you are signed in and restarts after failures, with a retry limit.
Terminal
```
ai-memory setup
```
Restart your agents
Ask an agent what it remembers about this project. For a server that runs before anyone signs in, use the WinSW recipe in the Windows guide.

Install

Start the server

127.0.0.1:49374

Run your agent

hooks / MCP

The whole solo path. The server stays on loopback, and your agent reaches it two ways: hooks capture the session, MCP lets the agent search it.

ai-memory run is the way to start an agent. It wires the harness on first launch, picks the right project scope and adds session resume across harnesses. An agent started directly still captures through its hooks, but you forget nothing by going through the launcher. Read how managed launches work.

Check that it works

Three checks, from the network up to the agent.

The server answers

On a fresh authenticated install, this unauthenticated request should return HTTP 401 with “auth required”. That proves reachability only. The next check tests authenticated CLI access.

Terminal

curl -i http://127.0.0.1:49374/mcp

The CLI reaches it

The CLI is a thin HTTP client. If this prints a status, hooks can reach the server too.

Terminal

ai-memory status

The agent remembers

In a non-sensitive project, ask the first agent to save a specific project decision. End the session, start another supported agent in the same directory, then ask for that decision and the saved page that supports it.

“What project decision did I save, and which memory page records it?”

After the first agent

All three are optional. Do them when you need them.

Add another agent

Launch it once through ai-memory and it is wired. Both agents then share one project memory.

Terminal

ai-memory run codex

See every supported agent and its name

Optional: better summaries with an LLM

Capture, search and rule-based summaries work without a provider. Adding one enables richer summaries and scheduled auto-improvement, which auto-applies validated edits by default. On shared servers set [auto_improve] require_approval = true. Set the variables below in the server environment and restart.

server environment

AI_MEMORY_LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

Compare providers, including subscriptions and local models

Undo everything

This removes only what ai-memory installed. Install commands are idempotent, and each one writes a timestamped backup next to any file it touches.

Terminal

ai-memory uninstall --apply

My team

One server that every machine and every teammate reaches. There is no replication between servers: shared memory means everyone connects to the same one.

alice

bob

carol

One shared server

Token

One wiki for the team

One API key each

The server holds the wiki. People get accounts, machines get API keys, and the root token stays with whoever runs the server.

Start the server behind a local proxy

Install the native CLI on the server host first. These commands publish Docker only on loopback and set root credentials for the CLI in this shell. Replace memory.example.com with your domain. Keep the root token private; laptops get individual keys later.

on the server

ROOT_TOKEN=$(ai-memory generate-auth-token)
export AI_MEMORY_SERVER_URL="http://127.0.0.1:49374"
export AI_MEMORY_AUTH_TOKEN="$ROOT_TOKEN"
docker run -d --name ai-memory \
    --restart unless-stopped \
    -p 127.0.0.1:49374:49374 \
    -v ai-memory-data:/data \
    -e AI_MEMORY_AUTH_TOKEN="$ROOT_TOKEN" \
    -e AI_MEMORY_AUTH__SECURE_COOKIE=true \
    -e AI_MEMORY_ALLOWED_HOSTS="memory.example.com,localhost,127.0.0.1" \
    akitaonrails/ai-memory:latest

Configure and verify TLS before connecting clients
Put a reverse proxy on the same host, forwarding HTTPS for your domain to 127.0.0.1:49374. Follow the TLS setup and verify the certificate from a laptop before sending keys. A bearer token authenticates; it does not encrypt traffic.
3
Create the people
Use the server shell where the root environment variables are still exported. The temporary password prints once and must be changed at first login. This command does not issue an API key. The users guide covers root identity and browser login setup.
Terminal
```
ai-memory user add-human --username alice --email alice@home --name "Alice Smith"
```
4
Give each person an API key
The aim_ secret is shown once. ai-memory api-key rotate <id> and ai-memory api-key revoke <id> take effect immediately.
Terminal
```
ai-memory api-key add --username alice --label codex-laptop
```

Point each machine at the server

Install the CLI on each laptop. Replace the domain and key below with your HTTPS endpoint and this person’s issued key. The hook installer stores the token in an owner-only file on Unix; generated hook commands do not contain it. --as-user labels the install and grants no permissions.

on every laptop

# Replace the placeholder with this person’s issued aim_ key; never use ROOT_TOKEN
USER_API_KEY='aim_REPLACE_WITH_ISSUED_KEY'
export AI_MEMORY_SERVER_URL="https://memory.example.com"
export AI_MEMORY_AUTH_TOKEN="$USER_API_KEY"

ai-memory install-mcp   --client claude-code --apply
ai-memory install-hooks --apply --agent claude-code \
    --as-user alice --auth-token "$USER_API_KEY"

# then launch as usual
ai-memory run claude

Stuck on a step?

The install cookbook on GitHub has the per-agent commands, remote servers and Windows. The issue tracker is open.

Install now Star it on GitHub

Just me

Install the binary

Set it up

Launch your agent through it

Install the binary

Create the data directory and start the server

Launch your agent through it

Install the package

Create the data directory

Start the user service

Launch your agent through it

Install the package

Create the data directory

Start the user service

Launch your agent through it

Download and extract

Create the data directory and start the server

Launch your agent through it

Install the wrapper script

Start the server

Launch your agent through it

Install in PowerShell

Set it up

Restart your agents

Check that it works

The server answers

The CLI reaches it

The agent remembers

After the first agent

Add another agent

Optional: better summaries with an LLM

Undo everything

My team

Start the server behind a local proxy

Configure and verify TLS before connecting clients

Create the people

Give each person an API key

Point each machine at the server

Keep reading

Advanced setup

Integrations

Security

Stuck on a step?