Junto Memory

MCP Shared Memory Server (junto-memory)

[](https://github.com/tlemmons/junto-memory/actions/workflows/ci.yml) [](https://opensource.org/licenses/MIT)

> The memory component of the Junto multi-agent coordination system. For a working stack with docker-compose + adopter walkthrough, start at junto-stack.

A shared memory and coordination server for multiple AI coding agents, built on the Model Context Protocol (MCP).

When you run multiple AI agents on the same codebase, three things break fast:

1. They forget everything between sessions. Agent parks, knowledge dies. The next agent re-reads the same code, re-discovers the same bugs, re-learns the same gotchas.
2. They step on each other. Two agents modify the same file. Nobody knows what anyone else is doing or has locked.
3. They get dumber as sessions get long. Research calls this "context rot" — model performance degrades as the context window fills up, even well below capacity. Longer sessions don't mean better work.

This server fixes all three. It gives your agents a shared brain that persists across sessions, coordinates work across agents, and lets them record what they learn so the next agent starts where the last one left off.

Battle-tested. This has been running in production coordinating 6 specialized agents across 500+ sessions on a commercial IoT platform — C#/.NET server, Python on Raspberry Pi, .NET MAUI mobile, MQTT, Redis, the works. The problems it solves were discovered the hard way.

---

What It Does

• Persistent knowledge base -- Store architecture docs, learnings, gotchas, and code snippets that survive across sessions and are searchable via vector similarity (ChromaDB).
• Multi-agent coordination -- File locking, inter-agent messaging, heartbeat monitoring, and overlap detection so multiple AI agents can work on the same codebase without stepping on each other.
• Task and backlog management -- Track work items, assign tasks to agents, manage checklists, and hand off context between sessions.
• Function registry with auto-enrichment -- Register functions once, and a librarian daemon analyzes the source code to add signatures, gotchas, and semantic search summaries.

---

How It Compares

There are 370+ MCP memory servers listed on PulseMCP. Most give a single agent persistent memory. This server is built for teams of agents working together on the same project over weeks and months.

| Capability | Typical MCP Memory Server | This Server | |---|---|---| | Persistent storage | Yes | Yes — MongoDB + ChromaDB vector search | | Multi-agent session tracking | No | Yes — Agent registry, heartbeat, overlap detection | | Cross-agent messaging | No | Yes — Send/receive messages with threading and status tracking | | Function registry | No | Yes — Register once, librarian daemon auto-enriches with code analysis | | Task backlog | No | Yes — Create tasks, assign to agents, track status and priority | | Versioned specs & contracts | No | Yes — Owner enforcement, semver history | | File locking | No | Yes — Atomic locks with stale detection, auto-release on session end | | Behavioral guidelines | No | Yes — Set rules once, every agent on every machine receives them | | Staleness management | No | Yes — Age warnings, supersede, archive, bulk cleanup by tag | | Librarian mode | No | Yes — Agents analyze source code and enrich the knowledge base | | External database access | No | Yes — Read-only SQL queries (MSSQL, MySQL) against your project databases | | Checklists | No | Yes — Shared launch readiness, deploy steps, etc. |

40 tools across 14 categories. Not a toy — a coordination system.

---

Works for Solo Agents Too

You don't need multiple agents to benefit from this server. A single Claude Code or Cursor instance gets:

• Persistent memory across sessions — your agent remembers what it learned yesterday
• Function registry — the agent doesn't re-read code it already analyzed
• Learnings — gotchas, workarounds, and non-obvious behaviors survive session restarts
• Librarian enrichment — your codebase gets indexed and searchable over time
• Backlog — track what's done and what's next between sessions
• State specs — resume exactly where you left off

The coordination features (messaging, file locks, multi-agent awareness) just sit there unused. They don't hurt anything — they're tools your agent doesn't call until you scale up.

Start with one agent. The multi-agent features are there when you're ready — they don't get in the way until you need them.

---

Architecture

graph LR
    A1[Claude Code] -->|MCP/HTTP| S[MCP Shared Memory Server]
    A2[Cursor] -->|MCP/HTTP| S
    A3[Other MCP Client] -->|MCP/HTTP| S
    S -->|Vector search| C[(ChromaDB)]
    S -->|Documents & state| M[(MongoDB)]
    S -.->|Optional| E[(External DBs)]

The server runs as a single Docker Compose stack. AI agents connect over MCP (streamable HTTP transport on port 8080). All knowledge, messages, and coordination state are persisted across restarts in MongoDB and ChromaDB volumes.

---

Install — Hand It to Your AI

This server is designed for AI coding agents, so the install procedure is too. Clone the repo, then ask your agent to install it for you:

git clone https://github.com/tlemmons/mcp-shared-memory.git
cd mcp-shared-memory
# Now hand the prompt below to your AI agent in a fresh session.

Copy this prompt to a fresh Claude Code (or Cursor, or any MCP-capable agent) session in the cloned directory:

> Install the MCP Shared Memory Server in this repository for me. Read AGENT_INSTALL.md and follow it step by step. Use the root-level docker-compose.yml. Stop and confirm with me before any destructive operation, before any change that needs a real value (passwords, API keys, port choices), and before enabling auth. When the install is done, run the smoke test described in the doc and report all six done-when results back to me.

The agent walks through prerequisites, env-file configuration, container start, health check, and MCP-client config — pausing at the right places to ask you for decisions (passwords, ports, auth on/off).

Why this way? The install has accumulated enough operational gotchas — Chroma volume mount path, Mongo init credentials, the auth env-var with soft-fallback, the difference between localhost and remote-host trust models — that a 6-line quickstart misleads more often than it helps. AGENT_INSTALL.md is dense, branchy, and tested against the actual current code; an agent reads and executes it in a few minutes. If you don't trust an AI agent to run the install, this server is probably not for you — its whole purpose is to coordinate fleets of AI agents working on real codebases.

Manual install: AGENT_INSTALL.md is human-readable too. It's denser than typical README prose, but follow it the same way and the install works.

After install, MongoDB listens on localhost:27019, ChromaDB on localhost:8001, and the MCP server on localhost:8080.

Your First Session

Once connected, your agent's first interaction looks like this:

Agent: memory_start_session(project="my-app", claude_instance="main")
→ Returns: session ID, any prior learnings, active work, handoff notes

Agent: memory_record_learning(
    session_id="...",
    topic="postgres connection pooling",
    content="PgBouncer silently drops connections after 5 min idle.
             Must set keepalive_idle=60 in connection string or
             requests fail with 'server closed the connection unexpectedly'."
)
→ Stored. Next session, memory_start_session returns this automatically.

Agent: memory_register_function(
    session_id="...",
    name="retry_with_backoff",
    file_path="src/utils/resilience.py:42",
    purpose="Retry async calls with exponential backoff and jitter",
    gotchas="Max 5 retries. Raises RetryExhausted, not the original exception."
)
→ Registered. Any future agent asking "how do we handle retries?"
  finds this via memory_find_function.

Three calls. Your agent now has persistent memory, and every future session starts with context instead of a blank slate.

---

Connecting Your AI

Claude Code

Add to ~/.claude.json (or your project's .mcp.json):

{
  "mcpServers": {
    "shared-memory": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

> Note on transport naming: the underlying MCP protocol is "streamable HTTP", but the value in the JSON config file is "http" for Claude Code 2.x. Using "streamable-http" in the config triggers a schema validation error.

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "shared-memory": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Any MCP-Compatible Client

Point your client to the MCP endpoint:

URL:       http://localhost:8080/mcp
Transport: Streamable HTTP (stateless)

Stdio transport is also supported for clients that prefer it. Pass --transport stdio when starting the server:

# From the project root:
python server.py --transport stdio

# Or as a module (from the src/ directory):
python -m shared_memory --transport stdio

Example MCP client config for stdio mode:

{
  "mcpServers": {
    "shared-memory": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "shared_memory", "--transport", "stdio"],
      "cwd": "/path/to/mcp-shared-memory/src"
    }
  }
}

No API keys or authentication tokens are required for local use (see [Security](#security) for remote deployments).

---

Tool Reference

48 tools organized into 14 categories. (For the canonical, current list with grouping and end-to-end flows, see the architecture spec inside the server: memory_get_spec(name="architecture:shared-memory-v1", project="shared_memory").)

Session Management (2)

| Tool | Description | |------|-------------| | memory_start_session | Register a session and receive context: recent learnings, active agents, file locks, pending signals. Call this first. | | memory_end_session | Record a summary, files modified, and handoff notes. Releases all locks. Call this when done. |

Knowledge Base (4)

| Tool | Description | |------|-------------| | memory_query | Search the knowledge base by natural language. Returns relevant docs with relevance scores. | | memory_get_by_id | Retrieve a specific document by its exact ID. | | memory_store | Store a new document (architecture, API spec, code snippet, interface contract, etc.). | | memory_record_learning | Quick shortcut to record a learning, gotcha, or technique for other agents. |

Search and Discovery (2)

| Tool | Description | |------|-------------| | memory_search_global | Search across all projects and shared collections at once. | | memory_list_projects | List all projects with document counts. No session required. |

File Locking (3)

| Tool | Description | |------|-------------| | memory_lock_files | Atomically lock files for exclusive editing. Supports directory locks. Auto-releases on session end. | | memory_unlock_files | Release specific file locks or all locks held by your session. | | memory_get_locks | View current file locks with stale detection (inactive > 30 min). |

Backlog Management (4)

| Tool | Description | |------|-------------| | memory_add_backlog_item | Add a task, feature request, or tech debt item to the backlog. | | memory_list_backlog | List backlog items with filters: project, status, priority, assignee, milestone. | | memory_update_backlog_item | Update a backlog item's status, priority, assignee, or description. | | memory_complete_backlog_item | Mark a backlog item as done or won't-do, with optional resolution notes. |

Inter-Agent Messaging (7)

| Tool | Description | |------|-------------| | memory_send_message | Send a message to another agent. Supports categories (task, question, blocker, etc.) and threading. | | memory_get_messages | Get pending messages for your agent. Scoped by project. | | memory_acknowledge_message | Mark a message as received (shortcut for status update). | | memory_update_message_status | Track message lifecycle: pending, delivered, received, completed, failed. | | memory_heartbeat | Send a heartbeat with your current status (idle, busy, error). Enables stale detection. | | memory_get_agent_status | Get heartbeat status of agents. Flags agents stale after 5 minutes. | | memory_list_agents | Discover registered agents across projects with roles and last activity. |

Function Registry (5)

| Tool | Description | |------|-------------| | memory_register_function | Register a function reference with name, file, purpose, and optional gotchas. Triggers librarian enrichment. | | memory_find_function | Search for functions by purpose or name. Check before implementing to avoid duplication. | | memory_enrich_function | Add deep analysis to a function ref: signature, parameters, side effects, complexity. For librarian use. | | memory_get_enrichment_queue | View functions awaiting librarian enrichment. | | memory_become_librarian | Get a prompt and unenriched functions to run local enrichment on your machine. |

Spec Management (3)

| Tool | Description | |------|-------------| | memory_define_spec | Create or update a versioned spec with owner-only enforcement. Supports semver and history. | | memory_get_spec | Retrieve a spec by name, optionally at a specific historical version. | | memory_list_specs | List all specs with optional version history and type filtering. |

Project Registry (1 CRUD tool)

| Tool | Description | |------|-------------| | memory_project | Manage projects and agents. Actions: create, get, list, delete, add_agent, remove_agent, update_agent. |

Checklists (1 CRUD tool)

| Tool | Description | |------|-------------| | memory_checklist | Shared checklists for launch readiness, deploy steps, etc. Actions: create, get, add, check, delete, list. |

External Database Queries (1 CRUD tool)

| Tool | Description | |------|-------------| | memory_db | Read-only queries against registered external databases. Actions: list, schema, query. SQL injection protection built in. |

Server-Managed Guidelines (1)

| Tool | Description | |------|-------------| | memory_guidelines | Manage behavioral rules that all agents receive at session start. Actions: list, set, delete, get. Update once, every agent on every machine picks it up. |

Admin (1 CRUD tool)

| Tool | Description | |------|-------------| | memory_admin | Manage API keys and view audit logs. Actions: create_key, revoke_key, list_keys, audit_log, auth_status. Requires owner role when auth is enabled. |

Document Lifecycle (4)

| Tool | Description | |------|-------------| | memory_update_work | Update your current work status and files touched. Enables overlap detection and dependency signaling. | | memory_change_status | Change a document's status: active, deprecated, superseded, archived. Preserves history. | | memory_archive_by_tag | Bulk archive all documents matching a tag (e.g., end-of-version cleanup). | | memory_restore_by_tag | Bulk restore previously archived documents by tag. |

---

Configuration

All configuration is via environment variables. See .env.example for the complete reference.

Required Variables

| Variable | Default | Description | |----------|---------|-------------| | MONGO_PASSWORD | changeme | MongoDB root password. Change this. | | MONGO_USER | mcp_orch | MongoDB username. | | MONGO_DB | mcp_orchestrator | MongoDB database name. | | MONGO_HOST | localhost | MongoDB host (set automatically in Docke

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tlemmons
• Source: tlemmons/junto-memory
• License: MIT

Install and usage instructions live in the source repository linked above.