Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion .github/workflows/publish-mcp.yml
Original file line number Diff line number Diff line change
Expand Up @@ -217,5 +217,4 @@ jobs:
echo "MARM MCP Server published successfully!"
echo "PyPI: https://pypi.org/project/marm-mcp-server/"
echo "Docker MCP: https://hub.docker.com/r/lyellr88/marm-mcp-server"
echo "Dashboard: bundled in lyellr88/marm-mcp-server at /dashboard"
echo "MCP Registry: https://registry.modelcontextprotocol.io/servers/io.github.Lyellr88/marm-mcp-server"
10 changes: 8 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
## Version 2 - MARM Protocol to Universal MCP Server Evolution

<details>
<summary><strong>Unreleased: SQLite Write Atomicity Hardening (v2.22.1)</strong></summary>
<summary><strong>Unreleased: SQLite Write Atomicity Hardening (v2.23.0)</strong></summary>

### Multi-Statement Writes Are Now Real Transactions

Expand All @@ -16,11 +16,17 @@
### MARM Console Memory Tab Reaches Dashboard Parity

- Filled the remaining Memory workspace gaps from the legacy `marm-dashboard`: Console can now create sessions, delete one session, delete all sessions, delete individual log rows, bulk-delete logs, add/delete notebook entries, and stage/apply/discard compaction candidates from the same Memory tab surface.
- The new Console routes call existing MARM MCP tool paths for mutations instead of writing directly to SQLite, preserving the queue-backed memory write rules and transport behavior while the old dashboard remains available for reference.
- The new Console routes call existing MARM MCP tool paths for mutations instead of writing directly to SQLite, preserving the queue-backed memory write rules and transport behavior.
- Added visible success/error feedback for session, log, notebook, and compaction actions so failed queue/MCP operations no longer disappear silently in the UI.
- Notebook add/delete now preserves optional `project`/`platform` scope across Console and the existing MCP tool paths, so same-name notebook entries in different scopes are not collapsed by UI mutations.
- Added FastAPI response-contract tests for the new Console Memory routes with the MCP adapter stubbed, matching the rule that every new Console API route gets at least one real response-layer test.

### Legacy Dashboard Removed From MCP Server Runtime

- Removed the bundled `marm_dashboard` package from the shipped `marm-mcp-server` package and Docker image. The old source is archived locally under `docs/archived/` for reference while marm-console becomes the human-facing local app.
- Unmounted `/dashboard` from the FastAPI app and removed the parent-server auth exemption that existed only for that mounted sub-app. `/dashboard` is now an ordinary missing route.
- Removed dashboard-specific tests and replaced the HTTP app coverage with assertions that the route is no longer mounted or public. Maintenance scripts now scan only shipped packages and marm-console.

</details>

<details>
Expand Down
6 changes: 2 additions & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

