Metadata-Version: 2.4
Name: amemo
Version: 0.1.0a5
Summary: Verifiable shared memory for AI agents and people: atoms with checked source quotes, revisions and review on PostgreSQL + pgvector
Author: empty-complete
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://github.com/empty-complete/amemo
Project-URL: Source, https://github.com/empty-complete/amemo
Project-URL: Issues, https://github.com/empty-complete/amemo/issues
Keywords: agent-memory,claude-memory,knowledge-base,mcp-server,pgvector,postgresql
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pymupdf>=1.24
Requires-Dist: rapidfuzz>=3.0
Requires-Dist: pydantic<3,>=2.13
Requires-Dist: pyyaml>=6
Requires-Dist: psycopg[binary]<4,>=3.2
Requires-Dist: pgvector<1,>=0.5.1
Requires-Dist: rfc8785==0.1.4
Requires-Dist: ucumvert==0.3.2
Requires-Dist: pint<0.26,>=0.25
Requires-Dist: openpyxl>=3.1
Requires-Dist: packaging>=23
Requires-Dist: starlette<2,>=1.10
Requires-Dist: anyio>=4.1
Requires-Dist: uvicorn>=0.30
Requires-Dist: psycopg-pool<4,>=3.2
Requires-Dist: python-multipart>=0.0.20
Requires-Dist: mcp<2.4,>=2.3
Requires-Dist: mcp-types<2.4,>=2.3
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.14; extra == "dev"
Requires-Dist: linkml==1.12.1; extra == "dev"
Requires-Dist: linkml-runtime==1.12.1; extra == "dev"
Requires-Dist: jsonschema>=4.20; extra == "dev"
Requires-Dist: ocfl-py==2.1.0; extra == "dev"
Requires-Dist: httpx2>=2.0; extra == "dev"
Requires-Dist: openapi-spec-validator>=0.8.4; extra == "dev"
Provides-Extra: embed
Requires-Dist: fastembed<0.10,>=0.9.1; extra == "embed"
Provides-Extra: web
Requires-Dist: amemo-web==0.1.0a5; extra == "web"

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/empty-complete/amemo/v0.1.0a5/docs/assets/readme/banner-dark.svg">
    <img alt="amemo — another memory" src="https://raw.githubusercontent.com/empty-complete/amemo/v0.1.0a5/docs/assets/readme/banner-light.svg" width="100%">
  </picture>
</p>

<h3 align="center">Shared memory for people and AI agents, where every claim comes with its proof.</h3>

<p align="center">
  An open knowledge base of small, sourced statements. Agents propose, automatic checks find
  the quote in the actual file, and a human has the final word.
</p>

<p align="center">
  <a href="https://github.com/empty-complete/amemo/actions/workflows/ci.yml"><img alt="Tests" src="https://img.shields.io/github/actions/workflow/status/empty-complete/amemo/ci.yml?branch=main&label=tests&style=flat-square"></a>
  <a href="https://github.com/empty-complete/amemo/actions/workflows/web.yml"><img alt="Web UI" src="https://img.shields.io/github/actions/workflow/status/empty-complete/amemo/web.yml?branch=main&label=web%20ui&style=flat-square"></a>
  <a href="https://github.com/empty-complete/amemo/blob/v0.1.0a5/LICENSE.txt"><img alt="License: AGPL-3.0" src="https://img.shields.io/badge/license-AGPL--3.0-2a78d6?style=flat-square"></a>
  <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-3776ab?style=flat-square&logo=python&logoColor=white">
  <img alt="PostgreSQL 18 with pgvector" src="https://img.shields.io/badge/PostgreSQL-18%20%C2%B7%20pgvector-4169e1?style=flat-square&logo=postgresql&logoColor=white">
  <img alt="Status: early development" src="https://img.shields.io/badge/status-early%20development-eb6834?style=flat-square">
</p>

<p align="center">
  <a href="#download"><b>Download</b></a> ·
  <a href="#install-with-your-agent"><b>Install</b></a> ·
  <a href="#see-it-in-action"><b>Demo</b></a> ·
  <a href="#quickstart"><b>Quickstart</b></a> ·
  <a href="#features"><b>Features</b></a> ·
  <a href="#how-it-works"><b>How it works</b></a> ·
  <a href="#roadmap"><b>Roadmap</b></a> ·
  <a href="https://github.com/empty-complete/amemo/blob/v0.1.0a5/docs/library.md"><b>Docs</b></a> ·
  <a href="https://github.com/empty-complete/amemo/blob/v0.1.0a5/docs/MANIFESTO.md"><b>Manifesto</b></a> ·
  <a href="https://github.com/empty-complete/amemo/blob/v0.1.0a5/README.ru.md"><b>Русский</b></a>
</p>

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/empty-complete/amemo/v0.1.0a5/docs/assets/readme/en/sky-dark.png">
    <img alt="The sky: the whole sample base as a constellation of records and objects, with folders and family filters" src="https://raw.githubusercontent.com/empty-complete/amemo/v0.1.0a5/docs/assets/readme/en/sky-light.png" width="100%">
  </picture>
</p>

