Skip to main content
Glama

memhive watches your Claude Code and Codex sessions, distills what happened into short observations (decisions, bugfixes, config changes and so on), and feeds the relevant ones back into the next session. Your agent stops re-learning the same codebase every morning.

Features

  • Automatic capture: hooks record prompts and tool use; an LLM turns them into typed observations

  • Context at session start: recent and relevant memory is injected, within a token budget

  • Hybrid search: SQLite full-text search plus optional vector search, merged with reciprocal rank fusion

  • MCP tools: the agent can search, browse a timeline, fetch full records, save_memory itself, pin / unpin what must always be in context and forget its own rows

  • Any provider: Anthropic or any OpenAI-compatible endpoint (Ollama, OpenRouter, vLLM, ...) for the observer and embeddings

  • Privacy first: <private> blocks and secrets are stripped before anything is stored; raw tool output never touches disk

  • Team hub: link a project to a self-hosted hub (Postgres + pgvector) to share memory with your team

  • Local by default: one SQLite file in ~/.memhive, no account, no cloud

The project is pre-1.0: settings and the hub protocol can still change between minor versions.

Related MCP server: Memory MCP

Quick start

Requires Node.js 22 or newer.

npm install -g memhive
memhive install

memhive install asks which hosts to wire up (Claude Code, Codex) and which observer provider to use. Flags: --host claude-code,codex, --provider anthropic|openai-compat, --yes to skip prompts.

Start a new session in Claude Code or Codex and work as usual. From the second session on, the agent starts with what it learned before. Check the setup at any time:

memhive doctor
memhive search "auth middleware"

Agent skill

The mem-search skill is also listed on skills.sh. It teaches an agent to search memhive's memory, so memhive must be installed first.

npx skills add trickstarcandina/memhive --skill mem-search

First session checklist

  1. Work through one session in a git repo and end it normally. The observer writes observations while you work and a summary at stop.

  2. Run memhive search <a word from that session> in the same repo. It should list what was recorded.

  3. Start a second session. It opens with a context block built from the first.

If search finds nothing, look in ~/.memhive/logs/daemon.log for observations stored lines. Errors from the LLM provider (wrong key, wrong model, unreachable endpoint) show up there too, and memhive doctor checks the credentials.

How it works

flowchart LR
  A[Claude Code / Codex] -- hooks --> D[memhive daemon]
  D -- batched events --> L[LLM observer]
  L -- observations --> S[(SQLite + FTS + vectors)]
  S -- context at session start --> A
  S <-- MCP search / timeline / pin --> A
  A -- forget --> S
  S <-. push rows and tombstones / pull .-> H[(Team hub<br>Postgres + pgvector)]
  • Hooks. Claude Code and Codex call memhive hook <host> <event> on session start, each prompt, each tool use, stop and session end. Hook commands always exit 0, so they never block the agent.

  • Daemon. The first hook starts a local daemon (memhive daemon status|start|stop|run). It owns the SQLite database (~/.memhive/memhive.db) and a per-session event buffer.

  • Observer. Buffered events are flushed to the LLM after 8 events, after 5 s of idle, or on stop. The LLM turns them into typed observations. A call that fails on the network, with a 5xx, or with an answer that is not JSON is tried once more; if that fails too, or the key or quota is refused, the batch is dropped and never replayed.

  • Context. At session start the daemon builds a context block, capped by MEMHIVE_CONTEXT_TOKENS, and injects it into the agent. Rows are ranked by age (weight halves about every 10 days) and type (decisions and bugfixes first), with boosts for your own rows (x1.5), rows touching files under the working directory (x1.3), rows from the same git branch (x1.2) and rows recorded again by later sessions (up to x1.5). Pinned rows come before all others, newest first, within the budget. The top 5 of your own rows also show up to 3 facts each; rows pulled from a hub show only their title, and their file lists give no boost.

  • MCP. memhive mcp exposes the memory to the agent through the tools below, scoped to the current project.

  • Forget. memhive forget or the MCP forget tool deletes a row and leaves a tombstone. In a linked project the tombstone is pushed, the hub deletes its copy and every teammate drops theirs on the next pull. See Forgetting a memory.

MCP tools

Tool

Purpose

search

Step 1 of 3: a compact index (ids, types, titles) of matching observations and session summaries. An empty query lists the newest rows (narrow with since or type).

timeline

Step 2 of 3: the observations recorded before and after an anchor observation in the same session.

