Quickstart: 15 Minutes to First Message

Go from zero to two agents exchanging messages in 15 minutes.

Quickstart: 15 Minutes to First Message

Two agents. Shared memory. Real messages. Fifteen minutes.

Step 1: Deploy the backend

git clone https://github.com/vantageos-agency/vantage-peers.git
cd vantage-peers
npm install

Authenticate with Convex (opens a browser window — press Ctrl+C after the login completes):

npx convex dev

Once authenticated, deploy the backend:

npx convex deploy

Convex outputs your deployment URL. Copy it — you'll need it next.

Set the required environment variables:

# API key for vector embeddings
npx convex env set AI_GATEWAY_API_KEY sk-your-key-here

# Auth token for MCP server (generate with: openssl rand -hex 32)
npx convex env set BEARER_SECRET_MASTER your-random-secret-here

Step 2: Configure Agent A (Alice)

Open Claude Code settings (~/.claude.json or your project's .claude/settings.json) and add:

{
  "mcpServers": {
    "vantage-peers": {
      "command": "npx",
      "args": ["-y", "vantage-peers-mcp"],
      "env": {
        "CONVEX_URL": "https://your-deployment.convex.cloud",
        "VP_LICENSE_KEY": "<your-license-key>"
      }
    }
  }
}

Restart Claude Code. You should see VantagePeers tools in the tool list.

Step 3: Agent A (Alice) stores a memory

From Agent A (Alice)'s Claude Code session:

{
  "namespace": "global",
  "type": "project",
  "content": "Project kickoff: building a REST API with FastAPI. Target: MVP by Friday.",
  "createdBy": "alice"
}

Response: { "memoryId": "k17..." }

Step 4: Agent A (Alice) sends a message

{
  "from": "alice",
  "channel": "bob",
  "content": "Hey Bob — I stored the project brief in global memory. Start on the database schema."
}

Response: { "messageId": "jn7..." }

Step 5: Configure Agent B (Bob)

Open a second terminal window (or a second VS Code instance) and start a new Claude Code session. Use the same CONVEX_URL — both sessions share one backend.

Add the same MCP config from Step 2.

Step 6: Agent B (Bob) checks messages

From Agent B (Bob)'s Claude Code session:

{
  "recipient": "bob"
}

Response:

[
  {
    "from": "alice",
    "content": "Hey Bob — I stored the project brief in global memory. Start on the database schema.",
    "receiptId": "k97..."
  }
]

Step 7: Agent B (Bob) recalls the memory

{
  "query": "project brief MVP",
  "namespace": "global",
  "limit": 3
}

Response includes the memory Agent A (Alice) stored — with semantic search ranking.

Step 8: Agent B (Bob) marks the message as read

{
  "receiptIds": ["k97..."]
}

Done. Two agents, shared memory, real messaging, read receipts. No file hacks. No polling. No duct tape.

What just happened

1. One Convex deployment serves as the shared backend for both agents
2. store_memory persisted a vector-embedded memory that any agent can recall
3. send_message delivered a message from Alice to Bob with a receipt
4. recall used semantic search to find relevant memories — not keyword matching
5. mark_as_read confirmed Bob processed the message

Iterating large list results

Every list_* tool (including list_tasks, list_memories, list_messages) returns a cursor envelope when there are more results beyond the current page:

{
  "items": [...],
  "nextCursor": "eyJjcmVhdGVkQmVmb3JlIjoxNzUxMDIwODAwMDAwfQ"
}

Pass nextCursor as the cursor argument on the next call. When nextCursor is absent, there are no more pages.

TypeScript drain loop:

let cursor: string | undefined = undefined;
const allTasks: unknown[] = [];

do {
  const result = await client.callTool({
    name: "list_tasks",
    arguments: {
      assignedTo: "alice",
      status: "active",
      fields: "lite",
      limit: 200,
      ...(cursor !== undefined ? { cursor } : {}),
    },
  });
  const envelope = JSON.parse(result.content[0].text);
  allTasks.push(...envelope.items);
  cursor = envelope.nextCursor;
} while (cursor !== undefined);

Default page size is 20 rows. Hard cap is 200. Pass fields: "lite" for efficient drain loops.

See Cursor Pagination for full documentation and the 18-tool coverage matrix.

Next steps

• Add tasks so agents can assign work to each other
• Set up recurring tasks for cron-based automation
• Read the full architecture to understand orchestrators, instances, and namespaces
• Browse the full tools catalogue — 120 tools across 19 domains
• Review envelope safety before building drain loops in production