SimpleMem Remote

Remote embedding API support for SimpleMem - Efficient Lifelong Memory for LLM Agents.

Overview

SimpleMem Remote extends the original SimpleMem with support for remote embedding APIs (OpenAI, Bailian, etc.) instead of local SentenceTransformers models. This provides:

• Faster initialization - No need to load large local models (~9s saved)
• Configurable dimensions - Support for 512, 1024, and other embedding dimensions
• Batch processing - Efficient batch embedding API calls
• OpenAI-compatible - Works with any OpenAI-compatible API endpoint

Installation

As an OpenClaw Skill

clawhub install simplemem-remote

Manual Installation

pip install simplemem openai lancedb pyarrow numpy

Configuration

Set the following environment variables:

# Required
export OPENAI_API_KEY="your-api-key"

# Optional
export OPENAI_BASE_URL="https://api.openai.com/v1"
export LLM_MODEL="gpt-4o-mini"
export EMBEDDING_MODEL="text-embedding-v4"
export EMBEDDING_DIMENSION="512"
export EMBEDDING_BATCH_SIZE="10"

Usage

Python API

from simplemem_wrapper import SimpleMemRemote

# Initialize
memory = SimpleMemRemote()

# Add memories
memory.add("User likes coffee, especially oat milk lattes")
memory.add("User's favorite programming language is Python")

# Finalize to process buffered memories
memory.finalize()

# Search
results = memory.retrieve("What does the user like?")
print(results)

CLI Usage

# Add a memory
python simplemem_wrapper.py add "User lives in Shanghai"

# Finalize
python simplemem_wrapper.py finalize

# Search
python simplemem_wrapper.py search "Where does the user live?"

# Stats
python simplemem_wrapper.py stats

Performance Comparison

Metric	Local (all-MiniLM-L6-v2)	Remote (text-embedding-v4, 512d)
Initialization	~9000ms (model loading)	~100ms
Retrieval	~1400ms	~300ms
Vector Size	1536 bytes	2048 bytes (512 floats)

Supported Embedding Dimensions

For text-embedding-v4:

• 2048, 1536, 1024, 768, 512, 256, 128, 64

Lower dimensions = smaller storage + faster search, with minor quality trade-off.

API Compatibility

Tested with:

• OpenAI API
• Alibaba Cloud Bailian (百炼)
• Azure OpenAI
• Any OpenAI-compatible endpoint

Key Changes from Original SimpleMem

1. Remote Embedding API

   • Replaced local SentenceTransformers with OpenAI-compatible API
   • Added configurable embedding dimensions via dimensions parameter
   • Batch embedding support to reduce API calls

2. Custom VectorStore

   • RemoteVectorStore class that uses remote embedding
   • Properly initializes with correct vector dimensions

3. Cleaner Interface

   • SimpleMemRemote class as the main entry point
   • Simplified configuration via environment variables

Credits

• Original SimpleMem: https://github.com/aiming-lab/SimpleMem
• Paper: https://arxiv.org/abs/2601.02553

License

MIT License