SimpleMem

The Problem

LLM agents quickly lose context when conversations exceed a few hundred tokens. Existing memory layers either replay raw dialogue (high token cost) or rely on costly re‑reasoning loops, making long‑term recall impractical for production bots.

What This Does

SimpleMem implements a three‑stage “semantic lossless compression” pipeline that turns raw chat into compact, query‑able facts.

Compression – core/memorybuilder.py extracts atomic facts from a dialogue using entropy‑based filtering. Indexing – core/hybridretriever.py builds a hierarchical index (atoms → molecules) stored in database/vectorstore.py. Adaptive Retrieval – core/answergenerator.py selects the smallest set of facts that satisfy a query, balancing semantic relevance and token budget.

The repository ships three usable forms:

How To Use It

Setup

Install core library + all optional components pip install -r requirements.txt # root requirements pip install -r MCP/requirements.txt # MCP server deps pip install -r SKILL/simplemem-skill/requirements.txt # Skill deps

Configuration

MCP server – edit MCP/config/settings.py to set HOST, PORT, and optionally JWTSECRET. Skill – create a config.yaml (see SKILL/simplemem-skill/src/config.py.example) with your OPENROUTERAPIKEY and MCPENDPOINT.

Running

Library – simple import: from core.memorybuilder import MemoryBuilder mb = MemoryBuilder() facts = mb.compressdialogue(chathistory)

MCP server – start the HTTP service: python MCP/run.py

The server listens on the host/port defined in MCP/config/settings.py.

Skill – register the skill and launch the CLI helper: python SKILL/simplemem-skill/scripts/clipersistentmemory.py --config config.yaml

The CLI prints a token that can be pasted into the Claude skill definition.

Real‑World Use

A customer‑support bot can call MemoryBuilder.compressdialogue() after each user turn, persisting the returned facts in the MCP server (POST /memory). When the bot needs context, it sends the current query to GET /retrieve?userid=…&query=…; the server runs answergenerator.generateanswer() and returns only the minimal fact set, saving ~70 % of token usage compared with naïve context concatenation.

import requests store new facts requests.post("https://mcp.simplemem.cloud/memory", json={"user":"123", "facts":facts})

retrieve relevant facts for a new question resp = requests.get("https://mcp.simplemem.cloud/retrieve", params={"user":"123", "query":"How do I reset my password?"}) context = resp.json()["facts"]

Code Health & Issues

Medium – Missing CI/CD – No .github/workflows or other pipeline files; automated testing is not enforced. Low – No lockfile – Dependencies are listed only in requirements.txt; reproducible builds rely on external package versions. Low – Sparse input validation – Core functions (e.g., memorybuilder.compressdialogue) lack explicit type checks; malformed inputs could raise uncaught exceptions. Low – Documentation gaps – README.md explains high‑level concepts, but API reference for library functions is missing. Medium – Security exposure – MCP/config/settings.py contains placeholders for secrets; accidental commit of real keys would be a risk. Positive – Test coverage – 9 test files (tests/, testref/) exercise vector store and retrieval logic, indicating functional intent.

The Bottom Line

SimpleMem delivers a practical, Python‑native memory layer that reduces token consumption while preserving relevant knowledge, suitable for teams building LLM‑backed assistants that need long‑term context. The codebase is functional but lacks production safeguards (CI, lockfiles, thorough docs). Use it if you can handle the modest operational overhead; otherwise, expect to add testing pipelines and stricter security handling before deploying at scale.