LycheeMem

LycheeMemory is a compact memory framework for LLM agents. It starts from efficient conversational memory—through structured organization, lightweight consolidation, and adaptive retrieval—and gradually extends toward action-aware, usage-aware memory for more capable agentic systems.

🔥 News

• [07/07/2026] OpenAI-compatible Chat Completions endpoints are now available, with request-level consolidation control via consolidate or store.
• [05/08/2026] Transformer memory reranker v0 improves evidence selection in semantic memory search, with positive hit@10 gains on LoCoMo and zero-shot LongMemEval-S / MSC-MemFuse / HotpotQA fixtures. See Transformer Reranker v0.
• [04/29/2026] Hermes and Claude Code plugin integrations are now available, bringing LycheeMemory's automatic recall, turn mirroring, and consolidation workflow to more agent runtimes. Setup guides: Hermes · Claude Code
• [04/26/2026] Visual (Multimodal) Memory module added! See Visual Memory.
• [04/13/2026] LycheeMem is now LycheeMemory.
• [04/03/2026] The project now supports installation via pip install lycheemem. You can easily start the service from anywhere using lycheemem-cli!
• [03/30/2026] We evaluated LycheeMemory on PinchBench with the OpenClaw plugin: compared to OpenClaw's native memory, it achieved an ~6% score improvement, while reducing token consumption by ~71% and cost by ~55%!
• [03/28/2026] Semantic memory has been upgraded to Compact Semantic Memory (SQLite + LanceDB), no Neo4j required. See /quick-start for details.
• [03/27/2026] OpenClaw Plugin is now available at /openclaw-plugin ! Setup guide →
• [03/26/2026] MCP support is available at /mcp !
• [03/23/2026] LycheeMemory is now open source: GitHub Repository →

🔗 Related Projects

LycheeMemory is part of the 3rd-generation Lychee (立知) large model series, which focuses on memory intelligence, continual learning, and long-context reasoning.

We welcome you to explore our related works:

• LycheeMemory (ACL 2026, CCF-A): a unified framework for implicit long-term memory and explicit working memory collaboration in large language models
  

• LycheeMem (this project): long-term memory infrastructure for LLM-based agents
  

• LycheeDecode (ICLR 2026, CCF-A): selective recall from massive KV-cache context memory
  

• LycheeCluster (ACL 2026, CCF-A): structured organization and hierarchical indexing for context memory
  

⚡ Quick Start

Prerequisites

• Python 3.9+
• An LLM API key (OpenAI, Gemini, or any litellm-compatible provider)

Installation

Install the core package:

pip install lycheemem

Recommended install with the default transformer memory reranker:

pip install "lycheemem[rerank]"

The rerank extra adds PyTorch / Transformers runtime dependencies. With it installed, LycheeMemory enables the hosted LycheeMem/reranker checkpoint by default. Without the extra, the core memory system still works and reranking falls back safely.

Once installed, you can start the backend server instantly using the CLI:

lycheemem-cli

For development or if you prefer to run from source:

git clone https://github.com/LycheeMem/LycheeMem.git
cd LycheeMem
pip install -e .

Configuration

Create a .env file in your working directory and fill in your values. The full template in .env.example also includes session/user DB paths, JWT settings, and working-memory thresholds; the snippet below shows the most important ones:

# LLM — litellm format: provider/model
LLM_MODEL=openai/gpt-4o-mini
LLM_API_KEY=sk-...
LLM_API_BASE=                     # optional

# Embedder
EMBEDDING_MODEL=openai/text-embedding-3-small
EMBEDDING_DIM=1536
EMBEDDING_API_KEY=                # optional
EMBEDDING_API_BASE=               # optional

Supported LLM providers (via litellm): openai/gpt-4o-mini · gemini/gemini-2.0-flash · ollama_chat/qwen2.5 · any OpenAI-compatible endpoint

Transformer Reranker

LycheeMemory includes a transformer reranker for semantic memory search. It can improve evidence selection when the correct memory is already in the wider candidate pool.

For the smoothest experience, install LycheeMemory with the rerank extra:

pip install "lycheemem[rerank]"

After that, no extra model command is required. The reranker is enabled by default and loads the current v0 checkpoint from Hugging Face on first use:

EXPERIMENTAL_TRANSFORMER_RERANK=true
TRANSFORMER_RERANK_MODEL_PATH=LycheeMem/reranker

To disable it explicitly:

EXPERIMENTAL_TRANSFORMER_RERANK=false

If you prefer to pin the model to a local directory, download it once and point the same variable at that path:

mkdir -p ~/.cache/lycheemem/models
huggingface-cli download LycheeMem/reranker \
  --local-dir ~/.cache/lycheemem/models/reranker-v0
export TRANSFORMER_RERANK_MODEL_PATH=~/.cache/lycheemem/mo