corthexis

Semantic memory for coding agents. Point it at a folder of notes; your agent recalls the right ones at the start of a task, in any language, without you loading an index into context.

A note is one markdown file holding one fact. corthexis embeds them, keeps the index in sync on a filesystem watch, serves recall over MCP, and — the part that turns out to matter most — checks that the memory is still actually there.

Apache-2.0. Python 3.10+. SQLite. No service to sign up for.

Why this exists

Agents do not fail at memory loudly. They fail by knowing less, and you attribute that to the model.

This tool exists because a memory layer went down twice in production without anyone noticing. Once the MCP server got overwritten in a config file while a different server was being added — nine days of sessions ran with no recall at all. Once the generated index outgrew the harness line budget, and dozens of notes became invisible at session start. Both times the session booted normally. Both times the only symptom was an agent that seemed to have gotten worse.

So corthexis ships a selfcheck that verifies rather than assumes, and the failure modes it knows about are written down in examples/ as notes, in the same format it indexes.

Related MCP server: memtomem

Quick start

git clone https://github.com/ninabot-ch/corthexis && cd corthexis
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt

export CORTHEXIS_NOTES_DIR=./examples          # or your own notes folder
export CORTHEXIS_DB=~/.local/share/corthexis/memory.db

.venv/bin/python -m corthexis.index            # embeds; first run downloads the model

Register the MCP server with your agent:

claude mcp add -s user corthexis $(pwd)/.venv/bin/python -m corthexis.server \
  -e CORTHEXIS_NOTES_DIR=$(pwd)/examples \
  -e CORTHEXIS_DB=$HOME/.local/share/corthexis/memory.db

Then ask it something the notes cover, in whatever language you like — « mon agent a répondu 202, c'est bon ? » matches an English note about HTTP 202, because the default model is cross-lingual.

Two tools are exposed: memory_search(query, top_k) returns ranked notes with a score and an excerpt; memory_get(name) returns one note in full.

To point it at Claude Code's own memory directory, set CORTHEXIS_NOTES_DIR to ~/.claude/projects/<project-slug>/memory.

Keeping it in sync

systemd/ has units for both halves: a .path unit reindexes within seconds of any note changing (inotify, incremental), and a .timer does a full pass nightly. A second timer runs the health check:

.venv/bin/python -m corthexis.selfcheck

It verifies the MCP server is declared in user scope (otherwise sessions started outside the project directory boot with no memory at all), that the server starts and serves its tools, that the generated index fits the harness budget in both lines and bytes, that every note on disk appears in it, and that no note has lost its description to a broken frontmatter block.

Exit 0 and silent when healthy. With --alert, the report is piped into $CORTHEXIS_ALERT_CMD — any shell command, so your paging credentials stay out of this repo.

Embedding backends

Set CORTHEXIS_EMBED_BACKEND:

The default model is multilingual on purpose. Changing CORTHEXIS_EMBED_MODEL means re-running with --rebuild: vectors from two models are not comparable.

The note format

See SCHEMA.md. The short version: one fact per file, a one-line description that doubles as the index hook and as embedded keywords, and a type of user, feedback, project or reference.

feedback and user notes are pinned to the top tier of the generated index, above the recency window — those are the working rules, and a rule you have to know to search for has already failed.

About the examples, and about the corpus

examples/ contains eight real notes, written for this repository. They are genuine engineering facts — the HTTP 202 trap, the browser profile lock, the YAML colon that silently kills recall — chosen because they are useful to anyone and specific to no one.

They are not a sample of our corpus, and there is no seeded demo data here. The corpus this tool was built for is private: five months, 289 notes, 260,000 words, produced while actually operating a company. Roughly every one of those notes contains either infrastructure detail or commercial information, so none of it ships, and a redacted version would leak by its shape alone.

We would rather say that plainly than dress up generated data as a working system. The engine is real and it is all here. The proof you should care about is not our notes — it is what happens when you run it against yours.

Built by Ninabot Sàrl, Geneva. The method around it: corthexis.com.