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.

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

Tool	What it does
brain_query	Search and recall memories using hybrid FTS + vector + spreading activation. Returns ranked nodes with retrievability and salience scores.
brain_write	Store a new memory node. Automatically queues for embedding and PRISM/NEXUS auto-linking.
brain_link	Create a typed edge between two existing nodes.
brain_supersede	Replace an outdated node with updated content. Closes old edges, writes a supersedes edge, preserving the memory graph's temporal integrity.
brain_stats	Return brain statistics: node/edge/episode counts, neuromodulator state, consolidation status, embedding coverage.
brain_history	Search episode history (raw conversation turns) by keyword.
brain_expand	Get full detail for a specific node: content, FSRS metrics, encoding context, and source episodes.
brain_review	Apply an FSRS-6 spaced-repetition review to a node. Updates stability, retrievability, and SIGMA calibration.
brain_forget	Physically delete a node from the brain. Refuses to delete nodes with active edges unless force=true.
brain_edges	Get all active incoming and outgoing edges for a node.

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.

Variable	Default	Purpose
SHARPWAVE_DATA_DIR	~/.sharpwave	Where the database lives
SHARPWAVE_DB_PATH	—	Full path to a specific database file, overriding DATA_DIR
SHARPWAVE_AGENT_ID	default	Namespace for separate, isolated memories
SHARPWAVE_EMBEDDING_MODEL	—	e.g. ollama/qwen3-embedding:0.6b
OLLAMA_BASE_URL	http://localhost:11434	Local embedding endpoint
OPENROUTER_API_KEY	—	Enables remote embeddings and generative consolidation

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.