get_observations

Step 3 of 3: full records for up to 50 ids (full ids, unique prefixes or 8-char short ids).

save_memory

Store an explicit note (a decision, a gotcha, a convention) for future sessions.

pin / unpin

Pin an observation so it is always listed first in the session-start context and never expires, or undo that.

forget

Delete observations or session summaries recorded on this machine; on a linked hub the deletion reaches teammates.

Observation types: decision, bugfix, feature, refactor, discovery, config, problem, workaround.

Ids are UUID v7. Anywhere an id is accepted you can pass a unique prefix or the short id, which is the last 8 characters of the id, as shown in CLI output.

Commands

Command

Purpose

memhive install [--yes] [--host claude-code,codex] [--provider anthropic|openai-compat] [--no-ping]

Wire memhive into Claude Code and Codex.

memhive uninstall [--purge [--yes]]

Remove the plugin; your memory is kept unless --purge. See Uninstall and data removal.

memhive doctor [--no-ping] [--json]

Check the setup; see Doctor. Exits 1 when a check fails.

memhive search <query> [--type t] [--user u] [--since 7d] [--limit n] [--offset n] [--project key|--all-projects] [--json]

Search observations and session summaries from the terminal. An empty query with --since or --type lists the newest observations under those filters. --since takes 30m, 12h, 7d, 2w or a date; anything else is a usage error.

memhive recent [--limit n] [--offset n] [--type t] [--user u] [--since 7d] [--project key|--all-projects] [--json]

The newest observations of the project, with the same filters as search.

memhive show <id...> [--project key|--all-projects] [--json]

Full observations or session summaries of the current project (or the one named).

memhive edit <id> [--title t] [--narrative t] [--pin|--unpin] [--project key] [--json]

Change an observation. Title and narrative only for your own rows, and the change stays on this machine; any row of the project can be pinned.

memhive forget <id...> [--yes] [--force] [--project key] [--json]

Delete observations or session summaries (full ids, prefixes or 8-char short ids) of the current project. Shows each row's title, author and date and asks first unless --yes. See Forgetting a memory.

memhive stats [--project key] [--json]

Row counts per project, type and origin (own and team), pinned rows, DB size, last push and pull, and observer counters since the daemon started.

memhive backup [path] [--json]

A consistent copy of the database (VACUUM INTO through the daemon), mode 0600. Default ./memhive-backup-<time>.db; never inside ~/.memhive.

memhive export [--project key] [--format jsonl|md] [--out file [--force]]

Every session, observation and summary of a project. jsonl: one row per line with kind; md: grouped by session. --out is created 0600 and only replaced with --force.

memhive import <file.jsonl> [--project key] [--sync] [--json]

Load an export. Rows are cleaned like rows pulled from a hub (secrets redacted, <private> blocks and control characters removed). Ids already present or forgotten are skipped. Rows are marked synced, so nothing is pushed, unless --sync, which imports them as your own rows. Linking the project to another hub later pushes your own rows either way, like any row recorded here; teammates' rows are never re-published.

memhive embed [--missing|--rebuild]

Compute embeddings for observations now. The daemon also backfills on its own (one batch per second while rows are missing) and drops every vector when embed.model or embed.dims changes. --rebuild drops every vector and embeds everything again.

memhive daemon run|start|stop|status [--json]

Control the background daemon.

memhive hook <claude-code|codex> <event>

Hook entry point; called by the host, not by you.

memhive mcp

MCP server over stdio; called by the host.

memhive serve [--reset-vectors]

Run the team hub. Configured by environment variables; see Team hub.

memhive key create --user <name> [--label <text>]|list|revoke <id>|rotate <id|user> [--json]

Manage hub API keys. Run it where the hub's DATABASE_URL is set.

memhive user list|remove <name> [--json] / memhive project list [--json]

Hub users and projects.

memhive login <hub-url> [--key-stdin]

Store an API key for a hub. Prompts without echo; --key-stdin reads the key from stdin.

memhive link <hub-url> / memhive unlink

Start or stop syncing the current project with a hub you are logged in to.

memhive sync [--json]

Push and pull the current project now.

memhive pause [30m|1h|2d] / memhive resume

Stop recording for a while (no duration: until resume). See Opting out.

memhive version

Print the version.

memhive <command> --help prints that command's flags and, for --json, the shape of its output. --json output is meant for scripts: the shapes are stable. An unknown flag is refused. Exit codes: 0 ok, 1 error, 2 usage.

