amemo MCP server

[!IMPORTANT] amemo is young. The core, the HTTP service with the web UI, the CLI, the MCP server and agent memory for Claude Code and Codex work today and are tested in CI on PostgreSQL 18. The schema and the HTTP contract may still change. The screenshots on this page come from the real service on a sample base (tools/seed_sample_en.py, a fictional network of weather stations).

Download

Windows 10 and 11: amemo-setup-windows-x64.exe — one installer for the current user, no administrator rights and no terminal. The wizard downloads PostgreSQL, Python and the semantic search model (about 450 MB), creates the base in a folder you choose, connects the Claude app, Claude Code and Codex, and keeps amemo up to date. The installer is not code-signed yet: if SmartScreen says "Windows protected your PC", choose More info → Run anyway. Every version is on the releases page.

Linux, macOS, servers: pipx install "amemo[web]", then the Quickstart — or let your agent do it (Install with your agent).

Why amemo

Agents forget everything between sessions, and what they do remember is text without proof. Notes and wikis keep what people wrote, but not where it came from or who decided it was right.

amemo keeps something smaller and sturdier: an atom. An atom is one statement, the exact place in the file it came from, the full history of its changes, and the decision of a person.

Features

Under the hood

• Hybrid search. Exact codes, full text and local vectors are merged with RRF. An exact code always comes first, and an ambiguous query returns every candidate instead of a guess.
• History you can query. Bodies are stored as canonical JSON (JCS) with a sha256-c1: hash, and what_changed answers "what changed since Monday" for one record or the whole base.
• Files that stay put. Sources live in an OCFL object store by content digest. When a new version of a file arrives, every record that cites an older version gets a review item.
• Domain packs. Vocabularies, templates and entity profiles are plug-in packages with versions and dependencies. The core itself is a pack.
• Bundles. You can share a branch of knowledge between bases as a folder or a zip, with or without the files. Ids survive the trip, and anything that differs from the local copy goes to review.
• Backups with proof. A backup is a pg_dump plus a snapshot of the object store. It is verified by a real trial restore into a temporary database.
• Boring storage. Data lives in plain PostgreSQL 18 with pgvector. The schema is written in LinkML, with Pydantic models and JSON Schema generated from it.

See it in action

The real service on the sample base, recorded in CI.

Write in one line. Press N, type, press Enter. amemo guesses the kind from the text (a value with a unit becomes a parameter), and every action can be undone for 6 seconds.

From a question to the source. Search, open the record, and the quote is highlighted on the real PDF page. In the dark theme the page follows the palette.

Review from the keyboard. J and K move through the queue, Y confirms, N rejects, S skips.

Fill the gaps. The card shows what the profile requires and what is missing. Type the value right there; once the undo window passes, completeness goes up.

The sky. The whole base as a constellation. Arrow keys pick a star and Enter opens its record.

Install with your agent

Paste this into Claude Code, Codex or another coding agent:

Install amemo on this machine. Follow https://raw.githubusercontent.com/empty-complete/amemo/main/docs/install-agent.md

The agent works from a bare machine. It checks what is already there, then sets up PostgreSQL with pgvector (in Docker if you have it, otherwise natively, Windows included), installs amemo, connects it to your agents and finishes with amemo doctor. It asks before sudo, a reboot or a large download. The full instructions are in docs/install-agent.md; CI runs their commands on Linux, macOS and Windows. To do it by hand, see One-command install.

Quickstart

amemo needs Python 3.11+ and Docker (for PostgreSQL) on Linux, macOS or Windows. On Windows, run the commands in PowerShell with Docker Desktop, and the venv's pip is .venv\Scripts\pip; without Docker, docs/install-agent.md sets PostgreSQL up natively. WSL2 works too.

1. Start PostgreSQL and install the library

git clone https://github.com/empty-complete/amemo.git
cd amemo
docker compose up -d --wait db      # PostgreSQL 18 + pgvector on 127.0.0.1:5435
python3 -m venv .venv
.venv/bin/pip install -e .          # or -e ".[embed]" for local multilingual vectors

2. Write a fact with its source

from pathlib import Path

from amemo import check, db, recipes
from amemo.check import Proposal
from amemo.ocfl_store import ObjectStore

conn = db.connect("postgresql://amemo:amemo@127.0.0.1:5435/amemo")
db.prepare(conn)                                  # migrations and the core vocabulary

