Lycheemem

Install from PyPI using pip. Add the optional [rerank] extra to enable transformer-based reranking for higher-quality memory retrieval.

pip install lycheemem
# With transformer reranker (higher quality retrieval):
pip install "lycheemem[rerank]"

Create a .env file in your working directory with the required LLM and embedding model settings. LycheeMem uses litellm format for model identifiers, so you can swap providers without code changes.

LLM_MODEL=openai/gpt-4o-mini
LLM_API_KEY=sk-your-openai-key-here

EMBEDDING_MODEL=openai/text-embedding-3-small
EMBEDDING_DIM=1536

# Optional: transformer reranker
EXPERIMENTAL_TRANSFORMER_RERANK=false
TRANSFORMER_RERANK_MODEL_PATH=LycheeMem/reranker

Launch the memory server using the lycheemem-cli command. It starts on http://localhost:8000 and exposes both a REST API and an MCP endpoint. The interactive API docs are available at http://localhost:8000/docs.

lycheemem-cli
# Server starts at http://localhost:8000
# MCP endpoint: http://localhost:8000/mcp
# API docs: http://localhost:8000/docs

Add LycheeMem to your MCP client configuration pointing at the running server's MCP endpoint. Since the server must already be running, start it first, then configure your client.

{
  "mcpServers": {
    "lycheemem": {
      "command": "uvx",
      "args": ["lycheemem"],
      "env": {
        "LLM_MODEL": "openai/gpt-4o-mini",
        "LLM_API_KEY": "sk-your-openai-key-here",
        "EMBEDDING_MODEL": "openai/text-embedding-3-small",
        "EMBEDDING_DIM": "1536"
      }
    }
  }
}

Run the included demo script to verify the full memory pipeline: conversation turn ingestion, semantic encoding, consolidation to long-term storage, and retrieval.

# Single turn demo:
python examples/api_pipeline_demo.py

# Multi-turn with consolidation:
python examples/api_pipeline_demo.py --multi-turn

# Persistent named session:
python examples/api_pipeline_demo.py --session-id my-session

The MCP endpoint exposes five tools: lychee_memory_smart_search (one-shot recall with optional synthesis), lychee_memory_search (unified retrieval), lychee_memory_append_turn (log conversation turns), lychee_memory_synthesize (fuse retrieved fragments), and lychee_memory_consolidate (persist session to long-term memory). Use these in your agent's tool loop.