memextend

Extend your AI coding assistant's memory. Free, local, private.

memextend lets Claude Code, Cursor, and OpenCode continually remember your project's context between sessions and compacting.

It remembers significant moments automatically, stores everything locally, and lets your agent quickly search for context when it needs it. This is all done without any external connections.

Activate the local webui to visually add, edit, and search your project's memories. Add global memories to use across all projects. Or use the CLI.

Installation barely takes a minute. Supercharge your AI coding agent's memory with fast vectorized search.

Features

• Persistent Memory - Remember what you worked on across sessions
• Fully Local - No cloud, no API costs, complete privacy
• Hybrid Search - Keyword (FTS5) + semantic (vector) search with RRF fusion
• Auto-Inject - Relevant memories loaded on session start
• Smart Deduplication - Removes similar memories, keeping newest versions
• Character Limits - Configurable injection sizes for session start vs post-compact
• On-Demand Search - MCP tools for mid-session memory queries
• Per-Project + Global - Project-specific and cross-project memories
• Extensible - Adapter architecture for multiple AI tools

Quick Start

One-Line Install (Recommended)

curl -H "Cache-Control: no-cache" -H "Pragma: no-cache" -fsSL https://raw.githubusercontent.com/zodttd/memextend/main/install.sh | bash

Install via npm

npm install -g memextend
memextend init

Or use without installing:

npx memextend init

Manual Install (Development)

git clone https://github.com/zodttd/memextend.git
cd memextend
npm install
npm run build
node apps/cli/dist/index.js init

After installation:

1. Restart Claude Code to load the new configuration
2. Start a new session - memories will be captured automatically
3. Use memextend status to check memory statistics

Memory Scopes

memextend supports two types of memories:

Project Memories

Project memories are automatically scoped to your git repository. When you work in a project, memextend:

• Identifies the project via a hash of your git root path
• Captures tool invocations (edits, writes, commands) specific to that project
• Retrieves only relevant project memories when you return

Use cases:

• "Remember we decided to use JWT for auth in this project"
• "Recall the API endpoint patterns we established"
• "What files did we modify for the user dashboard?"

Global Profile

Global memories persist across all projects. Use these for preferences and patterns that apply everywhere.

Save global memories via MCP:

Claude can use: memextend_save_global

Use cases:

• "I prefer tabs over spaces"
• "Always use TypeScript strict mode"
• "My preferred test framework is Vitest"

CLI filtering:

memextend search "preferences" --global   # Search global only
memextend search "auth" --project         # Search current project only
memextend search "patterns"               # Search both (default)

How It Works

Capture

memextend captures two types of content:

Reasoning (enabled by default):

• Claude's explanatory responses and thought processes
• Captured automatically before context compaction
• Maximum 10,000 characters per capture

Tool Calls (disabled by default):

• Edit, Write, Bash, Task tool invocations
• Enable selectively via WebUI Settings or config file
• Useful for tracking specific file changes or commands

Configure capture settings via:

• WebUI: memextend webui → Settings tab
• Config file: ~/.memextend/config.json

Context Compaction Handling

When Claude's context gets compacted (summarized to free space), memextend:

1. Before compaction - Captures important reasoning and enabled tool calls via PreCompact hook
2. After compaction - Re-injects preserved memories via SessionStart hook with source: compact
3. Doubled context - Injects up to 2x normal memories after compaction to restore context

This ensures important context survives long sessions where compaction occurs.

Recall

When a new session starts, memextend:

1. Identifies your project (via git root hash)
2. Retrieves relevant memories (recent work + semantic matches)
3. Deduplicates similar memories (keeps newest version of each topic)
4. Includes your global preferences
5. Applies character limits to keep injection size reasonable
6. Injects context automatically via <memextend-context> tag
7. Includes usage hints for memextend_search and memextend_save

Smart Injection:

• Session start uses richer context (default 10,000 chars ≈ 2,500 tokens)
• Post-compaction uses minimal context (default 2,000 chars ≈ 500 tokens)
• Deduplication removes memories >85% similar, keeping only the newest

Search

Mid-session, Claude can use MCP tools:

• memextend_search - Find memories by query
• memextend_save - Save a new project memory
• memextend_save_global - Save a global preference
• memextend_forget - Delete a memory
• memextend_status - Show memory statistics

Claude Guidance

During memextend init, a ~/.claude/CLAUDE.md template is created with:

• Overview of available MCP tools
• When to search memories (returning to projects, referencing past decisions)
• When to save memories (architectural decisions, conventions, preferences)

CLI Commands

View & Search

# Status
memextend status                    # Memory stats and database info
memextend status --project          # Stats for current project only
memextend status --check-embeddings # Run embedding model diagnostics

# List memories
memextend list                      # Recent memories (all)
memextend list --project            # Current project only
memextend list --limit 50           # Show more results

# Search
memextend search "authentication"   # Hybrid search all memories
memextend search "auth" --project   # Current project only
memextend search "prefs" --global   # Global profile only
memextend search "api" --limit 20   # More results

Create & Manage Memories

