Sharpwave

Long-term memory for AI agents. An MCP server that remembers across sessions, forgets what stops mattering, and consolidates the rest.

npx -y sharpwave

Works with Claude Code, Claude Desktop, Cursor, and any other MCP client.

The problem

Your agent forgets everything the moment a session ends. The usual fix is to dump conversation history into a vector store and retrieve the nearest chunks — which works until it doesn't:

• It never forgets. Every note lives forever at equal weight, so a throwaway remark from March competes with something that actually matters.

• It has no structure. A pile of embeddings can tell you what's similar. It can't tell you what caused what, or that one fact replaced another.

• Recall degrades as it grows. More memories means more near-matches, and precision falls off exactly when the memory becomes worth having.

Human memory doesn't work that way. It decays on a curve, strengthens what gets used, consolidates related things into concepts, and lets the rest fade. Sharpwave models that.

The name comes from sharp-wave ripples — the hippocampal events that replay and consolidate memories during rest. That's the mechanism this is built around, not a metaphor bolted on afterward.

Related MCP server: cell-mem

What makes it different

A real forgetting curve. Every memory carries FSRS-6 stability and retrievability. Unused memories decay on a power-law curve and drop out of recall; reviewed ones strengthen. Importance and emotional weight scale how durable a memory starts out.

Consolidation, not just storage. A background pass replays recent episodes, promotes recurring patterns into durable semantic nodes, synthesizes clusters into higher-level schemas, and downscales the noise — modeled on slow-wave and REM sleep.

A graph, not a bag. Memories connect through typed edges — caused_by, supports, contradicts, supersedes, instance_of and more. Retrieval spreads activation across those edges, so recalling one thing surfaces what's genuinely related, not merely similar.

Memories can be replaced. brain_supersede closes out a stale memory and links the replacement, so the graph keeps its temporal integrity instead of accumulating contradictions.

Hybrid retrieval. Full-text search fused with vector similarity via reciprocal rank fusion, then spread across the graph. Vector search is optional — full-text and graph retrieval work with no embedding provider at all.

Install

Claude Code

claude mcp add sharpwave -- npx -y sharpwave

Claude Desktop / Cursor

Add to your MCP config (claude_desktop_config.json, or Cursor's mcp.json):

{
  "mcpServers": {
    "sharpwave": {
      "command": "npx",
      "args": ["-y", "sharpwave"]
    }
  }
}

That's the whole setup. Memory lands in ~/.sharpwave/ as a SQLite database. Nothing leaves your machine unless you configure a remote embedding provider.

Tools

Memory types

Every node is typed, and the type affects how it's consolidated and retrieved:

identity · semantic · episodic · pattern · skill · goal · emotion · procedural · schema

Configuration

All optional. Sharpwave runs with zero configuration.

Update notifications

Once a day, Sharpwave asks the npm registry for its own latest version number and prints a single line to stderr if you are behind. It sends no identifiers and uploads nothing, runs after the server is already serving, and stays silent on failure — offline, blocked, or slow all resolve to no output.

To turn it off, set SHARPWAVE_NO_UPDATE_CHECK=1. It is also off automatically when CI or NO_UPDATE_NOTIFIER is set. With any of those, no request is made at all.

Enabling vector search

Full-text and graph retrieval work out of the box. Semantic similarity needs an embedding provider — the local option keeps everything on your machine:

ollama pull qwen3-embedding:0.6b

{
  "mcpServers": {
    "sharpwave": {
      "command": "npx",
      "args": ["-y", "sharpwave"],
      "env": {
        "SHARPWAVE_EMBEDDING_MODEL": "ollama/qwen3-embedding:0.6b"
      }
    }
  }
}

Multiple isolated memories — one per project, say — are just separate SHARPWAVE_AGENT_ID values.

Requirements

• Node.js 22 or newer

• macOS, Linux, or Windows (x64 and arm64; prebuilt native binaries, no compiler needed)

How retrieval works

1. Seed — full-text search over labels and content. Exact phrase first, then prefix-matched terms.

2. Fuse — if embeddings are available, vector search runs in parallel and the two rankings merge via reciprocal rank fusion. A 2-second cap means a slow or missing embedding provider degrades to full-text instead of hanging.

3. Spread — activation propagates across graph edges with lateral inhibition, so strongly-related memories surface and weak associations don't crowd the results.

4. Rank — final ordering weighs activation, salience, and FSRS retrievability, so a memory that's decayed past usefulness stays out of the way.

5. Touch — retrieved memories are marked as accessed, which strengthens them. Recall is itself a form of review.

Limitations

Worth knowing before you install:

• Generative consolidation needs an LLM. REM-style schema synthesis and contradiction detection call OpenRouter. Without OPENROUTER_API_KEY the deterministic consolidation passes still run, but the generative ones are skipped.

• Semantic similarity needs embeddings. Without a provider you get full-text plus graph retrieval — good, but not synonym-aware.

• Single-writer. SQLite with WAL. One server process per database; pointing two at the same file is not supported.

• Consolidation is time-based. Memory quality improves as passes accumulate. A brand-new database is a plain store until it has history to work with.

License

MIT — see LICENSE.

Built by Enlightened Republic.