Mohamed Ashraf Elsaed

How to use aletheia-mem: memory for AI agents

By Mohamed Ashraf ElsaedPublished 6 min read

aletheia-mem is the npm package for Aletheia, a free, local memory and rules hub for AI coding tools. It keeps memories in one SQLite file on your machine. Tools that speak MCP, and scripts that call the REST API or the command line, can read them; what has been checked on a real install is listed at the end. This tutorial takes a few minutes (I did not time it) and ends with a real look at what a new coding session would receive.

Aletheia logo: a network shaped like a brain, with a stack of memory layers inside

Before you start

Aletheia needs Bun 1.1 or newer. The command line runs on Bun, not on Node. There is no account and no telemetry, and by default the server listens on 127.0.0.1 only.

npm install -g aletheia-mem

To try everything without touching your real setup, point Aletheia at throwaway folders first. Do this in each terminal you use:

export HOME=$(mktemp -d) ALETHEIA_DATA_DIR=$(mktemp -d) ALETHEIA_PORT=37999

Skip that line when you want to keep what you save. Nothing in this tutorial writes into a tool’s configuration unless a step says --write.

I ran every command below with aletheia-mem 0.1.10 on 2026-10-30, inside throwaway folders. The memories are made-up demo data for an imaginary shop project.

Step 1: start the server

aletheia-server
aletheia-mem listening on http://localhost:37999
  source db : ~/.claude-mem/claude-mem.db (read-only)
  data dir  : ~/.aletheia
  refresh   : off (set ALETHEIA_PROVIDER=claude-cli|openai to enable)
  extraction: worker on (rule-based)

The paths are shortened. Your data folder differs if you used the throwaway line above.

The default port is 37790. Open the address in a browser. The first screen is Home: pick a project and see, in plain words, what Aletheia knows about it, the rules that apply and the tools connected.

The Aletheia Home page for a project called shop: what Aletheia knows, listed newest first, and the rules that apply, with switches
Home for the demo project shop. The five tabs are Home, Activity, Knowledge, Rules and Connections.

The aletheia command also works while the server is stopped. It opens the same SQLite file.

Step 2: save memories

aletheia save "The deploy script needs Node 20.19.6 on the staging server" --project shop --pin
aletheia save "We chose SQLite over Postgres because the hub must run with no extra service" --project shop --type decision
aletheia save "Webhook retries use exponential backoff, at most 5 attempts" --project shop --type gotcha
aletheia save "Fixed the login redirect loop when the session cookie was missing" --project shop --type bugfix

--project names the project, --pin keeps a memory at the top of session context, and --type labels it (decision, gotcha, bugfix, note and others).

Terminal showing four aletheia save commands, each answered with Saved as and a number
Four memories saved, one of them pinned.
aletheia search "retry" --project shop --explain

Each result line is the memory id, the date, the type, the title, then the project and the tool that wrote it. --explain prints which search channels ran. Out of the box this is keyword search; semantic search is optional.

Terminal showing a search for retry returning one gotcha memory, then adding a rule and listing it
A search with --explain, then a rule added and listed.

Step 4: see secrets removed before storing

Hooks redact secrets and <private> blocks before anything is stored. You can test it by feeding a hook a recorded payload that carries a fake key. The hook takes the project name from the folder it runs in, so run it from a folder named shop:

mkdir -p shop && cd shop && git init -q
printf '%s' '{"hook_event_name":"UserPromptSubmit","session_id":"s1","cwd":"'$PWD'","prompt":"Deploy to staging with token sk-abcdefghijklmnopqrstuvwx1234 and <private>customer list: Acme</private> then run the tests"}' \
  | aletheia hook claude-code UserPromptSubmit
aletheia search "staging" --project shop
Terminal showing the hook exiting with code 0 and the stored memory with a redacted api-key marker and a private marker
The hook exits 0, and the stored text holds markers, not the key or the private block.

Redaction is pattern based, so it is not complete. It also does not run when you write through the REST route POST /v1/memories or the dashboard note box. Do not paste secrets into those two.

Step 5: add a rule

A rule is a standing instruction for every tool. Write it once:

aletheia rules add "Run the tests before saying a task is done"
aletheia rules list

The Rules tab shows the same rules, with Confirm, Turn off, Edit and Replace. A separate step writes your rules into each tool’s own file, such as CLAUDE.md or AGENTS.md, and it starts as a preview.

The Aletheia Rules tab listing three rules, each with Confirm, Turn off, Edit and Replace buttons
The Rules tab. The screenshot also shows two extra demo rules that are not in the commands above.

Step 6: see what a new session receives

This is the block a coding tool gets when a session starts in the shop project:

aletheia context --project shop
Terminal showing the session-start block: pinned memory, recent memories grouped by day, session requests, rules, a legend, a fetch hint and an estimated token line
The pinned memory comes first, then recent ones, then the rule. The block is wrapped in aletheia-memory tags with a note that its content is data, not instructions.

The last line is an estimate (characters divided by four). With four short memories the block is larger than the memories it lists, because the legend and the hint cost tokens. A real saving needs longer notes.

Step 7: preview the connection to a tool

Connecting a real tool changes files, so the default is a dry run:

aletheia install claude-code
Terminal showing the dry run of aletheia install claude-code: three files that would be written and the note Dry run: nothing was written
Three files would change. Paths are shortened to ~ and the throwaway data folder.

It lists the MCP entry in ~/.claude.json, the hooks in ~/.claude/settings.json and the rules in ~/.claude/CLAUDE.md. Each changed file gets a timestamped backup. To apply it, run aletheia install claude-code --write with your real home folder. To undo it, run aletheia uninstall claude-code --write. The documentation says uninstall refuses if a file changed after install (it then needs --force) and has already cleaned the other files, so check the output.

Look around the dashboard

The Knowledge tab is where you search, edit, pin, hide and export what Aletheia stored.

The Aletheia Knowledge tab: counts of memories, facts, pinned and hidden items, filters by kind, scope and type, and a list of memory cards
Knowledge, with filters and one card per memory.

Where agents use it

Over MCP an agent gets 13 tools. The pattern the context block teaches is search for an index, timeline for the neighbours and get_observations for the full text. save_memory, add_rule and session_start_context are there too.

What I checked, and what I did not

I ran the commands, except the two --write commands, and took the terminal outputs and dashboard screenshots myself, with aletheia-mem 0.1.10 on 2026-10-30, using a throwaway home folder and data folder so no real memory was touched. The connection step was a dry run. I did not run aletheia uninstall.

Status as the project states it: the MCP configuration was listed by the real command line of Claude Code, Command Code, Codex CLI and OpenCode on 2026-10-27. Hooks have run in real sessions of Claude Code (two days of use), Command Code (one short session) and Codex CLI (one interactive session), for one user on one machine. Cursor, Gemini CLI and Windsurf are configuration written from their documentation, not tested on a real install, and no hook has run inside them or inside OpenCode. Windows is tested in continuous integration only. The status is alpha, and answer accuracy is not measured.

What I would do differently

  1. Redact on every write path. I would not have to write the warning in step 4 if the REST route and the dashboard note box redacted too.
  2. Put the throwaway-folder line at the top of the README. It is the safest way to try the tool, and today it sits in the quickstart instead of the first screen people read.

Sources

This post was drafted with AI assistance. I reviewed every claim and ran the commands shown.

About the project: Aletheia.

Mohamed Ashraf Elsaed
Mohamed Ashraf Elsaed
Technical Lead at Convertedin, Cairo. I build tools for AI coding agents and write about Laravel, Node and engineering.