> [!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](https://github.com/empty-complete/amemo/releases/download/updates/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](https://github.com/empty-complete/amemo/releases).

**Linux, macOS, servers:** `pipx install "amemo[web]"`, then the [Quickstart](#quickstart) — or let your agent do it
([Install with your agent](#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.

<table>
  <tr>
    <td width="50%" valign="top">
      <b>Every claim has a source</b><br>
      A quote is checked against the real text of the file: a page in a PDF, a heading in Markdown,
      a cell range in a spreadsheet.
    </td>
    <td width="50%" valign="top">
      <b>Nothing is overwritten</b><br>
      Every change is a new revision with a reason, an author and a content hash. Mistakes are
      superseded, not erased.
    </td>
  </tr>
  <tr>
    <td width="50%" valign="top">
      <b>Checks run on every write</b><br>
      Schema, units, the quote, common sense and duplicates are checked before anything lands.
      A failed batch writes nothing.
    </td>
    <td width="50%" valign="top">
      <b>The human decides</b><br>
      Agents propose and pre-verify. Accepting a claim into the canon is a person's call, and the
      system shows who made it.
    </td>
  </tr>
</table>

## Features

<table>
  <tr>
    <td width="50%" valign="top">
      <picture>
        <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/empty-complete/amemo/v0.1.0a5/docs/assets/readme/en/record-dark.png">
        <img alt="A record page with the quote highlighted on the source page" src="https://raw.githubusercontent.com/empty-complete/amemo/v0.1.0a5/docs/assets/readme/en/record-light.png">
      </picture>
      <h3>A claim next to its proof</h3>
      A record reads like a note: properties, a Markdown body and the quote highlighted on the real page
      of the source file. Cited files are stored once by content hash and kept forever.
    </td>
    <td width="50%" valign="top">
      <picture>
        <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/empty-complete/amemo/v0.1.0a5/docs/assets/readme/en/review-dark.png">
        <img alt="The review queue with the claim, the quote and the decision buttons" src="https://raw.githubusercontent.com/empty-complete/amemo/v0.1.0a5/docs/assets/readme/en/review-light.png">
      </picture>
      <h3>Review in one keystroke</h3>
      Anything doubtful, risky or changed lands in a queue. Each item shows the claim, the quote and
      its neighbours. <kbd>Y</kbd> confirms, <kbd>N</kbd> rejects, <kbd>J</kbd>/<kbd>K</kbd> move on, and
      parallel reviewers never get the same item.
    </td>
  </tr>
  <tr>
    <td width="50%" valign="top">
      <picture>
        <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/empty-complete/amemo/v0.1.0a5/docs/assets/readme/en/card-dark.png">
        <img alt="An entity card: completeness, grouped parameters with known, missing and conflicting values" src="https://raw.githubusercontent.com/empty-complete/amemo/v0.1.0a5/docs/assets/readme/en/card-light.png">
      </picture>
      <h3>Entity cards</h3>
      A profile says which parameters an object needs. The card shows what is known, missing or in
      conflict, and it is built live from atoms, so nothing goes stale.
    </td>
    <td width="50%" valign="top">
      <picture>
        <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/empty-complete/amemo/v0.1.0a5/docs/assets/readme/en/agent-dark.png">
        <img alt="An agent session over MCP: amemo_search, amemo_get with the source quote, amemo_helpful" src="https://raw.githubusercontent.com/empty-complete/amemo/v0.1.0a5/docs/assets/readme/en/agent-light.png">
      </picture>
      <h3>Memory for agents</h3>
      Claude Code and Codex ask amemo first. They read short cards, fetch only the records they need, and
      mark what helped, which costs fewer tokens than reading raw files.
    </td>
  </tr>
</table>

**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 <kbd>N</kbd>, type, press <kbd>Enter</kbd>. amemo guesses the kind from the text
(a value with a unit becomes a parameter), and every action can be undone for 6 seconds.

<img alt="Quick write: N opens a one-line field, the text ends with a value and a unit, the kind turns into a parameter, Enter saves it with an Undo toast" src="https://raw.githubusercontent.com/empty-complete/amemo/v0.1.0a5/docs/assets/readme/en/demo-write.gif" width="100%">

**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.

<img alt="Search for humidity accuracy, open the TH-20 record, the quote is highlighted on the PDF page, then the theme switches to dark" src="https://raw.githubusercontent.com/empty-complete/amemo/v0.1.0a5/docs/assets/readme/en/demo-source.gif" width="100%">

**Review from the keyboard.** <kbd>J</kbd> and <kbd>K</kbd> move through the queue, <kbd>Y</kbd> confirms,
<kbd>N</kbd> rejects, <kbd>S</kbd> skips.

<img alt="The review queue: J moves down twice, Y confirms the claim, a toast offers Undo and the next item opens" src="https://raw.githubusercontent.com/empty-complete/amemo/v0.1.0a5/docs/assets/readme/en/demo-review.gif" width="100%">

**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.

<img alt="The WS-100 station card: Needed on power consumption, 2.4 W typed in, the value lands and completeness grows" src="https://raw.githubusercontent.com/empty-complete/amemo/v0.1.0a5/docs/assets/readme/en/demo-card.gif" width="100%">

**The sky.** The whole base as a constellation. Arrow keys pick a star and <kbd>Enter</kbd> opens its record.

<img alt="The sky lays itself out, arrow keys select stars, and Enter opens a record with its quoted source" src="https://raw.githubusercontent.com/empty-complete/amemo/v0.1.0a5/docs/assets/readme/en/demo-sky.gif" width="100%">

## Install with your agent

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

```text
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`](https://github.com/empty-complete/amemo/blob/v0.1.0a5/docs/install-agent.md); CI runs their commands on Linux, macOS and Windows.
To do it by hand, see [One-command install](#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`](https://github.com/empty-complete/amemo/blob/v0.1.0a5/docs/install-agent.md) sets PostgreSQL up natively. WSL2 works too.

**1. Start PostgreSQL and install the library**

```bash
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**

```python
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**

```python
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**

```python
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](https://github.com/empty-complete/amemo/blob/v0.1.0a5/docs/library.md) 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`](https://github.com/empty-complete/amemo/blob/v0.1.0a5/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:

```bash
.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:

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

### One-command install

```bash
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`](https://github.com/empty-complete/amemo/blob/v0.1.0a5/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:

```bash
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](https://github.com/empty-complete/amemo/blob/v0.1.0a5/docs/api/http-v1.openapi.yaml) at `/api/v1` and the web UI at `/ui`.
Start it with `amemo serve` (or `python -m amemo.service`):

```bash
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](https://github.com/empty-complete/amemo/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.

```bash
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.

## Writing from the web

A person writes in the web UI: a form for each kind, their own kinds, file uploads and tasks for agents.

- **Forms from templates.** `GET /templates` gives every atom kind and entity class a form, with or without its
  own template. Fields come from the template's rules, so the form asks for what `check.submit` will check. An
  optional `ui` block in a pack template sets the body, the widgets and the labels of fields; it does not change
  the checks:

  ```yaml
  code: reading
  version: 1.0.0
  target: atom
  applies_to: reading
  fields:
    - {path: about, required: true, entity_classes: [artifact]}
    - {path: content.values, required: true}
  ui:
    body: none                       # wanted | required | none
    widgets: [sources, values_table] # sources, links, around, values_table, similar, children
    fields:
      - {path: "content.values[property=humidity]", label: {ru: Влажность, en: Air humidity}}
  ```

- **My kinds.** A person adds a kind of their own from the web (`PUT /packs/mine/templates/{code}`). It lives in
  the database as the `mine` pack and passes the same checks as a pack from files, and so do its records. Every
  edit is a new version of the template; a code taken by a file pack is refused (`409 template_exists`). A kind
  can be deleted only while it has no records (`409 template_in_use`). Only a person edits and deletes kinds; a
  model gets `403 forbidden`. `POST /bundles/export` with `with_packs` takes your kinds along; the import adds
  the missing ones, and the same code with other content is a `bundle_pack_conflict`.
- **Uploads and search.** `POST /objects` (multipart `file`, optional `path`) puts a file into the documents
  folder `AMEMO_DOCS`, by default as `Загрузки/<file name>`, and parses it. The same file at that path answers
  `200`, another file there is `409 object_path_taken` and stays untouched, and without `AMEMO_DOCS` the answer is
  `503 docs_unavailable`. `GET /objects?q=` finds objects by part of the name or path.
- **Tasks for agents.** In the web a person asks an agent to parse a file (`POST /tasks`); a repeat returns the
  same task. The agent picks it up over MCP: `amemo_tasks` lists open tasks and its own, `amemo_task_claim` takes one
  with a 30-minute lease, `amemo_task_release` gives it back, and `amemo_task_done` closes it with the result
  (links to the records it wrote), and `amemo_task_cancel` cancels a task it set. An expired lease frees the task for
  another agent. `GET /tasks` and `amemo tasks list` show open and claimed tasks, newest first (`--state done` for
  the closed ones); `amemo tasks cancel ID` cancels one (the one who set it, or a person).

## Docker compose

`docker-compose.yml` runs the database and the service; settings live in `.env` (copy `.env.example`), the file
itself holds no secrets.

```bash
cp .env.example .env                          # set AMEMO_PG_PASSWORD and AMEMO_AGENT
docker compose up -d --wait amemo              # PostgreSQL 18 + pgvector and the service on http://127.0.0.1:8767
docker compose exec amemo amemo doctor
docker compose --profile web up -d --wait amemo-web   # the same with the web UI at /ui (instead of amemo)
```

- **Inside and outside.** The service listens on `0.0.0.0:8767` inside the compose network and is published only
  on `127.0.0.1:8767`. `AMEMO_ALLOWED_HOSTS=amemo` lets other containers call it as `http://amemo:8767`.
- **Login.** Without `AMEMO_TOKENS` the service runs with `--no-auth`: anyone who reaches the port writes as a model,
  so keep it on `127.0.0.1`. For a shared service issue a token
  (`docker compose exec amemo amemo token create person:me --file /var/lib/amemo/state/tokens`), set
  `AMEMO_TOKENS=/var/lib/amemo/state/tokens` in `.env` and restart.
- **Volumes.** `amemo-pg` (database), `amemo-objects` (object store), `amemo-state` (bundles, uploads, query log,
  tokens), `amemo-backups` (`docker compose exec amemo amemo backup create`; the image has the PostgreSQL 18 client).
  `AMEMO_DOCS_DIR` mounts your documents folder read-only.
- **Health.** Both the image and compose check `/health`; `docker compose up --wait` waits for it.
- **Profile `web`.** `amemo-web` is the same service built with `amemo[web]`. It shares the port and the volumes, so
  run either `amemo` or `amemo-web`.
- **Image.** `docker build -t amemo .` (target `service`) or `--target web`; `--build-arg AMEMO_EXTRAS=embed` adds
  fastembed for [semantic search](#semantic-search), which `docker compose exec amemo amemo embed enable --yes` then
  turns on. `AMEMO_OCR_LANGS="rus eng"` in `.env` builds an image that recognises scans ([OCR](#scanned-pdfs-ocr)).

## CLI

`pip install -e .` puts the `amemo` command in the venv. It talks to the database directly (`AMEMO_DSN` or
`amemo init --dsn …`, which remembers the DSN in `~/.config/amemo/amemo.toml`) and does not need the service.

```
amemo init [--dsn DSN] [--ocr LANGS]   database and object store; --ocr rus,eng — recognise scans
amemo setup --pg-bin DIR [--data DIR]  own PostgreSQL in a data folder, amemo.toml, database (--embed --ocr --agents)
amemo pg start|stop|status             the cluster amemo setup created
amemo serve [--host --port --no-auth]  HTTP API, /mcp and the web UI
amemo mcp [--agent model:NAME]         MCP server on stdio, for an agent
amemo search QUERY [--kind --limit]    search, step 1
amemo timeline REF                     what is around a record, step 2
amemo get REF...                       full records, step 3
amemo card REF                         entity card
amemo submit FILE.json                 write a batch (same body as POST /submit; "-" reads stdin)
amemo review list|claim|release|resolve|stats
amemo folders tree|create|delete|rename|move
amemo export|inspect|import FILE.zip   bundles (import is a dry run without --apply)
amemo backup create|list|restore|verify
amemo tasks list|cancel              tasks for agents
amemo token create|list|revoke         tokens of a shared service
amemo base [name [NAME]]               database summary and name
amemo ocr install|list|remove          languages for recognising scans (OCR)
amemo embed enable|status              semantic search: download the model, embed, switch on
amemo doctor [--project DIR]          database, store, model, documents, OCR, agents, service
```

- **Output.** Text for people, or `--json` with the same object the HTTP API returns for that operation.
  An error names what to do next: «set AMEMO_DSN or run amemo init».
- **Exit codes.** `0` success, `1` environment (no database, no store), `2` wrong call, `3` ambiguous text
  instead of a reference (the candidates are printed), `4` not found, `5` the check rejected the batch (the
  report is printed), `6` conflict (item already resolved, folder taken, bundle collision).
- **Who writes.** In a plain terminal it is the person `AMEMO_AGENT` (by default `person:` and your OS user name).
  When the environment belongs to an agent, the command runs as a model: `CLAUDECODE=1` — `model:claude-code`,
  the Codex sandbox variables — `model:codex`, `AMEMO_AS_MODEL=name` — `model:name`. `--agent` sets the agent
  explicitly, but never `person:` inside an agent's environment.
- **Tokens.** `amemo token create person:ann` (or `model:…`, `--read-only`) prints the token once and stores only
  its hash in `AMEMO_TOKENS`. Only a person issues and revokes tokens.
- **Backups.** A model may run `amemo backup create`, but without rotation: `--keep` and `restore` are for people.
- **Debugging.** `AMEMO_DEBUG=1` adds the traceback of an internal error to stderr.

## Scanned PDFs (OCR)

A scanned PDF page is an image without a text layer: a quote from it can be checked only after the page is
recognised. OCR in amemo is an optional extension: install Tesseract languages or don't. Without OCR everything
works, and scanned pages are reported as having no text.

```bash
amemo ocr install rus eng            # download languages and turn OCR on (or: amemo init --ocr rus,eng)
amemo ocr install deu --quality best # more accurate, several times larger files
amemo ocr list                       # mode, languages, data folder
amemo ocr remove deu
```

- **What is installed.** Recognition runs in the Tesseract library built into PyMuPDF: no `tesseract` binary is
  needed, only the `.traineddata` language files. `amemo ocr install` downloads them over HTTPS from
  [tessdata_fast](https://github.com/tesseract-ocr/tessdata_fast) (the default, `--quality fast`) or
  [tessdata_best](https://github.com/tesseract-ocr/tessdata_best) (`--quality best`) into `ocr_data`
  (`~/.local/share/amemo/tessdata`) and writes `ocr = "tesseract"` and `ocr_languages` to `amemo.toml`. Running it
  again downloads nothing; `--force` downloads anew.
- **Languages.** tessdata codes: `rus`, `eng`, `deu`, `fra`, `chi_sim`, … — any from the repository. `rus` and
  `eng` are recognised by default.
- **Settings.** `ocr` (`AMEMO_OCR`): `none` — do not recognise, `tesseract` — recognise; unset — Tesseract when its
  language data is found. `ocr_data` (`AMEMO_OCR_DATA`) is the language data folder; `ocr_languages`
  (`AMEMO_OCR_LANGUAGES`) the list of languages (in the environment separated by `+`, comma or space). A system
  Tesseract (`apt install tesseract-ocr-rus`, `brew install tesseract-lang`, `TESSDATA_PREFIX`) works too: it is
  used when `ocr_data` has none of the languages.
- **Who installs.** Only a person: a model gets exit code 2 from `amemo ocr install` and `remove`, since they
  change the installation.
- **Docker.** `AMEMO_OCR_LANGS="rus eng"` in `.env` (or `--build-arg OCR_LANGS="rus eng"`) downloads the languages
  while the image is built; empty — an image without OCR.
- **Checking.** `amemo doctor` shows an OCR line: mode, languages and folder, and warns when `ocr = "tesseract"`
  but there is no data.
- **Cloud.** Cloud recognition comes later: the value `ocr = "cloud"` is reserved and for now fails with «not
  supported yet».

## Semantic search

Codes and full-text search work out of the box. The semantic channel finds records by meaning, across languages,
and is an optional extension: a local multilingual model
(`sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2` through fastembed, about 250 MB) and a vector for
each record. Nothing leaves the machine, and the model is downloaded only when a person allows it.

```bash
uv tool install 'amemo[web,embed]'   # or pip install 'amemo[embed]': adds the fastembed package
amemo embed enable                   # asks, downloads the model, embeds every record, switches the channel on
amemo embed status                   # active model, how many records have a vector, what to do next
```

- **What `enable` does.** It checks the database and the package, then downloads the model into `AMEMO_MODELS`
  (by default `~/.local/share/amemo/models`; `FASTEMBED_CACHE_PATH` works too). It asks first; where nobody can
  answer (`--json`, scripts, CI) pass `--yes`, otherwise nothing is downloaded and the exit code is 2. Then it
  registers the model in the database, computes a vector for every current record and makes the model active.
- **New records.** A write does not compute its vector yet. Run `amemo embed enable` again now and then: it
  downloads nothing and embeds only the records added or changed since. `amemo embed status` shows how many lack a
  vector, and search results report the share as `embedding_coverage`.
- **Who enables.** Only a person: a model gets exit code 2 from `amemo embed enable`, since it downloads a model
  and changes the installation. `amemo embed status` is for everyone.
- **Turning it off.** `AMEMO_BACKEND=none` turns the semantic channel off; lexical search keeps working and results
  say `semantic: unavailable`.
- **Checking.** `amemo doctor` shows a «semantic search» line: the active model and its coverage, or why the
  channel is unavailable and which command fixes it.
- **Docker.** Build the image with `--build-arg AMEMO_EXTRAS=embed`, then run
  `docker compose exec amemo amemo embed enable --yes`. The image keeps the model on the `amemo-state` volume
  (`AMEMO_MODELS=/var/lib/amemo/state/models`), so it survives a rebuilt container.

## MCP

The MCP server gives an agent 19 tools over the same operations as the HTTP API:

| Tool | What it does |
|---|---|
| `amemo_search(query, kind?, limit?)` | Step 1: short hits `{ref, label, kind, status, snippet}` and a `retrieval_id` |
| `amemo_similar(query \| ref, limit?)` | Similar records, in the same form |
| `amemo_timeline(ref)` | Step 2: recent events of the record and its neighbors |
| `amemo_get(refs)` | Step 3: full records with body, sources, status and open items |
| `amemo_card(ref)` | Entity card `amem.card/1` |
| `amemo_submit(proposals, links?, reason?)` | Write a batch through `check.submit` |
| `amemo_helpful(retrieval_id, refs)` | Mark the atoms that helped |
| `amemo_move(ref, folder)` | Move a record to an existing folder |
| `amemo_object_status(path)`, `amemo_mark_object(path, status, note?)` | What has been atomized from a document |
| `amemo_review_claim`, `amemo_review_release`, `amemo_review_resolve` | For the semantic reviewer |
| `amemo_tasks(object?, limit?)` | Agent tasks: open ones and those you hold |
| `amemo_task_claim(task?, kind?)`, `amemo_task_release(task)`, `amemo_task_done(task, result?)`, `amemo_task_cancel(task)` | Take a task with a lease, give it back, close it with the result, cancel your own |
| `amemo_vocab(scheme)` | Vocabulary codes with labels |

Search goes in three steps so the agent reads only what it needs: `amemo_search` gives short cards,
`amemo_timeline` shows what is around a hit, and `amemo_get` returns the full records it picked. Text that matches
several records without a clear leader comes back as `ambiguous: true` with candidates, not as the first match.

**Over stdio.** `amemo mcp` runs one session per process with its own small connection pool. Claude Code:

```bash
claude mcp add amemo --env AMEMO_DSN=postgresql://amemo:amemo@127.0.0.1:5435/amemo -- amemo mcp --agent model:claude-code
```

or in the project's `.mcp.json`:

```json
{
  "mcpServers": {
    "amemo": {
      "command": "amemo",
      "args": ["mcp", "--agent", "model:claude-code"],
      "env": { "AMEMO_DSN": "postgresql://amemo:amemo@127.0.0.1:5435/amemo" }
    }
  }
}
```

Codex CLI, in `~/.codex/config.toml` (the DSN stays in `amemo.toml` or in the environment, not in this file):

```toml
[mcp_servers.amemo]
command = "amemo"
args = ["mcp", "--agent", "model:codex"]
env_vars = ["AMEMO_DSN", "AMEMO_CONFIG"]
```

**Over HTTP.** A running service serves the same tools at `/mcp` (Streamable HTTP):

```bash
claude mcp add --transport http amemo http://127.0.0.1:8767/mcp --header "X-Amemo-Agent: model:claude-code"
```

```toml
[mcp_servers.amemo]
url = "http://127.0.0.1:8767/mcp"
http_headers = { "X-Amemo-Agent" = "model:codex" }
```

- **Always a model.** An MCP client writes as `model:…`, and its writes go through the checks. Over stdio the
  agent comes from `--agent model:…` or the agent's environment; over `/mcp` from the `X-Amemo-Agent` header,
  otherwise from the token's model agent, otherwise `AMEMO_MODEL_AGENT` (`model:local`). `person:` is refused.
- **Shared service.** With `AMEMO_TOKENS`, `/mcp` needs `Authorization: Bearer <token>` like the API; a read-only
  token can search, and write tools answer `read_only`. A header that disagrees with the token's model agent is
  refused.
- **Usefulness.** `amemo_helpful` marks atoms only from a search of the same session (or, for clients without
  sessions, of the same agent and login); someone else's `retrieval_id` answers `forbidden`.
- **Query log.** Explicit searches (`amemo search`, `amemo_search`, `amemo_similar`) add a line to
  `AMEMO_STATE/queries.jsonl`, like the service's `/search`; reading steps do not.

## Agent memory

`amemo install claude-code` and `amemo install codex` connect amemo to an agent, globally or with `--project DIR`.
`amemo uninstall …` removes exactly what was installed; `--dry-run` shows the changes first.

| | Claude Code | Codex CLI |
|---|---|---|
| MCP server | `claude mcp add --scope user` (or `~/.claude.json`); project — `.mcp.json` | `[mcp_servers.amemo]` in `~/.codex/config.toml`; project — `.codex/config.toml` |
| Hooks | `SessionStart`, `UserPromptSubmit`, `PreCompact` in `settings.json` | `SessionStart`, `UserPromptSubmit` in `hooks.json` |
| Skills | `~/.claude/skills/amemo-*`; project — `.claude/skills/` | `~/.agents/skills/`; project — `.agents/skills/`, plus a block in `AGENTS.md` |

- **Hooks.** `amemo hook SessionStart` adds 3–5 verified atoms about the project (by the git root name) and a
  reminder; `UserPromptSubmit` adds confident hits for the prompt («amemo first»); `PreCompact` asks the summary
  to list findings worth saving. A hook reads the database directly, fits in 1.5 s, and on any failure answers
  nothing with exit code 0. Text from memory comes framed as data with its review status, not as instructions.
- **Skills.** `amemo-remember` (write 1–3 atoms at the end of a task), `amemo-answer` (answer from memory with
  sources), `amemo-verify` (the semantic reviewer, level 5).
- **Who writes.** The installer sets `AMEMO_AS_MODEL` for the MCP server and the hooks, so the agent writes as
  `model:claude-code` or `model:codex`, never as you.
- **Edits only its own.** JSON keys `amemo` and hook entries with `amemo hook`, a `# amemo:begin … # amemo:end` block in
  TOML, a `<!-- amemo:begin … -->` block in Markdown. Before the first edit a file is copied to `<file>.amemo-backup`.
- **Codex.** Codex passes an MCP server only the variables listed in `env_vars`; the installer lists `AMEMO_DSN`,
  `AMEMO_CONFIG`, `AMEMO_STATE`, `PGPASSFILE` and `PGSERVICE` and never writes a connection string into
  `config.toml`. Put the database into `amemo.toml` with `amemo init --dsn …` (or into those variables). Codex reads
  project files only in a trusted project.
- **Project files.** With `--project` the files get a bare `amemo` command, without this machine's path, so they
  can be committed; `amemo` must be on the agent's `PATH`. A global install uses the full path.
- **Windows.** Native Windows needs no shell for the hooks: Claude Code gets a program with arguments (`command`
  and `args`), which runs the same with Git Bash or PowerShell, Codex a `cmd.exe` line. They carry no
  `AMEMO_AS_MODEL` (that is POSIX shell syntax), and they need none: hooks only read. Agent settings are found
  under `%USERPROFILE%`.
- **Check.** `amemo doctor` shows what is installed (globally and for the project of the current folder) and whether
  its command still exists; then `claude mcp list` or `codex mcp list` confirms the agent sees the server.

**Claude Cowork and the Claude app.** `amemo install cowork` builds a plugin zip, `~/amemo-plugin.zip` by default
(`--out FILE` picks another path). A person uploads it once in the Claude app or on claude.ai: **Customize → Plugins →
Add → Upload plugin**. Claude can't add a plugin to your account from the command line, and a plugin installed with
`claude plugin install` stays on that machine.

- **What's inside.** The same set as `amemo install claude-code`: the MCP server `amemo` with this machine's full
  path to `amemo` (`mcp --agent model:cowork`, `AMEMO_AS_MODEL=cowork`), the hooks `SessionStart`,
  `UserPromptSubmit` and `PreCompact` in exec form (`hooks/hooks.json`) and the three skills. With the amemo app for
  Windows the path is its launcher `%LOCALAPPDATA%\amemo\bin\amemo.exe`, which does not change with updates.
  Cowork loads plugin hooks in cloud sessions too, where `amemo` doesn't exist.
- **Where it works.** The local MCP server runs in Cowork sessions on your computer in the Claude app. Cloud
  sessions and chat on claude.ai don't start local servers, so they don't see amemo.
- **Claude Code too.** A plugin on your account also syncs into Claude Code (`amemo@synced` in
  `claude plugin list`). `amemo install claude-code --unless-synced` installs amemo into Claude Code directly until
  the plugin arrives, then removes the direct install so the server and hooks are not there twice — and puts it
  back if the plugin goes away. The amemo app for Windows runs it by itself.
- **Updates and removal.** Run `amemo install cowork` again after moving amemo, then upload the new zip.
  `amemo uninstall cowork` deletes only the zip; remove the plugin itself in **Customize → Plugins**.

**Scheduling `amemo-verify`.** The semantic reviewer is an agent run on a schedule of your choice, for example
every night with cron:

```cron
# m h dom mon dow
30 3 * * *  cd ~/notes && claude -p "Use the amemo-verify skill: review up to 20 open semantic items." >> ~/.local/state/amemo/verify.log 2>&1
```

or a systemd user timer:

```ini
# ~/.config/systemd/user/amemo-verify.service
[Service]
Type=oneshot
WorkingDirectory=%h/notes
ExecStart=/usr/bin/env claude -p "Use the amemo-verify skill: review up to 20 open semantic items."

# ~/.config/systemd/user/amemo-verify.timer
[Timer]
OnCalendar=*-*-* 03:30
Persistent=true
[Install]
WantedBy=timers.target
```

`systemctl --user enable --now amemo-verify.timer`. The agent needs the amemo MCP server (`amemo install …`).

## How it works

```mermaid
flowchart LR
    agents["Agents<br/>MCP · CLI · hooks"] -- propose --> check
    people["People<br/>web UI · CLI"] -- write --> check
    check["check.submit<br/>1 schema and templates<br/>2 quote found in the file<br/>3 common sense<br/>4 duplicates"]
    check -- one transaction --> base[("PostgreSQL + pgvector<br/>atoms · entities · links · revisions")]
    check -. cited files by digest .-> files[("OCFL object store")]
    base --> queue{{"review queue"}}
    queue -- confirm or reject --> people
    base --> search["search recipes<br/>exact_fact · similar<br/>what_changed · around_entity"]
    search -- short cards, then full records --> agents
```

Every write goes through `check.submit`. It checks the whole batch, then writes it in one transaction:

1. **Schema and templates:** fields, types, link rules and UCUM units.
2. **Binding to the source:** the quote is found in the file, the page matches, and the numbers of the
   claim appear in the fragment. Works for PDF, Markdown, xlsx and docx. A scanned PDF page (an image
   without a text layer) is OCR'd with Tesseract through PyMuPDF when OCR is installed (`amemo ocr install rus
   eng` or a system Tesseract, see [scanned PDFs](#scanned-pdfs-ocr)). A quote matched against OCR
   text gets an `info` finding `quote_ocr` and a softer fuzzy threshold; without OCR such pages are
   reported as having no text layer.
3. **Common sense:** value ranges, units, and contradictions with atoms already in the base.
4. **Duplicates:** by text and by vector.

An error at level 1 or 2 rejects the batch with a report. Otherwise each record gets a status:

| Status | Meaning |
|---|---|
| `draft` | Passed levels 1–4 without remarks; waits for the semantic review (level 5) |
| `needs_review` | Has a warning or a high risk; waits for a person |
| `auto_verified` | Passed all five levels with low risk |
| `verified` | Confirmed by a person against the source. A person's own record is verified at once |
| `rejected` | Rejected by a person |
| `deprecated`, `superseded` | Retired; kept for history |

**What an atom looks like** (`amem.atom/1`):

```yaml
kind: fact
key: pgvector.hnsw_max_dimensions
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.
content:
  values:
    - {property: max_indexed_dimensions, amount: 2000, unit: "1"}
sources:
  - path: pgvector/README.md
    selectors: [{type: heading, value: HNSW}]
    quote: vector - up to 2,000 dimensions
    role: primary
```

The agent never sets the status; the checks and people do.

**Core concepts**

| Concept | What it is |
|---|---|
| **Atom** | A small typed claim: fact, term, method, decision, question, lesson, requirement or parameter |
| **Entity** | What atoms are about: project, document, edition, organization, person, place, software, topic |
| **Object** | A source file, web page or message. Files are stored once by content digest |
| **Link** | A typed relation between records, with rules for its ends. Links are retired, never deleted |
| **Revision** | One change of a record: a canonical body, a content hash, an author and a reason |
| **Pack** | A domain vocabulary with templates and entity profiles. The core is a pack too |
| **Bundle** | A portable selection of records (`amem.bundle/1`), with or without files |

**Search recipes.** Five named recipes return plain JSON, so agents can work with them directly:

| Recipe | Answers |
|---|---|
| `exact_fact` | *What exactly is X?* Codes, marks, full text and vectors merged with RRF |
| `similar` | *What else is like this?* Semantic neighbours of a text or a record |
| `what_changed` | *What changed since Monday?* Revisions, decisions, statuses, moves and links |
| `around_entity` | *What do we know around X?* Shortest paths over links, rated by the weakest link; stops at `limit` (300 by default, was unlimited before), `total` counts nodes without it |
| `overview` | *What does the whole base look like?* Hubs by number of links (`degree`), their neighbours, the edges between them; filter by `project` |

Agents mark the atoms that helped them. These marks decay over time and give a small, capped boost in
ranking. They never change a status or skip a check.

## Roadmap

- [x] **Core and storage:** LinkML schema, revisions, objects by digest, domain packs
- [x] **Search engine:** four recipes, RRF ranking, usefulness marks, backups
- [x] **Automatic checks** (levels 1–4) and a **review queue** with leases, audit and metrics
- [x] **Ontology:** entity profiles, live cards, portable bundles
- [x] **Library for the service:** folders, record lists, references by key, object view
- [x] **HTTP service:** `amemo serve` with the [v1 contract](https://github.com/empty-complete/amemo/blob/v0.1.0a5/docs/api/http-v1.openapi.yaml)
- [x] **CLI and MCP server:** three-step retrieval, usefulness marks, `<private>` stripping
- [x] **Agent memory:** Claude Code hooks, Codex CLI, `amemo install`, core skills
- [x] **Writing from the web:** forms from templates, my kinds, uploads, tasks for agents
- [x] **Web UI:** all screens, on the service and on mock data; checked end to end against the service
- [ ] **asearch:** file search as an amemo plugin

## Documentation

| | |
|---|---|
| [Library reference](https://github.com/empty-complete/amemo/blob/v0.1.0a5/docs/library.md) | Data model, search, checks, review queue, cards, bundles, folders, backups |
| [HTTP API v1](https://github.com/empty-complete/amemo/blob/v0.1.0a5/docs/api/) | The OpenAPI contract between the service and the web UI |
| [Manifesto](https://github.com/empty-complete/amemo/blob/v0.1.0a5/docs/MANIFESTO.md) | Why amemo exists and what it stands for |
| [Design specs and plans](https://github.com/empty-complete/amemo/blob/v0.1.0a5/docs/superpowers/) | How each subproject was decided and built |

**Good to know**

- Text has two slots, `ru` and `en`; a record needs at least one, so a base can be kept in English only, as
  the sample is. Labels and snippets come in the language asked for — the UI language (`Accept-Language`),
  `--lang` in the CLI, `lang` in MCP tools, otherwise `AMEMO_LANG` — and fall back to the other slot. Full-text
  search indexes `ru` with the Russian configuration and `en` with the English one; the optional local vector
  model is multilingual.
- Vectors are local and optional: `pip install -e ".[embed]"` adds fastembed, and `amemo embed enable`
  downloads the model only with a person's permission ([Semantic search](#semantic-search)).
  `AMEMO_BACKEND=none` turns the semantic channel off, and lexical search keeps working.
- Backups need the PostgreSQL 18 client (`pg_dump`, `pg_restore`, `psql`) in `PATH`, in `AMEMO_PG_BIN` or in `pg_bin` of `amemo.toml`.

## Development

```bash
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

# test database: PostgreSQL 18 (port 5433)
docker compose --profile test up -d --wait db-test

# run the tests (backup tests need the PostgreSQL 18 client)
.venv/bin/pytest -q
```

To use other ports or servers, set `AMEMO_TEST_DSNS="postgresql://…/test,postgresql://…/test"`. A missing
test database or client counts as a failure, not a skip. If your environment exports a `PYTHONPATH` from
other tooling (ROS, for example), it breaks pytest plugin autoloading, so run `env -u PYTHONPATH .venv/bin/pytest -q`.

After editing `amemo/schema/amemo_v1.yaml`, regenerate the models:

```bash
.venv/bin/python tools/gen_schema.py          # writes amemo/model_v1.py and the JSON Schema
.venv/bin/python tools/gen_schema.py --check  # CI check: generated files are up to date
```
Before pushing, enable the privacy check: `git config core.hooksPath tools/hooks`; the hook reads its patterns from `~/.config/amemo/private-patterns.txt` (outside the repository).

Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) in English:
`type(scope): subject`, at most 100 characters, e.g. `fix(service): reject NUL in parameters`. The same
`core.hooksPath` enables a `commit-msg` hook that checks this when you commit;
`python3 tools/check_commits.py --revs origin/main..HEAD` checks a range by hand.


The web UI lives in [`web/`](https://github.com/empty-complete/amemo/blob/v0.1.0a5/web/) (React 19, HeroUI v3, TanStack). Run `npm run lint`, `npm test` and
`npm run e2e` there.

## Contributing

amemo is built in the open. Issues and discussions are welcome. For a larger change, please open an issue
first so we can agree on the approach. Every pull request runs the `ci` workflow (tests on PostgreSQL 18)
and the `commits` workflow (Conventional Commits in English); changes to `web/` also run the `web` workflow.

## Built with

[PostgreSQL](https://www.postgresql.org/) ·
[pgvector](https://github.com/pgvector/pgvector) ·
[LinkML](https://linkml.io/) ·
[OCFL](https://ocfl.io/) ·
[PyMuPDF](https://pymupdf.readthedocs.io/) ·
[fastembed](https://github.com/qdrant/fastembed) ·
[React](https://react.dev/) ·
[HeroUI](https://www.heroui.com/) ·
[force-graph](https://github.com/vasturiano/force-graph)

## License

GNU Affero General Public License v3.0 only (AGPL-3.0-only), see [LICENSE.txt](https://github.com/empty-complete/amemo/blob/v0.1.0a5/LICENSE.txt) and [NOTICE.txt](https://github.com/empty-complete/amemo/blob/v0.1.0a5/NOTICE.txt).


You may use, study, change and share amemo freely. If you distribute a modified version, or run one as a
service for other people over a network, you must offer its complete source code under the same license.

The domain packs in `amemo/packs` (vocabularies and templates) are data and stay under the MIT license, so they
can be reused anywhere.

A commercial license without the AGPL conditions (for example, for a closed hosted service) is available from
the author — open an issue on GitHub. Versions released before the change to AGPL remain available under MIT.

<p align="center"><sub>amemo is a tool for remembering well.</sub></p>