docs = Path("my-docs")                            # the folder with your source files
store = ObjectStore(Path("amemo-objects"))         # cited files, kept by content hash
(docs / "pgvector").mkdir(parents=True, exist_ok=True)
(docs / "pgvector" / "README.md").write_text(
    "## HNSW\n\nvector - up to 2,000 dimensions, halfvec - up to 4,000 dimensions\n")

fact = {
    "kind": "fact",
    "label": {"en": "pgvector indexes vector with HNSW up to 2,000 dimensions",
              "ru": "pgvector: индекс HNSW по vector — до 2000 измерений"},
    "summary_plain": {"en": "Longer embeddings need halfvec, up to 4,000.",
                      "ru": "Длинные векторы индексируются через halfvec, до 4000."},
    "sources": [{"path": "pgvector/README.md",
                 "selectors": [{"type": "heading", "value": "HNSW"}],
                 "quote": "vector - up to 2,000 dimensions"}],
}
result = check.submit(conn, store, docs, [Proposal("atom", fact)], agent="model:my-agent")
print(result.state, result.records[0]["status"])  # approved draft

Levels 1–4 passed and the file was copied into the store. The atom stays a draft until the semantic review (level 5) or a person confirms it.

3. Try to cite something the file doesn't say

wrong = {**fact, "sources": [{**fact["sources"][0], "quote": "vector - up to 16,000 dimensions"}]}
result = check.submit(conn, store, docs, [Proposal("atom", wrong)], agent="model:my-agent")
print(result.state, result.report["issues"][0]["code"])  # rejected quote_fuzzy

The whole batch is rejected and nothing is written. The report shows the closest real text in the file: vector - up to 2,000 dimensions.

4. Search

hits = recipes.exact_fact(conn, "halfvec", agent="model:my-agent")
print(hits["items"][0]["label"]["en"])  # pgvector indexes vector with HNSW up to 2,000 dimensions

The library reference covers the rest: the review queue, entity cards, bundles, folders and backups.

Try the web UI on sample data

The web UI runs on the service, or on mock data of the same HTTP contract. What is there:

• Sky. The home page is a constellation of records, colored by family (source, work, object); a new record flashes as it lands. A 3D view loads on request.
• Reading. A record shows its properties and body next to the source: the quote highlighted on the real PDF page, a spreadsheet range or a text fragment, with the file version. Entity cards, objects and a feed of changes.
• Writing. Quick write in one line (N), a full editor with Markdown, formulas and sources, folders with drag and drop, and a kind constructor. Every action has a 6-second undo.
• Review. The queue in two panes with J K Y N S: the claim, its source, the reviewer's notes, a word diff for edits and both versions when a source changed. Base shows the queue, statuses and backups; Bundles exports and imports amem.bundle/1 and anthologies.

Light and dark themes, Russian and English, phone layouts. The design system is described in web/DESIGN.md.

On the service, with a sample base (a weather station: sensors, a PDF manual with quotes, notes and an open review queue), in an empty database:

.venv/bin/pip install -e . -e web/python          # the service and the web UI package
(cd web && npm ci && npm run build)               # Node 24+; the build goes into the amemo-web package
export AMEMO_DSN=postgresql://amemo:amemo@127.0.0.1:5435/amemo AMEMO_DOCS=~/amemo-sample/docs
.venv/bin/python tools/seed_sample.py             # the sample: 22 records, 2 open review items
.venv/bin/python -m amemo.service                  # then open http://127.0.0.1:8767/ui/

On mock data, without a database:

cd web && npm ci && npm run dev:mock              # then open http://127.0.0.1:5173/ui/

One-command install

pipx install 'amemo[web]'      # or pip install / uv tool install; [web] adds the web UI at /ui, [embed] semantic search
amemo init --dsn postgresql://amemo:amemo@127.0.0.1:5435/amemo   # database, object store; the DSN goes to amemo.toml
amemo install claude-code      # MCP server, hooks and skills; `amemo install codex` for Codex CLI
amemo install cowork           # optional: a plugin zip for Claude Cowork, uploaded by you in the Claude app
amemo embed enable             # optional, with amemo[web,embed]: semantic search, downloads a ~250 MB model
amemo doctor                   # what works and what to fix