Doctor

memhive doctor prints one line per check: ok, warn, FAIL or info, with a fix hint where there is one. It checks:

  • the Node.js version (memhive needs 22 or newer);

  • settings.json: whether it parses (with the line and column of the first error), the provider and embedder, and whether their API keys are set (never the keys);

  • a provider and embedder ping (skip with --no-ping);

  • the database schema version against the one this memhive knows;

  • the rendered plugin files (hooks.json, codex-hooks.json, .mcp.json): the Node binary and bundle they run must exist and be this one, and the version that rendered them;

  • whether capture is paused or the current project is excluded;

  • the daemon: running, its version against the CLI's, observer auth failures, sqlite-vec loaded or degraded, observations still missing an embedding;

  • each linked project: hub, login and rejected keys, hub protocol, unsynced backlog, backoff and last error, last push and pull, quarantined rows;

  • log file sizes and rotation.

--json prints {"version", "home", "problems", "checks": [{"status", "check", "message", "hint"}]}.

Configuration

Settings live in ~/.memhive/settings.json (mode 0600), which memhive install writes. Environment variables override the file. Their names differ from the file's keys, which are nested:

{
  "llm": { "provider": "openai-compat", "model": "qwen2.5:7b", "baseUrl": "http://localhost:11434/v1", "apiKey": "optional" },
  "embed": { "baseUrl": "http://localhost:11434/v1", "model": "bge-m3", "dims": 1024, "apiKey": "optional" },
  "contextTokens": 2000,
  "context": { "scope": "team" },
  "excludeProjects": ["github.com/acme/secret-*", "/home/me/clients/**"],
  "retentionDays": { "discovery": 180 },
  "mcp": { "allowProjects": [] }
}

llm.apiKey holds the key for either provider. llm.model applies only to the provider saved next to it: switching provider through MEMHIVE_LLM_PROVIDER falls back to that provider's default model. embed needs baseUrl, model and dims; leave it out (or null) for full-text search only.

Variable

Default

Meaning

MEMHIVE_HOME

~/.memhive

Data directory (database, settings, daemon info, logs).

MEMHIVE_LLM_PROVIDER

anthropic

Observer provider: anthropic or openai-compat.

MEMHIVE_ANTHROPIC_API_KEY

none

Anthropic API key (provider anthropic, llm.apiKey). Required there.

MEMHIVE_ANTHROPIC_MODEL

claude-haiku-5-5

Anthropic model alias (llm.model).

MEMHIVE_LLM_BASE_URL

none

OpenAI-compatible endpoint, e.g. http://localhost:11434/v1 (llm.baseUrl). Required for openai-compat.

MEMHIVE_LLM_API_KEY

none

Key for the OpenAI-compatible endpoint, if it needs one (llm.apiKey).

MEMHIVE_LLM_MODEL

qwen2.5:7b

Model name for the OpenAI-compatible endpoint (llm.model).

MEMHIVE_EMBED_BASE_URL

none

OpenAI-compatible embeddings endpoint (Ollama, OpenAI, OpenRouter, ...) (embed.baseUrl).

MEMHIVE_EMBED_API_KEY

none

Key for the embeddings endpoint, if needed (embed.apiKey).

MEMHIVE_EMBED_MODEL

none

Embedding model name (embed.model).

MEMHIVE_EMBED_DIMS

unset

Vector size (embed.dims). Setting it enables vector search; unset means FTS-only search.

MEMHIVE_EMBED_MAX_DISTANCE

unset

Vector hits farther than this from the query are left out of search results (embed.maxDistance). Unset: the nearest rows are returned however far they are, so a query that matches nothing still lists rows. The value is sqlite-vec's L2 distance and depends on the embedding model: for a model with normalized vectors it runs from 0 (same) to 2 (opposite).

MEMHIVE_CONTEXT_TOKENS

2000

Token budget for the injected context block (contextTokens). A token counts as 4 characters, or 3 for text that is more than 20 % non-ASCII (CJK, Vietnamese).

MEMHIVE_CONTEXT_SCOPE

team

mine keeps teammates' pulled rows out of the session-start context; MCP search still finds them (context.scope). The older context.includeOtherUsers: false / MEMHIVE_CONTEXT_INCLUDE_OTHER_USERS=0 still work as a deprecated alias for mine.

MEMHIVE_EXCLUDE_PROJECTS

