io.github.ajc3xc/meridian
Persistent memory, task coordination, and HITL queue for AI coding sessions.
Open source Repository Open in the app JSON README (API)
About
Persistent memory, task coordination, and HITL queue for AI coding sessions.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- ajc3xc
- Origin
- official
- Category
- ferramentas
- Transport
- sse
- Version
- 1.0.2
- Last push
- 2026-09-04T00:48:40Z
- Repository state
- ativo
- Language
- Python
- License
- NOASSERTION
- Added
- 2026-08-29 03:02:24
- Updated
- 2026-08-29 03:02:24
- Origin id
io.github.ajc3xc/meridian
README
<!-- mcp-name: io.github.meridianmcp/meridian -->
<p align="center">
<img src="meridian/static/logo.svg" width="64" height="64" alt="Meridian">
</p>
# Meridian
**Claude Code has no memory between sessions. Meridian fixes that.**
Open-source MCP server for persistent AI session memory — shared task log,
pinned decisions, human-in-the-loop queue, and tiered handoffs. Works with
Claude Code, Cursor, Cline, Claude Desktop, or any MCP client.
[](https://github.com/meridianmcp/Meridian)
[](LICENSE)
[](https://github.com/meridianmcp/Meridian/actions/workflows/test.yml)
[](https://docs.usemeridian.us)
[](https://usemeridian.us)
[](https://neon.tech)
[](https://usemeridian.us)
[](https://docs.usemeridian.us/mcp-tools)
[](https://usemeridian.us)
## Why Meridian
Every AI coding session boots blind. You re-explain the architecture, re-describe
the constraints, re-list what's been tried. When context fills up mid-task,
everything is lost. This is context debt — and it compounds.
Meridian gives your sessions shared memory. They see the same task log, the same
pinned decisions, the same goal state. When context fills up, a new session resumes
from a compressed handoff in seconds. No copy-paste, no re-explaining from scratch.
[](https://usemeridian.us)
## What it is, in 30 seconds
A local MCP server every AI session connects to. They share goal state, see each
other's task log, and resume from a compressed handoff when context fills up.
**Two ways to run Meridian:**
- **Self-host** — free forever, any team size. Clone and run in 2 commands.
- **Hosted** at [usemeridian.us](https://usemeridian.us) — 30 days free (no card), then $20/mo Standard.
<!-- MERIDIAN:ANCHOR:START quickstart -->
## Quickstart
### Option 1 — binary release (recommended)
Signed binaries for Windows, macOS (Apple Silicon), and Linux are attached to
every [GitHub release](https://github.com/meridianmcp/Meridian/releases) (current: v0.2.6).
**Linux / macOS (one-liner via uv):**
```bash
uv tool install meridian-server
meridian --tunnel --repo .
```
**Linux / macOS (manual binary download):**
```bash
curl -fsSL https://usemeridian.us/install.sh | sh
```
**Windows (PowerShell, one-liner via uv):**
```powershell
uv tool install meridian-server
meridian --tunnel --repo .
```
**Windows (PowerShell, manual binary download):**
```powershell
irm https://usemeridian.us/install-windows.ps1 | iex
```
Dashboard opens at **http://localhost:7878**. Data persists in `~/.meridian/` by default.
### Option 2 — from source (dev setup / self-host)
**Linux / macOS:**
```bash
git clone https://github.com/meridianmcp/Meridian
cd Meridian
./install.sh
pixi run start
```
**Windows (PowerShell):**
```powershell
git clone https://github.com/meridianmcp/Meridian
cd Meridian
.\install.ps1
pixi run start
```
Dashboard opens at **http://localhost:7878**. Data persists in `./data/meridian.db`.
<!-- MERIDIAN:ANCHOR:END quickstart -->
## Wire it into your AI client
### Claude Code
Drop a `.mcp.json` at your project root.
**Hosted (no install)** — generate an API key at [usemeridian.us/settings](https://usemeridian.us/settings):
```json
{
"mcpServers": {
"meridian": {
"type": "http",
"url": "https://usemeridian.us/mcp",
"headers": { "Authorization": "Bearer sk_meridian_YOUR_KEY_HERE" }
}
}
}
```
**Self-host (from source):**
```json
{
"mcpServers": {
"meridian": {
"command": "pixi",
"args": ["run", "python", "-m", "meridian", "--mcp"],
"cwd": "/absolute/path/to/Meridian"
}
}
}
```
### Cursor / Windsurf
Same JSON snippet — both clients read `.mcp.json` from the project root.
### Claude Desktop
Add the same `mcpServers` block to:
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
Restart Claude Desktop. New chats have Meridian tools. If a newly deployed
tool is still missing, follow the [MCP tool-surface freshness guide](docs/mcp-tool-surface.md)
before editing any client cache.
### claude.ai web (recommended for planning chat)
Use [dnakov/claude-mcp](https://github.com/dnakov/claude-mcp) — included as a submodule — to bridge claude.ai to your local Meridian server:
```bash
git clone --recurse-submodules https://github.com/meridianmcp/Meridian
```
1. Open `chrome://extensions` and enable **Developer mode**
2. Click **Load unpacked** and select `extensions/claude-mcp`
3. Click the extension icon and set the URL to `http://localhost:7878/mcp`
All 54+ Meridian tools (`checkpoint`, `log_task`, `pin_decision`, etc.) are now available directly in claude.ai planning chat. No copy-pasting session output.
### Hosted tier (no install)
Sign in at [usemeridian.us](https://usemeridian.us) → Settings → MCP client setup → Generate API key → Copy config.
Or manually:
```json
{"mcpServers":{"meridian":{"type":"http","url":"https://usemeridian.us/mcp","headers":{"Authorization":"Bearer sk_meridian_YOUR_KEY_HERE"}}}}
```
**claude.ai (browser)** users: install the [dnakov/claude-mcp](https://github.com/dnakov/claude-mcp) Chrome extension, then visit [usemeridian.us/install-mcp](https://usemeridian.us/install-mcp) for a step-by-step setup guide with one-click copy buttons.
Get your API key at [usemeridian.us/settings](https://usemeridian.us/settings) after sign-in. Free tier: 30 days, no card, full features.
<!-- MERIDIAN:ANCHOR:START features-list -->
## What you get
- **Dashboard** at `http://localhost:7878` — sessions, tasks, sprint board,
swimlane timeline, HITL queue, pinned decisions.
- **MCP tools** — `start_session`, `log_task`, `claim_task`, `set_decision`,
`pin_decision`, `request_hitl`, `generate_handoff`, and ~50 more.
- **Symbol-level parallel safety** — `claim_file` can claim a single class or
function (parsed with `ast` / tree-sitter) so two sessions edit the same file
safely; an overlapping claim is blocked with the free symbols listed.
- **Live work queue** — planners inject sprint items mid-run; executors pick them
up at the next item boundary via a `board_change` signal, no interruption.
- **HITL recommended option** — `request_hitl` can flag a safe-default option the
dashboard highlights; Enter submits it, number keys pick others.
- **GitHub hub** (hosted) — connect your repo once in Settings; sessions get `read_file`,
`list_files`, `search_code`, `git_log`, `get_commit` injected automatically. No extra install.
- **Tiered handoffs** — L0/L1/L2 compression so a fresh session can resume in seconds.
- **Webhook intake** — push events from LangGraph / Autogen / custom agents into the same dashboard.
- **Works everywhere** — Claude Code, Claude Desktop, Cursor, Windsurf, LangGraph, custom.
<!-- MERIDIAN:ANCHOR:END features-list -->
## How it works
```
> start_session(project_id="meridian", session_name="feature-x")
✓ session registered · sprint loaded · 12 active tasks
> get_tasks(project_id="meridian", limit=5)
[DONE] backend / wire decisions_pinned table
[PENDING] frontend / add notes vtab (claimed by session-2)
> claim_task(task_id="a1f3...")
✓ claimed — other sessions skip this one
```
State lives in `data/meridian.db` (SQLite) or a Postgres URL via `MERIDIAN_DB_URL`.
No cloud required for local use.
## Team coordination
Point `MERIDIAN_DB_URL` at a shared Postgres (Neon free tier works great). Every
teammate runs their own local Meridian against the same DB — instant shared
sessions, no Meridian server in the cloud.
## Auto-checkpoint with hooks
One command wires Claude Code and Codex to Meridian. Every session start injects
your project context automatically. Every session end snapshots completed work and
writes a delta handoff.
**Mac/Linux:**
```bash
curl -fsSL https://usemeridian.us/hooks.sh | bash
```
**Windows:**
```powershell
irm https://usemeridian.us/hooks.ps1 | iex
```
Prompts for your Meridian server URL (default `http://localhost:7878`), then opens
your browser to connect this machine — no project ID or API token to paste. Writes
to `~/.claude/settings.json` (Claude Code) or `~/.codex/config.toml` (Codex). After
setup, every session automatically:
1. **On start** — calls `POST /hooks/session-start` → injects goal, sprint items,
recent tasks, and pinned decisions into the session context via `additionalContext`.
2. **On stop** — calls `POST /hooks/stop` → runs `auto_capture` and writes a delta
handoff so the next session resumes from where this one ended.
No more manual `start_session()` calls. No lost work when context fills.
<!-- MERIDIAN:ANCHOR:START pricing-table -->
## Hosted tier
| | Standard | Pro |
|---|---|---|
| **Price** | $20/mo | $49/mo (waitlist) |
| **Storage** | 1 GB included | 10 GB included |
| **Compute** | 2 CU · 100 hrs/mo | 4 CU · 300 hrs/mo |
| **Bring your own Postgres** | ✓ | ✓ |
| **OAuth + email magic link** | ✓ | ✓ |
| **Extra storage** | $0.50 / GB-month | $0.50 / GB-month |
| **Support** | Email | Priority |
30-day free trial · no card required
<!-- MERIDIAN:ANCHOR:END pricing-table -->
## License
[MSL-1.0](LICENSE) — free for local and internal use at any team size. Paid
license required if you host Meridian as a service for others. Converts to
MIT after 6 years.
For licensing questions: [hello@usemeridian.us](mailto:hello@usemeridian.us)
## Contributors
Built by [@ajc3xc](https://github.com/ajc3xc)
[](https://cursor.com/install-mcp?name=meridian&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vdXNlbWVyaWRpYW4udXMvbWNwIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIHNrX21lcmlkaWFuX1lPVVJfS0VZX0hFUkUifX0=)