You do not need to write code to contribute. Testing MARM with your client setup, reporting what broke, sharing your workflow in [Discussions](https://github.com/Lyellr88/marm-memory/discussions), or jumping into [Discord](https://discord.gg/nhyJWPz2cf) to help someone get unstuck are all real contributions.

If you do want to go deeper, MARM is focused on the MCP server, local memory workflows, the code and concept knowledge graphs, Docker/STDIO transports, IDE and client integrations, and the dashboard for inspecting local memory data. This guide covers that practical development workflow. For project history and community recognition, see [ACKNOWLEDGMENTS.md](docs/ACKNOWLEDGMENTS.md).
If you do want to go deeper, MARM is focused on the MCP server, local memory workflows, the code and concept knowledge graphs, Docker/STDIO transports, IDE and client integrations, and marm-console for inspecting local memory data. This guide covers that practical development workflow. For project history and community recognition, see [ACKNOWLEDGMENTS.md](docs/ACKNOWLEDGMENTS.md).

## Questions or Ideas

Expand Down Expand Up @@ -72,7 +72,6 @@ marm-mcp-server/
concept_extraction.py # spaCy entity/relationship extraction (optional extra)
graph_supervisor.py # Lazy singleton supervisor for the embedded graph engine
graph_client.py # Concept graph's in-process link into the code graph
dashboard_mount.py # Mounts the bundled dashboard under /dashboard
protocol_delivery_state.py # Bounded HTTP protocol-delivery state
models.py # Shared Pydantic request/response models
events.py # Internal event hooks
Expand Down Expand Up @@ -115,7 +114,7 @@ marm-mcp-server/
marm_graph/ # Embedded marm-graph wrapper: subprocess JSON-RPC client,
# tool router, and backend verification for the pinned
# codebase-memory-mcp binary
marm_dashboard/ # Bundled dashboard web UI
marm_dashboard/ # Archived dashboard UI, superseded by marm-console
tests/ # MCP server test suite
Dockerfile # One image, HTTP default, STDIO override
pyproject.toml # Package metadata and console scripts
Expand Down Expand Up @@ -299,7 +298,6 @@ The `v*` tag triggers the publish workflow for:

- PyPI package publish
- MCP server Docker image
- Dashboard Docker image
- MCP Registry publish

Use normal branch pushes for review. Use tag pushes only for intentional releases.
Expand Down
46 changes: 7 additions & 39 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
width="900"
height="250">
</picture>
<h1 align="center">MARM: Local-First Persistent Multi-Agent Memory Layer for MCP Clients v2.22.1</h1>
<h1 align="center">MARM: Local-First Persistent Multi-Agent Memory Layer for MCP Clients v2.23.0</h1>

[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/Lyellr88/marm-memory/blob/MARM-main/LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
Expand All @@ -26,7 +26,7 @@

## Important Messages

- marm-console now ships as the local web app successor to marm-dashboard, with live Memory, Knowledge, and Projects workspaces plus MCP-backed Memory mutation actions. Packaging and one-command startup polish are still in progress.
- marm-console now ships as the local web app for memory, knowledge, projects, and MCP-backed memory mutation actions. Packaging and one-command startup polish are still in progress.
- I am waiting to get access back to my PYPI account, till restored pip will be behind a few versions. I will update the README when it is back up to date.


Expand All @@ -39,7 +39,6 @@
- [Using MARM: Talk, Don't Call Tools](#using-marm-talk-dont-call-tools)
- [Understanding MARM Memory](#understanding-marm-memory)
- [Knowledge Graphs: Code & Concepts](#knowledge-graphs-code--concepts)
- [MARM Dashboard](#marm-dashboard)
- [Architecture & Internals](#architecture--internals)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
Expand Down Expand Up @@ -77,7 +76,7 @@ See [Performance & Scaling Benchmarks](#performance--scaling-benchmarks) for ret

**Recommended: guided setup with `marm-init`**

The easiest way to install MARM is to let your agent do the setup with you. `marm-init` turns the usual MCP setup mess into one guided conversation: Python or Docker, HTTP or STDIO, local or remote server, API keys, config paths, dashboard startup, and multi-agent linking for Claude, Codex, Gemini, Qwen, Cursor, VS Code, and other MCP clients. No hunting through install docs, no guessing which config file your client uses, and no rewriting the same connection by hand for every agent.
The easiest way to install MARM is to let your agent do the setup with you. `marm-init` turns the usual MCP setup mess into one guided conversation: Python or Docker, HTTP or STDIO, local or remote server, API keys, config paths, server startup, and multi-agent linking for Claude, Codex, Gemini, Qwen, Cursor, VS Code, and other MCP clients. No hunting through install docs, no guessing which config file your client uses, and no rewriting the same connection by hand for every agent.

```bash
npx degit Lyellr88/marm-memory/skills
Expand Down Expand Up @@ -521,7 +520,7 @@ Full platform walkthroughs, key setup, and OS-specific notes: [Windows](docs/INS

**Verify installation**

Use the MARM Dashboard status panel for the easiest live check. It polls the MCP server health endpoint and shows reachability, version, status, latency, and last checked time. For terminal validation:
Use the MCP server health endpoint for the fastest live check:

```bash
curl http://localhost:8001/health
Expand Down Expand Up @@ -759,37 +758,6 @@ How to use it:

This fills the cross-session structure gap that flat memory search leaves open: sessions organize memories, but the concept graph *connects* them, so "what depends on the write queue?" is answerable even when the answer spans five sessions from three different agents.

## MARM Dashboard

A local web UI for browsing and managing your MARM memory. It is bundled with `marm-mcp-server` and mounts at `/dashboard` when the HTTP server starts.

| What it gives you | How it works |
|-------------------|-------------|
| Browse/search/edit all memories | Direct SQLite access to the same `~/.marm/marm_memory.db` |
| Manage sessions and protocol logs | Open `http://localhost:8001/dashboard` beside the MCP endpoint on `:8001` |
| Notebook CRUD with inline editor | Same `MARM_API_KEY` auth model as the MCP server |
| Delete-all with count confirmation | Included in the unified pip package and Docker image |
| View the write queue in real time | Pulls live data from the write queue |
| Live server health panel | Polls the health endpoint: reachability, version, latency, last checked |

Start MARM HTTP, then open the dashboard:

```bash
python -m marm_mcp_server
# browser: http://localhost:8001/dashboard
```

Docker uses the same unified image and key:

```bash
docker run -d --name marm-mcp-server \
-p 127.0.0.1:8001:8001 \
-e MARM_API_KEY=your-key \
-v ~/.marm:/home/marm/.marm \
lyellr88/marm-mcp-server:latest
# browser: http://localhost:8001/dashboard
```

## Architecture & Internals

Everything above runs on a small number of deliberate mechanisms. This section is the full map, so you (or your agent) never have to guess what the server is doing.
Expand Down Expand Up @@ -905,14 +873,14 @@ Packaged docs are indexed into the `marm_system` memory namespace on startup and

**AI client can't connect to MARM**

- Verify server is running in the dashboard health panel, or with `curl http://localhost:8001/health`
- Verify the server is running with `curl http://localhost:8001/health`
- Check firewall isn't blocking port 8001
- For STDIO: use `marm-mcp-stdio` (console script) or `python -m marm_mcp_server.server_stdio`
- Restart both server and AI client

**Tools not appearing in AI client**

- Verify HTTP mode in the dashboard health panel, or with `curl http://localhost:8001/health`
- Verify HTTP mode with `curl http://localhost:8001/health`
- Check server logs for initialization errors
- Disconnect and reconnect AI client to refresh tool list
- Both HTTP and STDIO expose 14 tools: 7 core memory/logging/notebook/compaction tools, 5 bundled code-graph tools, and 2 concept-graph tools
Expand All @@ -939,7 +907,7 @@ Packaged docs are indexed into the `marm_system` memory namespace on startup and
- Verify `~/.marm/` directory exists and has write permissions
- Check available disk space
- Test with simple memory: ask AI to save a single line and check with `marm_log_show`
- For HTTP mode, verify server health in the dashboard health panel, or with `curl http://localhost:8001/health`
- For HTTP mode, verify server health with `curl http://localhost:8001/health`

**Search returns no results**

Expand Down
2 changes: 1 addition & 1 deletion docs/ACKNOWLEDGMENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

MARM has been shaped by early users, testers, reviewers, and open-source contributors who gave feedback when the project was still rough. This page recognizes that help and keeps a record of the community influence behind the project.

This project started as a personal answer to a simple problem: AI tools forget too much between sessions. The project is now focused on the MARM MCP server, local memory workflows, Docker and STDIO transports, IDE/client integrations, and the dashboard for inspecting local memory data.
This project started as a personal answer to a simple problem: AI tools forget too much between sessions. The project is now focused on the MARM MCP server, local memory workflows, Docker and STDIO transports, IDE/client integrations, and marm-console for inspecting local memory data.

## What This Page Is For

Expand Down
4 changes: 2 additions & 2 deletions docs/FAQ.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ marm-memory is a persistent memory layer for AI agents. The MCP server gives Cla
|-----------|-------------|----------|
| **MARM MCP Server** | Persistent memory server with 14 MCP tools (HTTP + STDIO): 7 core memory tools, 5 bundled code-graph tools, and 2 concept-graph tools | AI agents, IDEs, local workflows, shared team memory |
| **MARM Protocol** | Runtime guidance delivered automatically by the MCP server | Keeping agents aligned on what to store, recall, and trust |
| **MARM Dashboard** | Local browser UI for viewing memory and server health | Inspection, cleanup, and quick status checks |
| **MARM Console** | Local browser UI for viewing memory, knowledge, projects, and server health | Inspection, cleanup, and quick status checks |

### Q: How is MARM different from built-in AI memory?

Expand Down Expand Up @@ -71,7 +71,7 @@ Docker HTTP mode should use `MARM_API_KEY` because the server is listening throu

#### Q: How do I know if MARM is working correctly?

For HTTP mode, use the MARM Dashboard status panel or run `curl http://localhost:8001/health`. For STDIO mode, confirm your MCP client lists the MARM tools and can call a simple recall or log command.
For HTTP mode, run `curl http://localhost:8001/health` or use MARM Console when it is running locally. For STDIO mode, confirm your MCP client lists the MARM tools and can call a simple recall or log command.

---

Expand Down
2 changes: 1 addition & 1 deletion docs/INSTALL-DOCKER.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Universal Memory Intelligence Platform for AI Agents

**MARM v2.22.1** - Memory Accurate Response Mode
**MARM v2.23.0** - Memory Accurate Response Mode
*Docker deployment guide for Windows, Mac, and Linux*

---
Expand Down
4 changes: 2 additions & 2 deletions docs/INSTALL-LINUX.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Universal Memory Intelligence Platform for AI Agents

**MARM v2.22.1** - Memory Accurate Response Mode
**MARM v2.23.0** - Memory Accurate Response Mode
*Complete Linux installation guide*

---
Expand Down Expand Up @@ -320,7 +320,7 @@ curl -s http://localhost:8001/health
{
"status": "healthy",
"service": "MARM MCP Server",
"version": "2.22.1",
"version": "2.23.0",
"timestamp": "2026-01-01T00:00:00+00:00",
"database": "connected",
"semantic_search": "available"
Expand Down
2 changes: 1 addition & 1 deletion docs/INSTALL-PLATFORMS.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# MARM v2.22.1 MCP Server - Platform Integration Guide
# MARM v2.23.0 MCP Server - Platform Integration Guide

## Table of Contents

Expand Down
4 changes: 2 additions & 2 deletions docs/INSTALL-WINDOWS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Universal Memory Intelligence Platform for AI Agents

**MARM v2.22.1** - Memory Accurate Response Mode
**MARM v2.23.0** - Memory Accurate Response Mode
*Complete Windows installation guide*

---
Expand Down Expand Up @@ -293,7 +293,7 @@ Invoke-WebRequest -Uri http://localhost:8001/health
{
"status": "healthy",
"service": "MARM MCP Server",
"version": "2.22.1",
"version": "2.23.0",
"timestamp": "2026-01-01T00:00:00+00:00",
"database": "connected",
"semantic_search": "available"
Expand Down
30 changes: 15 additions & 15 deletions docs/ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@ MARM is focused on one clear goal: make AI memory practical across real tools, r
The active product direction has two tracks:

- **MARM MCP Server**: the agent-facing memory layer used by Claude, Codex, Gemini, Qwen, VS Code, Cursor, and other MCP clients.
- **MARM Dashboard**: the human-facing local admin UI for inspecting, editing, exporting, and maintaining the same memory database.
- **MARM Console**: the human-facing local admin UI for inspecting, editing, exporting, and maintaining the same memory database.

MARM is not currently being built as a paid upgrade product. The near-term focus is a strong open base: reliable local memory, clean transports, useful dashboard workflows, and future extension points for plugins, SDKs, research, and team workflows.
MARM is not currently being built as a paid upgrade product. The near-term focus is a strong open base: reliable local memory, clean transports, useful console workflows, and future extension points for plugins, SDKs, research, and team workflows.

---

Expand All @@ -25,7 +25,7 @@ MARM now has the core pieces needed for a serious local memory system:
- **Docker support** with HTTP and STDIO modes from one image
- **API-key auth** for Docker, exposed, or shared HTTP deployments
- **VS Code and Cursor support** through native MCP config files
- **MARM Dashboard** as an optional local SQLite admin UI for human memory management
- **MARM Console** as an optional local admin UI for human memory management
- **Fresh test suite** covering HTTP tools, auth, rate limits, response limits, database behavior, STDIO, and Docker smoke paths
- **Automation scripts** for version sync, test runs, stale-doc scans, Docker smoke, and release preflight

Expand Down Expand Up @@ -57,7 +57,7 @@ Planned direction:
- Track lightweight usage signals such as recalled, edited, deleted, reused, or ignored memories
- Improve ranking over time using recency, frequency, session/project relevance, and user cleanup behavior
- Identify related memories across sessions so solutions, decisions, and patterns are easier to rediscover
- Add stale-memory indicators so users can clean old or low-value entries from the dashboard
- Add stale-memory indicators so users can clean old or low-value entries from marm-console

Why it matters:

Expand Down Expand Up @@ -114,11 +114,11 @@ Fewer, clearer tools improve client discovery, reduce token overhead, and make a

---

## Dashboard Roadmap
## Console Roadmap

### 1. Export and Reporting

The dashboard is the natural place for human-friendly memory export.
marm-console is the natural place for human-friendly memory export.

Planned direction:

Expand All @@ -134,7 +134,7 @@ Memory should be portable. Users need backups, reports, and ways to move MARM kn

### 2. Safer Admin Workflows

The dashboard already asks before destructive actions. The next step is making high-impact edits even safer and easier to inspect.
marm-console already asks before destructive actions. The next step is making high-impact edits even safer and easier to inspect.

Planned direction:

Expand All @@ -147,22 +147,22 @@ Planned direction:

Why it matters:

The dashboard can edit real memory. It should feel efficient, but not casual about destructive changes.
marm-console can edit real memory. It should feel efficient, but not casual about destructive changes.

### 3. Dashboard and MCP Schema Alignment
### 3. Console and MCP Schema Alignment

The dashboard writes directly to SQLite, so it must stay aligned with MCP schema changes.
marm-console uses MCP-backed mutation paths and local read APIs, so it must stay aligned with MCP schema changes.

Planned direction:

- Add tests for dashboard compatibility with current MCP tables
- Keep dashboard CRUD behavior aligned with MCP sanitization and metadata conventions
- Add tests for console compatibility with current MCP tables
- Keep console CRUD behavior aligned with MCP sanitization and metadata conventions
- Surface MCP server reachability and database state clearly
- Avoid adding dashboard-only fields unless the MCP server also understands them
- Avoid adding console-only fields unless the MCP server also understands them

Why it matters:

The dashboard is useful because it manages the same data. Schema drift would make it dangerous.
marm-console is useful because it manages the same data. Schema drift would make it dangerous.

---

Expand All @@ -181,7 +181,7 @@ These are not product features, but they keep both tracks trustworthy.

## Long-Term Possibilities

These are conditional directions after the MCP server and dashboard are stable:
These are conditional directions after the MCP server and marm-console are stable:

- **Plugin integrations** for editors, local tools, and MCP client ecosystems
- **SDKs** for developers who want MARM-backed memory in their own apps
Expand Down
Loading
Loading