memtomem-stm 0.1.37

Short-term memory proxy gateway with proactive memory surfacing for AI agents

memtomem-stm

Official website & docs: https://memtomem.com

🚧 Alpha — APIs and defaults may change between 0.1.x releases. Feedback and issue reports are especially welcome: Issues · Discussions.

Spend fewer tokens. Remember more. Ship faster.

memtomem-stm is an MCP proxy that can substantially reduce the model-visible size of large tool responses and gives your agent memory across sessions — with no changes to your upstream MCP servers. The actual reduction depends on response shape, compression strategy, and whether the call travels through MCP; verify it against your workload with the repository's deterministic bench_qa suite.

It sits between your AI agent and its upstream MCP servers, compressing tool responses, caching repeated calls, and automatically surfacing relevant context from prior sessions via a memtomem LTM server.

What memtomem-stm does:

• Cuts token spend on repeated reads — compresses and caches tool responses, so the agent doesn't re-pay for the same file or search result. Works with Claude Code, Cursor, Claude Desktop, or any MCP client.
• Carries context across sessions — surfaces prior decisions from memtomem LTM automatically, so the agent picks up where it left off rather than re-discovering what it already knew.
• Drops in front of any MCP server — adds compression, caching, and observability as a proxy layer, without changes to upstream code.

flowchart TB
    Agent["Agent<br/>(Claude Code, Cursor, …)"]
    subgraph STM["memtomem-stm (STM)"]
        Pipe["CLEAN → COMPRESS → SURFACE"]
    end
    LTM[("memtomem LTM<br/>(MCP server)")]
    FS["filesystem<br/>MCP server"]
    GH["github<br/>MCP server"]
    Other["…any MCP server"]

    Agent -->|MCP| STM
    STM <-->|MCP: stdio / SSE / HTTP| FS
    STM <-->|MCP| GH
    STM <-->|MCP| Other
    STM <-.->|surfacing<br/>via MCP| LTM

Installation

pip install memtomem-stm

Or with uv:

uv tool install memtomem-stm     # install mms / memtomem-stm as global CLI tools
uvx memtomem-stm --help          # or run without installing
uv pip install memtomem-stm      # or install into the active environment

memtomem-stm is independent: it has no Python-level dependency on memtomem core. To enable proactive memory surfacing, point STM at a running memtomem MCP server (or any compatible MCP server) — communication happens entirely through the MCP protocol.

Connected LTM capability	STM behavior
No core	Proxying, compression, and caching remain available; LTM surfacing is disabled
No context_compose advertisement, or schema 0/1	Legacy mem_search surfacing
context_compose schema 2+	Optional scoped Pinned Context composition
candidate_propose schema 1+	Optional review-first proposal submission

Core 0.3.8 is the tested legacy baseline; 0.3.9 is the first release expected to advertise context-compose schema 2. Runtime behavior always follows the advertised capability, not the package version.

Quick Start

All three installed commands—mms, memtomem-stm, and memtomem-stm-proxy—resolve to the same CLI and MCP server entrypoint. The shortest first-success path is:

mms init      # add an upstream and optionally register STM with a client
mms doctor    # exit 0 (WARNs allowed) means the proxy setup is usable

Without the wizard, add an upstream and register STM explicitly:

mms add filesystem \
  --command npx \
  --args "-y @modelcontextprotocol/server-filesystem /home/user/projects" \
  --prefix fs
mms register
mms doctor

Your client should now list a proxied tool such as fs__read_file. An LTM warning is expected when no memtomem server is configured; it disables memory surfacing only, not proxying, compression, or caching.

Continue with the complete Getting Started guide, including manual client registration, imports, verification, and next steps.

What STM proxies — and what it doesn't

STM is an MCP proxy: it sees a tool call only if the client routes that call through the MCP protocol. Coverage depends on how your client invokes the tool, not on what the tool does.

STM sees: any MCP server you register with mms add — every tool under the mcp__<server>__<prefix>__<tool> namespace — plus LTM surfacing calls to a configured memtomem server.

STM does NOT see through the MCP proxy path:

• Claude Code's built-in tools — Read, Write, Edit, Bash, Grep, Glob, WebFetch. They run inside the client and never reach an MCP server, so their token spend is invisible to STM and unaffected by compression or caching.
• Cursor / Windsurf / Claude Desktop built-ins — same principle: anything the client provides natively bypasses the MCP layer.
• Sub-agent built-in calls — the parent's MCP wiring is inherited, but built-in tool calls inside an Agent / Task invocation stay client-internal.

mms hook is an optional PostToolUse bridge for that client-internal path, available for Claude Code, Codex CLI, Cursor, and Kimi Code. Claude and Codex can receive surfaced LTM context; Cursor and Kimi are metrics-only. Claude can also opt into guarded Bash compression. Native calls still do not gain proxy caching, retries, progressive reads, extraction, or indexing, and the hook always fails open. See the native-hook guide for the capability matrix, installation paths, daemon behavior, and privacy.

For multi-agent fleets, standalone surfacing can opt into the same daemon with MEMTOMEM_STM_SURFACING__USE_DAEMON=true, avoiding one private LTM child per agent while keeping proxy feedback, caching, and tuning local.

STM does not automatically write tool responses back to LTM. Surfacing reads from LTM via MCP. The opt-in review-first formation integration may submit an explicit pending candidate to a capable core, but it cannot create durable memory before core-side approval.

To bring file or shell operations under STM, register an MCP server that exposes them and steer the agent toward the proxied alias instead of the built-in. This is the same boundary every MCP proxy lives within—not one specific to STM.

Project-scoped MCPs (mms project + mms import)

A separate registry lets a project select which MCP definitions it wants to expose. ~/.mms/registry.toml and project .mms/project.toml files are deliberately independent of STM's ~/.memtomem/stm_proxy.json. Importing a definition does not automatically route it through the proxy. See Project-Scoped MCP Management.

Tutorial notebooks

Try it without wiring into your AI client first. A quickstart Jupyter notebook registers an upstream MCP server, calls a proxied tool, and reads stm_proxy_stats end-to-end. Clone the repo, uv sync, and uv run jupyter lab notebooks/ — no external services needed.

Documentation

Guide	Topic
Getting started	Install → register → doctor → first proxied tool
Operations	Diagnose setup, upstreams, surfacing, and hooks
Native hooks	Host capabilities, installation, daemon, and metrics
Surfacing	How agents recall prior context automatically
Compression	All 10 strategies — pick the right one for your content
Caching	Skip repeated work with response caching
Configuration	Configuration sources and reference map
Selection telemetry	Opt-in JSONL log of tool selection + execution outcomes
Use cases	Reproducible scenarios and honest measurement boundaries
CLI	Command-family and MCP-tool reference map

STM advertises four model-facing MCP tools by default. Eight observability and admin tools (stm_proxy_stats, stm_surfacing_stats, etc.) are hidden unless MEMTOMEM_STM_ADVERTISE_OBSERVABILITY_TOOLS=true is set, which keeps eager-loading clients from paying schema tokens for rarely used operator tools.

Compatibility & deprecation policy

memtomem-stm is alpha (0.x): behavior and defaults may change between minor releases while the design settles — defaults have flipped before (e.g. injection_mode prepend → append in 0.1.24). Every such change is flagged inline in CHANGELOG.md with a **Behavior change**: marker and — for releases after 0.1.31 — is also summarized up front in that release's Upgrade notes block; skim that block before upgrading (older releases record behavior changes inline only). Machine-readable surfaces (--json output shapes, exit codes) only change with an Upgrade notes entry; additive keys may appear at any time, so parse by key, not by shape equality. Deprecated CLI commands or flags keep working with a warning for at least one minor release before removal.

Development

uv sync                                                    # install dev deps
uv run pytest -m "not bench_qa_meta and not bench_qa_llm_judge and not bench_qa_sweep and not bench_qa_drift and not bench_qa_perf"   # tests (CI filter)
uv run ruff check src && uv run ruff format --check src    # lint (required)
uv run mypy src                                            # typecheck (required)

CI runs the same commands on every PR via .github/workflows/ci.yml. Lint (ruff check + ruff format --check), mypy, and tests must pass.

License

Apache License 2.0. Contributions are accepted under the terms of the Contributor License Agreement.