none

Comma-separated project keys or globs that are never recorded (excludeProjects). See Opting out.

MEMHIVE_RETENTION_DAYS

unset

Days to keep observations of types without their own entry (retentionDays.default; unset or 0: forever). retentionDays also takes one entry per type (0 or null: forever). Nothing expires unless you set it. Age counts from the last time a row was recorded again. Pinned rows are never removed, and in a linked project only rows already pushed to the hub are; their ids are remembered, so they are not pulled back. The daemon applies it at start and every 10 minutes.

MEMHIVE_MCP_ALLOW_PROJECTS

none

Comma-separated project keys or globs the MCP search tool may read when the agent passes project (mcp.allowProjects). Any other key is ignored and the current project is searched, so text in one repo cannot make the agent read another project's memory.

MEMHIVE_DISABLED

unset

Set to 1 to turn memhive off: hooks exit at once without contacting the daemon, and MCP tools answer "memhive disabled".

MEMHIVE_DEBUG

unset

Set to 1 or true for debug lines in the logs.

Opting out

  • Everything, for a while: memhive pause 1h (or 30m, 2d; no duration pauses until memhive resume). The pause lives in ~/.memhive/state.json, not in settings, and the daemon notices within 5 seconds. Nothing is recorded and session start injects no context while paused.

  • Everything, for a shell or a CI job: MEMHIVE_DISABLED=1.

  • Some projects, always: list them in excludeProjects. Each entry is a project key or a glob over keys, where * matches inside one / segment and ** matches across segments. Entries are also matched against the repo's root directory, which is the only way to exclude a directory without a git remote. The daemon reads settings at start; restart it (memhive daemon stop) after a change.

  • One repo, for everyone who clones it: commit .memhive.json with { "disabled": true } at the repo root (or in a subdirectory, for that part of the tree).

An excluded or paused session gets an empty context, and its prompts and tool calls are dropped before they reach the observer. memhive doctor says when capture is paused or the current project is excluded. Exclusion is decided when a session starts; a session that is already running keeps going until it ends, unless its project key matches excludeProjects.

Project identity

Memory is grouped by project. The key is the repo's origin remote, normalized: scheme, user and .git are dropped and the result is lowercased, so git@github.com:Acme/App.git and https://github.com/acme/app are the same project. Every clone of a repo, on any machine, shares one memory, which is what lets a team hub merge it.

  • A directory with no git origin gets a local key, path: plus a hash of the repo's top-level directory (or the directory itself outside a repo). It cannot be shared, and moving the directory starts a new memory.

  • Every package of a monorepo shares the repo's memory, and a fork with its own origin gets its own.

  • A package can have its own memory: commit .memhive.json with { "project": "github.com/acme/mono/packages/web" } in the package directory. The nearest .memhive.json between the working directory and the repo root applies. The override must start with the repo's own key and a /. Any other value is ignored, because a committed file could otherwise point a cloned repo at another project's memory.

Privacy

  • <private>...</private> is stripped first. Anything inside these tags is removed from prompts and tool payloads before it is buffered. Nested blocks are handled, and an unclosed tag drops the rest of the text.

  • Secrets are redacted before anything is stored. Keys and tokens in the usual formats (for example sk-, ghp_, AKIA, Bearer, and password=/token= assignments) are replaced with <redacted> in tool payloads, in generated observations and in save_memory notes.

  • Pulled rows are sanitized again. Rows pulled from a hub go through the same secret redaction and are clipped to the hub's field caps before they are stored, since another client (or anyone with a key) may have skipped both.

  • Images are never stored. Base64 image data and image content blocks are replaced with a placeholder.

  • Tool events are not written to disk. Tool inputs and outputs live only in the daemon's memory buffer, capped at 128 events per session and 16 000 characters per field. A hook event larger than 16 MB is dropped whole. Only the observations derived from them are saved.

  • Tool calls are sent to your LLM provider. To write observations, the daemon sends the prompt (up to 2 000 characters) and each tool call's input and output (up to 4 000 characters each, after the stripping and redaction above) to the observer you configured. With a hosted provider, that is your code and command output leaving the machine. Use a local model through openai-compat to keep it on the machine.

  • Cost. The observer makes one LLM call per flush (8 tool calls, 5 s of idle, or stop; one more when that call fails) of at most about 17 000 input tokens (8 calls of up to 8 000 characters, at about 4 characters per token) and usually much less, plus one small summary call per turn. Multiply by your provider's price for the model; a small model such as the default keeps it low, and a local model costs nothing.

  • Everything stays local in the default setup. The only outbound calls are to the LLM and embedding endpoints you configure.

