Waymark is a shared memory and handoff hub for AI agents, enabling seamless context transfer and task coordination across sessions via a local MCP server backed by SQLite.
Resume a workspace session (workspace_resume): Restore compact, token-budgeted project state (metadata, open tasks, ranked memories, active handoffs) for a new agent session — reducing orientation context by ~91.5% vs. cold reading.
Get task-specific context (context_get): Build focused, deterministically ranked project context tailored to a specific task, filtered by memory types and constrained to a token budget.
Write & manage memory nodes (memory_write, memory_read, memory_search): Create, read, search, and update named memory records (decisions, handoffs, references, feedback, etc.) with lifecycle statuses (active, superseded, stale, archived), confidence/importance ratings, and supersession of old records.
Coordinate tasks (task_create, task_list, task_update, task_claim): Create tasks with priorities, dependencies, and required capabilities; list/update them; and atomically claim pending tasks — ensuring only one agent takes a task after validating capabilities and resolved dependencies.
Log sessions (session_log): Record session outcomes (completed, partial, blocked) with summaries, decisions, commits, and files touched. Partial/blocked sessions automatically create handoff memories so the next agent can resume without retelling.
Register agents: Agents can register themselves with provider/model/client identity for tracking.
Manage projects: List, get, upsert, and set the status of projects to organize work.
Monitor usage & experiments: Log usage reports and manage experiments, including creation, listing, updating, and summarizing results.
Dashboard: A read-only web panel to view projects, tasks, memory, sessions, agents, and benchmark results.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Waymark Resume my workspace for project 'doc-bot'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Shared memory and handoff hub for AI agents. A waymark is a trail sign left for whoever walks the path next — Waymark does the same for agent sessions: Claude Code finishes work, and the next session of Codex, Claude Desktop, or any other MCP client starts already knowing what was done, what was decided, and what to do next.
No retelling. No re-reading the repo. One token-budgeted call.
Every new agent session starts cold: it re-reads files, re-asks questions, and burns tokens rediscovering context that another agent had five minutes ago. Waymark replaces that with a local MCP server over a single SQLite database shared by all your agents:
workspace_resume — one call returns a compact packet (project metadata,
open tasks, ranked memory, recent sessions, active handoff) within a token
budget you set (default 1,200 tokens).
Automatic handoffs — session_log(outcome: "partial", next_steps: [...])
writes a handoff memory that tops the next agent's resume. Logging
completed retires it. No discipline required.
Task queue with atomic claims — task_claim guarantees only one agent
takes a task, with capability and dependency checks.
Memory lifecycle — supersede instead of accumulate; feedback ratings demote stale records in ranking.
Provider-neutral — agents register with provider/model/client identity; nothing in the core is tied to one vendor.
Related MCP server: JustClone Coordination MCP Server
Continuation scenario (fresh session must orient in a project and name the next
step), estimated cohort, reproducible via node scripts/benchmark-orientation.cjs:
median tokens | |
Cold orientation (reading README, docs, sources, git log) | 13,540 |
Waymark resume (packet + core tool schemas + follow-up reads) | 3,392 |
Net saving | 74.9% |
The orientation context itself shrinks from ~13.1k tokens of raw files to a 1.1k-token ranked packet (−91.5%) — and unlike cold reading, the packet contains what files can't: what the previous agent actually did and decided. The exact-token A/B protocol with live clients is in docs/BENCHMARK_RUN.md.
Requires Node.js 22+.
npm install -g waymark-hub
waymark-hub init # registers the hub in Claude Code / Codex, offers the hook
waymark-hub doctor # verifies the whole installationinit asks before touching anything; init --yes enables everything
applicable. The database lives in ~/.waymark/hub.db (survives package
upgrades); override with WAYMARK_HOME or DB_PATH.
From source instead:
git clone https://github.com/SerjMihashin/waymark && cd waymark
npm install && npm test # build + 20 integration testswaymark-hub init --claude, or manually:
claude mcp add --scope user waymark node "<install>/dist/server.js"Optional but recommended — waymark-hub init --hook installs a SessionStart
hook that injects the resume packet into every new session (zero tool calls
spent on orientation).
waymark-hub init --codex, or manually:
# ~/.codex/config.toml
[mcp_servers.waymark]
command = "node"
args = ["<install>/dist/server.js"]waymark-hub serve --http # listens on 127.0.0.1:3747Add a custom connector: http://localhost:3747/mcp. Also available via
docker compose up -d / podman compose up -d.
Session start — one call, not three:
workspace_resume(project_id, task?, agent_id?, max_tokens=1200)Session end:
session_log(started_at, summary, outcome, next_steps?) # partial/blocked → auto-handoff
memory_write(...) # only durable decisions/factsCross-agent handoff happens automatically: agent A logs a partial session
with next_steps; agent B's workspace_resume surfaces that handoff first,
with the session trail and files touched. When someone logs completed, the
handoff retires itself.
Greedy MCP clients inject every tool schema into context each turn. Waymark
defaults to a core profile of 10 tools (~1.8k tokens instead of ~4.7k for
all 28). Set HUB_TOOLS=full where you need the admin surface (projects,
agents, experiments, telemetry).
Group | Tools |
Context |
|
Memory |
|
Tasks |
|
Projects |
|
Agents |
|
Sessions & telemetry |
|
Deep dives: docs/CONTEXT.md, docs/MEMORY_LIFECYCLE.md, docs/TASK_COORDINATION.md, docs/BENCHMARKING.md.
npm run dashboard → read-only web panel on http://localhost:4747: projects,
tasks, memory (FTS search), sessions, agents, benchmark results. Opens the DB
in read-only mode — it physically cannot mutate hub state.
src/server.ts entry point: stdio / HTTP (--http), tool profiles
src/db/client.ts SQLite singleton (WAL) + idempotent migrations 001..005
src/tools/ projects · memory · tasks · sessions · agents · context · telemetry
src/context/builder.ts deterministic ranking + token budget (no LLM calls)
src/cli/benchmark.ts A/B experiment CLI
dashboard/ read-only Express panelStorage: SQLite + FTS5. The core never calls an LLM or any external service.
Context on demand — summaries + ids by default; bodies only when asked.
Budget first — every aggregated response fits a token budget.
Evidence over retelling — link files/commits/tasks instead of copying text.
Replace, don't accumulate — supersede outdated memory, no duplicates.
Provider-agnostic — any MCP client is a first-class citizen.
MIT
Build task-specific project context using deterministic ranking within a token budget.
Inputs: task (required), project_id (required), agent_id, client_id, +3 more.
Read a single memory node by id or by project+name.
Inputs: id, name, project_id.
Full-text search across all memory nodes. Use to find anything known about a topic.
Inputs: query (required), limit, project_id, include_inactive.
Create or replace a named memory node (project-scoped, or global if no project_id).
Inputs: body (required), name (required), description (required), tags, +14 more.
Record a session summary at the end of significant agent work. On outcome "partial"/"blocked" (or when next_steps are given) the hub automatically writes a handoff memory so the next agent resumes without retelling; outcome "completed" retires that auto-handoff.
Inputs: summary (required), started_at (required), model, client, +9 more.
Atomically claim a pending task after validating assignment, capabilities, and dependencies.
Inputs: id (required), agent_id (required).
Create a handoff task for another agent or client.
Inputs: title (required), description (required), priority, created_by, +7 more.
List tasks by status, project, assignee, or blocker.
Inputs: limit, status, blocked, created_by, +5 more.
Update task status, progress, blocker, or notes.
Inputs: id (required), status, blocker, progress, +2 more.
Restore compact project state for a new agent session in one token-budgeted call.
Inputs: project_id (required), task, agent_id, client_id, +1 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 10 tools
Each tool has a clearly distinct purpose: context building, memory operations, session logging, task management, and workspace resumption. No overlapping functionality.
All tools follow a consistent verb_noun snake_case pattern (e.g., `memory_read`, `task_create`), making naming predictable and intuitive.
10 tools is well-scoped for the server's domain of agent orchestration and memory management, covering core operations without bloat.
Covers CRUD for memory (read, search, write) and tasks (create, list, update, claim) plus session logging and context. Minor gap: no explicit task deletion or memory deletion, but these are not critical for the intended workflows.
Durable agent-to-agent handoffs and shared scratchpad for multi-agent workflows.
Shared persistent memory for AI agents to read, verify, continue, and connect knowledge.
Private memory, scratchpads, context export/restore and task handoff for AI agents.
Shared project memory that keeps teammates and AI agents aligned across sessions.
