apex-memory
An MCP knowledge-store server that lets agents discover domains, read/search notes, and make checked, transactional markdown edits.
Discover domains with
list_domainsand load task context withbrief.Search notes (
bm25,exact,regex), read whole notes or sections, inspect links, and query logs/tool events.Create and edit notes/sections with version checks, summaries, page headers, build state, and safe
move/promotion.Manage domains, status items, narrative log entries, owner preferences, sources, and decision-record lifecycles.
Coordinate concurrent work with section leases and grouped all-or-nothing
batchwrites.Enforce owner/worker roles: workers read broadly but write only their working notes and append logs.
Run automatic checks on writes for broken links, missing summaries, duplicate paragraphs, malformed decisions, and stale live sources; new problems roll back the write.
Uses PostgreSQL as a database backend for the markdown knowledge store, including moving an existing store from SQLite to Postgres and backend-specific behavior.
Stores markdown knowledge in a local SQLite database, supporting domains, notes, sections, indexing, link and consistency checks, decision records, status items, logs, preferences, leases, backups, and markdown folder imports.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@apex-memory Give me the brief for the myproject domain"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_memoryCommand-line interface (CLI):
apex-memoryLicense: 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.
Make sure that
uvis installed. Runuv --version. If the command fails, install uv from https://docs.astral.sh/uv/.Install the package from GitHub:
uv tool install git+https://github.com/Shaurya-GitH/apex-memoryRun
apex-memory --help. If the shell cannot find the command, runuv tool update-shelland open a new shell.Create the store. The default database is the SQLite file
~/.apex-memory/memory.db.apex-memory initRegister the MCP server for all of your projects. Replace
claude-codewith a short name for the agent.claude mcp add apex-memory --scope user -- apex-memory serve --actor claude-code --role ownerStart a new Claude Code session. Run
/mcpand make sure thatapex-memoryshows as connected.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.Tell the agent to create the ops domain
memory-opswithcreate_domain. The store records refusals and errors there.Copy templates/AGENTS.md into your own
AGENTS.mdorCLAUDE.md. Replace its placeholders.In a new session, the agent calls
list_domains. It selects the domain whose description agrees with the subject of the work. Then it callsbriefwith that domain.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 ( | 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 | 60% |
Part of the store output that came from | 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 |
Note | One markdown page with a path such as |
Page header | Three fields on a project note: decision status, implementation status and evidence checked. The store also keeps the date |
Index | The page |
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 |
|
Decision record | A heading such as |
Decision status |
|
Build state | An optional value on a note: |
Domain mode | How native a domain is: |
Status item | One item on the page |
Log | The page |
Tool event | An automatic log record of each write, each search, each |
Source | A record of where knowledge came from: |
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 |
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 |
Note status | The status that the store keeps for each note: |
Ops domain | The domain that gets an automatic record of each refusal and each error. The default name is |
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
livesource, with averified_atdate 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_statuschanges the Status line.You can edit a
proposedrecord. You can only append text to anaccepted,rejected,voidor superseded record.The status can change from
proposedtoaccepted,rejectedorsuperseded. It can change fromacceptedtosupersededorvoid.superseded_bymust name an accepted decision.A record without a Status line is
unclassified. It has a row in the decisions table.set_decision_statuschanges it toproposed,acceptedorrejected, and writes the Status line as the first line of the record. Other targets givebad_transition.unclassifiedis 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
voidonly when an acceptance was an error.voidneeds areason. 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 |
| A scratch note. It is not project knowledge. | The path is under |
| Project knowledge that you can use. |
|
| The note cites a decision that is | The store sets it when |
| The note is not current guidance. The store keeps it as history. | The owner sets it with |
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,
D1does not agree withD10. A link to the decision record is also a citation.The store flags only
currentnotes. 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>/decisionsand<domain>/log, working notes or historical notes.The reason names the decision, for example
cites D09 (superseded by D15).set_decision_statuslists the flagged notes inneeds_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.
readputs anoticefirst, and givesstatusandreview_reason.searchhits give thestatus.briefandchecklist the pages.list_domainsgives a count.
To remove the flag, do these steps:
Read the note and the decision that replaced the old one.
Correct the note with
patch_section, if it is not correct.Call
patch_headerwith newevidenceor a newverified_at. The status goes back tocurrent.
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 |
|
SQLite and Postgres, with uv |
|
SQLite only, with pip |
|
SQLite and Postgres, with pip |
|
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:
The option
--url.The environment variable
APEX_MEMORY_URL.The SQLite file
~/.apex-memory/memory.db.
URL | Database |
| A SQLite file at an absolute path. |
| A SQLite file relative to your home folder. |
| A bare path is a SQLite file. |
| A Postgres database. |
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.dbThe output is store <store id> at <path>. Run init again to see the store id. It does not change a store.
Postgres
Install the package with the
postgresextra. See Install.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:17If 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.Create a user. The password of the
postgresuser istest.psqlasks for it.psql -h localhost -U postgres -c "CREATE ROLE apex LOGIN PASSWORD 'secret'"If
psqlis not installed, run it in the Docker container. Use this form for eachpsqlcommand in this section:docker exec -e PGPASSWORD=test apex-memory-pg psql -U postgres -c "CREATE ROLE apex LOGIN PASSWORD 'secret'"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"Create the store:
apex-memory init --url postgresql://apex:secret@localhost:5432/apex_memorySet 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 |
| The name of the domain. Use lowercase letters, digits and hyphens. |
| The name that the start pages show. |
| What the domain holds and when to select it. Agents read it in |
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.
At the start of a session, the agent calls
list_domains. It calls it again when the subject of the work changes.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.
The agent calls
brieffor 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 |
No, never for this topic | It calls |
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 |
| No step is left. |
| At least one step is left. |
| 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 |
| 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. |
| The role of the agent. The default for |
| The database. You can also set |
| The domain that gets the records of refusals and errors. The default is |
| 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 ownerFor 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 ownerOther 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 |
| The sessions of the owner. | All the tools. |
| Agents that you run for the owner. | Read and search all the knowledge. Write only its own working notes under |
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 |
| Shows each domain with its description, number of notes, number of pages that need review, |
| 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. |
| Finds text in notes, sections and log entries. |
| Reads a full note, or one section and its subsections, with ids, versions, the |
| Shows the links out of a note, into a note, or both, up to 3 hops. |
| Filters log entries by time, |
| Edits one section. |
| Edits the page header of a note with a version check. New |
| Creates a note in a domain that exists. It never overwrites. |
| Creates a domain with its description and its four start pages. Owner only. |
| Renames a note in its domain and rewrites all links to it. It also promotes a working note: the status changes from |
| Adds, updates or closes one status item. |
| Changes the Status line of one decision record. A record without a Status line ( |
| Appends one entry to the log of a domain. The pages that it names must exist. |
| Adds or retires a preference of the owner. |
| Adds a source, or cites or uncites a source from a note. |
| Takes or releases a lease on a section. |
| Shows the problems of a domain. |
| Does a list of writes in one transaction. See Write two or more notes together. |
How to edit a section
Call
readwithpathandheading. The result givessection_id,versionandcontent.Change the text of
content.Call
patch_sectionwithop: "replace", the newcontent,section_id, andif_versionset toversion.If the result is
version_conflict, another agent changed the section. Merge your change into thecontentof the refusal.Call
patch_sectionagain withif_versionset tocurrent_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:
| What it does |
|
| Replaces the section and its subsections with | Necessary |
| Adds | Not necessary. The store does not compare it. |
| Adds | Necessary |
| 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_appendandsource.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_appendwrites 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 noop_index.The result gives
results, with the result of each write in the order of the list.
Search modes
Mode | Use it for |
| 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. |
| Ids, hashes and paths. A search for full words that ignores case. |
| 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.
| Cause | What to do |
| The section or note changed after you read it. | Merge into the |
|
| Read the section. Give its |
| The write adds a problem. | Correct the problem in your text. Try again. |
| Another agent has a lease on that part. | Wait until |
| A worker tried to write outside its working notes. | Write under |
| A worker tried an owner action. | Ask the owner. |
| The domain is not in the store. | Use a domain from |
| The store cannot find the note or section, or the heading is not unique. | Use one of the |
|
| Give |
|
| Give |
| A project note needs a summary and a full page header. | Give |
| The note exists. | Use |
| The store makes the section from rows. | Use |
| The edit changes a decision record in a way that is not permitted. | Use |
|
| Name pages that exist. |
| The pattern does not compile in Python, or Postgres refuses it. | Correct the pattern. |
|
| Use |
|
| Use proposed to accepted, rejected or superseded, or accepted to superseded or void. An unclassified record goes to proposed, accepted or rejected. |
|
| Use |
| The topic is already a declined topic. | The refusal gives the |
|
| Give the reason. |
|
| Use |
| A | Correct that write. |
|
| Give the quote of the owner. |
|
| Give |
| The path is not permitted, for example a | Use a path of a normal note. |
|
| Use the domain that exists, or another domain name. |
|
| 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 |
| Creates the store, or shows the store that exists. |
| Starts the MCP stdio server. |
| Imports a folder of markdown notes as one domain. |
| Copies a full store, such as a SQLite file or a backup, into a new empty store. |
| Makes sure that each imported page renders back the same as its file. |
| Prints the brief of a domain. |
| Prints the problems of a domain. The exit code is 1 if there are problems. |
| Writes a verified backup. See Backups. |
| 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. |
| 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 |
| Rows such as |
| Sections that start with |
| The last level-2 headings with the format |
| Headings such as |
| Each note becomes a |
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 passThe 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/myprojectverify 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.
Create an empty Postgres database. See Postgres.
Copy the store:
apex-memory import ~/.apex-memory/memory.db --url postgresql://apex:secret@localhost:5432/apex_memoryDo a check of each domain:
apex-memory check myproject --url postgresql://apex:secret@localhost:5432/apex_memorySet
APEX_MEMORY_URLto 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 14If 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 |
|
Postgres | A logical copy of the store into a new SQLite file, then |
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.dbThe 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.
Copy the file:
cp ops/com.apex-memory.backup.plist ~/Library/LaunchAgents/Load the agent:
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.apex-memory.backup.plistTo do a test now, run
launchctl kickstart gui/$(id -u)/com.apex-memory.backup.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
Upgrade the package. Use the command for the installer that you used:
Installer
Command
uv
uv tool upgrade apex-memorypip
pip install --upgrade --force-reinstall "git+https://github.com/Shaurya-GitH/apex-memory"uv tool upgradegets 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.Restart each MCP client, or run
/mcpand reconnect the server. The client then starts the new server.Run
apex-memory status. The lineschema versionmust showup 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:
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.
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
backupsnext to the store file.Postgres: the backup is a SQLite file in
~/.apex-memory/backups.If
APEX_MEMORY_BACKUP_DIRis set, the backup goes into that folder for both backends.
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.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 statusThe 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
Install the old version. For example:
uv tool install "git+https://github.com/Shaurya-GitH/apex-memory@v0.1.0"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.dbSet
APEX_MEMORY_URLto 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 |
| Python | POSIX syntax of the |
| FTS5 |
|
Tokens for | Paths and URLs split into words. | Paths and URLs can stay as one token. |
| A trigram index for queries of 3 characters or more. | A scan of all section rows. |
Single writer |
| An advisory lock for each schema. |
Backup |
| 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 | Context around the match, with no brackets. |
| 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,\bis a backspace, so the search finds no sections.Do not use
\y,\mor\M. Python refuses them withbad_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
Clone the repository and go into it.
Run the tests on SQLite:
uv run python -m unittestThe Postgres tests are skipped. The result is
OK (skipped=93).To run the tests on Postgres too, install the extra:
uv sync --extra postgresStart 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:17Run the tests with the URL of that database:
APEX_MEMORY_TEST_POSTGRES_URL=postgresql://postgres:test@localhost:55432/postgres uv run python -m unittestRemove 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.
The procedure is .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/. 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.
Start a run. For Postgres, use
--backend postgres. Docker must be available.uv run --extra postgres scripts/verify launch --backend sqliteMake sure that the run is correct. The result must start with
OK.uv run --extra postgres scripts/verify doctorRun the journey of one feature, or all journeys:
uv run --extra postgres scripts/verify drive domain-discovery uv run --extra postgres scripts/verify allRead the evidence in
.verify/<run>/evidence/<feature>-<n>/.transcript.jsonlhas each call and its result.result.jsonhas each check.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.
Write a module in
apex_memory/backends/with a subclass ofBackend. Setnameandlocation.locationmust not contain a password.Write the schema in
apex_memory/backends/sql/<name>/001_schema.sql.migrate()applies the files in that folder in name order.Add one line for each URL scheme to
BACKENDSinapex_memory/backends/__init__.py.Add a test class that runs
MemoryTeston the new backend. UsePostgresMemoryTestintests/test_memory.pyas the example. Overridenew_url()to give a new empty store.Run all the tests.
The backend must supply these methods:
Method | What it must do |
| Connect to the database that the URL names. |
| Give one write transaction. Allow only one writer at a time across all processes. Commit on success. Roll back on an exception. |
| Run neutral SQL with |
| Run one statement. Return the number of rows that changed. |
| Insert one row and return its integer id. Accept a given id and move the id sequence after it. |
| Do a ranked full-text search with |
| Return a condition that is true when |
| Return SQL for the UTC time plus |
| Read and write the number of applied migrations. |
| Run one migration file. |
| Write a full, verified copy of the store as a new SQLite file. |
| 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 toolsbatchA
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.
linksA
Links of a note: 'out' (what it links to), 'in' (what links to it) or 'both', up to 3 hops. Each link has its source section, anchor, and whether it is broken or points outside the store.
Inputs: path (required), depth, direction.
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.
searchA
Search note titles and summaries, sections and log entries. mode: 'bm25' (ranked keywords; hits that hold more of the query terms rank higher, and weak hits holding few of them drop out), 'exact' (whole words or phrase, ignoring case, e.g. ids and hashes) or 'regex' (Python syntax). scope: a domain or folder such as 'project/docs'; empty searches every domain. Hits carry path, section id, heading path, version and a snippet.
Inputs: query (required), mode, limit, scope.
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
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.
Related MCP Connectors
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Related MCP Servers
- AlicenseAqualityDmaintenanceMarkdown + SQLite knowledge store with bidirectional wikilinks, exposed as an MCP server for AI agents to maintain an interconnected knowledge base.11MIT
- AlicenseAqualityCmaintenanceMCP 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.13MIT
- AlicenseAqualityBmaintenanceProvides 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.733 PyPI9MIT
- FlicenseNot gradedqualityAmaintenanceEnables 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.-