Metadata-Version: 2.4
Name: mcp-external-memory
Version: 0.1.2
Summary: An MCP server that gives LLMs persistent, searchable semantic memory
Project-URL: Homepage, https://github.com/daedalus/mcp-external-memory
Project-URL: Repository, https://github.com/daedalus/mcp-external-memory
Project-URL: Issues, https://github.com/daedalus/mcp-external-memory/issues
Author-email: Dario Clavijo <clavijodario@gmail.com>
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: lz4>=4.3.0
Requires-Dist: mcp>=1.4.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: orjson>=3.10.0
Requires-Dist: tenacity>=9.0.0
Provides-Extra: all
Requires-Dist: hatch; extra == 'all'
Requires-Dist: hypothesis; extra == 'all'
Requires-Dist: mypy; extra == 'all'
Requires-Dist: pytest; extra == 'all'
Requires-Dist: pytest-asyncio; extra == 'all'
Requires-Dist: pytest-cov; extra == 'all'
Requires-Dist: pytest-mock; extra == 'all'
Requires-Dist: ruff; extra == 'all'
Provides-Extra: cli
Requires-Dist: click>=8.0; extra == 'cli'
Provides-Extra: dev
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: lint
Requires-Dist: mypy; extra == 'lint'
Requires-Dist: ruff; extra == 'lint'
Provides-Extra: test
Requires-Dist: hypothesis; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-asyncio; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest-mock; extra == 'test'
Description-Content-Type: text/markdown

# mcp-external-memory

> An MCP server that gives LLMs persistent, searchable semantic memory.

[![PyPI](https://img.shields.io/pypi/v/mcp-external-memory.svg)](https://pypi.org/project/mcp-external-memory/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-external-memory.svg)](https://pypi.org/project/mcp-external-memory/)
[![Coverage](https://codecov.io/gh/daedalus/mcp-external-memory/branch/main/graph/badge.svg)](https://codecov.io/gh/daedalus/mcp-external-memory)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

## Install

```bash
pip install mcp-external-memory
```

## Usage

```python
from mcp_external_memory import memory_store, memory_search

# Store a memory
result = memory_store(content="Alice prefers dark mode", namespace="users", tags=["alice", "ui"])

# Search memories
results = memory_search(query="what does Alice prefer?", namespace="users")
```

## CLI

```bash
mcp-external-memory --help
```

## API

### Tools

| Tool | Description |
|------|-------------|
| `memory_store` | Persist text + optional namespace/tags/metadata |
| `memory_search` | Semantic search (cosine similarity) over all memories |
| `memory_get` | Retrieve a single memory by ID |
| `memory_delete` | Delete a memory by ID |
| `memory_list` | List memories with optional namespace/tag filter + pagination |
| `memory_stats` | Count of memories, namespaces, DB path |
| `memory_update` | Update an existing memory |

### Embedding Backends

The server supports multiple embedding backends:

- **TF-IDF** (default): Pure Python, no external dependencies
- **OpenAI**: Uses `text-embedding-3-small` model
- **Ollama**: Local embeddings with Ollama

Set via `MEMORY_EMBED_BACKEND` environment variable.

## Development

```bash
git clone https://github.com/daedalus/mcp-external-memory.git
cd mcp-external-memory
pip install -e ".[test]"

# run tests
pytest

# format
ruff format src/ tests/

# lint
ruff check src/ tests/

# type check
mypy src/
```

## MCP Registry

mcp-name: io.github.daedalus/mcp-external-memory