# Create a new memory
memextend save                      # Interactive mode (prompts for content)
memextend save -g                   # Create global memory (all projects)
memextend save -m "Use TypeScript"  # Create with content directly
memextend save --global -m "Prefer tabs over spaces"

# Edit a memory
memextend edit <memory-id>          # Interactive editor
                                    # - Shows current content
                                    # - Type new content
                                    # - Press Enter twice to save
                                    # - Ctrl+C to cancel

# Delete memories
memextend forget <memory-id>        # Delete specific memory

# Bulk delete (with confirmation prompts)
memextend forget --all              # Delete ALL memories
memextend forget --all --project    # Delete current project only
memextend forget --before 2025-01-01           # Delete old memories
memextend forget --before 2025-06-01 --project # Old project memories
memextend forget --delete-project myproject    # Delete all memories in a project
memextend forget --clear-global                # Clear all global profile entries

Import/Export

# Export memories
memextend export                    # Export all to current directory
memextend export --output ~/backup  # Export to specific directory
memextend export --project          # Export current project only

# Import memories
memextend import ./memextend-export-2026-01-31.json  # Import from file
memextend import ./backup.json --merge               # Skip duplicates
memextend import ./backup.json --validate-only       # Validate without importing

Web UI

memextend webui                     # Start web UI in background on localhost:3333
memextend webui --port 8080         # Custom port
memextend webui --host 0.0.0.0      # Bind to all interfaces
memextend webui stop                # Stop the web UI
memextend webui status              # Check if web UI is running
memextend webui --foreground        # Run in foreground (blocking)

The web UI provides:

• Dashboard - Memory statistics, activity charts, type breakdowns
• Memory Browser - Filter and paginate through all memories
• Create - Add new project or global memories via "+ New Memory" buttons
• Search - Hybrid search with semantic and keyword matching
• Edit/Delete - Modify or remove individual memories
• Delete Project Memories - Remove all memories from a project
• Global Profiles - View and manage cross-project preferences
• Clear Global Profile - Remove all global profile entries at once
• Settings - Configure capture and retrieval options:
  • Toggle reasoning capture and individual tool capture
  • Set max content lengths for captures
  • Configure auto-injection, max memories, and recent days
  • Enable/disable global profile inclusion

Uninstall

memextend uninstall                 # Interactive uninstall with confirmation
memextend uninstall --force         # Skip confirmation prompt
memextend uninstall --keep-data     # Remove integrations but keep memories

Uninstall removes:

• Claude Code hooks (SessionStart, Stop, PreCompact)
• Claude Code MCP server registration
• memextend section from ~/.claude/CLAUDE.md
• All data in ~/.memextend/ (unless --keep-data)

After using --keep-data, you can reinstall with memextend init to reconnect your memories.

Help

memextend help                      # Detailed help with examples
memextend help status               # Help for status command
memextend help save                 # Help for save command
memextend help search               # Help for search command
memextend help forget               # Help for forget command
memextend help edit                 # Help for edit command
memextend help export               # Help for export command
memextend help import               # Help for import command
memextend help webui                # Help for webui command
memextend help uninstall            # Help for uninstall command
memextend --help                    # Quick command reference

Use -h or --help on any command for options:

memextend webui -h                  # Show webui options (--port, --host)
memextend search -h                 # Show search options (--project, --global, --limit)
memextend uninstall -h              # Show uninstall options (--force, --keep-data)

Architecture

memextend/
├── packages/
│   ├── core/                   # Storage, embedding, memory operations
│   │   ├── storage/           # SQLite (FTS5) + sqlite-vec
│   │   ├── embedding/         # Local nomic-embed-text model
│   │   └── memory/            # Capture, retrieve, types
│   └── adapters/
│       ├── claude-code/       # Claude Code hooks + MCP server
│       ├── opencode/          # OpenCode MCP server (anomalyco/opencode)
│       └── cursor/            # Cursor MCP server + CLI tools
└── apps/
    ├── cli/                   # CLI commands
    └── webui/                 # Web interface for memory management

Technology Stack

• Language: TypeScript
• Text Search: SQLite with FTS5
• Vector Search: sqlite-vec
• Embeddings: node-llama-cpp with nomic-embed-text
• MCP: @modelcontextprotocol/sdk
• Testing: Vitest

Configuration

Config file: ~/.memextend/config.json

{
  "version": 1,
  "capture": {
    "captureReasoning": true,
    "maxReasoningLength": 10000,
    "maxToolOutputLength": 2000,
    "tools": {
      "Edit": false,
      "Write": false,
      "Bash": false,
      "Task": false
    }
  },
  "retrieval": {
    "autoInject": true,
    "maxMemories": 0,
    "recentDays": 0,
    "includeGlobal": true,
    "deduplicationThreshold": 0.85,
    "sessionMaxChars": 10000,
    "compactMaxChars": 2000
  },
  "storage": {
    "maxMemoriesPerProject": 10000,
    "maxTotalMemories": 0
  },
  "debug": false
}

Capture Settings

Setting	Default	Description
captureReasoning	true	Capture Claude's explanatory responses
maxReasoningLength	10000	Max characters for reasoning captures
maxToolOutputLength	2000	Max characters for tool output captures
tools.Edit	false	Capture Edit tool invocations
tools.Write	false	Capture Write tool invocations
tools.Bash	false	Capture Bash tool invocations
tools.Task	false	Capture Task tool invocations

