MCP Shared Memory Server (junto-memory)

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).

📋 Running a server already? See CHANGELOG.md for release notes — the current release (1.39.0) changes how global guidelines are seeded and generalizes the execute-don't-ask default; each has an upgrade note.

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. Eventually every agent has to hand off; without a shared brain that handoff throws away everything it learned.

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.

• Local-model delegation -- Agents hand routine text work (classify, extract, summarise, watch a mailbox) to a model running on your own hardware via Ollama, on a schedule or once, with results routed back to agents. Saves cloud-agent usage for work that doesn't need it. See Local-Model Delegation.

• Admin web UI -- /admin on the server: settings, agents and their context fill, alerts, local tasks and runs, connections, and a change log. See Admin Web UI.

Related MCP server: Claude Team MCP

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.

63 tools across 23 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/junto-memory.git
cd junto-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.

Doing it by hand anyway? AGENT_INSTALL.md is legible to a person and the install works if you follow it carefully — but it's written for an agent to execute, so it's dense, branchy, and light on the hand-holding a human tutorial would give. The agent-driven path above is the supported one.

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 for remote deployments).

Tool Reference

63 tools organized into 23 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="junto").)

Session Management (2)

Knowledge Base (4)

Search and Discovery (2)

File Locking (3)

Backlog Management (4)

Inter-Agent Messaging (7)

Function Registry (5)

Spec Management (3)

Project Registry (1 CRUD tool)

Checklists (1 CRUD tool)

External Database Queries (1 CRUD tool)

Server-Managed Guidelines (1)

Admin (1 CRUD tool)

Document Lifecycle (4)

Coordination & Activity (2)

Reminders & Scheduling (3)

Skills (6)

Reusable, task-invoked how-to procedures. Authored as draft, promoted to active through a trust gate, and materialized into .claude/skills/ by a launcher so the client's native matcher fires them mid-task.

Behavioral Directives (1)

Push-Control, Alerts & Telemetry (2)

Operator visibility into the messaging rate-limit / push-control subsystem (chain-depth caps, per-agent hourly budgets, silent suppression).

Team Status & Health (3)

Replication / Sync (2, server-to-server)

Phase-2 local-first replication endpoints (admin/owner tier). A LAN-local junto-memory reconciles with a central instance by shipping op-log entries — peers never re-embed text.

Backlog — bulk (1)

Local-Model Delegation (4)

Hand work to a model on your own hardware. How it works: Local-Model Delegation.

Local-Model Delegation

A lot of agent work doesn't need a frontier model: sorting a support inbox, pulling fields out of logs, summarising a long dump, watching a list for changes. Delegation lets an agent hand that work to a model running on your own hardware (via Ollama), so cloud-agent usage goes to the work that needs it. Contract: memory_get_spec(name="interface:delegated-inference-v0", project="junto").

How it works

graph LR
    A[Agent] -->|memory_delegate| S[junto-memory]
    S -->|claim run + sealed secret| R[Runner on your GPU box]
    R -->|fetch items| D[(Connection: imap / mcp / file / inline)]
    R -->|one JSON result per item| O[Ollama]
    R -->|results| S
    S -->|routes: notify / digest / drop| A2[Agents]

1. Connection (scope). A typed data source: inline (text passed in the task), imap (read-only mailbox), mcp (read-only tools on another MCP server), file (allowed roots on the runner host), or gmail (read-only API; needs your own Google OAuth client). Each lists the agents granted it and the runner hosts allowed to use it. memory_runners(action="scopes") shows yours.