Forgetting a memory

memhive forget <id...> (or the MCP forget tool) deletes a row for good: the row, its search index entry and its vector. Use it for a secret or a wrong fact recorded by mistake.

  • Only your own rows. Rows recorded on this machine can be forgotten. A teammate's row is refused as "recorded by someone else"; memhive forget --force removes only this machine's copy and tells nobody. The MCP tool never forces, so text in a repo cannot steer an agent into wiping teammates' memory. Ids of another project are reported as not found.

  • On a linked hub the deletion travels. The daemon queues a tombstone and pushes it. The hub deletes the row only for the user who pushed it, and every teammate drops their copy on the next pull. A forgotten id is never pulled or accepted back. A tombstone from the hub removes only rows this machine pulled from it; a row recorded here is kept (with one warning), so forgetting your own row on another machine does not delete this machine's copy. A hub older than protocol 2 cannot take tombstones: they stay queued (with one warning in the log) until the hub is upgraded, and the row stays on the hub until then.

  • Copies already made are out of reach. A teammate's backup, or a client still on memhive 0.1, keeps what it already pulled. Rotate any secret that reached a hub.

  • Edits are local. Changing a row in place (title, narrative, facts) only changes this machine's copy; hub rows are immutable. To change a team row, forget it and record it again.

Team hub

A hub shares the observations, summaries and session records of linked projects across a team. Personal memory stays local unless a project is linked.

Run the hub

The hub is a Node service backed by Postgres with pgvector. The compose stack in docker/ runs both.

cd docker
printf 'POSTGRES_PASSWORD=%s\n' "$(openssl rand -hex 24)" > .env   # once; never commit .env
docker compose up -d
docker compose exec hub cat /data/hub-admin-key

On first start the hub creates user admin and writes its API key to $MEMHIVE_HOME/hub-admin-key (mode 0600; /data/hub-admin-key in compose). The log shows only the path, so the key does not end up in docker compose logs. Read it once, create personal keys (see below), then revoke the initial key with memhive key revoke <id> and delete the file. MEMHIVE_ADMIN_KEY_FILE changes the path. MEMHIVE_PRINT_ADMIN_KEY=1 also prints the key on stdout; use it only where stdout is private, because container logs keep it on the host.

The hub speaks plain HTTP on port 7777. A bare memhive serve listens on 127.0.0.1 only; set HOST=0.0.0.0 (the Docker image does) to listen on all interfaces. Put it behind a TLS reverse proxy (Caddy, nginx, a cloud load balancer) that serves https://hub.example.com and forwards to the hub. Clients refuse any http:// hub except localhost, 127.0.0.1 and ::1. Compose publishes the hub on 127.0.0.1:7777 only, so the plain HTTP port is not reachable from the network. The proxy must run on the same host. If it runs elsewhere, change the port mapping in docker/compose.yml to a reachable address, and keep the hub behind TLS.

Hub settings are environment variables:

Variable

Default

Meaning

DATABASE_URL

none (required)

postgres://… or sqlite:<path>. Compose sets the Postgres URL.

PORT

7777

Listen port.

MEMHIVE_HOST / HOST

127.0.0.1

Listen address; MEMHIVE_HOST wins (some shells, such as tcsh, export HOST as the hostname). The Docker image sets HOST=0.0.0.0.

MEMHIVE_EMBED_MODEL

none

Embedding model the hub expects. Compose sets bge-m3.

MEMHIVE_EMBED_DIMS

unset

Vector size the hub expects. Compose sets 1024.

MEMHIVE_HUB_BODY_LIMIT

2097152 (2 MB)

Maximum request body, in bytes. Pull pages are capped to the same size.

MEMHIVE_RESET_VECTORS

unset

1 drops stored vectors when MEMHIVE_EMBED_DIMS changed (see below).

MEMHIVE_TRUST_PROXY

unset

1 reads the client address for the auth throttle from X-Forwarded-For.

MEMHIVE_HOME

~/.memhive

Directory for hub logs and the initial admin key. Compose sets /data.

MEMHIVE_ADMIN_KEY_FILE

$MEMHIVE_HOME/hub-admin-key

Where the first start writes the admin key.

