waymark-hub 1.0.0

package/docs/AGENT_IDENTITY.md

@@ -0,0 +1,67 @@
+# Agent identity
+
+Waymark supports provider-neutral agent identities while retaining legacy
+surface fields for existing clients.
+
+## Identity fields
+
+- `agent_id`: stable logical agent identity;
+- `provider`: model provider, such as OpenAI, Anthropic, Google, or local;
+- `model`: provider model identifier;
+- `client`: application or integration, such as Codex CLI or a browser agent;
+- `client_version`: optional client version;
+- `capabilities`: declared abilities such as `code`, `browser`, or `documents`;
+- `client_session_id`: session identifier supplied by the client.
+
+Provider, model, client, agent, and session are separate concepts. Changing a
+model or client does not require changing project data.
+
+## Registering an agent
+
+Use `agent_register` with a stable caller-controlled id when possible:
+
+```json
+{
+  "id": "codex-primary",
+  "display_name": "Primary coding agent",
+  "provider": "openai",
+  "model": "<model-id>",
+  "client": "codex",
+  "capabilities": ["code", "shell", "review"]
+}
+```
+
+When no id is supplied, the Hub generates a UUID.
+
+Available tools:
+
+- `agent_register`;
+- `agent_get`;
+- `agent_list`;
+- `agent_set_status`.
+
+## Linking work
+
+The following tools accept registered agent identities:
+
+- `session_log.agent_id`;
+- `usage_report.agent_id`;
+- `memory_write.agent_id`;
+- `task_create.created_by_agent`;
+- `task_create.assigned_agent_id`;
+- `task_list.created_by_agent`;
+- `task_list.assigned_agent_id`.
+
+When `usage_report` references a linked session, it inherits the session agent,
+project, provider, model, and client. Conflicting explicit values are rejected.
+
+## Backward compatibility
+
+Legacy fields remain supported:
+
+- `surface`;
+- `created_by`;
+- `assigned_to`.
+
+New clients should send agent identity fields. Existing clients can continue
+using legacy fields until the v2 migration is complete.

package/docs/BENCHMARKING.md

