aimemory-mcp-server 1.4.0__tar.gz

aimemory_mcp_server-1.4.0/.gitignore

@@ -0,0 +1,52 @@
+# dependencies
+node_modules/
+.pnp
+.pnp.js
+
+# testing
+coverage/
+
+# next.js
+.next/
+out/
+
+# production
+build/
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# env files
+.env*.local
+.env
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# database
+*.db
+*.db-journal
+*.db-shm
+*.db-wal
+data/
+
+# uploads
+uploads/
+
+__pycache__/
+*.pyc
+mcp-server/dist/
+
+# Python venvs
+*.venv/
+mcp-server/.venv/

aimemory_mcp_server-1.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Memory (aimemory.pro)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aimemory_mcp_server-1.4.0/PKG-INFO

@@ -0,0 +1,446 @@
+Metadata-Version: 2.4
+Name: aimemory-mcp-server
+Version: 1.4.0
+Summary: AI Memory MCP Server — persistent memory for AI assistants via Model Context Protocol
+Project-URL: Homepage, https://aimemory.pro
+Project-URL: Repository, https://github.com/jingchang0623-crypto/aimemory
+Project-URL: Issues, https://github.com/jingchang0623-crypto/aimemory/issues
+Project-URL: Documentation, https://aimemory.pro/docs/mcp
+Author-email: AI Memory <hello@aimemory.pro>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-memory,claude,cursor,fts5,knowledge-base,llm,mcp,model-context-protocol,persistent-memory,sqlite
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=2.0.0
+Description-Content-Type: text/markdown
+
+# AI Memory MCP Server
+
+[![PyPI version](https://img.shields.io/pypi/v/aimemory-mcp-server.svg)](https://pypi.org/project/aimemory-mcp-server/)
+[![Python versions](https://img.shields.io/pypi/pyversions/aimemory-mcp-server.svg)](https://pypi.org/project/aimemory-mcp-server/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io/)
+[![Homepage](https://img.shields.io/badge/Web-aimemory.pro-purple.svg)](https://aimemory.pro)
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that gives AI assistants **persistent memory**. Works with **Claude Desktop**, **Cursor**, **VS Code**, **Windsurf**, and **113+ MCP clients**.
+
+---
+
+## Installation
+
+### Option 1: PyPI Install (Recommended)
+
+```bash
+pip install aimemory-mcp-server
+```
+
+### Option 2: GitHub Install
+
+```bash
+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):
+
+```json
+{
+  "mcpServers": {
+    "ai-memory": {
+      "command": "aimemory-mcp-server"
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project root or `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ai-memory": {
+      "command": "aimemory-mcp-server"
+    }
+  }
+}
+```
+
+### VS Code (with Continue or MCP extension)
+
+Add to your MCP configuration file:
+
+```json
+{
+  "mcpServers": {
+    "ai-memory": {
+      "command": "aimemory-mcp-server"
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.windsurf/config.json`:
+
+```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)
+- 🔧 **12 core tools** — save, search, list, get, update, delete, stats, export, import, batch_save, get_tags, clear
+- 🚀 **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
+
+```json
+{
+  "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
+
+```json
+{
+  "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
+
+```json
+{
+  "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
+
+```json
+{
+  "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
+
+```json
+{
+  "memory_id": 42
+}
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `memory_id` | int | ✅ | ID of the memory to delete |
+
+### `get_memory` — Retrieve a memory by ID
+
+```json
+{
+  "memory_id": 42
+}
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `memory_id` | int | ✅ | ID of the memory to retrieve |
+
+### `memory_stats` — Get memory store statistics
+
+```json
+{}
+```
+
+Returns total memory count, memories created in the last 7 days, and top tags distribution.
+
+### `export_memories` — Export all memories for backup
+
+```json
+{}
+```
+
+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
+
+```json
+{
+  "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
+
+```json
+{
+  "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
+
+```json
+{}
+```
+
+**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
+
+```json
+{}
+```
+
+⚠️ **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).
+
+---
+
+## 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:
+
+```bash
+export AIMEMORY_DB="/path/to/your/aimemory.db"
+```
+
+### HTTP/SSE Transport (Remote Access)
+
+For remote access or integration with web-based MCP clients:
+
+```bash
+AIMEMORY_TRANSPORT=http AIMEMORY_PORT=8090 aimemory-mcp-server
+```
+
+Then configure your MCP client to connect via SSE:
+
+```json
+{
+  "mcpServers": {
+    "ai-memory": {
+      "url": "http://your-server:8090/sse"
+    }
+  }
+}
+```
+
+Or in your MCP client configuration:
+
+```json
+{
+  "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:
+
+```bash
+cd mcp-server
+pip install -r requirements.txt
+python server.py
+```
+
+And configure the MCP client with the full path:
+
+```json
+{
+  "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`:
+
+```bash
+# 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'`
+
+```bash
+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.
+
+---
+
+## Contributing
+
+Contributions are welcome! Please see the [main repository](https://github.com/jingchang0623-crypto/aimemory) for details.
+
+```bash
+git clone https://github.com/jingchang0623-crypto/aimemory.git
+cd aimemory/mcp-server
+pip install -e ".[dev]"
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](https://opensource.org/licenses/MIT) for details.
+
+---
+
+## Links
+
+- 🌐 **Website**: [aimemory.pro](https://aimemory.pro)
+- 📦 **PyPI**: [pypi.org/project/aimemory-mcp-server](https://pypi.org/project/aimemory-mcp-server/)
+- 🐙 **GitHub**: [github.com/jingchang0623-crypto/aimemory](https://github.com/jingchang0623-crypto/aimemory)
+- 📋 **MCP Spec**: [modelcontextprotocol.io](https://modelcontextprotocol.io/)