How do I use Claude Persistent Memory?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Claude Persistent Memory Remember that the login module uses JWT tokens." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Claude Persistent Memory

by MIMI180306

Overview Schema Related Servers Score Discussions

JavaScript

Local

Features

Hybrid Search — BM25 full-text (FTS5) + vector semantic similarity (sqlite-vec), combined ranking (0.7 vector + 0.3 BM25)

4-Channel Retrieval — Pull (MCP tools on demand) + Push (auto-inject via hooks on user prompt, pre-tool, post-tool)

LLM Structuring — Memories auto-structured into <what>/<when>/<do>/<warn> XML format via Azure OpenAI

Multi-Project Isolation — Single shared embedding server routes requests by dataDir. Each project has its own database, no cross-contamination.

Automatic Clustering — Similar memories grouped, mature clusters merged into high-confidence consolidated memories

Confidence Scoring — Memories gain/lose confidence through validation feedback and usage patterns

Local-First — All data stored locally in SQLite. Your memories never leave your machine.

Related MCP server: Central Brain

Quick Start

Install

# Set Azure OpenAI credentials (required for LLM structuring)
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com"
export AZURE_OPENAI_KEY="your-api-key"

# Install in any project
npm install @alex900530/claude-persistent-memory

The postinstall script automatically:

Generates .claude-memory.config.js (project config)
Configures .mcp.json (MCP server registration)
Configures .claude/settings.json (5 lifecycle hooks)
Downloads and verifies the embedding model (bge-m3, ~2GB)
Registers background services via launchd/systemd
Updates .gitignore

Open Claude Code in the project directory — memory is ready.

Note: The embedding model (~2GB) is downloaded and verified during install. If the download is interrupted or the model is corrupt, install will fail. Simply re-run npm install to retry.

Configure later

If you skipped Azure credentials during install:

npx claude-persistent-memory

Install from source

git clone https://github.com/MIMI180306/claude-persistent-memory.git
cd claude-persistent-memory
npm install
cp config.default.js config.js
# Edit config.js with your Azure credentials

# Start services
npm run embedding-server   # Terminal 1
npm run llm-server         # Terminal 2

Then manually configure .mcp.json and .claude/settings.json — see Configuration.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Claude Code Session                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Pull Channel (on demand)         Push Channels (auto)      │
│  ┌───────────────────┐    ┌──────────────────────────────┐  │
│  │ MCP Server        │    │ UserPromptSubmit Hook        │  │
│  │ memory_search     │    │ PreToolUse Hook              │  │
│  │ memory_save       │    │ PostToolUse Hook             │  │
│  │ memory_validate   │    │ PreCompact Hook (analysis)   │  │
│  │ memory_stats      │    │ SessionEnd Hook (clustering) │  │
│  └────────┬──────────┘    └──────────────┬───────────────┘  │
│           │                              │                  │
│           └──────────┬───────────────────┘                  │
│                      │  dataDir routing                     │
│                      ▼                                      │
│  ┌───────────────────────────────────────────────────────┐  │
│  │            Shared Embedding Server (TCP :23811)       │  │
│  │            bge-m3 model (shared across projects)      │  │
│  │            Database pool (per-project by dataDir)     │  │
│  └───────────────────────────────────────────────────────┘  │
│                      │                                      │
│       ┌──────────────┼──────────────┐                       │
│       ▼              ▼              ▼                       │
│  ┌─────────┐   ┌─────────┐   ┌─────────┐                   │
│  │Project A│   │Project B│   │Project C│                    │
│  │memory.db│   │memory.db│   │memory.db│                    │
│  └─────────┘   └─────────┘   └─────────┘                   │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │            LLM Server (TCP :23812)                    │  │
│  │            Azure OpenAI GPT-4.1                       │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Multi-Project Support

The embedding server is shared across all projects. Each request carries a dataDir parameter that routes to the correct project's database:

Embedding model — loaded once, shared across all projects (~2GB RAM)
Database connections — pooled per dataDir, created on first access (~5ms)
No cross-contamination — searching in Project A never returns Project B's memories

MCP Tools

Tool	Description
`memory_search`	Hybrid BM25 + vector search. Params: `query`, `limit?`, `type?`, `domain?`
`memory_save`	Save a new memory. Params: `content`, `type?`, `domain?`, `confidence?`
`memory_validate`	Feedback loop — helpful (+0.1) or unhelpful (-0.05). Params: `memory_id`, `is_valid`
`memory_stats`	System stats: total memories, type/domain distribution, cluster status

Hooks