@@ -0,0 +1,161 @@
+# Token usage benchmarking
+
+This document defines the Stage 1 measurement protocol for comparing agent work
+with and without the Hub.
+
+## Measurement rule
+
+The primary metric is total model usage for the complete task:
+
+```text
+total_model_tokens =
+  input_tokens
+  + output_tokens
+  + hub_llm_input_tokens
+  + hub_llm_output_tokens
+```
+
+`input_tokens` already includes tool schemas, prompts, retrieved context and
+memory-write requests sent to the agent model. Do not add `context_tokens` or
+tool-schema tokens to the total a second time.
+
+`cached_input_tokens` is diagnostic metadata. It is not subtracted unless a
+future cost-specific metric explicitly defines provider cache pricing.
+
+## Exact and estimated data
+
+- Use `measurement=exact` only when token counts come from the provider or
+  client usage report.
+- Use `measurement=estimated` for locally calculated counts.
+- Never combine exact and estimated runs in one result.
+- Never combine different providers, models or clients in one result.
+
+The `experiment_summary` tool enforces these cohort boundaries.
+
+## Running an experiment
+
+1. Create an experiment with `experiment_create`.
+2. Freeze the repository state and task instructions.
+3. Run the scenario without the Hub.
+4. Restore the same initial state.
+5. Run the scenario with the Hub.
+6. Submit each result with `usage_report`.
+7. Repeat both variants at least five times.
+8. Read the grouped result with `experiment_summary`.
+9. Mark the experiment completed with `experiment_update`.
+
+The same workflow is available from the command line:
+
+```powershell
+# Create an experiment
+npm run benchmark -- create `
+  --name "Continuation benchmark" `
+  --scenario "continue-bugfix" `
+  --project-id "D--Projects-ClaudePlus" `
+  --target-runs 5
+
+# Record one run from flags
+npm run benchmark -- record `
+  --experiment-id "<experiment-id>" `
+  --variant without_hub `
+  --provider openai `
+  --model "<model-id>" `
+  --client codex `
+  --measurement exact `
+  --input-tokens 12000 `
+  --output-tokens 1800 `
+  --duration-ms 90000 `
+  --success true
+
+# Record a richer run from JSON
+npm run benchmark -- record --file .\run-with-hub.json
+
+# Read the report and close the experiment
+npm run benchmark -- summary --id "<experiment-id>"
+npm run benchmark -- complete --id "<experiment-id>"
+```
+
+Use `DB_PATH` to run against a separate benchmark database:
+
+```powershell
+$env:DB_PATH = "D:\tmp\waymark-benchmark.db"
+npm run benchmark -- list
+```
+
+The installed package exposes the same CLI as `waymark-benchmark`.
+For repository development, run `npm run build` after source changes before
+using `npm run benchmark`. The benchmark command itself does not rebuild
+`dist`, so it can run while the MCP server is active on Windows.
+
+Example JSON run:
+
+```json
+{
+  "experiment_id": "<experiment-id>",
+  "variant": "with_hub",
+  "provider": "openai",
+  "model": "<model-id>",
+  "client": "codex",
+  "measurement": "exact",
+  "input_tokens": 8500,
+  "output_tokens": 1400,
+  "hub_llm_input_tokens": 0,
+  "hub_llm_output_tokens": 0,
+  "context_tokens": 900,
+  "tool_calls": 14,
+  "files_read": ["src/server.ts", "src/tools/memory.ts"],
+  "repeated_files": 1,
+  "clarification_count": 0,
+  "duration_ms": 62000,
+  "result_quality": 95,
+  "success": true
+}
+```
+
+## Required controls
+
+- Same provider, model and client within a cohort.
+- Same task statement and acceptance test.
+- Same initial repository state.
+- Same tool availability except for the Hub itself.
+- Separate sessions for every run.
+- Record failures instead of silently discarding them.
+
+## Recommended fields
+
+Every run should provide:
+
+- `experiment_id`;
+- `variant`;
+- `provider`;
+- `model`;
+- `client`;
+- `measurement`;
+- `input_tokens`;
+- `output_tokens`;
+- `hub_llm_input_tokens` and `hub_llm_output_tokens` when applicable;
+- `context_tokens` or `context_text`;
+- `tool_calls`;
+- `files_read`;
+- `repeated_files`;
+- `clarification_count`;
+- `duration_ms`;
+- `result_quality`;
+- `success`;
+- notes about deviations.
+
+## Interpreting the result
+
+```text
+net_token_saving =
+  median_without_hub
+  - median_with_hub
+
+net_token_saving_percent =
+  net_token_saving / median_without_hub * 100
+```
+
+A positive result means the Hub reduced model usage. Token reduction is not
+sufficient by itself: result quality and success rate must remain comparable.
+
+The MVP target is at least 20% median net token saving on continuation tasks.

package/docs/CONTEXT.md

@@ -0,0 +1,95 @@
+# Token-budgeted context
+
+The Hub provides two high-level read-only tools for restoring project context
+without loading all memory into the agent prompt.
+
+## `workspace_resume`
+
+Use once at the beginning of a session:
+
+```json
+{
+  "project_id": "D--Projects-ClaudePlus",
+  "task": "Continue implementation of compact context",
+  "agent_id": "codex-primary",
+  "client_id": "codex",
+  "max_tokens": 1200
+}
+```
+
+The task is optional. When supplied, it improves memory ranking.
+
+**When to use which:** `workspace_resume` is the session opener — call it exactly
+once, at the start, to restore the whole workspace picture (tasks, sessions,
+handoffs, top memories). `context_get` is the mid-session refiner — call it when
+you hit a *new sub-task* and want memories re-ranked for it (optionally filtered
+by `memory_types` or with bodies via `include_sources`). If you only need one
+known record, use `memory_read(id)` instead of either.
+
+The packet may include `notices` — short protocol nudges (for example, an
+unregistered `agent_id`). They cost a few tokens and appear only when relevant.
+
+## `context_get`
+
+Use when the agent needs context for a specific task:
+
+```json
+{
+  "project_id": "D--Projects-ClaudePlus",
+  "task": "Investigate SQLite write contention",
+  "agent_id": "codex-primary",
+  "max_tokens": 800,
+  "memory_types": ["decision", "handoff", "project"],
+  "include_sources": false
+}
+```
+
+`include_sources=true` includes truncated memory bodies and therefore consumes
+more of the budget. By default only compact summaries and record ids are
+returned.
+
+## Packet contents
+
+- compact project metadata;
+- the current task;
+- active pending and in-progress tasks;
+- ranked project and global memories;
+- recent session summaries;
+- counts of records omitted because of the budget;
+- estimated serialized response tokens.
+
+## Ranking
+
+The deterministic ranking uses:
+
+- memory type;
+- project records over global records;
+- term overlap with the requested task;
+- update recency.
+
+The core does not call an LLM or external service.
+
+## Budget behavior
+
+- Accepted budget: 200–20,000 estimated tokens.
+- Default budget: 1,200.
+- The estimate is calculated from the pretty-printed JSON returned to the
+  client.
+- Candidates are added one at a time and removed if they exceed the budget.
+- For very small budgets, optional project metadata is trimmed first.
+- Detailed bodies are omitted unless explicitly requested.
+
+The estimate uses the current deterministic fallback of approximately four
+UTF-8 bytes per token. Future model-specific tokenizers can replace this
+adapter without changing the context API.
+
+## Recommended session start
+
+New clients should use:
+
+1. `agent_register` or a previously assigned stable `agent_id`;
+2. one `workspace_resume` call;
+3. low-level tools only for details referenced by record or task id.
+
+This replaces the legacy requirement to always call `project_list`,
+`memory_list`, and `task_list` at session start.