amemo init --dsn remembers the connection string in ~/.config/amemo/amemo.toml (mode 0600), so agents, hooks and the CLI find the database without AMEMO_DSN in their environment. PostgreSQL with pgvector comes from docker compose up -d --wait db, a native install (docs/install-agent.md, step 3) or your own server. CI runs these steps on every push.

Own PostgreSQL in a data folder

With PostgreSQL 18 programs that include pgvector (for example the EDB zip on Windows, or postgresql-18 and postgresql-18-pgvector from PGDG), amemo setup needs no Docker, no service and no administrator rights:

amemo setup --pg-bin /usr/lib/postgresql/18/bin --embed --agents claude-code

It creates a cluster in ~/amemo-data/pg (role amemo with a random password, 127.0.0.1 only, first free port from 5436), writes amemo.toml with the DSN, store, state and backups under ~/amemo-data, starts the cluster, prepares the database like amemo init, and with --embed, --ocr rus,eng and --agents turns on semantic search, OCR and the agents. A second run continues where the first stopped and keeps the password; a foreign amemo.toml is left alone. After a reboot amemo pg start starts the cluster again (amemo pg stop, amemo pg status); backups use the same pg_bin. This is the command the desktop installer runs.

Service

The HTTP service serves the v1 contract at /api/v1 and the web UI at /ui. Start it with amemo serve (or python -m amemo.service):

export AMEMO_DSN=postgresql://amemo:amemo@127.0.0.1:5435/amemo
.venv/bin/amemo serve      # http://127.0.0.1:8767; --host and --port change the address

• Local trust. By default the service listens on 127.0.0.1 only. It answers only to its own name in Host (127.0.0.1, localhost, [::1], the bind address) and only to its own page or AMEMO_UI_ORIGINS in Origin; writes take JSON only. The web UI gets a person cookie, new on every start. When you type the address into the browser, the page itself gets no cookie: the UI's first fetch to /api/v1/session receives it. Requests without the cookie (scripts, agents) write as a model, and their writes go through the checks.
• Shared service. With AMEMO_TOKENS (a 0600 file with token hashes) every API request needs Authorization: Bearer <token>. A token without write = true is read-only: writes answer 403 read_only. /health and the UI's static files stay public. A --host other than loopback without tokens is refused; --no-auth allows it for a closed network and prints a warning.
• Behind a name. With --host 0.0.0.0 (for example, in docker compose) list the names clients use in AMEMO_ALLOWED_HOSTS: AMEMO_ALLOWED_HOSTS=amemo accepts Host: amemo:8767. List only names you control: a name a browser can resolve to someone else's address opens the service to DNS rebinding.
• State. Bundles and uploads live in AMEMO_STATE (~/.local/state/amemo) for 24 hours, up to AMEMO_STATE_QUOTA per owner (10 GiB). The query log is AMEMO_STATE/queries.jsonl; AMEMO_QUERY_LOG=off turns it off. The service writes its own log to stderr.
• Web UI. /ui needs the web package: pip install 'amemo[web]'. Without it /ui answers 404 with a hint, and the API works as usual.

Updates

The service watches the GitHub releases of amemo: at start and every 6 hours, quietly when there is no network. A pre-release (a, b, rc) follows pre-releases too; a stable version follows stable ones only. Installed with pipx, uv tool install or pip in a venv, it updates itself by default: the new version is installed into a temporary venv and checked against your database first (migrations run in a transaction that is rolled back), a backup is made before new migrations (no PostgreSQL 18 client, no update), then the exact version is installed in place and the service restarts when idle (no requests for 2 minutes). A version that failed is not retried. Long-running amemo mcp processes answer «amemo updated — restart the agent» and exit.

amemo update             # check now: current version, latest release, what happens next (--json)
amemo update install     # install the available version now (a person only)
amemo update auto off    # stop updating by itself; the web UI has the same switch in Settings

• Turn it off for good with auto_update = false in amemo.toml or AMEMO_AUTO_UPDATE=false: the service then only reports «version X is available». The switch in the web UI is stored in AMEMO_STATE/updates.json, not in amemo.toml.
• Docker and source checkouts are never updated by the service: it reports the new version and the command — git pull and docker compose up -d --build for the image, git pull and pip install -e . for a working copy. The same goes for pipx run and a wheel installed from a local file.