A memory server for AI agents. It stores facts, notes, and decisions in a versioned, hierarchical SQLite database. Your agent reads the database before a task and writes to it after the task.
The server speaks MCP to Claude Code, Cursor, or any MCP-capable client. The backing store is one SQLite file on your machine. No API keys. No hosted service. No daemon to manage. The first agent starts the daemon, and all later agents on the same machine use it.
You need Node 18 or later. The script checks for it before it downloads anything.
macOS or Linux (amd64 or arm64):
curl -fsSL https://raw.githubusercontent.com/map588/memstate/main/install.sh | bashWindows 10 1803 or later on amd64, or Windows 11 on arm64 (it runs the amd64 build), in PowerShell:
irm https://raw.githubusercontent.com/map588/memstate/main/install.ps1 | iexThe script does these steps:
- It downloads the newest release:
the
memstateddaemon for your platform andmemstate-mcp.tar.gz, which holds the MCP proxy and its Node packages. - It installs both. Then it starts the proxy once with a scratch database, to make sure that the proxy finds the daemon.
- In a terminal, it runs
memstate-mcp setup. Setup finds Claude Code, Claude Desktop, Cursor and Windsurf, asks for the embedding model, and asks before it changes a config. - It asks whether to install the Claude Code skill and hooks (see below).
Where the files go:
| macOS, Linux | Windows | |
|---|---|---|
| Programs | ~/.local/share/memstate/ ($XDG_DATA_HOME/memstate when set) |
%LOCALAPPDATA%\Programs\memstate\ |
| Commands | links in ~/.local/bin: memstated, memstate, memstate-mcp |
the server\ directory of the programs, added to your user PATH |
The proxy finds the daemon next to it, in server/, so the MCP config
does not depend on PATH. Your memories stay in ~/.memstate/.
Set these environment variables to change what the script does:
MEMSTATE_VERSION=v0.8.0installs that release, not the newest one.MEMSTATE_INSTALL_DIRchanges the directory for the links (macOS, Linux).MEMSTATE_SETUP=0or1skips or runsmemstate-mcp setupwith no prompt.MEMSTATE_INSTALL_SKILL=0or1skips or installs the skill with no prompt.
For example:
curl -fsSL https://raw.githubusercontent.com/map588/memstate/main/install.sh | MEMSTATE_INSTALL_SKILL=1 bash$env:MEMSTATE_INSTALL_SKILL = '1'; irm https://raw.githubusercontent.com/map588/memstate/main/install.ps1 | iexTo update, run the script again. It replaces the daemon and the proxy
together. memstated upgrade replaces only the daemon.
Each release has a SHA256SUMS file. The install scripts and
memstated upgrade check every download against it before they run or
unpack the download, and stop when a checksum is different. The file
comes from the same release, so the check finds a damaged or replaced
download. It does not replace trust in the release itself.
To uninstall on macOS or Linux:
python3 ~/.local/share/memstate/configure-claude-hook.py uninstall # removes the hooks from settings.json
rm -rf ~/.local/share/memstate ~/.claude/skills/memstate ~/.claude/skills/memstate-rectify ~/.claude/hooks/memstate-*.sh
rm -f ~/.local/bin/memstated ~/.local/bin/memstate ~/.local/bin/memstate-mcp
claude mcp remove memstate --scope userTo uninstall on Windows:
python "$env:LOCALAPPDATA\Programs\memstate\configure-claude-hook.py" uninstall
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Programs\memstate", "$HOME\.claude\skills\memstate", "$HOME\.claude\skills\memstate-rectify", "$HOME\.claude\hooks\memstate-*.sh"
claude mcp remove memstate --scope userThen remove %LOCALAPPDATA%\Programs\memstate\server from your user PATH.
Remove the memstate entry from the config of each other MCP client.
You need Go 1.27+ and Node 18+.
git clone git@github.com:map588/memstate.git
cd memstate
make installThis puts two programs on your PATH:
memstated: the Go daemon. It installs to$(go env GOPATH)/bin, or to$GOBINwhen set.memstate-mcp: the MCP stdio proxy, linked fromclient/withnpm link.
make uninstall removes both. make build compiles in place and does
not touch PATH. make test runs the Go tests, the end-to-end smoke
test, and the MCP regression suite (client/test/regression.mjs). The
regression suite calls each tool through the real proxy and daemon
against a temporary database.
On Windows the same make targets run from cmd.exe or PowerShell with
GNU make (for example choco install make), Go, Node and Python on PATH.
You do not need bash or coreutils. The build produces memstated.exe,
and make install copies it to GOBIN as memstated.exe and
memstate.exe instead of a symlink. Git Bash and WSL work too. The hook
scripts that make install-skill copies are bash scripts and need Git
Bash to run.
Semantic search needs a local embedding server. Two kinds work:
- Ollama, the default, at
http://127.0.0.1:11434. - Any server with an OpenAI-compatible embeddings API, for example the
llama.cpp server, LM Studio, or vLLM. Its base URL ends in
/v1, and the daemon then sendsPOST {url}/embeddingswith{"model", "input"}instead of Ollama's/api/embeddings.
Pick the server and model once, in the settings file (see Configuration); every later install, upgrade or restart keeps them:
# Ollama
ollama pull qwen3-embedding:4b
memstated config set MEMSTATE_EMBED_MODEL qwen3-embedding:4b
# llama.cpp server
llama-server -m Qwen3-Embedding-4B-Q8_0.gguf --embeddings --pooling last --alias qwen3-embedding-4b --port 8081
memstated config set MEMSTATE_EMBEDDING_URL http://127.0.0.1:8081/v1
memstated config set MEMSTATE_EMBED_MODEL qwen3-embedding-4b
memstated restart # a running daemon applies the change
memstated config # shows what is in effect, and whether the daemon matchesmemstate-mcp setup --embedding-url URL writes the same keys after
listing the models that server serves. The model name must be the one
the server answers to (Ollama: qwen3-embedding:4b; llama.cpp:
whatever --alias says).
If the server does not run, memstate still works. Writes and FTS search
are not affected. The default hybrid search returns FTS hits alone and
sets degraded in the response. Explicit semantic search returns 503
until the embedder is available.
MEMSTATE_OLLAMA_URL and --ollama-url are the old names. They still
work, print a notice, and will be removed.
When the server rejects a long memory ("context length" from Ollama, "too large to process" from llama.cpp), the daemon halves the text and tries again.
The daemon limits the embedding calls that it sends to the server at the same time: two for content embeds and the backfill, four for search queries. Many agents cannot overload one local model server, and a burst of writes does not make searches wait.
If you use Claude Code, the install script asks whether to install the
bundled skill and hooks. From a clone, make install-skill installs
them. The memstate skill goes to ~/.claude/skills/memstate/, and
three hook scripts are added. A second skill, /memstate-rectify, goes
to ~/.claude/skills/memstate-rectify/. It tells an agent to bring the
memories of one project into the current form: it splits a memory that
holds a list of facts, moves a memory away from the bare name of an
area, corrects keypaths, and makes each text start with the question.
memstate_audit.py in the memstate skill lists the memories that break
the write rules, and it writes nothing. Two hooks run on
UserPromptSubmit:
memstate-persist-reminder.shpoints you tomemstate_rememberafter three or more file edits since your last persist.memstate-recall.shrunsmemstated recall. It searches the current repository's memories with the prompt text (hybrid mode) and injects up to three hits the model has not seen in this session. It prints the hits that match the prompt by meaning; only when there is none (also with no embedder) does it print word matches, shorter. A shared-scope hit prints only for a match by meaning. It finds the shared daemon throughMEMSTATE_ADDRor~/.memstate/daemon.addr(see "One daemon for all agents"). A private daemon (MEMSTATE_CHILD=1) is not visible to the hook, and the hook then prints nothing. When the daemon runs a different version or build than the hook, the hook prints a notice one time and asks you to restart the daemon. SetMEMSTATE_NO_RECALL=1to turn the hook off.
The skill scripts need Python 3. The hooks are bash scripts. On Windows,
Claude Code runs hooks with Git Bash, so the install script adds the
hooks only when it finds Git Bash. The persist reminder also needs jq
and does nothing without it.
The third script, memstate-compact.sh, runs memstated compact-hook
on PreCompact and PostCompact, so a /compact or an auto-compact needs
no other step:
- Before the compact, it prints instructions for the summary. The
model writes a
## Sessionpart (the task, what is done with its evidence, what is not done) and then one### <topic>section for each decision, gotcha, todo item, open question and note, as many as the handoff needs. The hook also lists the keypaths that the project holds in those areas, so the model updates a fact under its name. Text that you give to/compactstays in effect. - After the compact, it files each
###section as one memory atdecisions.<topic>,gotchas.<topic>,todo.<topic>,questions.<topic>ornotes.<topic>in the session's project. A memory that exists under that name is superseded, as with any write, andmemstate historyshows each version. The session part goes totask.compact.<YYYY_MM_DD>with the list of the keypaths that were filed; a second compact on the same day supersedes it. The hook does not write totask.summary.<date>, which the agent writes at the end of a task, and not to an area keypath such asdecisionsitself. Each memory has the topiccompact.
The compact hook starts the shared daemon when none runs, for example after the daemon's idle timeout. It does not create a project outside a git repository, and it stores nothing from the home directory or for a subagent. When it cannot store a part of the summary, Claude Code shows you the reason. The summary is the model's text: the instructions tell it to leave out secrets and denied tool calls, and the hook does not check that.
make uninstall-skill removes the skill and the hooks. The install
is idempotent and safe to run again. It replaces existing memstate
entries in settings.json and does not duplicate them.
The install script runs memstate-mcp setup, which writes the config
for you (with node and the full path of the proxy). To do it by hand:
Claude Code (one command):
claude mcp add --scope user -- memstate memstate-mcpOther clients that read an MCP JSON config (Cursor, Windsurf, Claude Desktop, and more):
{
"mcpServers": {
"memstate": {
"command": "memstate-mcp"
}
}
}Restart the agent. The first proxy starts the shared storage daemon on
127.0.0.1:8765. Later proxies attach to it. The daemon continues
to run after the agent exits (see "One daemon for all agents").
If you do not want to change PATH, skip make install and use
make build. Then point the MCP config at the built script:
{
"mcpServers": {
"memstate": {
"command": "node",
"args": ["/abs/path/to/memstate-mcp/client/dist/index.js"]
}
}
}memstate-mcp --testFrom a clone without make install, run node client/dist/index.js --test.
Expected result: the proxy attaches to the shared daemon or starts one.
It prints the daemon address, the daemon mode (shared, attach or
child), and the seven tool names. Then it exits.
Every tool is scoped by project_id. The proxy derives the default id
from the git repository name (the directory basename outside a
repository), slugged to snake_case. Omit project_id in tool calls.
Pass it only to reach a different project. Keypaths use dot notation.
| Tool | Purpose |
|---|---|
memstate_set |
Write a short value at a keypath (config.port = "8080"). host=true adds the topic host_<host_slug> for a fact that holds only on this machine. |
memstate_remember |
Write a markdown summary. An explicit keypath stores all content there. Without a keypath, each ## heading becomes its own versioned memory, nested by ### depth. |
memstate_get |
Read a keypath, browse a subtree, or return the full project tree. |
memstate_search |
Search current memories. mode="hybrid" (default) fuses an any-word FTS5 match with the semantic ranking. mode="fts" uses SQLite FTS5 and requires every word. mode="semantic" embeds the query with Ollama and ranks by cosine similarity against the embedding of each keypath's current content. All modes accept category and topics filters. |
memstate_history |
Return every version of a keypath, newest first, with tombstones. |
memstate_delete |
Add a tombstone to a keypath. History is kept. |
memstate_delete_project |
Soft-delete a project. |
A useful agent loop:
- At task start, call
memstate_get()to load the tree. The proxy derives the project id from the repository name. The response also carries the shared scope undershared. Callmemstate_search(query=...)when you do not know the exact keypath. - At task end, call
memstate_remember(content="## Summary\n...\n## Decisions\n...")and let the server extract the sections. - Facts about the user or this machine, not about the code, go to
scope="user":preferences.*,profile.*,host.<host_slug>.env.*,host.<host_slug>.tools.*. The daemon rejects any other keypath there, so decisions and task summaries cannot leak into a shared store. - When the prompt is clearly about another subject than the directory (for example an nginx config asked from the home directory), pin the session once with
project_name. Prefer an existing id. A new id also needsnew_project=true. The proxy refuses a new id that looks like an existing one. On the first prompt, the recall hook prints a<memstate-scope>block. It shows the cwd project, whether it exists, and the other projects that the prompt matches. The recall hook follows a session pin through a per-process pin file. - A write creates a project only when it targets the git repository you are in, or when it carries
new_project=true. This rule applies to the cwd project outside a repository, to an explicitproject_id, and to a soft-deleted project. The proxy always refuses a name that resembles an existing project, and the name of your home directory. From the home directory, the proxy refuses all writes to the default project. Pin a project or use the shared scope. The same holds when the proxy was started in a system directory, such asC:\WINDOWS\system32, which is where a desktop app that is not itself running in a project starts its MCP servers: no default project, and the proxy's instructions say so. When the MCP client offers workspace roots, the proxy derives the default from the first root instead of its own working directory. Ids that start with_are reserved for the shared scope. The Python scripts apply the same rule with--new-project. - Never save a denied prompt. A denied prompt is a tool call that the user or a permission check denied.
node client/dist/index.js init writes rule files for several agents
(CLAUDE.md, AGENTS.md, .cursor/rules/, and more). These files
encode this loop.
The tool returns { method, project_id, items: [{keypath, action, version, id, prior?}] }
for both the explicit-keypath mode and the heading-extract mode. An item
names the write and carries no content. prior is the 40-word preview of
the version that the write replaced. Search hits carry a preview too, and
the agent reads the keypaths it wants with memstate_get. The proxy makes
these shapes from the daemon's answers (stored, superseded), which the
CLI and the skill scripts still print in full.
methodis"explicit"or"headings".actionis"created","superseded", or"unchanged"."superseded"means a prior version existed at that keypath."unchanged"means the content is identical to the current version, and no new row is written.- In extract mode, each
##heading becomes a top-level keypath (## Auth→auth). This is the same tree that explicit writes use. Passroot: "<prefix>"to nest all sections under a prefix. - Common section names collapse to canonical slugs:
## TODOs→todo,## Open Questions→questions,## Files to touch→files, and more. - The server stores prose before the first
##underpreamble, or under<root>.preamblewhen a root is given.
mode="hybrid" is the default. The daemon runs two searches. The first
is an FTS5 match where any query word may hit, ranked by bm25. The
second is the semantic search described below. Reciprocal rank fusion
(k=60) merges the two lists.
A keypath found by both searches outranks one found by only one. Each
result carries score (the fused score) and sources (fts,
semantic, or both). When the embedder is not configured or the query
embedding fails, the response holds the FTS hits alone and degraded
names the reason. Hybrid search never fails because Ollama is down.
A reranker is a second model that reads the query and one memory
together and gives a relevance score. It finds the memory that answers
the query among memories that only share words with it. The daemon has
no reranker until you set MEMSTATE_RERANK_MODEL.
Without a reranker there is no cost. A search sends no request to a
rerank server and does not wait for one. It gives the same hits in the
same order as a release from before the reranker. No command prints a
warning. memstated config shows the reranker as off and gives the
commands below.
-
Serve a reranker model from a server that answers
POST /v1/rerank: the llama.cpp server or vLLM. Ollama has no rerank API. A small model to start with isbge-reranker-v2-m3(0.6 B parameters, a 440 MB file as Q4_K_M, for example fromgpustack/bge-reranker-v2-m3-GGUFon Hugging Face). It works with each embedding model, also withnomic-embed-texton Ollama:llama-server -m bge-reranker-v2-m3-Q4_K_M.gguf --reranking \ --alias bge-reranker-v2-m3 --host 127.0.0.1 --port 8082 -ngl 99 -c 8192
-
Give the daemon the name of the model and the address of the server. The model is the name that the server gives it (
--alias). Leave out the URL when the embedding server is the same/v1server:memstated config set MEMSTATE_RERANK_MODEL bge-reranker-v2-m3 memstated config set MEMSTATE_RERANK_URL http://127.0.0.1:8082/v1 memstated restart
-
Make sure that it works.
memstated configmust show the model with no line that starts withreranker off. A search must name the model:memstate search --json "words of a question" | grep reranker
To turn the reranker off again: memstated config unset MEMSTATE_RERANK_MODEL, then memstated restart.
With a reranker, a hybrid search sends the first 10 fused hits to the
rerank server and orders them by score. The server gets the keypath and
at most 1200 bytes of each memory: the part that holds the most words
of the query, or the start of the memory when no part holds more. The response names the model in
reranker, and each hit carries rerank_score beside score and
sources. When the rerank server does not answer in
MEMSTATE_RERANK_TIMEOUT (15s), or its answer is not complete, the
response holds the fused order and rerank_degraded gives the reason.
A request with rerank: false skips the reranker. The recall hook
sends it, because a rerank is too slow for each prompt. A request with
rerank: true on a daemon with no reranker is not an error: the
response holds the fused order, and rerank_degraded says that no
reranker is configured. The fts and semantic modes are not
reranked.
The rerank server is the embedding server unless MEMSTATE_RERANK_URL
names another. The URL must end in /v1: the request is
POST {url}/rerank with query and documents, as the llama.cpp
server and vLLM serve it. Ollama has no rerank API.
Cost, measured on an Apple M4 Max with the llama.cpp server, for the 10 hits of one search (2026-11-19, 8 questions on one project):
| Reranker | Time for 10 hits |
|---|---|
bge-reranker-v2-m3 (Q4_K_M, 0.6 B) |
0.3 to 0.5 seconds |
| Qwen3-Reranker-4B (Q4_K_M) | 2.6 to 3.9 seconds |
The two models put the same memory first for 7 of the 8 questions. For one question the fused order had the wrong memory first, and each model put the right one first. With Qwen3-Reranker-4B, 20 hits took 9 seconds. That is why the bound is 10 hits.
The scale of rerank_score comes from the model. Qwen3-Reranker gives
a value from 0 to 1. bge-reranker-v2-m3 on the llama.cpp server gives
a value that can be below 0. Use the order of the hits, not the value.
A reranker reads text, not vectors. It does not need the vector space of the embedder, so each pair works in principle. These conditions decide if a pair works in practice:
- The server has
/v1/rerank, and it can serve the two models at one time. - The reranker file is made for the server. For llama.cpp, a
Qwen3-Reranker GGUF must come from
convert_hf_to_gguf.pyof llama.cpp. That converter writes the rerank prompt and thecls.outputtensor. A GGUF from another tool gives scores without meaning. - The context of the reranker holds the query and 1200 bytes of a memory.
| Embedder | Reranker | Server | Status |
|---|---|---|---|
qwen3-embedding (0.6b, 4b, 8b) |
qwen3-reranker of the same size |
llama.cpp | 4b pair measured on 2026-11-19: embedding parity 1.0, a relevant document scored 0.9996 and unrelated documents below 0.02 |
| each embedder | bge-reranker-v2-m3 |
llama.cpp | The small choice. Measured on 2026-11-19 with qwen3-embedding-4b as the embedder: 0.3 to 0.5 seconds for 10 hits, and the same first hit as Qwen3-Reranker-4B for 7 of 8 questions. |
bge-m3 |
bge-reranker-v2-m3 |
llama.cpp | The same model family. The reranker was measured (row above); this embedder was not. |
nomic-embed-text |
bge-reranker-v2-m3 |
Ollama for the embedder, a /v1 server for the reranker |
Needs MEMSTATE_RERANK_URL. The reranker was measured (row above); this embedder was not. |
Start with bge-reranker-v2-m3. Use a larger reranker only when a test
on your own memories shows a better order. memstated config prints
the commands when no reranker is set.
To serve the two models from one llama.cpp server, start llama-server
with no -m and a preset file (router mode). Each section is one model,
and the server sends a request to the section that its model field
names:
; llama-server --models-preset models.ini --models-max 2 --port 8081
version = 1
[qwen3-embedding-4b]
model = /models/Qwen3-Embedding-4B-Q4_K_M.gguf
embedding = true
pooling = last
[qwen3-reranker-4b]
model = /models/Qwen3-Reranker-4B-Q4_K_M.gguf
reranking = trueThe section names must be equal to MEMSTATE_EMBED_MODEL and
MEMSTATE_RERANK_MODEL. Do not use a colon in a section name: the
server writes the text after the colon in upper case, and a request for
qwen3-embedding:4b then gets "model not found".
In mode="semantic", the daemon embeds the query with the embedding
server (Ollama by default). It
ranks results by cosine similarity against the embedding of the
current content at each keypath. One embedding row exists per
unique (project, keypath, model), and the daemon recomputes it when
the content changes. The daemon drops results below threshold
(default 0.5). Set the threshold in the request or with
MEMSTATE_SEMANTIC_THRESHOLD. Each result pairs the keypath with the
current non-tombstoned memory and the similarity score. With
nomic-embed models, the daemon adds the search_query: and
search_document: task prefixes automatically. With Qwen3-Embedding
models, the daemon adds the retrieval instruction line to the query and
sends documents as raw text. Other models get raw text on both sides.
The daemon keys vectors by model name, so a model switch does not
destroy the old set. The daemon reports its model in /health as embed_model, and
the proxy warns when its own MEMSTATE_EMBED_MODEL differs from that of
a daemon it attached to. After a switch, the daemon fills in the new
model's vectors on its next start. Use the embed subcommand to inspect
or rewrite the sets directly:
memstated embed status [--watch] [--probe] # dashboard: coverage bars, sizes, threshold fit
memstated embed rebuild --model qwen3-embedding:4b # drop and recompute one model's vectors
memstated embed prune --keep qwen3-embedding:4b # delete every other model's vectorsembed status shows, per model, a coverage bar of current keypaths
with a vector, the vector dimension, storage size, and row count. It
also shows how many keypaths exceed the embed cap. The daemon embeds
only the head of such a keypath. For the configured model, it shows a
histogram of pairwise cosine scores, the nearest-neighbor percentiles,
and the share of pairs that pass the current threshold. Use the last
two to set MEMSTATE_SEMANTIC_THRESHOLD for a new model. Raise it
until few pairs pass but most nearest neighbors still do. --watch redraws every two
seconds while a backfill runs. --probe times one live Ollama call.
rebuild is the tool for a change in embedding structure under the same
model name: a new prompt format, a new Ollama build with different
output, or a corrupted set. It runs one Ollama call at a time and prints
progress per keypath.
The store holds one vector size per model name. When the server returns
a vector of another size for the name (another model, or another output
size), the daemon does not store it. A hybrid search then answers with
the FTS hits and degraded names the two sizes. A semantic search
answers HTTP 409. embed status marks a model that holds more than one
size. memstated embed rebuild --model NAME is the repair. The daemon
also refuses a vector of zeros and a vector with a value that is not
finite, which a model server returns when its computation failed.
Data is a versioned keypath tree, one tree per project:
project_id = "my_app"
├── auth.provider v1: "JWT" v2: "SuperTokens" v3: tombstone
├── db.engine v1: "Postgres 16"
└── task.summary.2026_04_21 v1: "## Refactor auth middleware …"
Each write appends a new version. If a prior version existed, the
response carries prior, its 40-word preview. The agent sees the conflict, and
no data is overwritten silently. memstate_history returns the full
chain. memstate_delete appends a tombstone row. The data stays in
history but no longer appears in reads or search.
There are two search paths: SQLite FTS5 (fast, lexical, works offline) and semantic search through Ollama embeddings. Embeddings are asynchronous on write. The HTTP write returns immediately, and a goroutine embeds the new content in the background. If Ollama is not reachable, the daemon logs once per hour and continues. FTS search is not affected. The daemon heals the missing vector the next time the same content is written.
On each startup, the daemon backfills missing vectors in the background, one Ollama call at a time. An embedding-model switch or a period of Ollama downtime heals itself on the next start.
A soft-deleted project blocks reads. A write to the project revives
it. Through MCP, that write also needs new_project=true. A deleted keypath loses its embedding row and no longer appears in
search, but its full version history stays readable.
Every setting is a MEMSTATE_* name. It can come from three places, and
the first one that sets it wins:
- a flag on the
memstatedcommand line (--embed-model,--embedding-url,--embed-timeout,--idle-timeout,--addr), - the environment of the process,
- the settings file
~/.memstate/config.env,KEY=VALUElines:
# ~/.memstate/config.env
MEMSTATE_EMBEDDING_URL=http://127.0.0.1:8081/v1
MEMSTATE_EMBED_MODEL=qwen3-embedding-4b
MEMSTATE_SEMANTIC_THRESHOLD=0.6The daemon, the MCP proxy, the memstate CLI, the recall hook and the
Python scripts all read the file at startup, so there is one place to
edit and nothing to pass on the command line. memstated config shows
each setting, its value, where it came from, and whether the running
daemon matches:
config file /home/me/.memstate/config.env (3 settings)
precedence daemon flag > environment > config.env > default
SETTING VALUE SOURCE
MEMSTATE_EMBEDDING_URL http://127.0.0.1:8081/v1 config.env
MEMSTATE_EMBED_MODEL qwen3-embedding-4b config.env
MEMSTATE_EMBED_TIMEOUT 1m0s default
MEMSTATE_SEMANTIC_THRESHOLD 0.6 config.env
...
running daemon 127.0.0.1:8765 pid 4242 started as: memstated --addr 127.0.0.1:8765
embedding_url http://127.0.0.1:8081/v1 ok
embed_model nomic-embed-text DIFFERS: config gives qwen3-embedding-4b
-> `memstated restart` starts a daemon from the config above; flags it was started with still win
memstated config set KEY VALUE and memstated config unset KEY edit
the file; memstated restart applies it to a running daemon. A restart
or upgrade replays the flags the old daemon was started with and reads
the environment and file afresh, then prints every embedding or idle
setting that changed. MEMSTATE_CONFIG names another file, and
MEMSTATE_CONFIG=off ignores it (the tests do this).
| Thing | Path |
|---|---|
| Settings file | ~/.memstate/config.env (override with MEMSTATE_CONFIG; see Configuration) |
| SQLite DB | ~/.memstate/memstate.db (override with MEMSTATE_DB, and ~/ is expanded) |
| Daemon log | memstated.log next to the DB (default ~/.memstate/memstated.log) |
| Shared daemon address | ~/.memstate/daemon.addr, next to the DB. A --addr daemon writes it at startup and removes it at shutdown. |
| Embedding URL | http://127.0.0.1:11434 (override with MEMSTATE_EMBEDDING_URL or --embedding-url). A URL that ends in /v1 selects an OpenAI-compatible API. |
| Embed model | nomic-embed-text (override with MEMSTATE_EMBED_MODEL or --embed-model) |
| Embed timeout | 60s per embedding call (override with MEMSTATE_EMBED_TIMEOUT or --embed-timeout). Must cover a cold model load: a 4B model needs about 20s on first use. |
| Semantic threshold | 0.5 (override with MEMSTATE_SEMANTIC_THRESHOLD or per request) |
| Rerank model | none (set MEMSTATE_RERANK_MODEL or --rerank-model); see reranker |
| Rerank URL | the embedding URL (override with MEMSTATE_RERANK_URL or --rerank-url). It must end in /v1. |
| Rerank timeout | 15s per rerank call (override with MEMSTATE_RERANK_TIMEOUT or --rerank-timeout) |
| Network | The daemon binds 127.0.0.1 unless --addr or MEMSTATE_ADDR names another address; see Who can reach the daemon. Embedding calls, when enabled, go to the configured embedding URL, which is usually also loopback. |
For a per-project database, set MEMSTATE_DB in the MCP config's
env: block:
{
"memstate": {
"command": "memstate-mcp",
"env": { "MEMSTATE_DB": "/abs/path/to/my_project.db" }
}
}The proxy still accepts --embed-model, --embedding-url and
--embed-timeout as its own arguments and hands them to every daemon it
starts, but the settings file is the place for them: an agent config
entry gets rewritten by memstate-mcp setup and the installers, the
file does not.
The default is one shared daemon per database. The first MCP proxy
starts it detached on 127.0.0.1:8765, and the daemon writes its
address to ~/.memstate/daemon.addr. Every later proxy, the recall
hook, the memstate CLI and the Python scripts find it through that
file. The daemon outlives the clients. With MEMSTATE_IDLE_TIMEOUT, it
exits when nothing has used it for the timeout period:
export MEMSTATE_IDLE_TIMEOUT=30m # optionalA proxy that is open when the daemon stops is not left without one. When a tool call cannot connect, the proxy finds or starts the daemon again with the same rule as at startup, and sends the call one more time. The compact hook starts the daemon too. The recall hook and the Python scripts do not.
Two variables change the default:
MEMSTATE_ADDR=HOST:PORTnames the daemon to use. The proxy attaches to it, or starts one there when nothing answers. Use it for a daemon on another port or another machine.MEMSTATE_CHILD=1gives the proxy a private daemon on a random port that lives and dies with it. The test suite uses this. A customMEMSTATE_DBwith no daemon of its own gets a private daemon too.
If port 8765 is held by another program, the proxy warns and starts a
private daemon.
Start, stop, or inspect the daemon manually:
memstated --addr 127.0.0.1:8765 --idle-timeout 30m # foreground
memstated stop --addr 127.0.0.1:8765 # POST /admin/shutdown
memstated status --addr 127.0.0.1:8765 # GET /health
memstated restart --addr 127.0.0.1:8765 # stop + start detached with the same configmemstated restart and memstated upgrade stop a daemon only when it
runs on this machine. If MEMSTATE_ADDR names the daemon of another
machine, restart stops with a message and upgrade replaces only the
binary. This machine cannot start that daemon again, so it does not
stop it. Run the command on the machine that runs the daemon.
Concurrent writers to the same database file are safe. The daemon uses SQLite in WAL mode with a small connection pool. Each write takes the write lock when its transaction starts, so other writers wait in a queue and do not fail. Reads run on the other connections during a write.
The daemon has no login. Every program that can connect to its address
can read, write and stop it. On the default address, 127.0.0.1, that
is every program on the machine. If you start it on a network address
with --addr, that is every machine that can reach the address, so use
only an address on a private network such as a VPN.
A web browser on the same machine can also connect, and a web page can make the browser send requests. The daemon refuses the requests that only a browser sends:
- A request with an
Originheader, or with aSec-Fetch-Siteheader other thannone, gets403. The clients of the daemon do not send these headers. - A request whose
Hostheader is a DNS name with a dot gets403, unless the name is the one in--addr. An IP address,localhostand a name without a dot are accepted. This stops a page that points its own DNS name at the daemon (DNS rebinding). - A request with a body must have
Content-Type: application/json, or it gets415. A page cannot send that type to another site without a permission request, which the daemon does not answer.
Two limits apply to every client:
- A request body larger than 4 MiB gets
413. - A write gets
400when a name is not safe to print later. A project id, each segment of a keypath, a category and a topic contain only letters, digits,_and-. A source is one line of text.memstate rmandmemstate_deletestill remove a keypath that an older daemon accepted.
The recall hook prints stored text into the session. It writes < as
< there, so a note cannot end the block that holds it. Read the
exact text with memstate_get.
client/skill/scripts/ contains a Python CLI for each tool. The CLI
finds a daemon the same way as the MCP proxy: MEMSTATE_ADDR first,
then ~/.memstate/daemon.addr. The scripts never start a shared
daemon. When no shared daemon answers, or MEMSTATE_CHILD=1 is set,
each invocation starts its own short-lived daemon and stops it on exit.
# Explicit keypath
python3 client/skill/scripts/memstate_remember.py \
--project my_app \
--keypath task.summary.2026_04_21 \
--content "## Auth migration done"
# Or omit --keypath to extract one memory per heading
python3 client/skill/scripts/memstate_remember.py \
--project my_app \
--content "$(cat summary.md)"
# Semantic search
python3 client/skill/scripts/memstate_search.py \
--project my_app --mode semantic --query "how do users log in"See client/skill/SKILL.md for the skill usage contract.
make install links memstate to the daemon binary. It reads the SQLite
file directly and sends writes through the shared daemon, so versioning,
embeddings and the user-scope rules apply exactly as they do for an agent.
The project defaults to the repository you are in.
memstate tree # keypath tree for this repo, plus the shared scope
memstate get decisions # content under one keypath
memstate get todo --raw | less # content only
memstate history config.port # every version, newest first
memstate search "why sqlite" --limit 5 # hybrid search via the daemon
memstate set config.port 8080 --category config
memstate edit notes.setup # $EDITOR on the current content
memstate rm branches.old --recursive # asks y/N; --yes to skip
memstate tree --shared # preferences, profile, practices, lessons, this host's env and tools
memstate tree --json | jq .shared # raw shapes for scripts
memstate projects # every live project
memstate ui # terminal browser, see below--project ID reaches another project, --shared the reserved shared scope,
--all (search) the whole store. Flags may follow positionals. Without a
shared daemon, reads still work and search falls back to FTS. set,
edit and rm need the daemon and tell you how to start one.
memstate ui opens the store in a full-screen browser. It starts on the
project of the repository you are in and shows every live project.
- Screen 1, browser: the projects, the keypath tree of the selected
project, and the content of the selected keypath.
vshows the version history of a keypath, with its tombstones./filters the projects or the keypaths. - Screen 2, raw tables: the six SQLite tables (
projects,memories,memories_fts,keypath_embeddings,meta,purged) as rows, 100 on a page.memoriesshows each version and each tombstone.enteropens one row with each column in full. This screen only reads, with one exception:Xon a row ofmemoriespurges the keypath of that row.
| Key | Action |
|---|---|
1 2 |
browser screen, raw tables screen |
h l ← → |
the pane to the left, to the right; on the raw tables screen, the columns to the left, to the right |
tab shift+tab |
next pane, previous pane |
j k g G pgup pgdn |
move |
/ |
filter the projects or the keypaths by name (esc clears it) |
s S |
search the content of this project, of each project; enter opens a match |
enter space |
fold or open a branch |
v |
versions of the keypath |
n |
new memory: keypath, category, topics, then $EDITOR |
e |
edit the content in $VISUAL or $EDITOR; category and topics stay |
m |
change category and topics |
d |
delete the keypath, or each keypath below a branch (you confirm with y) |
D |
soft-delete the project (you type its id to confirm) |
X |
purge: erase the keypath, or each keypath below a branch (you type purge) |
r |
read the store again |
? q |
keys, quit |
The writes follow the same rules as set, edit and rm: each one is a
new version or a tombstone, and each one goes through the shared daemon.
Without a daemon the browser is read-only and says so. With --db PATH it
is read-only too, unless --addr names the daemon that serves that file.
The browser shows control characters in stored text as symbols, so a note
cannot send an escape sequence to your terminal.
In the shared scope (_shared) the tree shows host for this machine only,
as memstate tree --shared does. d and X on the host branch act on the
facts of this machine only. The facts of another machine are in the raw
memories table.
The search (s, S) is the hybrid search of the daemon. Without a daemon
it is a word search on the store file, and the status line says so.
Purge (X) is for a note that must not be in the collection at all. A
delete (d) keeps the content in the history; a purge erases the content,
each version, the search row and the vectors. It has no undo. It works on
the store file, so it needs no daemon. To purge a keypath that is deleted
already, use X on one of its rows in the raw memories table.
A purge is local. The store keeps a record of it (table purged), and
memstated import does not restore the purged versions from the file of
another machine, also with --force; it prints each keypath that it did
not restore. The other machine keeps its copy until you purge there too.
A note that someone writes at the same keypath after the purge is imported
as normal.
Tab completion for zsh completes verbs, flags, project ids, config keys and
keypaths (one dotted segment at a time, in the project that --project or
--shared selects). Save the script in a directory on $fpath and open a
new shell:
memstate completions zsh > "${fpath[1]}/_memstate"Claude Code ──stdio──> client/dist/index.js ──HTTP loopback──> server/memstated ──> SQLite
(MCP) (thin TS proxy) (Go daemon)
The TypeScript proxy exists only to speak MCP. Each tool call becomes one HTTP POST. All logic (keypath versioning, FTS, conflict detection, tombstones, embeddings) lives in the Go daemon.
Who starts what: the agent (Claude Code) starts the proxy, node client/dist/index.js, from its MCP config. The proxy starts memstated
when no daemon is running, and otherwise attaches to the one that is.
Both read ~/.memstate/config.env first, so a daemon the proxy starts
and one you start by hand (memstated --addr 127.0.0.1:8765, or
memstated restart) run with the same settings. memstated config
shows which process is serving, its pid, and the flags it was started
with.
The proxy selects one of three modes at startup:
- Shared (the default): the proxy reads
daemon.addrnext to the DB and attaches when/healthanswers there. For the default DB, it then tries127.0.0.1:8765. When nothing answers, it starts a detached daemon there. - Attach (
MEMSTATE_ADDRset): the proxy attaches to that address, or starts a detached daemon there. It stops with an error when a program that is not memstate holds the port. - Child (
MEMSTATE_CHILD=1, a customMEMSTATE_DBwith no daemon, or a foreign program on port 8765): the proxy starts a private daemon on127.0.0.1:0(an OS-picked port) and passes its own PID with--owner-pid. The daemon printsMEMSTATE_READY addr=127.0.0.1:<port>on stderr, and the proxy reads it.
In child mode, the proxy sends SIGTERM to the daemon on a clean exit.
After a SIGKILL, the daemon's kill(owner_pid, 0) poll notices within
about 2 seconds, and the daemon exits on its own.
- LLM fallback for keypath extraction when headings are absent. Such content now lands under
<root>.preamble. - Time-travel reads. The server now rejects an
at_revisionrequest field instead of ignoring it.
MIT. The project derives from memstate-ai/memstate-mcp. The storage engine, the lifecycle model, and the wire shape are all new.