Skip to main content
The quickest start is hosted: AmpUp runs the server, and you sign up and connect your agents. To run it yourself instead, skip to Install.

Hosted

1

Sign up

Open memory.ampup.ai and sign in with Google.
2

Create my memory

Press Create my memory. It makes your own AmpUp Memory org, with you as its admin, and signs you in to it. The Starter plan is free for 30 days, with 1,000 episodes and 2M model tokens a month. Invite your team once it is set up (Invite people).
3

Copy your key and the install line

Your memory is ready shows your personal key, first_key, only once: copy it to your password or secrets manager. It writes to your org’s memory as you, for 90 days. Below it are the lines to install.The command line:
Or Claude Code, typed in Claude Code:
/ampup-memory:login signs you in through the browser, so the plugin doesn’t need the key; the memory is on from the next session. With the command line installed, ampup-memory setup https://memory-api.ampup.ai signs you in the same way and sets up every coding agent it finds (Claude Code, Codex, Gemini CLI, Cursor, Copilot); add --dry-run to see what it would change first. Other MCP clients connect to https://memory-api.ampup.ai/mcp (MCP). The key is for a script or an app that isn’t an MCP client: send it to https://memory-api.ampup.ai as Authorization: Bearer <key>, with your org in x-memstore-org: <org> (HTTP API), or pass both to the Python or TypeScript client (from code). The console’s API keys page shows the exact lines for your org, and makes more keys and revokes them.

Run it yourself

From nothing to a running memory, a first note, a first search and a first piece of advice. Everything here runs on one machine with no cloud account.

1. Install

That installs ampup-memory (server and CLI) and ampup-memory-client into ~/.local/bin from the newest release, with only curl (or wget) and tar. Set AMPUP_MEMORY_INSTALL_DIR for another directory, or AMPUP_MEMORY_VERSION for a given release.

Or build from source

You need:
  • Rust, through rustup. The toolchain is pinned in rust-toolchain.toml (1.99.1) and installs itself on the first cargo command.
  • protoc (the Protocol Buffers compiler) on your PATH, as the CI builds install it (brew install protobuf, apt install protobuf-compiler).
  • macOS on Apple Silicon or Linux on arm64 or x86_64. The ONNX Runtime behind local embeddings is downloaded prebuilt during the build; there is none for Intel macOS.

2. Run it

Everything lives under ~/.ampup-memory (pass a directory to --local for another). Nobody signs in; the server binds to 127.0.0.1 only. curl localhost:8080/ready answers {"ready":true,…} once it has warmed up. With no model key, the server stores and searches but extracts, compiles and learns nothing. To turn the model work on, start it with a key:
AMPUP_MEMORY_EXTRACT_GOAL_BLIND=1 reads every episode into facts. Other providers (Anthropic, OpenAI-compatible, Bedrock, Vertex AI, a local Ollama) are in configuration.md.

Offline, on your laptop

Everything can run with no network and no key: embeddings with a small local model (bge-small, about 130 MB, the default when no embeddings key is set), and every model call (extracting, compiling, learning advice, judging, routing) through Ollama or any OpenAI-compatible server on your machine.
  • AMPUP_MEMORY_LLM=ollama sends every role to Ollama, on one model: AMPUP_MEMORY_LLM_MODEL names another (qwen2.5:7b or larger learns better advice, where the machine has the memory), AMPUP_MEMORY_LLM_URL another address. A role’s own variables (AMPUP_MEMORY_EXTRACT, AMPUP_MEMORY_ADVICE_MODEL, …) still win.
  • Ollama is called through its own API with a 32,768-token context (AMPUP_MEMORY_LLM_CONTEXT), so the longest prompts (60,000 characters) aren’t cut off: its OpenAI-compatible endpoint ignores a request’s context size, and its default is as low as 4,096 tokens on a machine with little memory.
  • Another local server (LM Studio, llama.cpp’s server, vLLM): AMPUP_MEMORY_LLM_URL=http://localhost:1234/v1 and AMPUP_MEMORY_LLM_MODEL=<its model>. Set the server’s own context to 32k tokens or more.
  • With a local model, no decisions model is asked (they are OpenAI’s and OpenRouter’s alone, and AMPUP_MEMORY_DECIDE still names one): kept notes are matched to a task by shared words, and the learning model sorts and merges advice alone.
  • HF_HUB_OFFLINE=1 never fetches the embedding model; AMPUP_MEMORY_MODEL_DIR (or HF_HOME) says where it is kept, and HF_ENDPOINT names a mirror to fetch it from. Until the model loads, searches rank by keyword alone rather than failing.
  • AMPUP_MEMORY_CLIENT_UPDATE=off keeps the hooks’ client from checking for a new release.
Run ampup-memory serve --local in a terminal with nothing configured and it asks once: paste an OpenRouter, OpenAI or Anthropic key, use the local Ollama (listing its models), or continue without learning. The answer is kept in ~/.ampup-memory/llm.json (delete it to be asked again); environment variables override it. A key typed there is not shown and only goes to that provider: embeddings stay local. Without a terminal nothing is asked, and the server says how to turn learning on.

3. A first memory

Passages (the text itself) are searchable at once, with or without a model:
Facts (POST /search) appear once a model has extracted them. Over MCP, search_memory shows both: the facts, and the source text no fact cites yet.

5. Connect an agent

The agent is offered start_session, end_session, search_memory, get_episode, remember_memory and forget_memory, plus get_advice once the server has a model. For hooks that drive the loop without the model choosing to, install the Claude Code plugin: coding-agents.md.

6. A first session and first advice

Advice needs a model key (step 2). Without one, POST /advice answers 503.
A new memory has nothing to serve yet: situation is null. Advice appears from one of two sources. Procedures compiled from your documents. Name the sources to compile, and get_advice serves the matching procedure before any runs exist. Notes sent to /remember are stored under the source mcp:remember_memory:<caller>:<source>, so this compiles every remembered note:
The server compiles new sources every AMPUP_MEMORY_COMPILE_SECS (60). Compiling runs on the learning model (Claude Opus 5.5 by default), so name sources narrowly. Notes learned from rewarded runs. Record runs with their outcomes, then learn:
Rules this example works around, on purpose:
  • A team note is learned only from runs of at least 2 people (AMPUP_MEMORY_ADVICE_LEARN_PEOPLE, default 3, never below 2). serve --local has one anonymous caller, so the runs are loaded as two people.
  • A situation needs at least 2 runs that went wrong (--min-wrong) or enough that went right.
On a running serve --local, the same happens on its own: rewarded sessions and runs come in, and every 10 minutes the server learns once 10 new rewarded ones are waiting. See advice.md. Not verified end to end for this guide: the compile and learn steps above (they call a paid model). The build, the server, /remember, the passage search, /sessions, /sessions/end, /runs, /runs/reward, runs load and the 503 from /advice without a model were run against this tree.

Next