MEMHIVE_PRINT_ADMIN_KEY

unset

1 also prints the first admin key on stdout.

POSTGRES_PASSWORD is required: compose refuses to start without it. Compose reads it from docker/.env and passes it to the hub as PGPASSWORD, outside the connection URL, so any characters work.

The hub limits each key to 60 requests per minute; the 429 carries retry-after, and a client waits that long before it sends the rest (a first push of many thousand rows takes a few minutes). After 30 failed authentications in a minute from one client address, that client gets 429 with retry-after for keys the hub has not seen succeed, until the minute ends, without a database lookup; keys that authenticated before keep working, and other clients are not affected. Behind a reverse proxy every request comes from the proxy's address, so set MEMHIVE_TRUST_PROXY=1 to take the client address from the last X-Forwarded-For entry (the one your proxy appends; with two proxy layers, such as a CDN in front of nginx, that is the outer proxy's address). Set it only when the hub is reachable through that proxy alone, since otherwise clients can forge the header.

Add members

Create one key per person or machine. Run these from docker/:

docker compose exec hub node dist/memhive.cjs key create --user alice --label laptop
docker compose exec hub node dist/memhive.cjs key list
docker compose exec hub node dist/memhive.cjs key revoke <id>
docker compose exec hub node dist/memhive.cjs key rotate <id|user>
docker compose exec hub node dist/memhive.cjs user list
docker compose exec hub node dist/memhive.cjs user remove <name>
docker compose exec hub node dist/memhive.cjs project list

The new key is printed once and starts with mh_. Give it to its owner through a private channel. key revoke takes the id shown by key list. key rotate revokes a key and creates its replacement (same user and label) in one step; it takes a key id, or a user name when that user has one active key. user list shows each user's active keys, observation count and last activity. user remove revokes every key of a user; their rows stay on the hub and remain visible to the team. project list shows each project's row counts and last activity. Every admin command takes --json. Admin commands need only DATABASE_URL: they skip the embedding dims check and never reset vectors.

Connect a machine

On each machine, log in once. The command asks for the key without echoing it:

memhive login https://hub.example.com

To script it, pipe the key on stdin. Never pass the key as a command-line argument, because arguments show up in shell history and process listings:

printf '%s' "$MEMHIVE_KEY" | memhive login https://hub.example.com --key-stdin

Then, inside each project you want to share:

memhive link https://hub.example.com

link runs an initial pull. memhive sync pushes and pulls the current project now. memhive unlink stops syncing the current project; its local memory stays.

What syncs

Observations, summaries and session records of linked projects are pushed to the hub. A session record carries the host, the host's session id and its start and end times; the hub drops the session's working directory, so local paths and usernames are not shared. Prompts and raw tool output never leave the machine, and <private> blocks and redacted secrets are removed before anything is stored.

Embedding model must match

Clients that embed must use the same embedding model and vector size as the hub. Set MEMHIVE_EMBED_MODEL and MEMHIVE_EMBED_DIMS on the hub to the embed model and dims in each client's ~/.memhive/settings.json. The hub rejects a pushed row whose embedding model differs from its own, or whose vector length differs from MEMHIVE_EMBED_DIMS, with 422 embedding_model_mismatch. Rows without a vector are accepted. memhive login warns when the local settings differ from the hub's.

The vector size is fixed when the hub database is created. If MEMHIVE_EMBED_DIMS later differs from the database, the hub refuses to start and says so. To switch, start it once with memhive serve --reset-vectors (or MEMHIVE_RESET_VECTORS=1): this drops every vector stored on the hub (rows stay, and clients keep their local vectors). The flag does nothing when the sizes already match.

Hub-side search is full-text only, because the hub runs no embedder. Client search stays hybrid over local rows, including rows pulled from the hub.

Protocol version

GET /v1/config reports the hub's protocol version: 2 since memhive 0.2 (push and pull carry tombstones). A client refuses to sync with a hub whose protocol is newer than its own, so upgrade clients after the hub. A 0.2 client keeps syncing sessions, observations and summaries with a protocol 1 hub (0.1.x): sessions go out with an empty cwd, which those hubs require. Forgotten rows (tombstones) stay queued until the hub is upgraded. memhive doctor shows each linked hub's protocol. docs/ARCHITECTURE.md documents the wire format.

Upgrading

npm install -g memhive@latest
memhive install

