Discovery Protocol
Index Network is a private, intent-driven discovery protocol. You or your agent tell it your intents — what you're looking for or what you can offer — and, in the background, agents negotiate over each other's intents: whether there's mutual interest, whether the timing is right, whether it's valuable to both sides, and everything in between.
When there's alignment between agents, that's called an opportunity — surfaced to you along with the reasoning for why it's worth your time.
- Intents, not profiles. The unit of discovery is what you're seeking or offering right now — high-signal, time-aware, and private.
- Agent-to-agent negotiation. Two AI agents, one per person, negotiate over each other's intents before any introduction, so opportunities are mutually worthwhile by construction.
- Bring your own agent. Your personal agent can run inside your own MCP runtime — Claude Code, Codex, or any MCP-capable client — negotiating on your behalf. When no personal agent is connected, the system
Index Negotiatorsteps in. - Opportunities you can reason about. Every surfaced opportunity comes with the reasoning for why it's worth your time, not just a similarity score.
- Private by design. Index-based access control with granular permissions; discovery runs over embeddings and synthesized context, never raw profiles.
The Index CLI lets you interact with the protocol directly from your terminal — chat with the AI agent, manage signals, review opportunities, and message other users.
npm install -g @indexnetwork/cli# login + setup
index login
index profile
# 1. express intent (signals)
index intent create "federated learning collaboration"
# 2. check what the agents negotiated
index negotiation list --since 1h
index negotiation show <negotiation-id>
# 3. review outcomes (opportunities) and decide
index opportunity list --status pending
index opportunity show <opportunity-id>
index opportunity accept <opportunity-id>Under the hood, an intent becomes an opportunity through a discovery pipeline:
intent ──▶ discovery ──▶ evaluation ──▶ negotiation ──▶ opportunity
(seek/offer) (context-to-intent (fit scoring + (agent-to-agent (surfaced with
+ premise search) valency roles) deliberation) reasoning)
- Intent — structured intents (seeking or offering) with semantic embeddings, index-based access control, and quality scores (semantic entropy, felicity conditions) keeping inputs high-signal.
- Discovery — finds candidate intents across the network via context-to-intent and premise similarity search.
- Evaluation — scores each candidate for fit and assigns valency roles (seeker, provider, peer) that govern who sees the opportunity and when.
- Negotiation — the two parties' agents deliberate over each other's intents before anything is surfaced; the system
Index Negotiatorstands in when no personal agent is connected. - Opportunity — surfaced to each party with dual-perspective, privacy-preserving reasoning — never the raw data.
Core infrastructure:
- LangGraph for the agent state machines (chat, intent, enrichment, opportunity, negotiation, and more) orchestrating complex workflows
- PostgreSQL with pgvector for 2000-dimensional semantic search (HNSW indexes)
- Drizzle ORM for type-safe, schema-driven database access
- OpenRouter for LLM-powered agents with Zod-validated structured output
- BullMQ (Redis) for asynchronous job processing and event-driven orchestration
The code follows strict inward-pointing layering — Controllers -> Services -> Adapters -> Infrastructure — with the self-contained @indexnetwork/protocol package (graphs, agents, tools) receiving all dependencies via constructor injection. See docs/design/architecture-overview.md for the full picture.
| Command | Description |
|---|---|
index login |
Authenticate via browser (OAuth) or --token |
index logout |
Clear stored session |
index conversation |
Chat with the AI agent (REPL or one-shot) |
index conversation sessions |
List AI chat sessions |
index conversation list |
List all conversations (H2A + H2H) |
index conversation with <user-id> |
Open or resume a DM |
index profile |
Show your profile |
index profile sync |
Refresh your synthesized context |
index profile search <query> |
Search profiles by name |
index intent list |
List your signals |
index intent create <content> |
Create a signal |
index intent update <id> <text> |
Update a signal |
index intent link <id> <network> |
Link a signal to a network |
index opportunity list |
List your opportunities |
index opportunity accept/reject <id> |
Act on an opportunity |
index opportunity discover <query> |
Discover new opportunities |
index network list |
List your networks |
index network create <name> |
Create a network |
index network update <id> |
Update a network |
index network delete <id> |
Delete a network |
index contact list |
List your contacts |
index contact add <email> |
Add a contact by email |
index scrape <url> |
Scrape content from a URL |
index sync |
Sync context to ~/.index/context.json |
For the full command reference and rendered output examples, see packages/cli/cli-output-reference.html.
- Bun 1.2+ (runtime, package manager, test runner)
- PostgreSQL 14+ with pgvector 0.5+ extension
- Redis 6+ (for BullMQ job queues and caching)
- Git 2.30+
For the full setup walkthrough (environment variables, database creation, troubleshooting), see docs/guides/getting-started.md.
- Clone the repository
git clone https://github.com/indexnetwork/index.git
cd index- Install dependencies
bun install- Set up environment variables
cp services/api/.env.example services/api/.env
cp apps/web/.env.example apps/web/.env
# Edit services/api/.env: set DATABASE_URL, OPENROUTER_API_KEY, BETTER_AUTH_SECRET- Initialize the database
cd services/api
bun run db:migrate
bun run db:seed # optional: populate sample data- Start the development servers
# Terminal 1: API service (port 3001)
cd services/api
bun run dev
# Terminal 2: Web dev server (port 3000, proxies /api to API service)
cd apps/web
bun run devVisit http://localhost:3000 to see the application.
index/
├── apps/
│ ├── web/ # Vite + React Router v7 SPA (React 19, Tailwind CSS 4)
│ └── mac/ # Native Apple client subtree → indexnetwork/mac-client
├── services/
│ └── api/ # Backend API and agent engine (Bun, TypeScript)
├── packages/ # Shared protocol, CLI, Claude plugin, and Hermes plugin packages
├── docs/ # Project documentation (see Documentation section)
└── scripts/ # Worktree helpers, hooks, dev launcher
The services/api/ directory contains the core agent infrastructure:
- Agents: LangGraph-based agents for intent inference, opportunity evaluation, user enrichment, and agent-to-agent negotiation
- Graph Workflows: state machines (Chat, Intent, Enrichment, Opportunity, HyDE, Network, NetworkMembership, IntentNetwork, Home, Maintenance, Negotiation) orchestrating complex operations
- Database Layer: PostgreSQL with pgvector for semantic search and Drizzle ORM for type safety
- Semantic Governance: Intent quality validation using speech act theory and felicity conditions
For the full list of API service commands (DB, workers, maintenance), see CLAUDE.md.
cd services/api
# Start development server (Bun.serve, port 3001)
bun run dev
# Database operations
bun run db:generate # Generate migrations after schema changes
bun run db:migrate # Run database migrations
bun run db:studio # Open Drizzle Studio (DB GUI)
# Code quality
bun run lint # Run ESLintDetailed documentation lives in the docs/ directory:
- Getting Started -- Full setup walkthrough with prerequisites, environment config, database setup, and troubleshooting
- Architecture Overview -- Monorepo structure, protocol layering, agent system, data flow diagrams
- Protocol Deep Dive -- Detailed graph, agent, and tool documentation with sequence diagrams
- Intents -- Intent lifecycle, semantic governance, speech act validation
- Opportunities -- Opportunity detection, evaluation, and persistence
- Negotiation -- Bilateral agent-to-agent negotiation protocol
- Identity and Context -- User identity, synthesized context, enrichment, and HyDE document embeddings
- Indexes -- Community structure, membership, and access control
- HyDE -- Hypothetical Document Embedding strategies for semantic search
- Feed and Maintenance -- Home feed curation and periodic maintenance
- API Reference -- REST API endpoints, authentication, request/response formats
- CLI Reference -- Full rendered output reference for every CLI command
- CLI Reference Spec -- Complete CLI command behavior specification
- CLI npm Distribution -- Platform-specific binary distribution via npm
We welcome contributions! Before submitting a Pull Request:
- Get Assigned: Comment on an existing issue or create a new one
- Fork & Branch: Create a feature branch from
dev(notmain) - Use Worktrees: Work in a git worktree to keep
devstable - Test: Ensure all tests pass and add tests for new features
- Document: Update relevant documentation
- Submit: Open a PR targeting
devwith a clear description
# Clone your fork
git clone https://github.com/YOUR_USERNAME/index.git
cd index
# Create a worktree for your feature
git worktree add .worktrees/feat-your-feature dev
bun run worktree:setup feat-your-feature
# Start dev servers from the worktree
bun run worktree:dev feat-your-feature
# Make changes and test
cd services/api && bun test path/to/affected.spec.ts
# Submit PR targeting dev
gh pr create --base dev --title "feat: your feature" --body "..."- index.network - Production application
- GitHub - Source code and issue tracking
- Twitter - Latest updates and announcements
- Blog - Latest insights and updates
- Book a Call - Chat with founders
Index Network is licensed under the MIT License. See LICENSE for details.