package/docs/MEMORY_LIFECYCLE.md

@@ -0,0 +1,65 @@
+# Memory lifecycle
+
+Memory records are durable project knowledge, not an append-only transcript.
+The lifecycle prevents obsolete records from polluting future agent context.
+
+## Statuses
+
+- `active`: eligible for normal search and context packets;
+- `superseded`: replaced by a newer record;
+- `stale`: known to require verification;
+- `archived`: retained for audit but excluded from normal work.
+
+Existing records migrate as `active`.
+
+## Quality and provenance
+
+`memory_write` supports:
+
+- `importance`: 0–100;
+- `confidence`: 0–100;
+- `source_type`: file, commit, task, URL, user, or another source class;
+- `source_ref`: path, SHA, URL, task id, or other source identifier;
+- `valid_from` and `valid_until`;
+- `last_verified_at`;
+- `supersedes_id`.
+
+Context ranking uses importance, confidence, recency, task relevance, memory
+type, project scope, and feedback.
+
+## Replacing a record
+
+Create the new record with `supersedes_id` referencing the old record. The Hub
+uses one SQLite transaction to:
+
+1. write the new record;
+2. mark the old record `superseded`.
+
+This prevents both versions from appearing as active context.
+
+## Feedback
+
+Use `memory_feedback` after consuming a context packet:
+
+- `used`;
+- `not_used`;
+- `helpful`;
+- `irrelevant`;
+- `stale`;
+- `incorrect`;
+- `too_verbose`.
+
+Positive feedback increases ranking. Negative feedback reduces ranking.
+Feedback does not automatically delete or rewrite memory.
+
+Use `memory_set_status` when a record is known to be stale, archived, or active
+again after verification.
+
+## Read behavior
+
+- `context_get` and `workspace_resume` include only active and currently valid
+  records.
+- `memory_search` excludes inactive and expired records by default.
+- `memory_search(include_inactive=true)` supports audit and historical lookup.
+- `memory_read(id=...)` can always retrieve a known record regardless of status.
+- `memory_list` can filter by status and returns lifecycle metadata.

package/docs/TASK_COORDINATION.md

