AI Memory MCP Server

A Model Context Protocol (MCP) server that gives AI assistants persistent memory. Works with Claude Desktop, Cursor, VS Code, Windsurf, and 113+ MCP clients.

🚀 Quick Install (One-Click)

Smithery (Cursor, Windsurf, Claude Desktop)

npx @smithery/cli install aimemory-mcp-server --client cursor
# or for windsurf:
npx @smithery/cli install aimemory-mcp-server --client windsurf

VS Code / Continue

Add to your MCP settings:

{
  "mcpServers": {
    "ai-memory": {
      "command": "npx",
      "args": ["-y", "@smithery/cli@latest", "run", "aimemory-mcp-server", "--client", "vscode"]
    }
  }
}

Installation

Option 1: PyPI Install (Recommended)

pip install aimemory-mcp-server

Option 2: GitHub Install

pip install git+https://github.com/jingchang0623-crypto/aimemory.git#subdirectory=mcp-server

Note: GitHub install provides the latest development version directly from the repository.

That's it! The aimemory-mcp-server command is now available.

Quick Start

Claude Desktop

Add to ~/.config/claude-desktop/claude_desktop_config.json (Linux/macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ai-memory": {
      "command": "aimemory-mcp-server"
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ai-memory": {
      "command": "aimemory-mcp-server"
    }
  }
}

VS Code (with Continue or MCP extension)

Add to your MCP configuration file:

{
  "mcpServers": {
    "ai-memory": {
      "command": "aimemory-mcp-server"
    }
  }
}

Windsurf

Add to ~/.windsurf/config.json:

{
  "mcpServers": {
    "ai-memory": {
      "command": "aimemory-mcp-server"
    }
  }
}

Tip: To use a custom database location, add "env": {"AIMEMORY_DB": "/path/to/your/aimemory.db"} to any configuration above.

Features

🔍 Full-text search — powered by SQLite FTS5 for fast, ranked results
🏷️ Tag-based organization — categorize memories with tags
💾 Persistent storage — memories survive restarts (SQLite)
- 🔧 16 core tools — save, smart_search, timeline, consolidate, search, list, get, update, delete, stats, export, import, batch_save, get_tags, clear, memory_inject
🚀 Easy install — pip install aimemory-mcp-server from PyPI
🪶 Zero config — works out of the box with sensible defaults

Available Tools

`save_memory` — Save a new memory

{
  "content": "The user prefers Python over JavaScript for backend work",
  "tags": ["preferences", "coding"],
  "source": "conversation-123"
}

Parameter	Type	Required	Description
`content`	string	✅	The memory content to store
`tags`	list[str]	❌	Tags for categorization, e.g. `["work", "meeting"]`
`source`	string	❌	Source identifier (URL, file path, conversation ID)

`search_memories` — Full-text search

{
  "query": "python backend",
  "limit": 5
}

Parameter	Type	Required	Description
`query`	string	✅	Search query (supports FTS5 syntax)
`limit`	int	❌	Max results (default: 10, max: 100)

`list_memories` — List memories

{
  "limit": 20,
  "tag": "coding"
}

Parameter	Type	Required	Description
`limit`	int	❌	Max results (default: 20, max: 200)
`tag`	string	❌	Filter by tag

`update_memory` — Update a memory

{
  "memory_id": 42,
  "content": "Updated content",
  "tags": ["updated-tag"]
}

Parameter	Type	Required	Description
`memory_id`	int	✅	ID of the memory to update
`content`	string	❌	New content (keeps existing if omitted)
`tags`	list[str]	❌	New tags (keeps existing if omitted)

`delete_memory` — Delete a memory

{
  "memory_id": 42
}

Parameter	Type	Required	Description
`memory_id`	int	✅	ID of the memory to delete

`get_memory` — Retrieve a memory by ID

{
  "memory_id": 42
}

Parameter	Type	Required	Description
`memory_id`	int	✅	ID of the memory to retrieve

`memory_stats` — Get memory store statistics

{}

Returns total memory count, memories created in the last 7 days, and top tags distribution.

`export_memories` — Export all memories for backup

{}

Returns all memories as a JSON list with count and export timestamp. Use this to backup your knowledge base or migrate to another system.

Returns:

count: Number of memories exported
memories: List of all memory objects (id, content, tags, source, timestamps)
exported_at: UTC timestamp of export

`import_memories` — Import memories from backup

{
  "memories": [
    {"content": "User prefers dark mode", "tags": ["preferences"]},
    {"content": "Project uses PostgreSQL", "tags": ["tech-stack"]}
  ],
  "skip_duplicates": true
}

Parameter	Type	Required	Description
`memories`	list[dict]	✅	List of memory dicts to import
`skip_duplicates`	bool	❌	Skip memories with existing content (default: true)

Returns: imported count and skipped count (duplicates).

`batch_save_memories` — Save multiple memories at once

{
  "memories": [
    {"content": "User prefers dark mode", "tags": ["preferences"]},
    {"content": "Project uses PostgreSQL", "tags": ["tech-stack"]},
    {"content": "Team uses GitHub for CI/CD", "tags": ["devops"]}
  ]
}

Parameter	Type	Required	Description
`memories`	list[dict]	✅	List of memory dicts (content required, tags/source optional)

Returns: saved count and ids list of newly created memory IDs.

Use this for bulk operations — much faster than calling save_memory repeatedly. Perfect for extracting key takeaways from a conversation in one call.

`get_all_tags` — List all unique tags with counts

{}

Returns: total_tags count and tags dict mapping tag name to usage count (sorted by most-used first).

Use this to discover what categories of memories you have stored. Great for building navigation UI or understanding your knowledge base structure.

`clear_all_memories` — Delete all memories

{}

⚠️ WARNING: This permanently removes every memory. Export first using export_memories if you want to keep a backup.

Returns: success boolean and deleted_count (number of memories removed).

`memory_smart_search` — 🔍 Smart search with tag boost & recency

Enhances basic FTS5 search by boosting results that match tags or were created recently.

{
  "query": "react nextjs project",
  "limit": 10,
  "tag_boost": 1.5,
  "recency_days": 30
}

Parameter	Type	Required	Default	Description
`query`	string	✅	—	Search query (FTS5 syntax supported)
`limit`	int	❌	10	Max results (max: 100)
`tag_boost`	float	❌	1.5	Boost factor for tag matches (set to 1.0 to disable)
`recency_days`	int	❌	30	Memories from last N days get recency boost

Returns: Memories reranked by relevance + tag match + recency.

`memory_timeline` — 📅 Memory timeline grouped by date

Perfect for visualizing how your memory collection evolved over time. Groups by creation date.

{
  "days": 7,
  "tag": null
}

Parameter	Type	Required	Default	Description
`days`	int	❌	7	Number of days to look back
`tag`	string	❌	null	Optional tag filter

Returns: Timeline data grouped by date with count and memory previews.

`memory_consolidate` — 🧩 Find & consolidate related memories

Analyzes a group of related memories and suggests consolidation strategies.

{
  "query": "tech stack preferences",
  "max_memories": 20
}

Parameter	Type	Required	Default	Description
`query`	string	✅	—	Search to find related memories
`max_memories`	int	❌	20	Max memories to analyze (max: 100)

Returns: Memory IDs, shared tags, tag frequency, avg length, and consolidation suggestions.

`memory_inject` — 💉 Inject memories into AI context (Claude Memory Tool protocol)

Retrieves memories and formats them for injection into an AI assistant's context window. Supports three injection modes for different use cases.

{
  "inject_type": "append",
  "query": "python project",
  "format": "markdown"
}

Parameter	Type	Required	Default	Description
`inject_type`	string	❌	`"append"`	How to inject: `"append"`, `"prepend"`, or `"replace"`
`content`	string	❌	`""`	Additional content to prepend/append alongside memories
`memory_ids`	int[]	❌	`null`	Specific memory IDs to inject (if omitted, uses query)
`query`	string	❌	`null`	Search query to find memories (FTS5 syntax supported)
`format`	string	❌	`"text"`	Output format: `"text"`, `"json"`, or `"markdown"`

Returns: Formatted memory content ready for injection, with metadata.

Injection modes:

append — Add memories at end of context (safest, default)
prepend — Add memories at start of context (for important facts)
replace — Replace existing context with memories (use carefully)

Example use cases:

Inject project memories before starting a new coding session
Prepend user preferences when generating responses
Append related facts to provide context for a question

Format options:

text — Plain text, one memory per line (compact)
json — JSON array with full metadata (machine-readable)
markdown — Markdown formatted list with metadata (human-readable)

Search Syntax

The search uses SQLite FTS5 syntax:

Syntax	Example	Description
Simple	`python tutorial`	Words appearing anywhere
AND	`python AND machine learning`	Both terms required
OR	`react OR vue`	Either term matches
Phrase	`"exact phrase match"`	Exact phrase in quotes
NEAR	`NEAR/3(word1 word2)`	Words within 3 tokens of each other
Prefix	`prog*`	Matches "program", "programming", etc.

Environment Variables

Variable	Default	Description
`AIMEMORY_DB`	`./aimemory.db`	Path to the SQLite database file
`AIMEMORY_TRANSPORT`	`stdio`	Transport mode: `stdio` (local) or `http` (remote via SSE)
`AIMEMORY_PORT`	`8090`	Port for HTTP transport mode
`AIMEMORY_HOST`	`0.0.0.0`	Host for HTTP transport mode

Set a custom database path:

export AIMEMORY_DB="/path/to/your/aimemory.db"

HTTP/SSE Transport (Remote Access)

For remote access or integration with web-based MCP clients:

AIMEMORY_TRANSPORT=http AIMEMORY_PORT=8090 aimemory-mcp-server

Then configure your MCP client to connect via SSE:

{
  "mcpServers": {
    "ai-memory": {
      "url": "http://your-server:8090/sse"
    }
  }
}

Or in your MCP client configuration:

{
  "mcpServers": {
    "ai-memory": {
      "command": "aimemory-mcp-server",
      "env": {
        "AIMEMORY_DB": "/path/to/your/aimemory.db"
      }
    }
  }
}

Running Without pip Install

You can also run directly from the repository:

cd mcp-server
pip install -r requirements.txt
python server.py

And configure the MCP client with the full path:

{
  "mcpServers": {
    "ai-memory": {
      "command": "python3",
      "args": ["/path/to/mcp-server/server.py"]
    }
  }
}

Troubleshooting