Retrieval Settings

Setting	Default	Description
autoInject	true	Auto-inject memories at session start
maxMemories	0	Maximum memories to retrieve (0 = unlimited)
recentDays	0	Days to look back for memories (0 = unlimited)
includeGlobal	true	Include global profile in injection
deduplicationThreshold	0.85	Similarity threshold for removing duplicates (0-1)
sessionMaxChars	10000	Max characters for session start injection (~2,500 tokens)
compactMaxChars	2000	Max characters for post-compact injection (~500 tokens)

Storage Settings

Setting	Default	Description
maxMemoriesPerProject	10000	Max auto-captured memories per project (0 = unlimited). Oldest are pruned first. Manual saves are never pruned.
maxTotalMemories	0	Max total auto-captured memories across all projects (0 = unlimited). Manual saves are never pruned.
deduplicateOnPrune	true	Remove highly similar memories during pruning (uses deduplicationThreshold)

All settings can be configured via the WebUI Settings page (memextend webui).

Claude Code Integration

The installer automatically configures Claude Code. For manual setup, add to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": {
      "command": "node",
      "args": ["/path/to/memextend/packages/adapters/claude-code/dist/hooks/session-start.cjs"],
      "timeout": 30000
    },
    "Stop": {
      "command": "node",
      "args": ["/path/to/memextend/packages/adapters/claude-code/dist/hooks/stop.cjs"],
      "timeout": 30000
    },
    "PreCompact": {
      "command": "node",
      "args": ["/path/to/memextend/packages/adapters/claude-code/dist/hooks/pre-compact.cjs"],
      "timeout": 30000
    }
  },
  "mcpServers": {
    "memextend": {
      "command": "node",
      "args": ["/path/to/memextend/packages/adapters/claude-code/dist/mcp/server.cjs"]
    }
  }
}

Hooks

Hook	Purpose
SessionStart	Inject memories at session start (including after compaction)
Stop	Capture memories when session ends
PreCompact	Capture memories before context compaction (preserves context)

Embedding Model

memextend uses a local embedding model (nomic-embed-text-v1.5) for semantic search. The model is downloaded automatically on first use (~274MB).

Diagnostics

Run embedding diagnostics to verify everything is working:

memextend status --check-embeddings

This will:

1. Check if the model file exists and is valid
2. Download the model if missing
3. Load the model and verify it initializes correctly
4. Generate test embeddings (document and query)
5. Verify semantic similarity is working properly

Fallback Mode

If the model can't be loaded, memextend falls back to hash-based embeddings. These work for basic matching but lack semantic understanding. Run diagnostics to ensure you're using real embeddings for best results.

Privacy

Everything stays on your machine:

• SQLite database: ~/.memextend/memextend.db
• Vector store: ~/.memextend/vectors/
• Embedding model: ~/.memextend/models/ (downloaded on first use)

No data is ever sent to external servers.

Requirements

• Node.js 18+ (Node 22 LTS recommended for best compatibility)
• Claude Code (for Claude Code adapter)

Comparison with Supermemory

Feature	Supermemory Pro	memextend
Cost	$19/month	Free
Storage	Cloud	Local
Privacy	Data on servers	100% local
Offline	No	Yes
Search	API-based	Hybrid local (FTS + vector)
Extensible	Claude Code only	Adapter architecture

Roadmap

• Core storage (SQLite + sqlite-vec)
• Local embeddings (nomic-embed-text)
• Memory capture and retrieval
• Claude Code adapter (hooks + MCP)
• CLI commands
• Real embedding model integration (uses model when available, fallback otherwise)
• Import/export functionality
• OpenCode adapter (MCP server for anomalyco/opencode) ⚠️ experimental
• Cursor adapter (MCP server + CLI tools) ⚠️ experimental
• Web UI for browsing memories
• Web UI Settings for capture/retrieval configuration
• Context compaction handling (PreCompact hook + post-compact injection)
• Reasoning capture (Claude's explanatory responses)
• Uninstall command with data preservation option
• CLAUDE.md template for memory tool guidance
• Smart memory deduplication (removes similar memories, keeps newest)
• Configurable character limits for session start vs post-compact injection
• Storage limits with automatic pruning (oldest memories deleted when limits exceeded)
• VS Code extension for Cursor (better session detection)
• OpenCode hooks (when/if supported upstream)

Note: The OpenCode and Cursor adapters are experimental and untested in production environments. They were developed based on each tool's MCP documentation. Community feedback and testing are welcome!

Development

# Install dependencies
npm install

# Build all packages
npm run build

# Run tests
npm run test

# Run tests (excluding slow embedding tests)
npm run test -- --exclude="**/embedding/**"

Contributing

Contributions welcome! The project uses an adapter pattern, making it easy to add support for new AI coding tools.

License

MIT - Copyright (c) 2026 ZodTTD LLC

See LICENSE for details.

---

Inspired by Vannevar Bush's Memex concept and built on learnings from the open-source projects of supermemory and QMD.