mcp-memory-service: Instructions file for Codex

AGENTS.md

AI coding agent instructions for MCP Memory Service - a universal memory service providing semantic search and persistent storage for AI assistants.

Project Overview

MCP Memory Service implements the Model Context Protocol (MCP) to provide semantic memory capabilities for AI assistants. It supports multiple storage backends (SQLite-vec, ChromaDB, Cloudflare) and works with 13+ AI applications including Claude Desktop, VS Code, Cursor, and Continue.

Setup Commands

# Install dependencies (platform-aware)
python install.py

# Alternative: UV installation (faster)
uv sync

# Start development server
uv run memory server

# Run with inspector for debugging
npx @modelcontextprotocol/inspector uv run memory server

# Start HTTP API server (dashboard at https://localhost:8443)
uv run memory server --http --port 8443

Testing

# Run all tests
pytest tests/

# Run specific test categories
pytest tests/test_server.py          # Server tests
pytest tests/test_storage.py         # Storage backend tests
pytest tests/test_embeddings.py      # Embedding tests

# Run with coverage
pytest --cov=mcp_memory_service tests/

# Verify environment setup
python scripts/validation/verify_environment.py

# Check database health
python scripts/database/db_health_check.py

Code Style

• Python 3.10+ with type hints everywhere
• Async/await for all I/O operations
• Black formatter with 88-char line length
• Import order: stdlib, third-party, local (use isort)
• Docstrings: Google style for all public functions
• Error handling: Always catch specific exceptions
• Logging: Use structured logging with appropriate levels

Project Structure

src/mcp_memory_service/
├── server.py           # Main MCP server implementation
├── mcp_server.py       # MCP protocol handler
├── storage/            # Storage backend implementations
│   ├── base.py        # Abstract base class
│   ├── sqlite_vec.py  # SQLite-vec backend (default)
│   ├── chroma.py      # ChromaDB backend
│   └── cloudflare.py  # Cloudflare D1/Vectorize backend
├── embeddings/         # Embedding model implementations
├── consolidation/      # Memory consolidation algorithms
└── web/               # FastAPI dashboard and REST API