memoryweb

memoryweb

A memory MCP server for agents.

The idea

Human memory doesn't work by location. You don't retrieve a fact from a filing cabinet. 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.

This is why the memory palace works. Place feels like storage — this fact lives in this room — but that's not what's actually happening. Place creates a sequence. A sequence creates a story. The story is what holds the memory. Location is just a human shortcut for narrative.

Agents don't navigate by location at all. There is no place. 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.

You don't remember facts in isolation. You remember them because of what they connect to. The boot crash is significant 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. What makes it retrievable is the narrative edge — the because that links it to something else. A concept with rich connections is reachable from many starting points. A concept filed alone, with no story linking it to anything, is effectively lost.

Philosophy

memoryweb optimises for remembering things well, not remembering things fast. 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?

The metric is whether the next session starts with genuine understanding rather than a pile of raw facts.

This makes memoryweb a decision log, not an event log. The difference matters:

• An event log records what happened. A decision log records what was learned, decided, and why.
• An event log grows automatically. A decision log requires intent.
• An event log is useful for reconstructing the past. A decision log is useful for continuing work.

For long-running technical projects — where the hard problems are architectural decisions, subtle bugs, and design tradeoffs — the decision log is 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. Nodes without why_matters will surface as drift candidates.

Tools

Core graph

Archive / forget

Nodes are never hard-deleted via the tools. Archive = soft delete; the node disappears from search and retrieval but can be restored.

Domain aliases

Relationship types

caused_by led_to blocked_by unblocks connects_to contradicts depends_on is_example_of

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.

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
memoryweb purge --before 2026-01-01    # only nodes archived before a date

Build

go build -o memoryweb .

Requires Go 1.22+. Uses github.com/mattn/go-sqlite3 — CGO must be available.

Storage

Default DB path: ~/.memoryweb.db

Override with MEMORYWEB_DB=/path/to/your.db

MCP config

Add to your MCP host's config (example for Claude Desktop on macOS — ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "memoryweb": {
      "command": "/path/to/memoryweb",
      "env": {
        "MEMORYWEB_DB": "/Users/yourname/.memoryweb.db"
      }
    }
  }
}

Conventions

• Use domain to separate concerns: deep-game, sedex, general
• The why_matters field is the most important one for retrieval — don't skip it
• The narrative on an edge is the because — the reasoning that makes the connection meaningful, not just the fact that a connection exists
• Add edges immediately after adding related nodes
• Call recent_changes at the start of a session to orient without needing to know what to search for
• Use find_connections when asking about the relationship between two specific things

Hooks

Two Claude Code hooks automate filing and pre-compaction capture.

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 add_nodes and add_edges for anything significant before continuing. 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.

Install (Claude Code)

Run the setup tool once after building:

go build -o memoryweb-setup ./cmd/setup
./memoryweb-setup --hooks-dir /path/to/hooks

Or install manually:

chmod +x hooks/memoryweb_save_hook.sh hooks/memoryweb_precompact_hook.sh

Add to ~/.claude/settings.local.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/hooks/memoryweb_save_hook.sh"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/hooks/memoryweb_precompact_hook.sh"
          }
        ]
      }
    ]
  }
}

Restart Claude Code to activate.

Configuration

Set MEMORYWEB_SAVE_INTERVAL in the hook's environment to change the trigger frequency (default: 15 human messages).

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.

Other tools

GitHub Copilot and Claude Desktop do not support hooks. For those tools, add session-start and filing instructions to your system prompt manually.