Skip to content
map588Public

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

memstate

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.

Install

Install script

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

Windows 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 | iex

The script does these steps:

  1. It downloads the newest release: the memstated daemon for your platform and memstate-mcp.tar.gz, which holds the MCP proxy and its Node packages.
  2. It installs both. Then it starts the proxy once with a scratch database, to make sure that the proxy finds the daemon.
  3. 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.
  4. 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.0 installs that release, not the newest one.
  • MEMSTATE_INSTALL_DIR changes the directory for the links (macOS, Linux).
  • MEMSTATE_SETUP=0 or 1 skips or runs memstate-mcp setup with no prompt.
  • MEMSTATE_INSTALL_SKILL=0 or 1 skips 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 | iex

To 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 user

To 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 user

Then remove %LOCALAPPDATA%\Programs\memstate\server from your user PATH. Remove the memstate entry from the config of each other MCP client.

Build from source

You need Go 1.27+ and Node 18+.

git clone git@github.com:map588/memstate.git
cd memstate
make install

This puts two programs on your PATH:

  • memstated: the Go daemon. It installs to $(go env GOPATH)/bin, or to $GOBIN when set.
  • memstate-mcp: the MCP stdio proxy, linked from client/ with npm 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.

Embeddings (optional)

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 sends POST {url}/embeddings with {"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 matches

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

Claude Code skill and hook (optional)

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.sh points you to memstate_remember after three or more file edits since your last persist.
  • memstate-recall.sh runs memstated 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 through MEMSTATE_ADDR or ~/.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. Set MEMSTATE_NO_RECALL=1 to 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 ## Session part (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 /compact stays in effect.
  • After the compact, it files each ### section as one memory at decisions.<topic>, gotchas.<topic>, todo.<topic>, questions.<topic> or notes.<topic> in the session's project. A memory that exists under that name is superseded, as with any write, and memstate history shows each version. The session part goes to task.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 to task.summary.<date>, which the agent writes at the end of a task, and not to an area keypath such as decisions itself. Each memory has the topic compact.

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.

Connect memstate to your agent

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

Other 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").

Without a global install

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"]
    }
  }
}

Verify

memstate-mcp --test

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

The seven tools

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 under shared. Call memstate_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 needs new_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 explicit project_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 as C:\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.

memstate_remember: write shape

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.

  • method is "explicit" or "headings".
  • action is "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. Pass root: "<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 ## under preamble, or under <root>.preamble when a root is given.

memstate_search: hybrid mode

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.

memstate_search: reranker (optional)

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.

Turn a reranker on

  1. 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 is bge-reranker-v2-m3 (0.6 B parameters, a 440 MB file as Q4_K_M, for example from gpustack/bge-reranker-v2-m3-GGUF on Hugging Face). It works with each embedding model, also with nomic-embed-text on 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
  2. 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 /v1 server:

    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
  3. Make sure that it works. memstated config must show the model with no line that starts with reranker 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.

What a reranker does to a search

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.

Embedder and reranker pairs

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.py of llama.cpp. That converter writes the rerank prompt and the cls.output tensor. 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 = true

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

memstate_search: semantic mode

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.

Embedding models

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 vectors

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

How storage works

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.

Configuration

Every setting is a MEMSTATE_* name. It can come from three places, and the first one that sets it wins:

  1. a flag on the memstated command line (--embed-model, --embedding-url, --embed-timeout, --idle-timeout, --addr),
  2. the environment of the process,
  3. the settings file ~/.memstate/config.env, KEY=VALUE lines:
# ~/.memstate/config.env
MEMSTATE_EMBEDDING_URL=http://127.0.0.1:8081/v1
MEMSTATE_EMBED_MODEL=qwen3-embedding-4b
MEMSTATE_SEMANTIC_THRESHOLD=0.6

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

Where your data lives

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.

One daemon for all agents

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

A 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:PORT names 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=1 gives the proxy a private daemon on a random port that lives and dies with it. The test suite uses this. A custom MEMSTATE_DB with 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 config

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

Who can reach the daemon

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 Origin header, or with a Sec-Fetch-Site header other than none, gets 403. The clients of the daemon do not send these headers.
  • A request whose Host header is a DNS name with a dot gets 403, unless the name is the one in --addr. An IP address, localhost and 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 gets 415. 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 400 when 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 rm and memstate_delete still remove a keypath that an older daemon accepted.

The recall hook prints stored text into the session. It writes < as &lt; there, so a note cannot end the block that holds it. Read the exact text with memstate_get.

Python CLI (for skills, hooks, scripts)

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.

Browse and edit from the shell (memstate)

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.

Terminal browser (memstate ui)

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. v shows 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. memories shows each version and each tombstone. enter opens one row with each column in full. This screen only reads, with one exception: X on a row of memories purges 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"

How the pieces fit

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.addr next to the DB and attaches when /health answers there. For the default DB, it then tries 127.0.0.1:8765. When nothing answers, it starts a detached daemon there.
  • Attach (MEMSTATE_ADDR set): 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 custom MEMSTATE_DB with no daemon, or a foreign program on port 8765): the proxy starts a private daemon on 127.0.0.1:0 (an OS-picked port) and passes its own PID with --owner-pid. The daemon prints MEMSTATE_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.

Not done yet

  • 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_revision request field instead of ignoring it.

License

MIT. The project derives from memstate-ai/memstate-mcp. The storage engine, the lifecycle model, and the wire shape are all new.

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages