aimemory-mcp-server 1.7.0

AI Memory MCP Server — persistent memory for AI assistants via Model Context Protocol. Cross-platform search across ChatGPT, Claude, DeepSeek, Gemini & Kimi.

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

aimemory-mcp-server: command not found

Make sure the pip install directory is in your PATH:

# Check where it was installed
pip show aimemory-mcp-server

# Common fix: use python -m instead
python -m aimemory_mcp.server

ModuleNotFoundError: No module named 'fastmcp'

pip install fastmcp>=2.0.0

MCP client doesn't see the tools

1. Restart your MCP client after changing configuration
2. Verify the server runs: aimemory-mcp-server (should block/wait for stdin)
3. Check MCP client logs for connection errors

Database locked errors

Only one process should write to the database at a time. If you see lock errors, ensure you don't have multiple server instances running.

---

📋 MCP Registry

Register this server in the official MCP Registry to make it discoverable:

1. Fork the MCP Registry repository
2. Add to servers.json:

{
  "io.github.jingchang0623-crypto/ai-memory": {
    "name": "AI Memory MCP Server",
    "description": "Persistent memory for AI assistants with cross-platform conversation search",
    "repository": "https://github.com/jingchang0623-crypto/aimemory",
    "homepage": "https://aimemory.pro",
    "license": "MIT",
    "tags": ["memory", "search", "conversation", "cross-platform"],
    "install": {
      "type": "pip",
      "package": "aimemory-mcp-server"
    }
  }
}

3. Submit a Pull Request

---

Contributing

Contributions are welcome! Please see the main repository for details.

git clone https://github.com/jingchang0623-crypto/aimemory.git
cd aimemory/mcp-server
pip install -e ".[dev]"

---

License

MIT — see LICENSE for details.

---

Links

• 🌐 Website: aimemory.pro
• 📦 PyPI: pypi.org/project/aimemory-mcp-server
• 🐙 GitHub: github.com/jingchang0623-crypto/aimemory
• 📋 MCP Spec: modelcontextprotocol.io