junto-memory MCP server

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.

[!IMPORTANT] This is meant to be set up by an AI agent, not installed by hand. Junto exists to coordinate fleets of coding agents, so the install is written for one of those agents to read and run — clone the repo and hand it to a Claude Code (or any MCP-capable) session, and let it drive. The commands in this README and in AGENT_INSTALL.md are there so you can follow along and so the agent has something exact to execute; they are not a hand-tuned human tutorial, and reading them straight through isn't the intended path. You stay in control — the agent pauses for every real decision (passwords, ports, auth). If handing setup to an agent isn't something you'd want to do, this probably isn't the tool for you.

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.

---

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.
Local-model delegation	No	Yes — Agent-owned tasks run on a local Ollama runner; results routed to agents or a daily digest
Secrets for data sources	No	Yes — Encrypted vault; agents request connections, the operator activates them, agents never see the secret
Operator web UI	No	Yes — /admin: settings, agents, alerts, tasks, connections, change log

65 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

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

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 (8)

Tool	Description
memory_send_message	Send a message to another agent. Supports categories (task, question, blocker, etc.) and threading.
memory_notify	Send a message to a PERSON over their own Gmail/Slack. Junto queues it; the person's notify runner (contrib/notify-runner, on their machine) delivers it through their approved Claude connector with a headless claude -p, behind a local recipient allowlist. Scheduled tasks can route to human:<name> too. Each person registers and tests their own channels.
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 (5)

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_verify	Mark a doc verified / rejected / unreviewed (separate from status). Verified docs lead their relevance band; rejected docs drop out of search and recall. Human, admin/owner or librarian only; no self-verify.
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.

Coordination & Activity (2)

Tool	Description
memory_get_active_work	See what other agents are currently working on — tasks, files touched, timestamps. Avoid overlap.
memory_claim_message	Claim a message so exactly one agent in a group handles it (multi-consumer coordination).

Reminders & Scheduling (3)

Tool	Description
memory_set_reminder	Schedule a message to your future self (or a peer) at a specific time — deadlines, follow-ups, "ping me after X".
memory_cancel_reminder	Cancel a previously scheduled reminder.
memory_list_reminders	List your pending scheduled reminders.

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.

Tool	Description
memory_register_skill	Author a reusable skill (trigger + steps + gotchas + preconditions). Always creates a draft.
memory_confirm_skill	Promote a draft skill to active — the trust gate. Owner/human only.
memory_get_skill	Fetch one skill's full body by id or name.
memory_list_skills	List skills (headers) scoped by project/role/directory/status. Pinned first, then active.
memory_pin_skill	Pin/unpin a skill so it ranks first in surfacing.
memory_export_skills	Export active, scope-matched skills as ready-to-write SKILL.md payloads for a launcher to materialize.

Behavioral Directives (1)

Tool	Description
memory_ack_directive	Acknowledge a server-issued directive (e.g. a park or behavioral instruction) so it clears.

Push-Control, Alerts & Telemetry (2)

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

Tool	Description
memory_list_alerts	List push-control alerts — budget warnings, budget breaches, hard-ceiling trips — for an operator dashboard or polling fallback.
memory_get_emission_stats	Per-agent message-emission counters and budget usage.

Team Status & Health (3)

Tool	Description
memory_report_context	Report agents' context-window fill from any machine (used by the per-box contrib/context-report reporter). memory_get_agent_status then shows every agent's context gauge, and the idle→park nudge uses it (see Context Gauge and Idle-Park Nudge).
memory_standup	Auto-compiled team standup for a project — every agent's current task, blockers, stale state specs, and an aggregated decision queue. Read-only, needs no agent to produce it.
memory_health	Server health — MongoDB + ChromaDB status and active session/lock/signal counts. No session required.

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.

Tool	Description
memory_sync_pull	Pull op-log entries newer than the caller's per-origin cursor.
memory_sync_push	Apply a batch of op-log entries received from a peer (seq-monotonic, intent-deduped).

Backlog — bulk (1)

Tool	Description
memory_batch_backlog	Create or update many backlog items in one call.

Local-Model Delegation (4)

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

Tool	Description
memory_delegate	Create a task for the local model: data source (scope), instructions, JSON output schema, routes, optional schedule and canaries. No schedule = run once now. Can request a new connection in the same call.
memory_schedule	Manage your tasks: list, get, edit (versioned), pause, resume, delete, run_now, history, runs, approve (operator).
memory_job	One run: status, result (each item's output and the route it took), cancel. Owner only.
memory_runners	Runners and connections: list (hosts, models, last heartbeat), scopes (connections you can use), request_connection; operator-only define_scope, create_runner_key.

---

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