Skip to main content
From a checkout of the ampup-memory repository 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. Build

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.
There are no public release binaries yet.

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