Hook	Event	Timeout	What it does
`user-prompt-hook.js`	UserPromptSubmit	1500ms	Embeds user query, searches, injects top memories via stdout
`pre-tool-memory-hook.js`	PreToolUse	300ms	Embeds tool context, searches, injects via `additionalContext`
`post-tool-memory-hook.js`	PostToolUse	300ms	Embeds tool context + result, searches, injects via `additionalContext`
`pre-compact-hook.js`	PreCompact	async	Spawns LLM analysis of full transcript, extracts memories
`session-end-hook.js`	SessionEnd	async	Incremental transcript analysis + clustering + mature cluster merging

Memory Types

Type	Use case
`fact`	Stable facts about the codebase
`decision`	Architectural decisions and rationale
`bug`	Bug fixes and root causes
`pattern`	Recurring code patterns
`context`	Session-specific context
`preference`	User workflow preferences
`skill`	Promoted from mature clusters

Memory Lifecycle

Save       → memory_save or auto-extract from transcript
Structure  → LLM converts to <what>/<when>/<do>/<warn> XML
Embed      → bge-m3 generates 1024-dim vector
Dedupe     → Jaccard similarity >= 0.95 → update existing
Search     → 0.7 * vectorSimilarity + 0.3 * normalizedBM25
Validate   → memory_validate adjusts confidence ±
Cluster    → similar memories auto-grouped
Merge      → mature clusters consolidated into single memory

Uninstall

npx claude-persistent-memory-uninstall

Or manually: remove memory from .mcp.json, remove memory hooks from .claude/settings.json, then npm uninstall @alex900530/claude-persistent-memory. The .claude-memory/ data directory is preserved — delete manually if no longer needed.

Configuration

All settings in config.default.js (override via .claude-memory.config.js):

module.exports = {
  embeddingPort: 23811,          // TCP port for embedding server
  llmPort: 23812,                // TCP port for LLM server
  dataDir: './data',             // memory.db location (per-project)
  azure: {
    endpoint: process.env.AZURE_OPENAI_ENDPOINT,
    apiKey: process.env.AZURE_OPENAI_KEY,
    deployment: 'gpt-4-1',
  },
  embedding: {
    model: 'Xenova/bge-m3',     // 1024 dimensions, 8192 token context
    dimensions: 1024,
  },
  search: {
    maxResults: 3,               // top-K results per query
    minSimilarity: 0.6,          // vector similarity threshold
  },
  cluster: {
    similarityThreshold: 0.70,   // min similarity to join a cluster
    maturityCount: 5,            // memories needed for mature cluster
  },
};

Project Structure

claude-persistent-memory/
├── bin/
│   ├── setup.js                  # postinstall + interactive setup
│   └── uninstall.js              # cleanup script
├── hooks/
│   ├── user-prompt-hook.js       # UserPromptSubmit → memory injection
│   ├── pre-tool-memory-hook.js   # PreToolUse → memory injection
│   ├── post-tool-memory-hook.js  # PostToolUse → memory injection
│   ├── pre-compact-hook.js       # PreCompact → transcript analysis
│   └── session-end-hook.js       # SessionEnd → clustering + merging
├── lib/
│   ├── memory-db.js              # SQLite + FTS5 + sqlite-vec + connection pool
│   ├── embedding-client.js       # TCP client for embedding server
│   ├── llm-client.js             # TCP client for LLM server
│   ├── compact-analyzer.js       # Transcript → memory extraction
│   └── utils.js
├── services/
│   ├── embedding-server.js       # Shared embedding service (bge-m3)
│   ├── llm-server.js             # LLM proxy (Azure OpenAI)
│   └── memory-mcp-server.js      # MCP server (stdio, per-project)
├── config.default.js
└── package.json

Requirements

Node.js >= 18
macOS or Linux
~2GB RAM for embedding model (bge-m3)
~2GB disk for model cache (~/.cache/huggingface/transformers-js/)
Azure OpenAI API access (for LLM structuring)

Notes

LLM provider: Currently supports Azure OpenAI only. Modify services/llm-server.js for other providers.
Ports: Embedding and LLM servers default to TCP 23811 / 23812. Change in config if conflicting.
Multi-project: All projects share one embedding server process. The model is loaded once; databases are pooled by dataDir.
Data: .claude-memory/ directory (containing memory.db and logs) is auto-created and gitignored per project.

Contributing

Contributions welcome! Please read the Contributing Guide before submitting a PR.

License

MIT

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

1Releases (12mo)

Commit activity

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/MIMI180306/claude-persistent-memory'

If you have feedback or need assistance with the MCP directory API, please join our Discord server