apex-memory
# apex-memory
apex-memory is a knowledge store for AI agents. It keeps markdown notes in a database: SQLite or Postgres. Agents use the store through the Model Context Protocol (MCP).
Each write is one transaction. The store does a check of the knowledge in each write. If the write adds a problem, such as a broken link, the store rolls back the write. The store then tells the agent why.
- Python package: `apex_memory`
- Command-line interface (CLI): `apex-memory`
- License: MIT
- Python: 3.12 or later
The project started as a part of a private project. This repository is the public extract.
**Low token cost.** In 21 days of real use, the store used less than 1% of all new context tokens. File reads, search and shell output used approximately 15 times more. See [Token cost](#token-cost).
## Contents
- [Quick start for agents](#quick-start-for-agents)
- [Token cost](#token-cost)
- [Data model](#data-model)
- [Install](#install)
- [Choose the database](#choose-the-database)
- [Create a domain](#create-a-domain)
- [Connect an MCP client](#connect-an-mcp-client)
- [Roles](#roles)
- [MCP tools](#mcp-tools)
- [Refusals](#refusals)
- [CLI commands](#cli-commands)
- [Import a folder of markdown notes](#import-a-folder-of-markdown-notes)
- [Move a store from SQLite to Postgres](#move-a-store-from-sqlite-to-postgres)
- [Backups](#backups)
- [Upgrade](#upgrade)
- [Differences between the backends](#differences-between-the-backends)
- [Run the tests](#run-the-tests)
- [Verify a change](#verify-a-change)
- [Add a database backend](#add-a-database-backend)
- [Agent rules template](#agent-rules-template)
- [License](#license)
## Quick start for agents
This procedure installs the store with SQLite, connects Claude Code and creates one domain. For other MCP clients, see [Connect an MCP client](#connect-an-mcp-client).
1. Make sure that `uv` is installed. Run `uv --version`. If the command fails, install uv from <https://docs.astral.sh/uv/>.
2. Install the package from GitHub:
```sh
uv tool install git+https://github.com/Shaurya-GitH/apex-memory
```
3. Run `apex-memory --help`. If the shell cannot find the command, run `uv tool update-shell` and open a new shell.
4. Create the store. The default database is the SQLite file `~/.apex-memory/memory.db`.
```sh
apex-memory init
```
5. Register the MCP server for all of your projects. Replace `claude-code` with a short name for the agent.
```sh
claude mcp add apex-memory --scope user -- apex-memory serve --actor claude-code --role owner
```
6. Start a new Claude Code session. Run `/mcp` and make sure that `apex-memory` shows as connected.
7. In the session, tell the agent to create your first domain with the tool `create_domain`. Give a name, a title and a description. See [Create a domain](#create-a-domain).
8. Tell the agent to create the ops domain `memory-ops` with `create_domain`. The store records refusals and errors there.
9. Copy [templates/AGENTS.md](templates/AGENTS.md) into your own `AGENTS.md` or `CLAUDE.md`. Replace its placeholders.
10. In a new session, the agent calls `list_domains`. It selects the domain whose description agrees with the subject of the work. Then it calls `brief` with that domain.
11. If no domain agrees, the agent asks you one time if you want a knowledge base for the work. If you answer "never for this", the agent records the declined topic and does not ask again for that topic. See [Select a domain](#select-a-domain).
If you have a folder of markdown notes, you can import it as a domain. See [Import a folder of markdown notes](#import-a-folder-of-markdown-notes).
## Token cost
An agent reads knowledge from the store into its context. Thus the store adds tokens to each session. We measured this cost in real use, not in a benchmark.
The data: all Claude Code sessions of one owner for 21 days. That is 3,515 sessions. 245 of these sessions used the store.
| Measure | Result |
| --- | --- |
| Store output, as a part of all new context tokens | **0.77%** |
| File reads, search and shell output (`Read`, `Grep`, `Bash`), for comparison | 11.9% |
| Store cost in the sessions that used the store, with cache re-reads | 3.4% (median 1.7%) |
| Store output in one session that used the store, on average | approximately 29,000 tokens |
| Part of the store output that came from `read` | 60% |
| Part of the store output that came from `brief` | 20% |
The store keeps the cost low because an agent reads one section, not a full page. `brief` gives the agent its start context in one call.
How we measured:
- We counted the characters in each tool result. We used 4 characters for each token.
- For cost, we used these weights: input 1, cache write 1.25, cache read 0.1, output 5.
- For "with cache re-reads", each later turn reads each store result again from the cache, until the context is compacted.
Your results can be different. They change with the size of your knowledge and with how your agents use it.
## Data model
The store keeps knowledge in domains. A domain is one area of knowledge, for example one product. This table gives each part of the model.
| Item | What it is |
| --- | --- |
| Domain | A set of notes with the path prefix `<domain>/`. Each domain has its own description, index, status page, log and decision records. You create a domain with `create_domain`, or with `apex-memory import` from a folder of markdown notes. |
| Note | One markdown page with a path such as `<domain>/topics/storage`. A note has a title, a summary and a version. A project note also has a page header. |
| Page header | Three fields on a project note: decision status, implementation status and evidence checked. The store also keeps the date `verified_at`. |
| Index | The page `<domain>/index`. Its catalog table shows one line for each note: the link and the summary. The store makes the catalog from the summaries. The summary of the index is the description of the domain. `list_domains` shows it. |
| Section | One heading of a note and its text. Each section has an id and a version. You read and edit one section at a time. |
| Link | `[[<domain>/<note>]]`, `[[<domain>/<note>#Heading]]` or `[[<note>#^block]]` in the text. The store keeps the links in the two directions. `move` rewrites them in notes. The index catalog and the log are generated from rows, so their links are not stored as links. Log entries keep the old page name after a `move`. |
| Decision record | A heading such as `D01 — Use SQLite (2026-10-30)` on the page `<domain>/decisions`. It has one `- **Status:**` line. |
| Decision status | `proposed`, `accepted`, `rejected`, `superseded by Dnn`, `void` or `unclassified`. `unclassified` is the state of a record that has no Status line. Only `set_decision_status` changes the Status line. |
| Build state | An optional value on a note: `planned`, `built`, `verified`, `deployed` or `not_applicable`. No value means not set. `impl_status` keeps the detail as text. Set it with `create_note`, `patch_header` or `move`. Any change is permitted, because work can go back. The page header shows `**Build:**` only when the value is set. `search` hits and `read` give it. `brief` counts the project notes for each build state. |
| Domain mode | How native a domain is: `native`, `partly_native` or `imported`. `list_domains` and `brief` give the mode and the steps that are left. See [Domain mode](#domain-mode). |
| Status item | One item on the page `<domain>/status`. The kinds are `state`, `open`, `blocker` and `next`. |
| Log | The page `<domain>/log`. It is append-only. The database stamps the time of each entry. |
| Tool event | An automatic log record of each write, each search, each `read` and each `brief`. A `read` event records the path, the section id, the heading, whether the store found it and the number of characters returned. A `brief` event records the domain and the number of characters. These events never hold note text. A failure to record an event never fails the call. A write event records the shape of the write: the size in characters and lines, the number of headings, and the sections that the write created, changed or removed. It does not record the new text. The log page does not show tool events. `log_query` shows them on request. |
| Source | A record of where knowledge came from: `snapshot`, `live`, `transcript`, `web` or `owner`. A note can cite a source. |
| Preference | A rule from the owner about how to do work, with the words of the owner. Each brief shows the active preferences. |
| Declined topic | A preference with a `topic`. It records the answer "never" to the question "Create a knowledge base for this topic?". `list_domains` gives them as `declined_topics`. |
| Lease | A claim on a section for 1 to 60 minutes. A longer time becomes 60 minutes. Other agents cannot write to that section while the lease is active. |
| Working note | A scratch note under `<domain>/working/<actor>/`. It needs no summary and no page header. It is not in the index. |
| Note status | The status that the store keeps for each note: `working`, `current`, `needs_review` or `historical`. See [Note status](#note-status). |
| Ops domain | The domain that gets an automatic record of each refusal and each error. The default name is `memory-ops`. |
### The check
The store does a check of a domain before and after each write. The check finds these problems:
- Broken links, and anchors that the store cannot find.
- Notes that have no summary, so they are not in the index.
- An index that has no summary, so the domain has no description.
- The same paragraph of 200 characters or more in two notes.
- Decision records that do not have exactly one Status line.
- Notes that cite a `live` source, with a `verified_at` date older than 14 days.
If a write adds a new problem, the store rolls back the write. The refusal `check_failed` lists the problems. Problems that were there before the write do not stop it. The tool `check` and the command `apex-memory check` show all the problems of a domain.
These rules tell when a problem is new:
- The store counts the copies of each paragraph. A write that removes one copy is permitted. A write that adds a copy, or that makes a new duplicate paragraph, is refused.
- A domain starts to use Status lines when one record gets a Status line. After that, the older records without a Status line are old problems. A new record without a Status line is a new problem.
### Decision records
A decision record is a heading on `<domain>/decisions`. The heading starts with an id: `D` or `P` and digits. Then it has ` — ` and a title. Write the record as in this example:
```markdown
## D01 — Use SQLite first (2026-10-30)
- **Status:** proposed
- **Decision:** The store uses SQLite first.
```
These rules apply to decision records:
- You cannot delete a record. Supersede it with `set_decision_status`.
- Only `set_decision_status` changes the Status line.
- You can edit a `proposed` record. You can only append text to an `accepted`, `rejected`, `void` or superseded record.
- The status can change from `proposed` to `accepted`, `rejected` or `superseded`. It can change from `accepted` to `superseded` or `void`.
- `superseded_by` must name an accepted decision.
- A record without a Status line is `unclassified`. It has a row in the decisions table. `set_decision_status` changes it to `proposed`, `accepted` or `rejected`, and writes the Status line as the first line of the record. Other targets give `bad_transition`. `unclassified` is not a dead state: it flags no note. The brief shows the number of unclassified records and up to 10 ids. A record with two or more Status lines is a problem and has no row.
- Use `void` only when an acceptance was an error. `void` needs a `reason`. The record stays on the page. The store adds a `- **Void reason:**` line with the reason and the date. The brief shows void decisions on a line of their own.
### Note status
The store keeps a status for each note. This table gives the four values.
| Status | What it means | How a note gets it |
| --- | --- | --- |
| `working` | A scratch note. It is not project knowledge. | The path is under `<domain>/working/<actor>/`. |
| `current` | Project knowledge that you can use. | `create_note` outside the working folder, or a promotion with `move`. |
| `needs_review` | The note cites a decision that is `superseded`, `void` or `rejected`. The note can be out of date. | The store sets it when `set_decision_status` changes the decision. |
| `historical` | The note is not current guidance. The store keeps it as history. | The owner sets it with `patch_header`, with a `reason`. |
These rules apply to the `needs_review` flag:
- A note cites a decision when the id of the decision is a full word in its page header or in its text. For example, `D1` does not agree with `D10`. A link to the decision record is also a citation.
- The store flags only `current` notes. An id in the text counts only in the domain of the decision. A link to the record counts from all domains.
- The store does not flag the pages `<domain>/decisions` and `<domain>/log`, working notes or historical notes.
- The reason names the decision, for example `cites D09 (superseded by D15)`. `set_decision_status` lists the flagged notes in `needs_review`.
- The flag is not a problem of the check. It does not refuse a write. An edit of a section does not remove the flag.
- `read` puts a `notice` first, and gives `status` and `review_reason`. `search` hits give the `status`. `brief` and `check` list the pages. `list_domains` gives a count.
To remove the flag, do these steps:
1. Read the note and the decision that replaced the old one.
2. Correct the note with `patch_section`, if it is not correct.
3. Call `patch_header` with new `evidence` or a new `verified_at`. The status goes back to `current`.
If the note is only history, the owner calls `patch_header` with `status: "historical"` and a `reason`. The store does not flag a historical note again. `brief` marks it `(historical)` in the index. To make it current again, the owner calls `patch_header` with `status: "current"`.
You cannot set `needs_review` or `working` by hand. The store records each status change as a `tool:note_status` event.
## Install
The package is not on PyPI. Install it from GitHub. You need Python 3.12 or later.
| Need | Command |
| --- | --- |
| SQLite only, with uv | `uv tool install git+https://github.com/Shaurya-GitH/apex-memory` |
| SQLite and Postgres, with uv | `uv tool install "apex-memory[postgres] @ git+https://github.com/Shaurya-GitH/apex-memory"` |
| SQLite only, with pip | `pip install git+https://github.com/Shaurya-GitH/apex-memory` |
| SQLite and Postgres, with pip | `pip install "apex-memory[postgres] @ git+https://github.com/Shaurya-GitH/apex-memory"` |
The `postgres` extra installs `psycopg[binary]` 3. To add Postgres to an installed tool, run the second uv command with `--force`.
`uv tool install` puts the command `apex-memory` in `~/.local/bin`. If that folder is not on your `PATH`, run `uv tool update-shell`. Use pip in a virtual environment.
To update the tool, run `uv tool upgrade apex-memory`.
## Choose the database
The store finds its database in this sequence:
1. The option `--url`.
2. The environment variable `APEX_MEMORY_URL`.
3. The SQLite file `~/.apex-memory/memory.db`.
| URL | Database |
| --- | --- |
| `sqlite:///absolute/path/memory.db` | A SQLite file at an absolute path. |
| `sqlite://~/path/memory.db` | A SQLite file relative to your home folder. |
| `/absolute/path/memory.db` | A bare path is a SQLite file. |
| `postgresql://user:password@host:port/database` | A Postgres database. `postgres://` also works. |
Each command and the MCP server open the database and create or update the schema. The store refuses a database whose schema is newer than the installed package. If that occurs, upgrade the package.
### SQLite
SQLite needs no setup. `apex-memory init` creates the file and its folder. Many processes can use one file at the same time. The store lets only one process write at a time.
```sh
apex-memory init --url sqlite:///Users/you/stores/memory.db
```
The output is `store <store id> at <path>`. Run `init` again to see the store id. It does not change a store.
### Postgres
1. Install the package with the `postgres` extra. See [Install](#install).
2. Start a Postgres server. For a local test server, use Docker:
```sh
docker run -d --name apex-memory-pg -e POSTGRES_PASSWORD=test -p 5432:5432 postgres:17
```
If a Postgres server already uses port 5432 on your computer, use a different host port, for example `-p 55432:5432`. Then use that port in the URLs below.
3. Create a user. The password of the `postgres` user is `test`. `psql` asks for it.
```sh
psql -h localhost -U postgres -c "CREATE ROLE apex LOGIN PASSWORD 'secret'"
```
If `psql` is not installed, run it in the Docker container. Use this form for each `psql` command in this section:
```sh
docker exec -e PGPASSWORD=test apex-memory-pg psql -U postgres -c "CREATE ROLE apex LOGIN PASSWORD 'secret'"
```
4. Create a database that the user owns. The user must be able to create tables in it.
```sh
psql -h localhost -U postgres -c "CREATE DATABASE apex_memory OWNER apex"
```
5. Create the store:
```sh
apex-memory init --url postgresql://apex:secret@localhost:5432/apex_memory
```
6. Set the URL for all commands. Put this line in your shell profile:
```sh
export APEX_MEMORY_URL=postgresql://apex:secret@localhost:5432/apex_memory
```
The URL accepts each libpq parameter. To keep a store in its own schema, create the schema first. Then add the `options` parameter:
```sh
psql -h localhost -U apex -d apex_memory -c "CREATE SCHEMA team_a"
apex-memory init --url 'postgresql://apex:secret@localhost:5432/apex_memory?options=-csearch_path%3Dteam_a'
```
One schema holds one store. If the password contains special characters, percent-encode them in the URL. The store does not show the password in its output.
If the `postgres` extra is not installed, a Postgres URL stops with the message `postgresql needs the psycopg package: install apex-memory[postgres]`.
## Create a domain
The owner creates a domain with the tool `create_domain`. A worker cannot create a domain.
```text
create_domain(
domain="myproject",
title="My project",
description="The My project product: its plans, contracts and decisions. Not for the website; use website.",
)
```
| Argument | What it is |
| --- | --- |
| `domain` | The name of the domain. Use lowercase letters, digits and hyphens. |
| `title` | The name that the start pages show. |
| `description` | What the domain holds and when to select it. Agents read it in `list_domains`. Write the limits too, for example "Not for X; use Y". The store keeps it as the summary of `<domain>/index`. |
`create_domain` makes four start pages: `<domain>/index` with its catalog, `<domain>/status`, `<domain>/log` and `<domain>/decisions`. If the domain exists, the refusal is `domain_exists`.
The store records refusals and errors only when the ops domain exists. Create the ops domain `memory-ops` in the same way:
```text
create_domain(
domain="memory-ops",
title="Memory ops",
description="Failures and friction of the memory system itself. Not for project knowledge.",
)
```
To use a different name for the ops domain, give `--ops-domain <name>` to `apex-memory serve`.
Keep the description current. When the scope of a domain changes, change the summary of `<domain>/index`. Use `patch_section` with `summary` and `op: "replace_own_text"` on the text before the first heading of the index (`heading=[]`). For `content`, give the `content` that `read` gives for `heading=[]`. If the own text does not change, the page does not change. Do not use the first heading of an imported index: it can hold the generated catalog, and the store then refuses the write with `generated_section`.
A domain that you imported from markdown has no description. `list_domains` then shows the first paragraph of its index, with `description_missing: true`. The check shows the problem until you give a summary to the index.
To import a folder of markdown notes as a domain, see [Import a folder of markdown notes](#import-a-folder-of-markdown-notes).
### Select a domain
The agent selects the knowledge base for the work. It does not use the repository name or the tool name.
1. At the start of a session, the agent calls `list_domains`. It calls it again when the subject of the work changes.
2. The agent selects the domains whose description agrees with the subject of the work. Usually one domain agrees. The agent uses a second domain only when the task has an explicit dependency on that domain. In a test on 75 real tasks, this rule removed most of the unnecessary second domains.
3. The agent calls `brief` for each domain that it selected.
If no domain agrees, and the work will make knowledge that is important to keep, the agent asks the owner one time. It asks at the start of the work. It proposes a name and a description of one line.
| Answer of the owner | What the agent does |
| --- | --- |
| Yes | It calls `create_domain` with that description, then `brief`. |
| No, never for this topic | It calls `preference` with `action="decline_domain"`, the `topic` and the words of the owner as `owner_quote`. It does not ask again for that topic. |
| Not now | It records nothing. It does not ask again in this session. |
`list_domains` gives the declined topics as `declined_topics: [{id, topic, owner_quote}]`. Thus the agent sees each "never" answer at the start of a session, before it calls `brief`. The agent checks the list before it asks. A second answer for the same topic (any case) is refused with `already_declined` and the id of the first. `preference` with `action="retire"` ends a declined topic. If the owner later creates a domain with that name or title, `create_domain` retires the declined topic and lists it in `retired_declined_topics`. `list_domains` also gives the other active preferences that apply to all domains, as `preferences: [{id, text}]`.
### Domain mode
`list_domains` and `brief` give the mode of each domain. The store finds it from the domain itself.
| Mode | Meaning |
| --- | --- |
| `native` | No step is left. |
| `partly_native` | At least one step is left. |
| `imported` | The index catalog is written by hand and the status is a prose page. |
The steps are short sentences. A step names the tool to use, or says that no tool converts the page yet. The steps are: the index catalog is written by hand, the status is a prose page and not items, some decision records are unclassified, and the description is missing. The store has no tool that converts an index or a status page.
A worker does not create a domain and does not record a preference. It tells the session of the owner that no domain agrees.
## Connect an MCP client
The MCP server uses stdio. The client starts this command:
```sh
apex-memory serve --actor <name> --role <owner or worker>
```
| Option | What it does |
| --- | --- |
| `--actor <name>` | The name of the agent. Use lowercase letters, digits and hyphens. The name is in each log entry and in the path of the working notes. |
| `--role owner`, `--role worker` | The role of the agent. The default for `serve` is `worker`. See [Roles](#roles). |
| `--url <url>` | The database. You can also set `APEX_MEMORY_URL` in the environment of the server. |
| `--ops-domain <name>` | The domain that gets the records of refusals and errors. The default is `memory-ops`. |
| `--run-id <id>` | An id for this run. The default is a new UUID. Log entries keep it. |
When the client connects, the server sends instructions to the agent. The instructions start with the rule for domains in [Select a domain](#select-a-domain). The instructions for a worker tell it to report a missing domain to the session of the owner. The instructions also give the store id, the actor, the role and the main rules.
### Claude Code
Use `--scope user` to register the server for all of your projects. Give the URL with `-e`:
```sh
claude mcp add apex-memory --scope user \
-e APEX_MEMORY_URL=sqlite:///Users/you/.apex-memory/memory.db \
-- apex-memory serve --actor claude-code --role owner
```
For Postgres, set `APEX_MEMORY_URL` to the Postgres URL. Without `-e`, the server uses `~/.apex-memory/memory.db`.
To remove the server, run `claude mcp remove apex-memory --scope user`.
### Codex
```sh
codex mcp add apex-memory --env APEX_MEMORY_URL=sqlite:///Users/you/.apex-memory/memory.db \
-- apex-memory serve --actor codex --role owner
```
### Other MCP clients
Most clients accept a JSON configuration of this type:
```json
{
"mcpServers": {
"apex-memory": {
"command": "/Users/you/.local/bin/apex-memory",
"args": ["serve", "--actor", "my-agent", "--role", "owner"],
"env": { "APEX_MEMORY_URL": "sqlite:///Users/you/.apex-memory/memory.db" }
}
}
}
```
A desktop client can start without your shell `PATH`. If the client cannot find `apex-memory`, give the full path. To find the full path, run `command -v apex-memory`.
## Roles
You give the role when you register the server. The store does not authenticate the role. It is for one machine with one owner.
| Role | Who | What it can do |
| --- | --- | --- |
| `owner` | The sessions of the owner. | All the tools. |
| `worker` | Agents that you run for the owner. | Read and search all the knowledge. Write only its own working notes under `<domain>/working/<actor>/`. Append log entries. |
A worker cannot do these actions:
- Write a project note, a page header or a section outside its working notes.
- Create a domain.
- Add, update or close a status item.
- Change a decision status.
- Add or retire a preference.
- Promote a working note into project knowledge.
- Change a source that exists.
The owner promotes a working note with `move`. The promotion needs a summary and a page header.
Search results do not show the working notes of other actors. To see them, search with a `scope` in the `working` folder.
## MCP tools
Each tool returns a JSON object. A result has `"ok": true`. A refusal has `"ok": false` and an `error`.
| Tool | What it does |
| --- | --- |
| `list_domains` | Shows each domain with its description, number of notes, number of pages that need review, `mode` (and `steps` when the mode is not `native`) and time of the last log entry. `ops: true` marks the ops domain. `declined_topics` gives the topics that the owner declined. `preferences` gives the other active preferences that apply to all domains. All roles. |
| `brief` | Gives the start read for a domain: store identity, number of problems, mode and steps, a count of notes for each build state, pages that need review, index, preferences, decisions, open status items and the last log entries. |
| `search` | Finds text in notes, sections and log entries. `mode` is `bm25`, `exact` or `regex`. `scope` is a domain or folder; empty means all domains. A hit gives the `status` of its note when the status is not `current`. |
| `read` | Reads a full note, or one section and its subsections, with ids, versions, the `build` state and the `status` of the note. A `notice` comes first for a `needs_review` or `historical` note. If the store cannot find the heading or the note, the refusal gives `candidates`. |
| `links` | Shows the links out of a note, into a note, or both, up to 3 hops. |
| `log_query` | Filters log entries by time, `op` text, page or task id. `include_tool` adds the tool events. |
| `patch_section` | Edits one section. `op` is `replace`, `append`, `prepend` or `replace_own_text`. All operations except `append` need a version check. |
| `patch_header` | Edits the page header of a note with a version check. New `evidence` or `verified_at` sets a `needs_review` note back to `current`. `status` sets `historical` (with a `reason`) or `current`; owner only. `build` sets the build state. |
| `create_note` | Creates a note in a domain that exists. It never overwrites. `build` is optional. |
| `create_domain` | Creates a domain with its description and its four start pages. Owner only. |
| `move` | Renames a note in its domain and rewrites all links to it. It also promotes a working note: the status changes from `working` to `current`. `build` is optional. |
| `status_item` | Adds, updates or closes one status item. `update` changes the text, and as an option the kind, of an open item. The event keeps the old text. Owner only. |
| `set_decision_status` | Changes the Status line of one decision record. A record without a Status line (`unclassified`) goes to `proposed`, `accepted` or `rejected`. `void` needs a `reason`. `superseded`, `void` and `rejected` flag the current notes that cite the decision; `needs_review` lists them. Owner only. |
| `log_append` | Appends one entry to the log of a domain. The pages that it names must exist. |
| `preference` | Adds or retires a preference of the owner. `add` needs the words of the owner. `decline_domain` records a declined topic (`topic` and `owner_quote`). Owner only. |
| `source` | Adds a source, or cites or uncites a source from a note. |
| `lease` | Takes or releases a lease on a section. |
| `check` | Shows the problems of a domain. `needs_review` lists the pages that need review; they are not problems. It changes nothing. |
| `batch` | Does a list of writes in one transaction. See [Write two or more notes together](#write-two-or-more-notes-together). |
### How to edit a section
1. Call `read` with `path` and `heading`. The result gives `section_id`, `version` and `content`.
2. Change the text of `content`.
3. Call `patch_section` with `op: "replace"`, the new `content`, `section_id`, and `if_version` set to `version`.
4. If the result is `version_conflict`, another agent changed the section. Merge your change into the `content` of the refusal.
5. Call `patch_section` again with `if_version` set to `current_version`.
The headings in `content` are relative to the section. A direct subsection starts with `#`. `replace` accepts the same format that `read` gives.
This table gives the operations of `patch_section`:
| `op` | What it does | `if_version` |
| --- | --- | --- |
| `replace` | Replaces the section and its subsections with `content`. | Necessary |
| `append` | Adds `content` after the last subsection. It can add subsections. | Not necessary. The store does not compare it. |
| `prepend` | Adds `content` before the own text of the section. It cannot add headings. | Necessary |
| `replace_own_text` | Replaces only the own text of the section: the text before its first subsection. The subsections do not change. It cannot add headings. | Necessary |
If `replace`, `prepend` or `replace_own_text` has no `if_version`, the refusal is `version_required`.
The text before the first heading of a note is a section too. To edit it, give `heading=[]` or its `section_id`. It cannot contain headings. There is one exception: if a note has only this section, `append` and `replace` on it can add headings. Then the note gets an outline.
`heading` can be the heading text or a list with the full heading path. The path starts at the highest heading in the note text. An imported note usually has an H1, so its path starts with the H1, for example `["myproject status", "Blockers"]`. A note from `create_note` has its title outside the text, so its path starts with its first heading, for example `["Design", "Details"]`. If two sections have the same heading, the store gives the candidates. Then use `section_id`. If the store cannot find a heading, the refusal `not_found` gives a maximum of 5 `candidates`: the sections with the nearest headings. A heading without its date, such as `(2026-10-12)`, also finds the section. If the store cannot find a note, `candidates` gives the nearest note paths.
The index catalog, the status items and the log entries are generated sections. `patch_section` refuses them. Use the `summary` field, `status_item` and `log_append`.
### Write two or more notes together
`batch` does a list of writes in one transaction. If one write is refused, the store rolls back all of them. Use it when two notes link to each other, or when one change goes across many notes.
```text
batch(ops=[
{"tool": "create_note", "args": {"path": "myproject/a", ...}},
{"tool": "create_note", "args": {"path": "myproject/b", ...}},
{"tool": "log_append", "args": {"domain": "myproject", "pages": ["myproject/a", "myproject/b"], ...}},
])
```
- The tools are `create_note`, `patch_section`, `patch_header`, `status_item`, `set_decision_status`, `log_append` and `source`.
- Each write has the same role rules and refusals as when you call its tool.
- The store does the check one time, after the last write. Thus note A can link to note B before B exists in the list.
- `log_append` writes go after the other writes. The pages that they name must exist at the end.
- A refusal gives `op_index`, the position of the refused write in the list. A failed check at the end gives no `op_index`.
- The result gives `results`, with the result of each write in the order of the list.
### Search modes
| Mode | Use it for |
| --- | --- |
| `bm25` | Topics. A keyword search with a rank order. Lower scores are better. A hit that has more of the words of the query gets a better score. If some hits have half of the words, with a minimum of 2, the store does not show the hits that have fewer. |
| `exact` | Ids, hashes and paths. A search for full words that ignores case. `D51` finds `D51` but not `9ad51f0`. |
| `regex` | Patterns. Each pattern must compile in Python. See [Differences between the backends](#differences-between-the-backends). |
The snippets of `exact` and `regex` hits start and stop at the end of a word.
## Refusals
A refusal is an expected result. It is not an error of the server. The `error` field gives the reason. Many refusals also give a `hint`.
| `error` | Cause | What to do |
| --- | --- | --- |
| `version_conflict` | The section or note changed after you read it. | Merge into the `content` of the refusal. Try again with `current_version`. |
| `version_required` | `replace`, `prepend` or `replace_own_text` has no `if_version`. | Read the section. Give its `version` as `if_version`. |
| `check_failed` | The write adds a problem. `problems` lists it. | Correct the problem in your text. Try again. |
| `leased` | Another agent has a lease on that part. | Wait until `expires_at`, or ask the holder to release it. |
| `not_allowed` | A worker tried to write outside its working notes. | Write under `<domain>/working/<actor>/`. |
| `owner_only` | A worker tried an owner action. | Ask the owner. |
| `unknown_domain` | The domain is not in the store. | Use a domain from `domains`. To see the descriptions, call `list_domains`. Ask the owner before you create a domain. |
| `not_found`, `ambiguous_heading` | The store cannot find the note or section, or the heading is not unique. | Use one of the `candidates`, a heading path or a `section_id`. |
| `path_required` | `read` has no `path` and no `section_id`. | Give `path` for a full note, `path` and `heading` for one section, or `section_id`. |
| `heading_required` | `patch_section` or `lease` has a `path` but no `heading`. | Give `heading`, or `section_id`. `heading=[]` is the text before the first heading. |
| `summary_required`, `header_required` | A project note needs a summary and a full page header. | Give `summary`, `decision_status`, `impl_status` and `evidence`. |
| `exists` | The note exists. `create_note` does not overwrite. | Use `patch_section`. |
| `generated_section` | The store makes the section from rows. | Use `status_item`, `log_append` or the `summary` field. |
| `status_line_changed`, `decision_overwritten`, `decision_removed` | The edit changes a decision record in a way that is not permitted. | Use `set_decision_status`, or append text only. |
| `unknown_pages` | `log_append` names a page that is not in the store. | Name pages that exist. |
| `bad_regex` | The pattern does not compile in Python, or Postgres refuses it. | Correct the pattern. |
| `headings_not_allowed` | `prepend` or `replace_own_text` text contains a heading, or a write puts a heading in the text before the first heading of a note that has other sections. | Use `append` to add subsections. |
| `bad_transition` | `set_decision_status` asks for a change that the life cycle does not permit, for example accepted to proposed. | Use proposed to accepted, rejected or superseded, or accepted to superseded or void. An unclassified record goes to proposed, accepted or rejected. |
| `bad_build` | `build` is not one of the allowed values. | Use `planned`, `built`, `verified`, `deployed` or `not_applicable`. |
| `already_declined` | The topic is already a declined topic. | The refusal gives the `item_id`. Retire it first if the owner changed the answer. |
| `reason_required` | `set_decision_status` to `void` has no `reason`, or `patch_header` with `status: "historical"` has no `reason`. | Give the reason. |
| `bad_status` | `patch_header` has a `status` that is not `current` or `historical`, or the note is a working note. | Use `current` or `historical`. Promote a working note with `move`. |
| `bad_batch`, `bad_args` | A `batch` write names a tool that `batch` does not accept, or its arguments do not agree with the tool. `op_index` shows the write. | Correct that write. |
| `quote_required` | `preference` `add` has no words of the owner. | Give the quote of the owner. |
| `promotion_needs_summary_and_header` | `move` of a working note into project knowledge has no summary or page header. | Give `summary` and the header fields. |
| `bad_path` | The path is not permitted, for example a `move` of the index. | Use a path of a normal note. |
| `domain_exists` | `create_domain` or `apex-memory import` of a domain that is in the store. | Use the domain that exists, or another domain name. |
| `bad_name`, `description_required` | `create_domain` has a name that is not lowercase letters, digits and hyphens, or it has no description. | Correct the name. Give a description. |
If the ops domain exists, the store records each refusal and each error in it. The record keeps the tool, the arguments and the result. The store replaces the `content` argument and long text with their length.
## CLI commands
The CLI uses the same database rules as the server. All commands accept `--url`. The CLI acts as the actor `cli` with the role `owner`.
| Command | What it does |
| --- | --- |
| `apex-memory init` | Creates the store, or shows the store that exists. |
| `apex-memory serve --actor <name> --role <role>` | Starts the MCP stdio server. |
| `apex-memory import <folder>` | Imports a folder of markdown notes as one domain. |
| `apex-memory import <store>` | Copies a full store, such as a SQLite file or a backup, into a new empty store. |
| `apex-memory verify <folder>` | Makes sure that each imported page renders back the same as its file. |
| `apex-memory brief <domain>` | Prints the brief of a domain. |
| `apex-memory check <domain>` | Prints the problems of a domain. The exit code is 1 if there are problems. |
| `apex-memory backup [--to <folder>] [--keep <n>]` | Writes a verified backup. See [Backups](#backups). |
| `apex-memory status` | Shows the package version, the schema version of the store, the pending migrations, the location of the store and the last backup. It does not change the store. See [Upgrade](#upgrade). |
| `apex-memory --version` | Shows the package version. |
## Import a folder of markdown notes
`apex-memory import <folder>` reads each `*.md` file in the folder and its subfolders. The import only reads the files. The path of a note is `<folder name>/<relative path without .md>`. The report lists other files in `not_imported`.
The import gives special treatment to these files:
| File | Treatment |
| --- | --- |
| `index.md` | Rows such as `\| [[<domain>/<note>]] \| <summary> \|` give the summaries. If the rows are a plain table at the end of a section, the store makes that catalog from the summaries. If not, the page stays as written. |
| `status.md` | Sections that start with `Current state`, `Unfinished / open`, `Blockers` or `Next concrete action` become status items. Each bullet or paragraph is one item. `None.` means no items. |
| `log.md` | The last level-2 headings with the format `## 2026-10-01T10:00:00+05:30 — OP` become log entries. Older sections stay as written. |
| `decisions.md` | Headings such as `D01 — Title` or `P01 — Title` become decision records. |
| `sources/*.md` | Each note becomes a `snapshot` source. |
A note gets a page header from its first line before the first heading, in this format:
```markdown
> **Decision status:** accepted **Implementation status:** built **Evidence checked:** 2026-10-30, tests pass
```
The import accepts simple YAML front matter: `key: value` lines and lists of `- item` lines. Other front matter stops the import.
The import prints a report. Read `problems`, `catalog_unknown`, `unclassified_decisions` and `kept_as_written`.
You can import each domain one time. A second import of the same domain gets the refusal `domain_exists`. For a test, `--fresh` deletes the database first. `--fresh` only works on a SQLite file whose name contains `test`.
Then do a check of the import:
```sh
apex-memory verify ~/apex-notes/myproject
```
`verify` renders each page from the store and compares it with its file. It ignores spaces at line ends, extra blank lines and blank lines at the start and end. If a page is different, `verify` prints a diff and the exit code is 1.
## Move a store from SQLite to Postgres
`apex-memory import` copies a full store when its argument is a file or a URL and not a folder.
1. Create an empty Postgres database. See [Postgres](#postgres).
2. Copy the store:
```sh
apex-memory import ~/.apex-memory/memory.db --url postgresql://apex:secret@localhost:5432/apex_memory
```
3. Do a check of each domain:
```sh
apex-memory check myproject --url postgresql://apex:secret@localhost:5432/apex_memory
```
4. Set `APEX_MEMORY_URL` to the Postgres URL in your shell profile and in each MCP client.
The copy keeps all rows, ids, the store id and the dates. It reads the source in one transaction and writes the target in one transaction. The target must not have notes or log entries. If it has, the copy stops with `already holds knowledge`. A copy of a store into the same store stops with `cannot copy a store into itself`.
The same command moves a store from Postgres to SQLite, or from SQLite to SQLite. The source can be a backup file or a URL.
## Backups
```sh
apex-memory backup --to ~/.apex-memory/backups --keep 14
```
If you do not give `--to`, the command uses `APEX_MEMORY_BACKUP_DIR`, then `~/.apex-memory/backups`. The command writes `<folder>/memory-YYYY-MM-DD.db`. Each backup is a SQLite file. The command does an integrity check of the file before it keeps it. It then deletes the oldest backups and keeps the newest `--keep` files. A second backup on the same day replaces the first one.
| Backend | How the backup works |
| --- | --- |
| SQLite | `VACUUM INTO` a new file, then `PRAGMA integrity_check`. |
| Postgres | A logical copy of the store into a new SQLite file, then `PRAGMA integrity_check`. It does not need `pg_dump`. |
For a full backup of a Postgres cluster, also use `pg_dump`.
To restore a backup, import it into a new empty store:
```sh
apex-memory import ~/.apex-memory/backups/memory-2026-10-30.db --url sqlite:///Users/you/.apex-memory/restored.db
```
The target of a restore can also be a Postgres URL.
### Nightly backup on macOS
The file `ops/com.apex-memory.backup.plist` is a launchd agent. It runs `apex-memory backup --keep 14` each day at 03:00. If the Mac is asleep at that time, the backup runs when the Mac wakes. The output goes to `/tmp/apex-memory-backup.log`.
The agent runs the command in a zsh login shell. Thus `~/.zprofile` or `~/.zshenv` must put `~/.local/bin` on `PATH`. If you do not use the default database, the same file must set `APEX_MEMORY_URL`. A login shell that is not interactive does not read `~/.zshrc`.
1. Copy the file:
```sh
cp ops/com.apex-memory.backup.plist ~/Library/LaunchAgents/
```
2. Load the agent:
```sh
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.apex-memory.backup.plist
```
3. To do a test now, run `launchctl kickstart gui/$(id -u)/com.apex-memory.backup`.
4. Read `/tmp/apex-memory-backup.log`. Make sure that it shows the path of a new backup.
On Linux, use cron or a systemd timer to run the same command.
## Upgrade
An upgrade is one command and a restart. The store keeps all the knowledge. Before the new version changes the schema, it writes a backup.
### Upgrade the package
1. Upgrade the package. Use the command for the installer that you used:
| Installer | Command |
| --- | --- |
| uv | `uv tool upgrade apex-memory` |
| pip | `pip install --upgrade --force-reinstall "git+https://github.com/Shaurya-GitH/apex-memory"` |
`uv tool upgrade` gets the newest commit of the branch that you installed. pip needs `--force-reinstall`. Without it, pip does not get a new commit that has the same version number.
2. Restart each MCP client, or run `/mcp` and reconnect the server. The client then starts the new server.
3. Run `apex-memory status`. The line `schema version` must show `up to date`.
To install one release, give its tag:
```sh
uv tool install "git+https://github.com/Shaurya-GitH/apex-memory@v0.2.0"
```
When you install a tag, `uv tool upgrade` does not change the version. To follow the branch again, run `uv tool install "git+https://github.com/Shaurya-GitH/apex-memory"`.
### What occurs automatically
The first time that the new version opens a store with an older schema, it does these steps:
1. It gets the writer lock of the store. If two servers start at the same time, only one of them does the next steps. The other server waits, then uses the new schema.
2. It writes a backup of the store to `pre-migration-YYYYMMDD-HHMMSS-<unique>-v<old>-to-v<new>.db`, and does an integrity check of the backup. It syncs the file and its directory before migration. The unique suffix prevents different stores from overwriting each other's safety backups.
- SQLite: the backup goes into the folder `backups` next to the store file.
- Postgres: the backup is a SQLite file in `~/.apex-memory/backups`.
- If `APEX_MEMORY_BACKUP_DIR` is set, the backup goes into that folder for both backends.
3. It applies the migrations. Then, one time for each store, it does the backfill of version 0.3.0: it sets the note status, derives the decisions table of each domain (a record without a Status line gets the status `unclassified`), flags the notes that cite a dead decision, and gives a topic to each active global "No knowledge base for ..." preference.
4. If the ops domain exists, it appends a log entry `MIGRATION: schema <old> to <new>` to the ops domain. The entry gives the path of the backup.
If the backup fails, the store does not change. The server stops and tells why. Make disk space available, or set `APEX_MEMORY_BACKUP_DIR` to a folder that you can write to. Then start the server again.
The store does not delete pre-migration backups. Delete old ones yourself when you do not need them.
If an old version of the package opens a store that a newer version changed, the old version stops. Upgrade the package and restart the MCP client.
### Do a check of the store
```sh
apex-memory status
```
The command does not change the store. It shows:
- The version of the package.
- The location of the store, without a password, and the store id.
- The schema version of the store, and the number of migrations that this package knows. If migrations are pending, the next start of the server applies them.
- The newest backup in the backup folders.
### Roll back
1. Install the old version. For example:
```sh
uv tool install "git+https://github.com/Shaurya-GitH/apex-memory@v0.1.0"
```
2. Import the pre-migration backup into a new, empty store:
```sh
apex-memory import ~/.apex-memory/backups/pre-migration-20261031-120000-7c29e0fc51324efebfe947858d65b7ac-v1-to-v2.db --url sqlite:///Users/you/.apex-memory/rolled-back.db
```
3. Set `APEX_MEMORY_URL` to the new store in each MCP client. Restart the clients.
The knowledge that agents wrote after the upgrade is not in the backup.
## Differences between the backends
SQLite and Postgres give the same pages, checks, briefs, links and log queries. These differences remain:
| Area | SQLite | Postgres |
| --- | --- | --- |
| `regex` search | Python `re` syntax. | POSIX syntax of the `~` operator. The pattern must also compile in Python. |
| `bm25` search | FTS5 `bm25()`. | `ts_rank` with BM25 weights. The hits are almost the same, but the rank order can be different. |
| Tokens for `bm25` | Paths and URLs split into words. | Paths and URLs can stay as one token. |
| `exact` search | A trigram index for queries of 3 characters or more. | A scan of all section rows. |
| Single writer | `BEGIN IMMEDIATE` and WAL. | An advisory lock for each schema. |
| Backup | `VACUUM INTO`. | A logical copy into a SQLite file. The file has the oldest SQLite schema that can hold the rows. Thus the old version can import a backup from before a migration. |
| Search snippets | The match is in brackets, for example `The [café] on`. | Context around the match, with no brackets. |
| `section_id` values | A refused write uses no id. | A refused write can use an id. Thus ids can be different from the ids of the same history on SQLite. Do not compare ids between backends. |
### Regular expressions on Postgres
The store compiles each `regex` pattern in Python first. Then it sends the pattern to Postgres to find sections. It finds log entries with Python. Thus a pattern must have the same meaning in the two syntaxes.
- Do not use `\b`. In Postgres, `\b` is a backspace, so the search finds no sections.
- Do not use `\y`, `\m` or `\M`. Python refuses them with `bad_regex`.
- For a word boundary, use character classes, for example `(^|[^A-Za-z0-9_])copies([^A-Za-z0-9_]|$)`.
- Do not use named groups `(?P<name>...)`. Do not use inline flags after the start of the pattern.
### Speed
`exact` search on Postgres scans rows. `log_query` with `page` scans rows on the two backends. This is fast for thousands of rows. For much larger stores, add an index.
## Run the tests
1. Clone the repository and go into it.
2. Run the tests on SQLite:
```sh
uv run python -m unittest
```
The Postgres tests are skipped. The result is `OK (skipped=93)`.
3. To run the tests on Postgres too, install the extra:
```sh
uv sync --extra postgres
```
4. Start a Postgres server. The tests create and drop one schema for each test in the database that you give.
```sh
docker run -d --name apex-memory-test-pg -e POSTGRES_PASSWORD=test -p 55432:5432 postgres:17
```
5. Run the tests with the URL of that database:
```sh
APEX_MEMORY_TEST_POSTGRES_URL=postgresql://postgres:test@localhost:55432/postgres uv run python -m unittest
```
6. Remove the server: `docker rm -f apex-memory-test-pg`.
## Verify a change
The unit tests do a check of the store. The verification harness does a check of the full path that an agent uses: the MCP stdio server, the CLI, and SQLite or Postgres. Use it before you say that a change works. Any agent can use it: Claude Code, Codex, Cursor or a person in a shell.
- The harness is [scripts/verify](scripts/verify).
- The procedure is [.claude/skills/verify-apex-memory/SKILL.md](.claude/skills/verify-apex-memory/SKILL.md). The folders `.cursor/skills/` and `.agents/skills/` contain a link to the same skill.
- The feature map is [.claude/skills/verify-apex-memory/features/](.claude/skills/verify-apex-memory/features/README.md). It has one file for each feature, with the steps and the result that proves each step.
Each run has its own folder `.verify/<run>/`, with its own `HOME` and its own databases. The harness does not open your real store. The Postgres run starts its own Docker container.
1. Start a run. For Postgres, use `--backend postgres`. Docker must be available.
```sh
uv run --extra postgres scripts/verify launch --backend sqlite
```
2. Make sure that the run is correct. The result must start with `OK`.
```sh
uv run --extra postgres scripts/verify doctor
```
3. Run the journey of one feature, or all journeys:
```sh
uv run --extra postgres scripts/verify drive domain-discovery
uv run --extra postgres scripts/verify all
```
4. Read the evidence in `.verify/<run>/evidence/<feature>-<n>/`. `transcript.jsonl` has each call and its result. `result.json` has each check.
5. Remove the run. The evidence stays.
```sh
uv run --extra postgres scripts/verify cleanup
```
Use `uv run --extra postgres`. A plain `uv run` removes the Postgres driver from the environment.
If you add or change a feature, add or change its journey in `scripts/verify` and its file in the feature map.
## Add a database backend
The store reaches the database only through the `Backend` interface in `apex_memory/backends/base.py`. Each backend is one module.
1. Write a module in `apex_memory/backends/` with a subclass of `Backend`. Set `name` and `location`. `location` must not contain a password.
2. Write the schema in `apex_memory/backends/sql/<name>/001_schema.sql`. `migrate()` applies the files in that folder in name order.
3. Add one line for each URL scheme to `BACKENDS` in `apex_memory/backends/__init__.py`.
4. Add a test class that runs `MemoryTest` on the new backend. Use `PostgresMemoryTest` in `tests/test_memory.py` as the example. Override `new_url()` to give a new empty store.
5. Run all the tests.
The backend must supply these methods:
| Method | What it must do |
| --- | --- |
| `__init__(url)` | Connect to the database that the URL names. |
| `transaction()` | Give one write transaction. Allow only one writer at a time across all processes. Commit on success. Roll back on an exception. |
| `query(sql, args)` | Run neutral SQL with `?` placeholders. Return rows that you can index by position and by column name. |
| `execute(sql, args)` | Run one statement. Return the number of rows that changed. |
| `insert(table, values)` | Insert one row and return its integer id. Accept a given id and move the id sequence after it. |
| `search(table, query, where, args, exact)` | Do a ranked full-text search with `score` and `snippet`. When `exact` is true, do a substring search. |
| `regex(expr)` | Return a condition that is true when `expr` matches the next `?` argument. |
| `now(minutes)` | Return SQL for the UTC time plus `minutes` as `YYYY-MM-DDTHH:MM:SS.mmmZ`. |
| `schema_version()`, `set_schema_version(version)` | Read and write the number of applied migrations. |
| `run_script(sql)` | Run one migration file. |
| `backup(destination)` | Write a full, verified copy of the store as a new SQLite file. |
| `close()` | Close the connection. |
`store.py`, `importer.py` and `server.py` contain only neutral SQL: `?` placeholders, `lower`, `coalesce`, `count`, `max`, `LIKE ... ESCAPE '!'`, `||`, `LIMIT` and `EXISTS`. All database-specific SQL goes in the backend. The test `PortabilityTest.test_no_database_specific_sql` fails if these files contain tokens such as `fts5`, `PRAGMA`, `ON CONFLICT`, `RETURNING`, `::`, `ILIKE` or `psycopg`.
## Agent rules template
[templates/AGENTS.md](templates/AGENTS.md) is a template of rules for agents that use this store. Copy it into your own `AGENTS.md` or `CLAUDE.md`. Then replace the placeholders.
## License
MIT. See [LICENSE](LICENSE).
TDQS
Scored across 19 tools
Most tools have clearly distinct purposes: read vs search, patch_section vs patch_header, log_query vs log_append, lease vs batch all differ in scope. Some residual overlap: patch_header's decision status field vs set_decision_status's Status line, and batch vs individual write tools could confuse an agent about which path to use. Descriptions are highly detailed and largely disambiguate these.
Mixed conventions: bare verbs (move, brief, read, search, check, batch), verb_noun (log_query, patch_section, create_note, set_decision_status, create_domain, list_domains), and bare nouns (links, preference, source, lease, status_item). All are readable and snake_case throughout, but there is no single predictable pattern.
19 tools is at the upper end for what the domain needs, but each maps to a distinct capability (notes, sections, headers, links, log, status, decisions, sources, preferences, leases, checks, batch). Nothing appears gratuitous, though the surface is slightly heavy.
Coverage is broad: create/read/update for notes, sections, headers, status items, decisions, sources and domains, plus search, links, log and validation. The notable gap is deletion/archival (no delete_note, delete_domain or link removal beyond uncite), which may be intentional for an auditable memory store but limits lifecycle completeness.