memoryweb

# memoryweb [](https://glama.ai/mcp/servers/corbym/memoryweb) <div style="text-align:center"><img src="web.png" alt="memoryweb" /></div> A persistent knowledge graph MCP server for AI agents. ## The idea Human memory doesn't work by location — you pull a thread. A smell connects to a kitchen, connects to a person, connects to a feeling from thirty years ago. The thread is always there. Pull any part of it and the rest follows. Agents are no different. Context is tokens in relation to other tokens. What makes something retrievable is its associative chain — the path of connections that lead to it from something else. The narrative edge, the *because*, is the mechanism. Not the index, not the address. *The boot crash matters because it blocks the tutorial, which blocks the demo, which is why the fix matters now.* Pull on any of those threads and you get the rest. memoryweb works the same way: each concept is a node, and what makes it reachable is the narrative that links it to everything else. > The graph has considerably richer context than my flat file memory — including design decisions, failure modes from dogfooding, and the philosophy behind the tool. That's the point, I suppose. -- Claude Opus 4.6 > It's a fantastic project. Most MCP memory implementations I see are just flat vector databases or simple key-value stores that degrade into a digital junk drawer. By enforcing typed relationships, narrative reasoning, soft-deletes, and drift review, you've built a system that actively fights entropy. -- Gemini 3.1 Pro ## Philosophy memoryweb optimises for remembering things *well*, not remembering things in their entirity. Filing requires a moment of judgement: why does this matter, how does it connect to what else is known, what would be useful to know when coming back to this cold? This makes it a **decision log**, not an event log. An event log records what happened. A decision log records what was learned, decided, and why — and that's what lets you pick up where you left off without re-learning everything. The `why_matters` field is not optional. A node without it is an event, not a decision. ## Table of contents - [Installation](#installation) - [MCP config](#mcp-config) - [Storage](#storage) - [Tools](#tools) - [Filing memories](#filing-memories) - [Connecting memories](#connecting-memories) - [Retrieving memories](#retrieving-memories) - [Archive / forget](#archive--forget) - [Domain management](#domain-management) - [Relationship types](#relationship-types) - [Conventions](#conventions) - [CLI](#cli) - [Hooks](#hooks) - [Updating](#updating) - [Build](#build) ## Installation **Homebrew (macOS and Linux — recommended):** ```bash brew tap corbym/memoryweb brew install memoryweb ``` Pre-built binaries are also available on the [releases page](https://github.com/corbym/memoryweb/releases/latest) for each platform. Step-by-step setup guides covering installation, Ollama, and MCP client configuration: - [macOS (Apple Silicon & Intel)](docs/install-macos.md) - [Linux (x86-64 & ARM64)](docs/install-linux.md) - [Windows (x86-64)](docs/install-windows.md) Once installed, see the **[User guide](docs/user-guide.md)** for how to orient the agent, what phrases to use, and how to get the most out of memoryweb in Claude Code, GitHub Copilot, and Claude Desktop. ## MCP config Add to your MCP host's config (example for Claude Desktop on macOS — `~/Library/Application Support/Claude/claude_desktop_config.json`): ```json { "mcpServers": { "memoryweb": { "command": "/path/to/memoryweb", "env": { "MEMORYWEB_DB": "/Users/yourname/.memoryweb.db" } } } } ``` `memoryweb setup` writes this file automatically when the Claude application directory is detected. > **Note:** ChatGPT Desktop does not support stdio-based MCP servers and is not compatible with memoryweb. ## Storage Default DB path: `~/.memoryweb.db` Override with `MEMORYWEB_DB=/path/to/your.db` ## Tools 18 MCP tools (v1.56.1). Retired names (`recent`, `restore`, `trace`, `alias`, `rename_domain`, and others) return hard-cut migration errors — see [docs/memoryweb-skill.md](docs/memoryweb-skill.md) for replacements. ### Filing memories | Tool | What it does | |------|-------------| | `remember` | File a single concept, decision, or finding. Required: `label`, `domain`. Optional: `description`, `why_matters`, `occurred_at` (ISO8601), `tags` (space-separated keywords), `related_to` (auto-connect at creation), `transient` (mark as short-lived). Supply an `items` array to file multiple nodes in one transaction. Response includes `suggested_connections` and `possible_duplicates`. | | `revise` | Update `label`, `description`, `why_matters`, `tags`, or `occurred_at` on a live node without archiving it. Supply an `items` array for batch updates. Writes an audit log entry on every call. | ### Connecting memories | Tool | What it does | |------|-------------| | `connect` | Connect two nodes with a typed relationship and narrative *because*. Both nodes must exist first. Supply an `items` array to create multiple connections in one transaction. | | `disconnect` | Remove a connection by edge ID. Hard delete — cannot be restored. Obtain the ID from `recall`. | | `suggest_connections` | Given a node ID, return up to 5 candidate connections. Returns a `domain` field on each suggestion so cross-domain connects can be scoped correctly. Read-only. | ### Retrieving memories | Tool | What it does | |------|-------------| | `recall` | Retrieve a node and all its connections by ID. | | `search` | Text search across `label`, `description`, `why_matters`, and `tags`. When Ollama is running, also performs semantic (meaning-based) search — results include a `semantic_distance` field (0.0–1.0, lower = closer). Returns `truncated: true` when results are capped by the limit. | | `history` | Chronological listing. `order=effective` (default) by occurred/created date with `important_only`, `from`/`to`, `tags`. `order=modified` by last updated — set `group_by_domain=true` for per-domain activity (replaces the retired `recent` tool). Both modes support `memory_id` + `depth` for neighbourhood scoping. | | `why_connected` | Direct edges between two memories (prefer `from_id`/`to_id` for pair verification). | | `orient` | Return all nodes for a domain structured for synthesis — current state, recent activity, and a `declared_spine` of key decisions in chronological order. Includes `total_nodes` and `server_version`. | | `visualise` | Mermaid flowchart for a domain or a single node's neighbourhood (pass `memory_id`). Output inside a mermaid code block. | | `significance` | Dual-signal importance analysis for a domain. Returns four sections: `declared` (nodes with `occurred_at` set), `structural` (ranked by recency-weighted inbound degree), `uncurated` (structural top-N without `occurred_at` — curation candidates), and `potentially_stale` (declared but low structural score). | ### Archive / forget Nodes are never hard-deleted via the tools. Archive = soft delete; the node disappears from search but can be un-archived. | Tool | What it does | |------|-------------| | `forget` | Archive a node with a reason, or un-archive with `restore=true`. Strict protocol: only after `audit(mode=stale)` surfaces a candidate or the user explicitly confirms. | | `forget_all` | Archive multiple nodes atomically in a single call. Same strict protocol applies. | | `audit` | Surface nodes that need attention. `mode=stale` — stale, contradicted, duplicated, or overdue transient nodes. `mode=orphans` — live nodes with zero connections. `mode=archived` — review what has been archived (default limit 25). `mode=conflicts` — semantic contradiction candidates. `mode=kind_coverage` — taxonomy health and migration candidates. | ### Domain management | Tool | What it does | |------|-------------| | `domains` | Domain admin and discovery. Default lists domains and aliases. Actions: `add_alias`, `remove_alias`, `resolve`, `rename`. | ### Relationship types `caused_by` `led_to` `blocked_by` `unblocks` `connects_to` `contradicts` `depends_on` `is_example_of` `governed_by` `resolved` `resolved_by` `supersedes` ## Conventions - Use `domain` to separate concerns: `deep-game`, `sedex`, `general` - Call `domains` at session start if you don't know what domains exist - The `why_matters` field is the most important one for retrieval — don't skip it - The `narrative` on a connection is the *because* — the reasoning that makes it meaningful, not just the fact that a connection exists - Add connections immediately after filing related nodes, or use `related_to` on `remember` to auto-connect at creation time - Call `orient` at the start of a session to orient without needing to know what to search for - Use `why_connected` when asking about the relationship between two specific things - Use `transient: true` for ticket state, sprint notes, or anything expected to go stale within days — `audit(mode=stale)` will surface these for cleanup - `remember` returns `suggested_connections` and `possible_duplicates` — review both before filing more nodes ## CLI The `purge` subcommand hard-deletes archived nodes from the database. It is intentionally not exposed as an MCP tool — it's a maintenance operation, not an agent operation. ```bash memoryweb purge --dry-run # show what would be deleted (default behaviour without --confirm) memoryweb purge --confirm # actually deletes memoryweb purge --domain sedex # scope to a domain (case/whitespace-insensitive match) memoryweb purge --before 2026-01-01 # only nodes archived before a date ``` By default `purge` only ever touches **archived** nodes — a node must be `forget`-archived first before it's eligible. If you scope to a domain and see `0 node(s) would be purged` but the domain isn't actually empty, that's a sign it still has *live* nodes that were never archived; a domain-scoped run prints a note like `2 live node(s) still exist in domain "sedex"` whenever that's the case, so it's never mistaken for "domain is empty". To skip archiving and hard-delete a domain outright — live nodes included — pass `--include-live`. This requires `--domain` (it refuses to run unscoped, to avoid wiping every live node in the database) and is irreversible: ```bash memoryweb purge --domain sedex --include-live --dry-run # preview: shows live nodes too memoryweb purge --domain sedex --include-live --confirm # hard-deletes the whole domain, archived or not ``` The `dream` subcommand prints a digest of recent nodes and drift candidates — useful for session orientation and embedded automatically by the save and precompact hooks at filing time. ```bash memoryweb dream # reads ~/.memoryweb.db memoryweb dream --db /path/to/your.db # explicit DB path ``` The `backfill` subcommand generates embeddings for all live nodes that don't yet have one. Requires Ollama to be running with the configured embedding model (default: `snowflake-arctic-embed`). ```bash memoryweb backfill # reads ~/.memoryweb.db memoryweb backfill --db /path/to/your.db # explicit DB path memoryweb backfill -q # quiet mode — no progress output ``` #### Embedding model By default, memoryweb uses `snowflake-arctic-embed` for semantic search embeddings. Set `MEMORYWEB_EMBED_MODEL` to switch to a different model: ```bash export MEMORYWEB_EMBED_MODEL=bge-m3 ``` Only models that output **exactly 1024-dimensional vectors** are compatible. The vector table dimension is fixed at schema creation time (migration 9). Mismatched models are detected by a dimension guard and rejected with a clear log message rather than silently corrupting the database. **Compatible models (1024-dim):** | Model | Notes | |-------|-------| | `snowflake-arctic-embed` | Default. English-optimised. | | `bge-m3` | Multilingual — 100+ languages including Chinese, Japanese, Korean. Recommended for non-English use. | | `mxbai-embed-large` | English-focused; strong general retrieval quality. | Common incompatible models: `nomic-embed-text` (768-dim), `all-minilm` (384-dim). Always verify with `ollama show <model>` before switching. **Switching models:** ```bash # 1. Pull the new model ollama pull bge-m3 # 2. Set the env var (add to your shell profile or MCP server config) export MEMORYWEB_EMBED_MODEL=bge-m3 # 3. Regenerate — backfill detects the model change and clears automatically memoryweb backfill ``` memoryweb tracks which model was used for the last backfill. When `MEMORYWEB_EMBED_MODEL` changes, the next backfill detects the difference, logs the change, clears all existing embeddings, and regenerates from scratch. No manual intervention needed — embeddings from different models live in incompatible vector spaces, and the auto-clear ensures the database is always consistent. > **Note:** Run `memoryweb backfill` promptly after changing the env var. Any nodes filed between the model change and the next backfill will have their embeddings cleared and regenerated at backfill time — this is correct behaviour; backfill is the point of consistency. **Checking the configured model:** `memoryweb doctor` reports the active model under "Ollama model". The `setup` subcommand installs hooks into `~/.claude/settings.json`, detects Claude Desktop and offers to configure it automatically, and configures Ollama for semantic search. If Ollama is not installed, `setup` will ask whether to install it automatically via `https://ollama.com/install.sh` (Linux and macOS only — on Windows you must install Ollama manually before running setup). If Ollama is already installed but the server is not running, `setup` starts it automatically. Finally it checks for the configured embedding model and pulls it if missing. ```bash memoryweb setup # interactive setup memoryweb setup --dry-run # preview without writing memoryweb setup --hooks-dir /path/to/hooks # explicit hooks directory memoryweb setup --db /path/to/your.db # explicit DB path ``` When Claude Desktop is detected, setup prints: ``` Detected Claude Desktop. Configure it? [y/N] ``` The `stats` feature records tool usage for every MCP session. See [docs/stats.md](docs/stats.md) for setup and how to read the output. The `doctor` subcommand checks every part of a memoryweb installation and prints a structured health report. Use it after setup to verify everything is wired correctly, or run it in an agent session to check whether semantic search is available before relying on it. ```bash memoryweb doctor # check ~/.memoryweb.db memoryweb doctor --db /path/to/your.db # explicit DB path memoryweb doctor --json # machine-readable JSON output ``` Each check prints a status symbol: `[✓]` pass, `[✗]` fail, `[!]` warning, `[i]` informational. The command exits with code 1 if any check fails. Example output: ``` [✓] Database: ~/.memoryweb.db (WAL, schema v16) [✓] sqlite-vec: v0.1.6 — 142/145 nodes embedded (98%) [✗] Ollama binary: not found in PATH — install from https://ollama.com/download [!] Ollama server: skipped (Ollama binary not found) [!] Ollama model: skipped (Ollama server not available) [✓] Claude hooks: All hooks installed [i] Graph: 145 live nodes, 12 archived, 203 edges, 4 domain(s) (deep-game, ...), 2 alias(es) [i] Drift: 3 candidate(s): 1 contradicts, 2 stale labels [i] Last activity: 2026-04-29 update (node "open question on backfill") [i] Update: running dev build — skipping update check ``` The `merge-domains` subcommand consolidates two domains into one: ```bash memoryweb merge-domains --source <domain> --target <domain> [--dry-run] ``` - `--dry-run` reports what would happen without making any changes - Detects label collisions between the two domains — reported as warnings, not blocking - Automatically creates an alias from source → target The `backup` subcommand writes a consistent standalone snapshot of the database using `VACUUM INTO`: ```bash memoryweb backup /path/to/snapshot.db # snapshot ~/.memoryweb.db memoryweb backup --db /path/to/your.db /path/to/snapshot.db ``` - Produces a **single self-contained file** with no `-wal`/`-shm` sidecars - Safe to run **while memoryweb is in use** — it reads a transactionally-consistent snapshot - Refuses to overwrite an existing destination > **Backup safety.** Do not back up by copying the live database *folder* (e.g. via a cloud-sync client). In WAL mode the recent data lives in the `-wal` sidecar until checkpointed; a folder copy can capture the `.db` and `-wal` at different instants, and recombining a mismatched pair corrupts the database. Always back up the output of `memoryweb backup` (or `sqlite3 source.db ".backup dest.db"`), and only sync that standalone file. memoryweb checkpoints the WAL into the main file on clean shutdown, but a snapshot is the only safe way to capture a *running* instance. The `check-for-updates` subcommand checks GitHub for a newer release: ```bash memoryweb check-for-updates ``` ## Hooks Six Claude Code hooks automate filing, pre-compaction capture, context reinjection, and sub-agent orientation. ### What they do **`hooks/memoryweb_save_hook.sh`** (Stop hook — fires after every AI response) Counts human messages in the session transcript. Every `SAVE_INTERVAL` messages (default 15) it blocks the response and asks the model to call `remember` and `connect` for anything significant before continuing. Before blocking, it runs `memoryweb dream` and embeds the resulting digest — recent nodes and drift candidates — directly in the `stopReason` so the model has live context before it files. If `memoryweb` is not available the hook still blocks but omits the digest. Uses a re-entry flag so the block fires once and allows immediately after the model files. **`hooks/memoryweb_precompact_hook.sh`** (PreCompact hook — fires before context compaction) Blocks compaction once and asks the model to file everything important that hasn't been filed yet. Allows on re-entry so compaction proceeds after the filing pass. **`hooks/memoryweb_userpromptsubmit_hook.sh`** (UserPromptSubmit hook — fires on every prompt) If the agent has not oriented this session, it is nudged to run `orient`. With the `session_orient_enabled` and `auto_recall` options (see `memoryweb options`), it also injects relevant prior memories into the prompt context. **`hooks/memoryweb_subagent_start_hook.sh`** (SubagentStart hook — fires when a sub-agent starts) Tells the sub-agent to orient into the parent session's domain and topic (captured from the parent's last `orient` call), and injects a `memoryweb dream` digest so nested agents do not start cold. Opt-in via the `subagent_orient_enabled` option. **`hooks/memoryweb_subagent_stop_hook.sh`** (SubagentStop hook — fires when a sub-agent exits) Prompts the sub-agent to connect any orphaned nodes it filed before it finishes. **`hooks/memoryweb_postcompact_hook.sh`** (PostCompact hook — fires after context compaction) Reinjects orient context — including the last oriented domain and its topic — after the conversation is compacted so the agent regains its bearings. Configurable via the `reinject_on_compact` option. ### Install (Claude Code) Run setup once after building: ```bash ./memoryweb setup --hooks-dir /path/to/hooks ``` Or install manually: ```bash chmod +x hooks/memoryweb_save_hook.sh hooks/memoryweb_precompact_hook.sh hooks/memoryweb_userpromptsubmit_hook.sh hooks/memoryweb_subagent_start_hook.sh hooks/memoryweb_subagent_stop_hook.sh hooks/memoryweb_postcompact_hook.sh ``` Add to `~/.claude/settings.json`: ```json { "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "/path/to/hooks/memoryweb_save_hook.sh", "env": { "MEMORYWEB_DB": "/path/to/your.db" } } ] } ], "PreCompact": [ { "hooks": [ { "type": "command", "command": "/path/to/hooks/memoryweb_precompact_hook.sh", "env": { "MEMORYWEB_DB": "/path/to/your.db" } } ] } ] } } ``` Restart Claude Code to activate. ### Configuration | Variable | Default | Purpose | |----------|---------|---------| | `MEMORYWEB_SAVE_INTERVAL` | `15` | Human messages between filing prompts. | | `MEMORYWEB_DB` | `~/.memoryweb.db` | Path to the SQLite database. | | `MEMORYWEB_BIN` | `memoryweb` | Path to the memoryweb binary (used by the hook to run `dream`). | ### Token cost Unlike passive hooks, these cost tokens because the model must actually produce quality nodes. Expect one short filing exchange per trigger — typically under 1,000 tokens for a focused session. ### GitHub Copilot (VS Code) GitHub Copilot in VS Code supports the same `Stop` and `PreCompact` hook events in the same JSON format. VS Code loads hooks from `.github/hooks/*.json` in your workspace, as well as from `~/.claude/settings.json` and `.claude/settings.local.json`. Make the scripts executable first: ```bash chmod +x hooks/memoryweb_save_hook.sh hooks/memoryweb_precompact_hook.sh ``` Create `.github/hooks/memoryweb.json` in your repository: ```json { "hooks": { "Stop": [ { "type": "command", "command": "/path/to/hooks/memoryweb_save_hook.sh", "env": { "MEMORYWEB_DB": "/path/to/your.db" } } ], "PreCompact": [ { "type": "command", "command": "/path/to/hooks/memoryweb_precompact_hook.sh", "env": { "MEMORYWEB_DB": "/path/to/your.db" } } ] } } ``` VS Code loads the hooks automatically — no restart needed. If you have already installed the Claude Code hooks via `~/.claude/settings.json`, VS Code Copilot picks them up from there without any additional configuration. ### Other tools **Claude Desktop and GitHub Copilot cloud agent do not support hooks.** Add session-start and filing instructions to your system prompt manually. `memoryweb setup` configures Claude Desktop's MCP server entry automatically when it detects the application's data directory. **GitHub Copilot cloud agent** (the coding agent that runs on GitHub.com) uses a different hook format and event model that does not include `Stop` or `PreCompact`. Add filing instructions to your system prompt for that surface instead. ## Updating To check whether a newer version is available, run: ```bash memoryweb doctor ``` The `Update:` line in the output will tell you if a newer release is available and where to download it. To update: **Homebrew:** ```bash brew update && brew upgrade memoryweb ``` **Manual:** 1. Download the latest binary for your platform from the [releases page](https://github.com/corbym/memoryweb/releases/latest). 2. Replace the existing binary (build tip: rename to `memoryweb.tmp` first, then `mv memoryweb.tmp memoryweb` so the replacement is atomic). 3. Restart your MCP client (Claude Code, Claude Desktop, etc.) so it picks up the new binary. Your database is forward-compatible — the binary runs any pending migrations automatically on startup. ## Build ```bash go build -o memoryweb . ``` Requires Go 1.25+. Uses `github.com/mattn/go-sqlite3` and [sqlite-vec](https://github.com/asg017/sqlite-vec) for semantic search — CGO must be available. To deploy safely when the binary is already running: ```bash go build -o memoryweb.tmp . && mv memoryweb.tmp memoryweb ```