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: elephantasm-mcp

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.

Recent updates (v0.3.0)

Ports the ClawBrain v0.4.0 audit fixes into the TypeScript codebase. All changes are additive — the existing API is preserved.

• WAL retry — every critical write path (nodes, edges, episodes, meta, self-model, forget) now retries on SQLITE_BUSY / SQLITE_LOCKED with exponential backoff (100ms → 200ms → 400ms + 0–50ms jitter, 3 attempts). Async + sync variants.

• Embedding LRU cache — Map-based, default 1024 entries, SHARPWAVE_EMBEDDING_CACHE_MAXSIZE override. Re-entrancy guard via a busy-key flag. Exposes embeddingCacheStats().

• MinHash entity resolution — findNearDuplicates with embedding cosine fast path + character-trigram Jaccard fallback; deduplicateExisting union-find grouping for offline maintenance; mergeCoreferentNodes wires coreference_of edges.

• FTS5 maintenance — maintenance() runs rebuild + optimize; bumpWriteCounter() auto-triggers optimize every 100 writes (SHARPWAVE_FTS_OPTIMIZE_EVERY override). Graceful no-op when FTS tables are absent.

• Observability — diagnostic counters (always on) + optional JSONL event log when SHARPWAVE_OBSERVABILITY=1 (default off). Counters surface via the new brain_health tool and an extended brain_stats section.

• Input validation — new src/validation.ts. All tool handlers that take user-provided IDs/strings now reject empty inputs and clamp numeric ranges; enum-style fields validate against allowlists with safe defaults.

Companion tools

The companion tools ecosystem extends Sharpwave with utility scripts for memory management, consolidation, and meta-reasoning. All tools are in the ools/ directory and work with any Sharpwave-compatible brain.

Available tools

New patterns (2026-08-19)

• Fractal reasoning: Every carry closure produces a 4-level breakdown (L0 fix → L1 pattern → L2 flaw → L3 meta-rule) with explicit edge types (CAUSED_BY, LEADS_TO, CONTRADICTS, RESOLVED_BY) that link to a marley-self-corrections-sentinel node.

• Memory tiers: MEMORY.md sections auto-degrade through 5 tiers based on age + access count. Full → summary → essence → ghost → metadata.

• Silent-failure trio: surface_error must throw (not fall through to continue_normal), credential files checked before store-expiry, runtime asset copier must include .md/.txt/.yaml/.yml.

See LRN-20260819-001 for the universal pattern documentation.

License

MIT — see LICENSE.

Built by Enlightened Republic.