This release is a pre-release and may not be stable for production use.
Shared memory for people and AI agents, where every claim comes with its proof.
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.
Quickstart · Features · How it works · Roadmap · Docs · Manifesto · Русский
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.
|
Every claim has a source 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. |
Nothing is overwritten Every change is a new revision with a reason, an author and a content hash. Mistakes are superseded, not erased. |
|
Checks run on every write Schema, units, the quote, common sense and duplicates are checked before anything lands. A failed batch writes nothing. |
The human decides Agents propose and pre-verify. Accepting a claim into the canon is a person's call, and the system shows who made it. |
Features
A claim next to its proofA 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. |
Review in one keystrokeAnything doubtful, risky or changed lands in a queue. Each item shows the claim, the quote and its neighbours. Y confirms, N rejects, J/K move on, and parallel reviewers never get the same item. |
Entity cardsA 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. |
Memory for agentsClaude 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. |
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, andwhat_changedanswers "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_dumpplus 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 16+ with pgvector. The schema is written in LinkML, with Pydantic models and JSON Schema generated from it.
Quickstart
amemo needs Python 3.11+, Docker (for PostgreSQL) and Linux or macOS. On Windows, use WSL2.
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
JKYNS: 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 importsamem.bundle/1and 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
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 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 or your own server. CI runs these steps on every push.
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.1only. It answers only to its own name inHost(127.0.0.1,localhost,[::1], the bind address) and only to its own page orAMEMO_UI_ORIGINSinOrigin; 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 firstfetchto/api/v1/sessionreceives it. Requests without the cookie (scripts, agents) write as a model, and their writes go through the checks. - Shared service. With
AMEMO_TOKENS(a0600file with token hashes) every API request needsAuthorization: Bearer <token>. A token withoutwrite = trueis read-only: writes answer403 read_only./healthand the UI's static files stay public. A--hostother than loopback without tokens is refused;--no-authallows 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 inAMEMO_ALLOWED_HOSTS:AMEMO_ALLOWED_HOSTS=amemoacceptsHost: 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 toAMEMO_STATE_QUOTAper owner (10 GiB). The query log isAMEMO_STATE/queries.jsonl;AMEMO_QUERY_LOG=offturns it off. The service writes its own log to stderr. - Web UI.
/uineeds the web package:pip install 'amemo[web]'. Without it/uianswers 404 with a hint, and the API works as usual.
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 /templatesgives 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 whatcheck.submitwill check. An optionaluiblock in a pack template sets the body, the widgets and the labels of fields; it does not change the checks: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 theminepack 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 gets403 forbidden.POST /bundles/exportwithwith_packstakes your kinds along; the import adds the missing ones, and the same code with other content is abundle_pack_conflict. -
Uploads and search.
POST /objects(multipartfile, optionalpath) puts a file into the documents folderAMEMO_DOCS, by default asЗагрузки/<file name>, and parses it. The same file at that path answers200, another file there is409 object_path_takenand stays untouched, and withoutAMEMO_DOCSthe answer is503 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_taskslists open tasks and its own,amemo_task_claimtakes one with a 30-minute lease,amemo_task_releasegives it back, andamemo_task_donecloses it with the result (links to the records it wrote), andamemo_task_cancelcancels a task it set. An expired lease frees the task for another agent.GET /tasksandamemo tasks listshow open and claimed tasks, newest first (--state donefor the closed ones);amemo tasks cancel IDcancels 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.
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:8767inside the compose network and is published only on127.0.0.1:8767.AMEMO_ALLOWED_HOSTS=amemolets other containers call it ashttp://amemo:8767. - Login. Without
AMEMO_TOKENSthe service runs with--no-auth: anyone who reaches the port writes as a model, so keep it on127.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), setAMEMO_TOKENS=/var/lib/amemo/state/tokensin.envand 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_DIRmounts your documents folder read-only. - Health. Both the image and compose check
/health;docker compose up --waitwaits for it. - Profile
web.amemo-webis the same service built withamemo[web]. It shares the port and the volumes, so run eitheramemooramemo-web. - Image.
docker build -t amemo .(targetservice) or--target web;--build-arg AMEMO_EXTRAS=embedadds the local embedding model.
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] database and object store
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 doctor [--project DIR] database, store, model, documents, agents, service
- Output. Text for people, or
--jsonwith 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.
0success,1environment (no database, no store),2wrong call,3ambiguous text instead of a reference (the candidates are printed),4not found,5the check rejected the batch (the report is printed),6conflict (item already resolved, folder taken, bundle collision). - Who writes. In a plain terminal it is the person
AMEMO_AGENT(by defaultperson: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.--agentsets the agent explicitly, but neverperson:inside an agent's environment. - Tokens.
amemo token create person:ann(ormodel:…,--read-only) prints the token once and stores only its hash inAMEMO_TOKENS. Only a person issues and revokes tokens. - Backups. A model may run
amemo backup create, but without rotation:--keepandrestoreare for people. - Debugging.
AMEMO_DEBUG=1adds the traceback of an internal error to stderr.
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:
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:
{
"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):
[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):
claude mcp add --transport http amemo http://127.0.0.1:8767/mcp --header "X-Amemo-Agent: model:claude-code"
[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/mcpfrom theX-Amemo-Agentheader, otherwise from the token's model agent, otherwiseAMEMO_MODEL_AGENT(model:local).person:is refused. - Shared service. With
AMEMO_TOKENS,/mcpneedsAuthorization: Bearer <token>like the API; a read-only token can search, and write tools answerread_only. A header that disagrees with the token's model agent is refused. - Usefulness.
amemo_helpfulmarks atoms only from a search of the same session (or, for clients without sessions, of the same agent and login); someone else'sretrieval_idanswersforbidden. - Query log. Explicit searches (
amemo search,amemo_search,amemo_similar) add a line toAMEMO_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 SessionStartadds 3–5 verified atoms about the project (by the git root name) and a reminder;UserPromptSubmitadds confident hits for the prompt («amemo first»);PreCompactasks 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_MODELfor the MCP server and the hooks, so the agent writes asmodel:claude-codeormodel:codex, never as you. - Edits only its own. JSON keys
amemoand hook entries withamemo hook, a# amemo:begin … # amemo:endblock 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 listsAMEMO_DSN,AMEMO_CONFIG,AMEMO_STATE,PGPASSFILEandPGSERVICEand never writes a connection string intoconfig.toml. Put the database intoamemo.tomlwithamemo init --dsn …(or into those variables). Codex reads project files only in a trusted project. - Project files. With
--projectthe files get a bareamemocommand, without this machine's path, so they can be committed;amemomust be on the agent'sPATH. A global install uses the full path. - Windows. Hook commands are POSIX shell lines (
AMEMO_AS_MODEL=… amemo hook …): they work on Linux, macOS and WSL2, not in native Windows shells. Use WSL2. - Check.
amemo doctorshows what is installed (globally and for the project of the current folder) and whether its command still exists; thenclaude mcp listorcodex mcp listconfirms the agent sees the server.
Scheduling amemo-verify. The semantic reviewer is an agent run on a schedule of your choice, for example
every night with 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:
# ~/.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
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:
- Schema and templates: fields, types, link rules and UCUM units.
- 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 its language data is installed
(
sudo apt install tesseract-ocr tesseract-ocr-ruson Debian/Ubuntu,brew install tesseract tesseract-langon macOS; languagesrus+engby default,AMEMO_OCR_LANGUAGESto change). A quote matched against OCR text gets aninfofindingquote_ocrand a softer fuzzy threshold; without Tesseract such pages are reported as having no text layer. - Common sense: value ranges, units, and contradictions with atoms already in the base.
- 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):
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
- Core and storage: LinkML schema, revisions, objects by digest, domain packs
- Search engine: four recipes, RRF ranking, usefulness marks, backups
- Automatic checks (levels 1–4) and a review queue with leases, audit and metrics
- Ontology: entity profiles, live cards, portable bundles
- Library for the service: folders, record lists, references by key, object view
- HTTP service:
amemo servewith the v1 contract - CLI and MCP server: three-step retrieval, usefulness marks,
<private>stripping - Agent memory: Claude Code hooks, Codex CLI,
amemo install, core skills - Writing from the web: forms from templates, my kinds, uploads, tasks for agents
- 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 | Data model, search, checks, review queue, cards, bundles, folders, backups |
| HTTP API v1 | The OpenAPI contract between the service and the web UI |
| Manifesto | Why amemo exists and what it stands for |
| Design specs and plans | How each subproject was decided and built |
Good to know
- Schema v1 requires the
ruslot of every label; other languages are optional. A base kept in English writes its English text there, as the sample does. Full-text search is tuned for Russian, and the optional local vector model is multilingual. - Vectors are local and optional:
pip install -e ".[embed]"adds fastembed, and a model is downloaded only with explicit permission.AMEMO_BACKEND=noneturns the semantic channel off, and lexical search keeps working. - Backups need the PostgreSQL 18 client (
pg_dump,pg_restore,psql) inPATHor inAMEMO_PG_BIN.
Development
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
# test databases: PostgreSQL 18 (port 5433) and 16 (port 5434)
docker compose --profile test up -d --wait db-test db-test-pg16
# 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:
.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 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/ (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 16)
and the commits workflow (Conventional Commits in English); changes to web/ also run the web workflow.
Built with
PostgreSQL · pgvector · LinkML · OCFL · PyMuPDF · fastembed · React · HeroUI · force-graph
License
MIT, see LICENSE.txt.
amemo is a tool for remembering well.
Metadata
Release files for amemo 0.1.0a1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| amemo-0.1.0a1.tar.gz | 734.9 kB | Without provenance | Details for amemo-0.1.0a1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| amemo-0.1.0a1-py3-none-any.whl | Python 3 | none | any | Details for amemo-0.1.0a1-py3-none-any.whl |
Total release size: 1.2 MB
Release files / amemo-0.1.0a1.tar.gz
| Download URL | amemo-0.1.0a1.tar.gz |
|---|---|
| Size | 734.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1a0ec3a126a3f6283a09b012e60d892f7a3fe8ae2f957f3e085fa696af8b0a9f
|
|
BLAKE2b-256 checksum How to use checksums |
713634b977caff37ada3b82ab2a1f323589e2d8ed19a0962fe0668135d184260
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / amemo-0.1.0a1-py3-none-any.whl
| Download URL | amemo-0.1.0a1-py3-none-any.whl |
|---|---|
| Size | 475.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8288c44df7e141276a7d7637ea83aecc4df0d2f1b00486f9eab5276ebb756661
|
|
BLAKE2b-256 checksum How to use checksums |
7a4d1ce468fc0fffa2527ab50c0b39058a383f0b6c1b512303ccfdde28cfdab0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for amemo 0.1.0a1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.