SMOS: A Semantic Memory Layer for Claude
I built SMOS — a local MCP server that gives Claude persistent semantic memory across sessions, compressing codebase knowledge by 51× with no factual loss.
The problem
Every Claude session starts cold. Files get read into the context window, analysed, and then held there — taking up space even after the useful knowledge has been extracted. On a codebase of twenty files you pay token costs for source code that has already been processed, every single turn. When the session ends, everything disappears. The next session starts from scratch.
This gets expensive fast, and it scales badly. The larger the project, the more of your context budget goes to raw material instead of actual thinking.
What SMOS is
SMOS — Semantic Memory Operating System — is an MCP server that runs locally and gives Claude a persistent memory layer outside the context window. Instead of loading files directly, Claude compresses them into queryable summaries and stores them between sessions. When it needs something, it retrieves by meaning — not by filename or keyword — and pulls back only what is relevant.
The context window stays clear. The knowledge accumulates.
How it works
SMOS combines three components:
Local LLM compression. Every file that enters the system passes through a locally-running language model (Ollama with Qwen 2.5 by default). The model produces a ~85-token summary that captures the semantic content without reproducing the raw text. No cloud API calls; everything stays on your machine.
FAISS vector index. Summaries are embedded and indexed so retrieval is by meaning. Ask "where is the authentication logic?" and you get the relevant summaries, not a keyword scan.
SQLite backend. Full content, summaries, embeddings, and metadata are stored
in a per-project .smos/ folder. Memories created in one session are
immediately available in the next.
There are two storage paths: semantic for prose, notes, and analysis (goes through LLM compression), and verbatim for code, diffs, and structured data (stored losslessly, retrieved by key). The routing is explicit — you decide what needs to be exact and what can be compressed.
The numbers
Across tested file sizes, SMOS achieves 51× average compression with 100% factual retention in the test suite. Query latency scales sublinearly: P95 grows only 1.21× when the stored data grows 100×. The project ships with 86 tests and was validated by running it against its own codebase — achieving a 5.8× context reduction versus the baseline of loading files directly.
Version 0.1.4 adds repository ingestion tools for scanning entire codebases in parallel with duplicate detection.
Find it on GitHub
SMOS is open source under the MIT licence. The repository includes architecture documentation, benchmark results, and update tooling.