Skip to main content
Glama

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.

Contents

Related MCP server: Zero Brain MCP Server

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.

  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:

    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.

    apex-memory init
  5. Register the MCP server for all of your projects. Replace claude-code with a short name for the agent.

    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.

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

If you have a folder of markdown notes, you can import it as a domain. See 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.

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.

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:

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

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.

  2. Start a Postgres server. For a local test server, use Docker:

    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.

    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:

    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.

    psql -h localhost -U postgres -c "CREATE DATABASE apex_memory OWNER apex"
  5. Create the store:

    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:

    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:

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.

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:

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.

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:

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.

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

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

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:

{
  "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.

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.

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.

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.

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.

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:

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

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.

  2. Copy the store:

    apex-memory import ~/.apex-memory/memory.db --url postgresql://apex:secret@localhost:5432/apex_memory
  3. Do a check of each domain:

    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

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:

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:

    cp ops/com.apex-memory.backup.plist ~/Library/LaunchAgents/
  2. Load the agent:

    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:

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

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:

    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:

    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:

    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:

    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.

    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:

    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.

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.

    uv run --extra postgres scripts/verify launch --backend sqlite
  2. Make sure that the run is correct. The result must start with OK.

    uv run --extra postgres scripts/verify doctor
  3. Run the journey of one feature, or all journeys:

    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.

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

Available Tools

19 tools
batchA

Several writes in one transaction, all or nothing: ops = [{"tool": name, "args": {...}}, ...] with tools create_note, patch_section, patch_header, status_item, set_decision_status, log_append and source. Each op has its own role rules and refusals. The checks (and the pages that log_append names) run once, against the final state, so notes that link to each other can be created together. A refusal rolls back every op and gives op_index. Returns the result of each op.

Inputs: ops (required), task_id.

briefB

Start-of-task read: store identity and open check problems, the index, decisions by status and open status items, then the last log_entries log entries. max_chars caps the index and the status block separately; the log entries always appear in full.

Inputs: domain (required), max_chars, log_entries.

checkB

Read-only check of a domain: broken links and anchors, notes missing from the index, an index without its summary (the domain description), the same paragraph claimed in two notes, decision records without exactly one Status line, stale live sources. The same check runs inside every write and rolls the write back if it adds a problem.

Inputs: domain (required).

create_domainA

Create a new domain with its start pages: index (with the catalog), status, log and decisions. description is the domain's line in list_domains: what it holds and when to choose it (e.g. "not for X; use Y"); it is kept as the index summary. domain: lowercase letters, digits and hyphens. Owner only.

Inputs: title (required), domain (required), description (required), task_id.

create_noteB

Create a new note (never overwrites) in an existing domain. body is markdown (text before the first heading is allowed). A project note needs a summary (its index line) and the page header (decision_status, impl_status, evidence). A working note (/working//…) needs neither and stays out of the index.

Inputs: path (required), title (required), body, tags, +5 more.

leaseA

Claim a section (and its subsections) while drafting a long edit, for minutes (1–60, default 15). Other agents' writes to it, its subsections or its ancestors are refused until it expires or is released; your own patch_section releases it. action: 'take' or 'release'.

Inputs: action (required), path, heading, minutes, +2 more.

list_domainsA

Every domain: its description (what it holds and when to choose it), note count, last log activity, and ops: true for the domain that records the memory system's own failures. Choose domains by description, then call brief. description_missing: true means the index has no summary; the first paragraph of the index stands in for it. preferences: the owner's active preferences for every domain (e.g. "No knowledge base for ": do not ask again to create one).

Inputs: no named parameters.

log_appendB

Append a narrative log entry. The database stamps the time; pages must exist in the store.

Inputs: op (required), pages (required), domain (required), source (required), +2 more.

log_queryA

Log entries filtered by time (since/until: ISO date or date-time, local time if no offset; until a date includes that day), op substring, page and task id; the newest limit matches, oldest first. include_tool adds the automatic tool events (writes, searches).

Inputs: domain (required), op, page, limit, +4 more.

moveB

Rename a note within its domain; every link to it is rewritten in the same transaction (anchors kept). Moving a working note out of /working/ promotes it into project knowledge: owner only, and it needs a summary and, if it has none, the page header. Index, status, log and decisions pages do not move.

Inputs: path (required), new_path (required), summary, task_id, +3 more.

patch_headerA

Edit a note's page header: decision status, implementation status, evidence checked, verified_at (YYYY-MM-DD). if_version is the note version (read without a heading returns it). Fields left out keep their value; new evidence sets verified_at from its first date unless verified_at is given.

Inputs: path (required), if_version (required), task_id, evidence, +3 more.

patch_sectionB

Edit one section. op: 'replace' (content = what read returned for the section, subsections included, headings relative), 'append' (after the subtree; may add subsections), 'prepend' (before the own text; no headings) or 'replace_own_text' (only the text before the first subsection; subsections kept; no headings). All but append need if_version (the section version read returned). On a page whose only section is the root, append and replace on the root can add headings. Optional summary updates the note's index line (on /index: the domain description). All or nothing, with the checks inside.

Inputs: op (required), content (required), path, heading, +4 more.

preferenceA

Owner preferences layer. action='add' records how the owner wants work done (text) with the owner's own words (owner_quote, required); domain limits it to one domain, empty means everywhere. action='retire' (owner only) ends one by item_id. Every brief shows the active ones.

Inputs: action (required), text, domain, item_id, +2 more.

readB

Read a whole note (no heading) or one section with its subsections. A section's content has headings relative to it (a direct child is '#'), exactly what patch_section's replace accepts. Returns ids and versions for the outline, the page header fields and live-source flags.

Inputs: path, heading, max_chars, section_id.

set_decision_statusA

Move a decision record through its life cycle by rewriting its one Status line: proposed -> accepted, rejected or superseded; accepted -> superseded (superseded_by must be an accepted decision) or void (an acceptance made in error; needs reason, which is added to the record as a Void reason line). Owner only.

Inputs: id (required), domain (required), status (required), reason, +2 more.

sourceA

Sources behind knowledge. action='add' registers or updates one (kind: snapshot, live, transcript (ref = run id or file), web, owner; verify_live=True means re-check the live system before acting on a copy) and, with path, cites it from that note. 'cite' / 'uncite' link an existing source to a note. Citing a verify_live source is refused while the note's verified_at is stale: refresh it with patch_header first.

Inputs: id (required), action (required), ref, kind, +4 more.

status_itemA

Add one status item (action='add', kind: state|open|blocker|next, text), change the text (and optionally the kind) of an open one (action='update', item_id, text) or close one (action='close', item_id). The status page and brief render from these items; the event keeps the old text. Owner only.

Inputs: action (required), domain (required), kind, refs, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 19 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Markdown + SQLite knowledge store with bidirectional wikilinks, exposed as an MCP server for AI agents to maintain an interconnected knowledge base.
      11
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for managing a local, domain-agnostic knowledge base using Markdown notes with frontmatter. Enables AI agents to capture, read, search, link, and maintain notes with atomic writes and privacy controls.
      13
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Provides AI agents with a local, private Markdown-based memory vault and SQLite search. Enables agents to search, read, list, and traverse linked knowledge pages via MCP with zero external runtime dependencies.
      7
      33 PyPI
      9
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables creating, linking, searching, exploring, and synthesizing atomic notes as a knowledge graph through MCP-compatible clients such as Claude. Supports tags, note types, semantic relationships, Markdown storage, and an SQLite index for efficient traversal.
      -