Re-run memhive install after every upgrade. It rewrites the plugin files with the paths of the new build and stops the running daemon, so the next hook starts the new one.

The hooks call the Node binary that ran memhive install, by absolute path. With a Node version manager (nvm, fnm, asdf, Volta), re-run memhive install after switching or removing that Node version, or the hooks keep using the old one.

Uninstall and data removal

memhive uninstall
npm uninstall -g memhive

memhive uninstall stops the daemon, removes the plugin from Claude Code and Codex, whichever has a config directory on this machine (in Codex it also sets the plugin to enabled = false in config.toml), and deletes the rendered plugin files in ~/.memhive/marketplace. It sets Codex's [features] hooks back to false only if memhive install turned it on; if it was on before, or memhive 0.1 installed it (nothing recorded), it is left as it is and uninstall says so.

Your data stays in ~/.memhive: the memory database (memhive.db), logs, settings.json with your LLM and embedding API keys, and credentials.json with your hub keys. uninstall prints the rm -rf line that deletes it; memhive uninstall --purge deletes it after asking (--yes skips the question). It refuses when the folder holds files memhive did not create. Run memhive backup or memhive export first to keep a copy. Revoke the hub key on the hub (memhive key revoke <id>) and rotate the provider keys if the machine is not yours to keep. Rows already pushed to a hub stay on the hub.

Troubleshooting

  • npm install -g memhive fails with node-gyp / "Could not find any Visual Studio" errors (Windows, Node 22, npm 10): the SQLite binding ships prebuilt, but npm 10 tries to compile it anyway. Install with npm install -g memhive --ignore-scripts.

  • Run memhive doctor first. It checks settings, credentials, plugin paths, the daemon and sync; see Doctor.

  • Logs are in ~/.memhive/logs/ (hook.log, daemon.log, and others). Set MEMHIVE_DEBUG=1 for more detail.

  • If session context is missing, check that memhive daemon status reports the daemon running. Hooks start it automatically on the next session.

  • Plugin warnings (the files name a missing or different Node binary or bundle, or were rendered by another memhive version) mean the hooks run an old build. Re-run memhive install.

  • A daemon whose version differs from the CLI's: the next hook replaces an older daemon on its own; memhive daemon stop does it now.

  • A database schema newer than this memhive: a newer memhive opened the database. Upgrade (npm install -g memhive@latest) instead of running the older one.

  • sqlite-vec degraded, or observations missing an embedding: search falls back to full text for those rows. The daemon backfills on its own; memhive embed --missing does it now.

  • Sync checks run per linked project: not logged in or a rejected key (memhive login <hub-url>), a hub protocol newer than this client (upgrade memhive), an unsynced backlog with its backoff and last error, and quarantined rows (pulled rows that could not be stored).

Contributing

git clone https://github.com/trickstarcandina/memhive.git
cd memhive
npm ci
npm run lint      # Biome
npm run typecheck
npm test          # unit and integration tests
npm run build     # bundles dist/memhive.cjs

The Postgres hub tests run when TEST_DATABASE_URL points to a pgvector database whose name contains test. CONTRIBUTING.md has the full setup, the commit convention and the release steps; docs/ARCHITECTURE.md explains the components and the hub protocol.

Releases are published to npm by the publish workflow with provenance: bump version in package.json (the only place it is written), add the release to CHANGELOG.md, push, then publish a GitHub release tagged v<version>.

Security

Please report vulnerabilities privately through GitHub security advisories, not in public issues. See SECURITY.md for supported versions and scope.

License

MIT

Stats

Weekly downloads from npmjs.com, redrawn every day by the stats workflow, with a dashed line for each release. Click the chart for npm-stat's daily breakdown.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Provides AI coding agents with persistent, long-term memory through local semantic search and SQLite storage. It enables agents to save and retrieve architectural decisions or project context across different conversation sessions without requiring cloud services.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides persistent cross-session memory and full-text search for AI coding assistants, storing project context, decisions, and preferences while enabling searchable access to conversation history via local SQLite.
      8
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Gives AI coding agents persistent memory by storing observations, decisions, and learnings in a local SQLite database with vector search, full-text search, and a rules engine.
      4
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Gives AI coding agents a local-first persistent memory they can read and write directly during sessions, storing decisions, preferences, error patterns, and guidelines in per-project and global SQLite stores. Enables semantic and keyword retrieval of relevant context across sessions so agents start work already knowing a codebase's conventions and history.
      -