@@ -0,0 +1,27 @@
+# Task Coordination
+
+The task queue supports coordinated work by multiple registered agents.
+
+## Claim protocol
+
+1. Create tasks with `required_capabilities` and optional `dependency_ids`.
+2. An agent calls `task_claim` with its registered `agent_id`.
+3. The hub validates that the task is pending, dependencies are done, the
+   assignment matches, and the agent has every required capability.
+4. The claim changes the task to `in_progress` in an immediate SQLite
+   transaction. A competing claim cannot take the same task.
+5. Update `progress` and `blocker` with `task_update`.
+6. Mark the task `done`, or return it to the queue with `task_release`.
+
+## Tools
+
+- `task_create`: accepts `required_capabilities` and `dependency_ids`.
+- `task_add_dependency`: adds a prerequisite to an existing task.
+- `task_claim`: atomically assigns available work to one agent.
+- `task_update`: updates status, progress, blocker, notes, and context.
+- `task_release`: releases work only when called by the claiming agent.
+- `task_list`: filters by claiming agent and blocker state.
+
+Task dependencies prevent premature work, and cyclic dependency graphs are
+rejected. Capabilities describe functional requirements such as `code`,
+`browser`, or `review`; they are not tied to a specific provider or model.

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "waymark-hub",
+  "version": "1.0.0",
+  "description": "Shared context and coordination MCP hub for AI agents",
+  "main": "dist/server.js",
+  "bin": {
+    "waymark-hub": "dist/cli/waymark.js",
+    "waymark-benchmark": "dist/cli/benchmark.js"
+  },
+  "files": [
+    "dist",
+    "dashboard",
+    "scripts/hooks",
+    "README.md",
+    "docs/BENCHMARKING.md",
+    "docs/AGENT_IDENTITY.md",
+    "docs/CONTEXT.md",
+    "docs/MEMORY_LIFECYCLE.md",
+    "docs/TASK_COORDINATION.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SerjMihashin/waymark.git"
+  },
+  "homepage": "https://github.com/SerjMihashin/waymark#readme",
+  "bugs": {
+    "url": "https://github.com/SerjMihashin/waymark/issues"
+  },
+  "scripts": {
+    "build": "tsc && node -e \"const fs=require('fs');const path=require('path');fs.mkdirSync('dist/db/migrations',{recursive:true});fs.readdirSync('src/db/migrations').forEach(f=>fs.copyFileSync('src/db/migrations/'+f,'dist/db/migrations/'+f));console.log('Migrations copied.')\"",
+    "test": "npm run build && node --test --test-concurrency=1 tests/*.test.js",
+    "dev": "tsx src/server.ts",
+    "dev:http": "tsx src/server.ts --http",
+    "start": "node dist/server.js",
+    "start:http": "node dist/server.js --http",
+    "benchmark": "node dist/cli/benchmark.js",
+    "dashboard": "node dashboard/server.mjs",
+    "backup:db": "tsx scripts/backup-db.ts",
+    "import:memory": "tsx scripts/import-existing-memory.ts"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "ai-agents",
+    "agent-memory",
+    "handoff",
+    "shared-context",
+    "claude",
+    "codex",
+    "sqlite"
+  ],
+  "author": "Serj",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.10.0",
+    "express": "^5.2.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.8.0",
+    "tsx": "^4.22.0",
+    "typescript": "^6.0.3"
+  }
+}

package/scripts/hooks/session-start-resume.cjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// Claude Code SessionStart hook: injects a compact workspace resume from the hub
+// into the new session's context, so the agent starts already knowing what other
+// agents did — without spending a single tool call on it.
+//
+// Wiring (user or project settings.json):
+//   "hooks": {
+//     "SessionStart": [
+//       { "hooks": [ { "type": "command",
+//           "command": "node D:\\Projects\\ClaudePlus\\scripts\\hooks\\session-start-resume.cjs" } ] }
+//     ]
+//   }
+//
+// Prints nothing (exit 0) when the current directory is not a hub project, so it
+// is safe to enable globally.
+
+const path = require('path');
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    setTimeout(() => resolve(data), 2000).unref();
+  });
+}
+
+function projectIdFromPath(dir) {
+  return path.resolve(dir).replace(/[^A-Za-z0-9]/g, '-');
+}
+
+async function main() {
+  let input = {};
+  try {
+    input = JSON.parse(await readStdin() || '{}');
+  } catch {
+    // no/invalid stdin — fall back to cwd
+  }
+  const cwd = input.cwd || process.cwd();
+  const projectId = projectIdFromPath(cwd);
+
+  // dist/ is CommonJS; db path is anchored to the hub install dir by db/client.
+  const { buildContextPacket } = require(path.join(__dirname, '..', '..', 'dist', 'context', 'builder.js'));
+
+  let packet;
+  try {
+    packet = buildContextPacket({ projectId, maxTokens: 1200 });
+  } catch {
+    process.exit(0); // hub db unavailable — stay silent, never break session start
+  }
+  if (!packet) process.exit(0); // not a hub project
+
+  const context = [
+    'Shared agent-hub resume for this project (from the hub DB; other agents may have worked here).',
+    'Read memory bodies on demand via memory_read(id). End significant work with session_log',
+    '(outcome + next_steps) so the next agent resumes without retelling.',
+    '',
+    JSON.stringify(packet),
+  ].join('\n');
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: context,
+    },
+  }));
+}
+
+main();