MARM Systems

The Problem

LLM‑driven agents lose context as soon as a request finishes, forcing developers to rebuild conversation state manually. In production‑grade tooling this results in duplicated logs, missed hand‑offs, and fragile orchestration across multiple models.

What This Does

MARM‑Systems ships a Universal MCP Server that stores prompts, responses, and notebook entries in a persistent SQLite layer (marm-mcp-server/core/memory.py). The server exposes the same API over HTTP, STDIO, and WebSocket, letting any compliant agent read or write the shared memory store.

Key modules:

• core/memory.py – connection pool, get_connection, store_memory, recall_similar.
• core/response_limiter.py – caps token usage (estimate_response_size, limit_memory_response).
• endpoints/websocket_handlers_complete.py – concrete handlers (handle_smart_recall, handle_start, handle_log_entry).
• server.py (root) – boots the FastAPI app, registers routes, and starts the event loop.

The duplicated marm_mcp_server/ package mirrors the root package, providing an alternate import path for downstream projects.

How It Is Wired

Execution begins at python marm-mcp-server/server.py (or python -m marm_mcp_server.server). The module’s main routine creates the FastAPI app, registers the endpoint modules, and calls lifespan (defined in marm_mcp_server/server.py line 104).

lifespan → track_usage (writes usage stats to the SQLite DB via core/memory.py::get_connection) → launches the HTTP/WebSocket listeners.

All request handling funnels through a small set of hot‑spot functions:

External effects are limited to three short paths identified by the static analysis:

• Network – main → check_server_health performs a requests.get.
• Database – lifespan → track_usage opens a SQLite connection.
• Shell – publish_to_mcp.py → install_mcp_publisher runs an external installer script.

The import graph is shallow (only two import edges) and contains no circular dependencies, making the codebase easy to navigate. The most connected modules (marm-mcp-server/server.py and its counterpart in marm_mcp_server) have an instability of 0, indicating low risk of cascade failures when they are modified.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/MARM-Systems
cd MARM-Systems/marm-mcp-server

# Install Python deps (no lockfile – see health section)
pip install -r requirements.txt

# Run directly (development)
python server.py   # starts HTTP + WebSocket on default ports

# Or build/run the official container
docker build -t marm-mcp-server .
docker compose up -d   # uses marm-mcp-server/docker-compose.yml

Configuration lives in marm-mcp-server/config/settings.py (e.g., DB path, rate‑limit values). Environment variables are not required for a basic run; the defaults create a local marm.db file.

Real‑World Use

A downstream AI service can connect via WebSocket (ws://localhost:8000/ws) and issue JSON messages like:

{
  "type": "log_entry",
  "session_id": "abc123",
  "content": "User asked about pricing."
}

The server stores the entry in SQLite, updates the session state, and pushes the same payload to any other connected agents, enabling instant cross‑model recall.

Code Health & Issues

• HIGH – Pin GitHub Actions to commit SHAs (.github/workflows/*).
• HIGH – Add a lockfile for pyproject.toml (poetry.lock/requirements.txt).
• MEDIUM – Enable Dependabot or Renovate for automated updates.
• MEDIUM – Pin Docker base image by digest (Dockerfile).
• MEDIUM – Add a dependency‑vulnerability scan step in CI.
• MEDIUM – Set persist-credentials: false on checkout steps.
• LOW – Define timeout-minutes on workflow jobs.

Additional observations: tests are present (marm-mcp-server/tests/), CI runs via GitHub Actions, and a LICENSE file exists. No secrets are committed, but the lack of a lockfile makes reproducible builds unreliable.

The Bottom Line

MARM‑Systems delivers a functional, multi‑protocol memory server with a clear separation of concerns and modest external dependencies. The codebase is small enough to grasp quickly, but high‑impact functions (get_connection, send_personal_message) and duplicated package trees increase maintenance cost. Adding a lockfile, pinning external resources, and reducing deep nesting will make it production‑ready for teams that need shared, persistent LLM context.