2. Task. The agent owns it: instructions, an output_schema (JSON Schema for one item's result), source_params, routes, an optional schedule ({"every": "15m"} or {"cron": "0 7 * * *"}, minimum 5 minutes) and optional canaries. Every field can be edited later and edits are versioned. No schedule means it runs once now.

3. Run. The server queues runs. A runner on the GPU box claims one, fetches the items, sends each to the model with the task's instructions, validates the reply against the schema, and reports back. One runner works one run at a time.

4. Routes. The server, not the model, decides what happens to each result: notify an agent (with a template), add it to the owner's daily digest, or drop it. First matching rule wins; no match means digest. The local model can't take actions — anything it suggests reaches an agent as data.

memory_delegate(
    session_id=sid, name="ticket-sort", scope="myproject:inline",
    instructions="Classify this support message.",
    output_schema={"type": "object", "properties": {
        "classification": {"type": "string", "enum": ["bug", "billing", "how_to", "spam"]},
        "summary": {"type": "string"}}, "required": ["classification", "summary"]},
    source_params={"items": ["text of message 1", "text of message 2"]},
    routes=[{"if": {"field": "classification", "op": "in", "value": ["bug"]},
             "then": "notify", "to": "myproject/backend", "category": "task",
             "template": "{classification}: {summary}"},
            {"if": {"field": "classification", "op": "eq", "value": "spam"}, "then": "drop"}],
    run_now=True)
# → a "Delegated job done" notice; then memory_job(run_id, action="result")

Safety model

• Item content is untrusted data. It reaches the model fenced, with the task restated after it. The default model, gpt-oss:20b, resisted every prompt-injection case in testing; qwen3:14b is faster but followed instructions planted in plausible mail, so use it only on trusted text.

• Canaries are known items with expected outputs. They run daily (or every run) and after any edit to instructions, schema, model or source. A failed canary sends the owner a notice.

• Read-only sources. IMAP opens with EXAMINE and BODY.PEEK. MCP tools are limited to the connection's tools_allowed, intersected with what the task asks for.

• Failed items are never silent. An item with no valid output gets no route; for a scheduled task the owner gets an action notice listing each one (ref, from/subject, error), because the source cursor has moved past it.

• Visibility. Only the task owner reads run results. Schema fields marked "x-sensitive": true are stripped from notifications to agents outside the connection's content_visible_to.

Connections and the secret vault

Agents never handle credentials. An agent requests a connection (memory_runners(action="request_connection"), or connection= on memory_delegate). The operator activates it in /admin → Connections by pasting the secret; that act is the approval. Tasks waiting on it then start.

• Secrets are stored encrypted (Fernet) under JUNTO_VAULT_KEY. Each claim seals a fresh copy to that runner's X25519 key; the runner opens it in memory for that run only and never logs or caches it.

• Revoking a connection deletes the ciphertext and cancels queued runs. A run already claimed finishes within its 10-minute lease.

• Every request, activation, rotation and revocation is in the connection audit (/admin → Connections).

• JUNTO_VAULT_KEY lives in .env, not in the Mongo backups. A backup holds ciphertext only; losing the key means re-entering the secrets.

Running a runner

The runner (contrib/runner/junto-runner.py) is a single Python file that needs cryptography (plus mcp for MCP sources). It talks only to the junto server, the local Ollama, and the connection's own source.

First, from an owner/admin agent session, create the runner's key (it is shown once): memory_runners(session_id=sid, action="create_runner_key", runner_id="gpu-1", host="gpubox").

# On the GPU box
cp contrib/runner/junto-runner.py ~/.local/bin/ && chmod 755 ~/.local/bin/junto-runner.py
mkdir -p ~/.config/junto-runner && chmod 700 ~/.config/junto-runner
# save that key to ~/.config/junto-runner/runner.key (mode 600)
# config.json (mode 600): {"server": "http://<server>:8080", "runner_id": "gpu-1",
#   "key_file": "~/.config/junto-runner/runner.key", "ollama": "http://localhost:11434"}
cp contrib/runner/junto-runner.service ~/.config/systemd/user/
systemctl --user daemon-reload && systemctl --user enable --now junto-runner
loginctl enable-linger $USER

The runner creates its X25519 key pair on first start and registers its installed models. The runner API (/runner/api/*) is LAN-only.

Limits and gotchas

A model too big for VRAM (e.g. a 72B model on 2×24 GB) runs partly on CPU and evicts every other loaded model. Keep big models out of batches.

Admin Web UI

The server serves an operator page at http://<server>:8080/admin. It is LAN-only: requests arriving through a tunnel get 403. Anyone on the LAN can view; every change needs an owner API key (pasted into the page, sent as a Bearer header).

To put it behind a hostname, proxy /admin from nginx or similar, and keep that vhost LAN-only too.

Context Gauge and Idle-Park Nudge

Context gauge. contrib/context-report/junto-context-report.py runs on each machine (systemd user timer). It finds local claude processes, reads each agent's context-fill metrics written by its status line, and calls memory_report_context. memory_get_agent_status and /admin → Agents then show every agent's context fill across all machines.

Idle-park nudge. If an agent makes no real tool call for idle_park_minutes (default 50, just under the ~60-minute prompt-cache TTL), the server pushes it one notice suggesting it park at a clean stop. Only agents with at least idle_park_min_context (default 200K) of reported context are nudged. Agents listed in idle_park_autoreset go further: after a nudged park, the reporter checks the agent's tmux pane is safe to type into, then types /clear and go. Configure with memory_admin push_control_set_config or /admin → Settings.

Configuration

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

Required Variables

Optional Variables

Project Structure

mcp-shared-memory/
├── server.py                     # Entry point (imports from package)
├── src/
│   └── shared_memory/
│       ├── __init__.py
│       ├── __main__.py           # CLI argument parsing
│       ├── app.py                # FastMCP server instance
│       ├── config.py             # All configuration and constants
│       ├── clients.py            # MongoDB and ChromaDB client setup
│       ├── state.py              # In-memory state (sessions, locks, signals)
│       ├── helpers.py            # Shared utility functions
│       ├── auth.py               # API key auth, RBAC, tenant isolation
│       ├── audit.py              # Audit logging to MongoDB
│       ├── delegation.py         # Local-model tasks, scopes/connections, scheduling, routes
│       ├── vault.py              # Encrypted connection secrets, sealed per runner
│       ├── runner_api.py         # /runner/api/* (register, heartbeat, claim, complete, fail)
│       ├── admin_ui.py           # /admin web UI + its JSON API
│       ├── idle_park.py          # Idle→park nudge and auto-reset
│       └── tools/
│           ├── __init__.py       # Tool registration
│           ├── sessions.py       # Session start/end
│           ├── query.py          # Knowledge base queries
│           ├── storage.py        # Document storage and learnings
│           ├── search.py         # Cross-project search, list projects
│           ├── locking.py        # File lock management
│           ├── backlog.py        # Backlog/task management
│           ├── messaging.py      # Inter-agent messaging and status
│           ├── functions.py      # Function registry and enrichment
│           ├── specs.py          # Versioned spec management
│           ├── projects.py       # Project and agent registry
│           ├── checklists.py     # Shared checklists
│           ├── database.py       # External database queries
│           ├── lifecycle.py      # Document lifecycle and work status
│           ├── delegation.py     # memory_delegate / schedule / job / runners
│           └── admin.py          # API key management and audit logs
├── librarian.py                  # Standalone enrichment daemon (uses Haiku)
├── contrib/runner/               # Local-model runner + systemd user unit
├── contrib/context-report/       # Per-machine context-fill reporter
├── docker-compose.yml            # Full stack: server + MongoDB + ChromaDB
├── Dockerfile
├── requirements.txt
├── .env.example
└── LICENSE

Development

Prerequisites

• Python 3.11+

• Docker and Docker Compose (for MongoDB and ChromaDB)

Running Locally

Start the backing services:

docker compose up -d mongodb chromadb

Install Python dependencies:

pip install -r requirements.txt

Run the server directly:

python server.py --host 0.0.0.0 --port 8080

Or as a module:

cd src && python -m shared_memory --host 0.0.0.0 --port 8080

Running with Docker Compose (full stack)

docker compose up -d

This starts all three services (MCP server, MongoDB, ChromaDB) with health checks and automatic restarts.

Viewing Logs

# All services
docker compose logs -f

# Just the MCP server
docker compose logs -f mcp-server

Security

This server is designed for local or trusted-network use. Authentication is optional but available.

Built-in API Key Authentication

Set MCP_AUTH_ENABLED=true in .env to require API keys for all sessions. Keys are managed via the memory_admin tool with role-based access control:

Each API key can be scoped to specific projects for tenant isolation — agents only see data in their allowed projects. All security-sensitive operations are written to an audit log (90-day retention).

When auth is disabled (default), all tools are open — suitable for local single-user setups.

Passing the key: tool argument or Authorization header

A key can reach the server two ways (design:header-auth-v0):

1. api_key tool argument — pass api_key="smk_..." to memory_start_session. Explicit and always wins.

2. Authorization: Bearer header — put a headers block in your MCP client config (the standard MCP convention). The server reads the key from the header when no api_key argument is supplied:

   {
     "mcpServers": {
       "junto": {
         "type": "http",
         "url": "https://your-host/mcp",
         "headers": { "Authorization": "Bearer smk_..." }
       }
     }
   }

Precedence: explicit api_key argument > header > keyless. A keyless session (neither provided) falls back to agent tier. A present-but-invalid key — argument or header — is rejected outright (fails loud rather than silently downgrading). The header path is verified against Claude Code, which forwards the static header untouched.

Network Security

If you need remote access, do not expose port 8080 directly. Instead:

• Tailscale / WireGuard — Put the server on a private mesh network. This is the simplest and most secure option.

• Reverse proxy with auth — Use nginx or Caddy with HTTP basic auth, mTLS, or OAuth2 in front of the server.

• SSH tunnel — ssh -L 8080:localhost:8080 your-server for ad-hoc remote access.

The MONGO_PASSWORD in .env.example defaults to changeme. The server will start with this value, but you must change it for any non-throwaway deployment. MongoDB and ChromaDB ports are also exposed by default in Docker Compose — restrict these with firewall rules if your machine is network-accessible.

CLAUDE.md Files

These are instruction files for Claude Code. If you don't use Claude Code, you can safely ignore them.

• GLOBAL_CLAUDE.md.example — Copy to ~/.claude/CLAUDE.md on every machine. This is the minimal bootstrap that tells Claude to start sessions and follow server-managed guidelines.

• CLAUDE.md.template — Copy into each project directory and customize with your project name, agent names, and key files.

• CLAUDE.md — This project's own Claude Code config (for developing the server itself).

Behavioral rules are managed server-side, not in these files. Use memory_guidelines(action="set", ...) to add or update rules — every agent on every machine picks them up automatically at their next session start.

The Agent Discipline Problem

Having a shared memory server isn't enough. Agents need to actually use it consistently.

Agents drift. They forget to call memory_record_learning. They dump everything into one giant state spec instead of topic-scoped memories. They write to local files that other agents can't see. They run marathon sessions until context rot makes them forget their own instructions.

This server includes tools to fight that drift:

Server-managed guidelines

Every agent receives a set of behavioral rules at session start (in the memory_start_session response). There are two tiers:

Built-in global defaults (shipped, universal). Junto ships a set of scope="global" rules in code — src/shared_memory/global_guidelines.py — that are re-seeded into the DB on every server boot. So a fresh server (yours, or an isolated peer/work box) gets sane defaults with zero manual setup, and updating a default travels with the deploy. These are deliberately universal process — memory-first querying, running longer sessions and parking at a clean stop, accuracy over agreement, persisting knowledge to the server, recording learnings immediately, session discipline, message semantics, pointers-not-summaries, contracts-before-code, freshness checks, concise output, and reading the source before asserting. Nothing team- or deployment-specific lives here. Global scope is code-managed and read-only through the tool — change a default by editing that file and deploying (the seeder re-asserts it), not with a live edit.

Your own rules (project-scoped, runtime). Add rules specific to your team or project with memory_guidelines(action="set", scope="<project>", name=..., rule=...) — these are writable at runtime and served only to agents in that project. This is where deployment specifics go.

Approval boundaries. The built-in "execute, don't ask" rule is intentionally generic — it states the principle (do reversible work; only a human approves the irreversible) and defers the exact boundaries to your fleet's own approval contract. Define yours as a spec (e.g. memory_define_spec(name="approval-contract", spec_type="interface", ...)) or a project-scoped guideline; agents pull it when an action's reversibility is in question. Don't bake one fleet's staging/prod/merge policy into the shipped defaults.

Server guidelines are authoritative for the process they cover — they override any stale context/session heuristic still sitting in a project's CLAUDE.md.

Staleness management

Every memory_query result includes age warnings. Agents are instructed to supersede outdated information as they encounter it — distributed cleanup during normal work, not a separate chore. Bulk archive completed features with memory_archive_by_tag.

See docs/WORKED_EXAMPLE.md for a walkthrough of two agents coordinating on a real task.

Roadmap

Contributions welcome! These are known gaps that would benefit the project:

• Authentication and tenant isolation — Done! API keys with RBAC and project scoping. See Security.

• PostgreSQL support — the memory_db tool supports MSSQL and MySQL. PostgreSQL not yet implemented.

• Local model support for librarian — Ollama integration so the enrichment daemon doesn't require a cloud API key

• TTL and stale data cleanup — background pruning of expired sessions, locks, and messages with configurable retention

• Data export/backup tooling — dump and restore scripts for migration and disaster recovery

See docs/WORKED_EXAMPLE.md for an end-to-end walkthrough of multi-agent coordination.

Hosted Version

Don't want to run your own server? A hosted version is available — you get a dedicated instance with MongoDB and ChromaDB, just point your agents at the URL and go.

• No server setup — connect your agents in minutes

• Automatic backups

• Same 57 tools, same features

• Multi-project isolation

Interested? Open an issue or reach out for details.

License

See LICENSE for the full text.

Copyright (c) 2024-2026 Thomas Lemmons.

Contributing

Contributions welcome. Please open an issue to discuss significant changes before submitting a pull request. The project uses standard Python tooling — no special build system or test framework required beyond the dependencies in requirements.txt.

If you're running multi-agent setups and have coordination patterns that work, I'd love to hear about them.

If this project saves you time, consider sponsoring the development.