# Peeriodical

> Peeriodical is a platform for AI peer learning groups. Leaders create groups, members join via landing pages, session transcripts are imported and processed into a knowledge graph, and an MCP server exposes group knowledge to IDE tools and chatbots.

Peeriodical is built by Atomic 47 Labs / Worksona.io.

## Core Concept

Small peer groups (6-12 people) meet weekly to discuss AI topics. Sessions are transcribed, and transcripts are processed into a knowledge graph using Claude for entity extraction and OpenAI for embeddings. The knowledge graph is accessible via MCP (Model Context Protocol) so members can query their group's collective intelligence from any MCP-enabled tool — Claude Desktop, Claude Code, Cursor, Windsurf, ChatGPT, and more.

## Authentication

All API and MCP access uses Bearer token authentication. One Peeriodical token works for both REST API and MCP access.

- Header: `Authorization: Bearer <token>`
- Tokens are SHA-256 hashed (never stored raw)
- Each token is scoped to a specific group and set of permissions
- 401 = missing/invalid token, 403 = insufficient scope, 429 = rate limited

## MCP Server

Endpoint: `https://peeriodical.com/mcp`
Transport: Streamable HTTP with Bearer token auth

### MCP Tools (9)

- `search_knowledge_graph` — Search the group knowledge graph for topics, concepts, and discussions. Returns relevant passages, entities, and relationships. Parameters: query (required), passage_limit (default 8, max 20), entity_limit (default 5, max 20).
- `list_sessions` — List peer group sessions ordered by date descending. Parameters: page (default 1), limit (default 20, max 100).
- `get_session` — Get detailed information about a specific session by ID. Parameters: session_id (required).
- `download_session` — Download the full transcript text of a session. Parameters: session_id (required).
- `get_entity` — Get detailed information about a knowledge graph entity including citations and connected edges. Parameters: node_id (required).
- `explore_graph` — Explore the knowledge graph by listing edges connected to a node, optionally filtered by relation type. Parameters: node_id (required), relation_type (optional: discusses, uses, part_of, related_to, created_by, recommends, compares).
- `list_entities` — List knowledge graph entities ranked by mention count, optionally filtered by type. Parameters: type (optional: person, concept, tool, framework, methodology, organization, book, paper), limit (default 20, max 50).
- `import_session` — Import a session transcript. Creates a new session record and optionally builds the knowledge graph from it. Parameters: title (required), session_date (required, YYYY-MM-DD), transcript (required), summary (optional), tags (optional array), build_knowledge_graph (optional boolean).
- `get_group_info` — Get information about the current peer group including KG statistics. No parameters.

### MCP Resources (3)

- `group://overview` — Overview of the group with member count and KG stats.
- `group://sessions/recent` — 10 most recent sessions.
- `group://kg/top-entities` — 20 most mentioned entities.

## REST API

Base URL: `https://peeriodical.com/api/v1`

All endpoints require Bearer token auth unless noted as public.

### Sessions

- `GET /v1/sessions` — List all sessions. Scopes: sessions:read.
- `GET /v1/sessions/:date` — Get session by date. Scopes: sessions:read.
- `GET /v1/sessions/:date/download` — Download transcript. Scopes: sessions:read.
- `POST /v1/sessions/:date/publish` — Publish/unpublish session. Scopes: sessions:write.
- `GET /v1/sessions/search` — Semantic search across sessions. Scopes: sessions:read.
- `POST /v1/sessions/import` — Import session from file. Scopes: sessions:write.

### Knowledge Graph

- `GET /v1/kg/search` — Hybrid search (vector similarity + graph expansion). Scopes: kg:read.
- `GET /v1/kg/nodes` — List KG nodes. Scopes: kg:read.
- `GET /v1/kg/nodes/:id` — Get single node with edges and citations. Scopes: kg:read.
- `GET /v1/kg/edges` — List KG edges. Scopes: kg:read.
- `GET /v1/kg/stats` — KG statistics. Scopes: kg:read.
- `POST /v1/kg/build` — Build KG for a session. Scopes: kg:write.
- `POST /v1/kg/rebuild` — Full KG rebuild for group. Scopes: kg:write.

### Groups

- `GET /v1/groups` — List all groups. Public.
- `GET /v1/groups/:slug` — Get group by slug. Public.
- `GET /v1/groups/:slug/members` — List group members. Scopes: members:read.
- `DELETE /v1/groups/:slug/members/:id` — Remove member. Scopes: members:write.
- `GET /v1/groups/:slug/join-requests` — List join requests. Scopes: admin:read.
- `POST /v1/groups/:slug/join-requests` — Submit join request. Scopes: group:write.
- `PATCH /v1/groups/:slug/join-requests/:id` — Approve/reject request. Scopes: admin:write.

### Tokens

- `GET /v1/tokens` — List active tokens. Scopes: tokens:read.
- `POST /v1/tokens` — Generate new token. Scopes: tokens:write. Parameters: name (string, required), scopes (string[], required).
- `DELETE /v1/tokens/:id` — Revoke token. Scopes: tokens:write.

### Billing

- `POST /v1/billing/checkout` — Create Stripe checkout session.
- `POST /v1/billing/portal` — Access Stripe customer portal.

### Community

- `GET /v1/community` — Global community feed with cross-group content. Scopes: group:read.

## Token Scopes

- `sessions:read` — Read session data and transcripts
- `sessions:write` — Create, update, and publish sessions
- `sessions:import` — Import sessions from files
- `kg:read` — Read knowledge graph nodes, edges, and search
- `kg:write` — Build and modify the knowledge graph
- `group:read` — Read group information
- `group:write` — Modify group settings
- `members:read` — Read member list
- `members:write` — Manage group members
- `tokens:read` — List tokens
- `tokens:write` — Create and revoke tokens
- `admin:read` — Read admin data and join requests
- `admin:write` — Approve/reject requests, admin actions
- `emails:send` — Send emails to group members

## Knowledge Graph

The knowledge graph is built from session transcripts through a pipeline:

1. Transcripts are chunked (~400 tokens) preserving speaker attribution
2. Claude extracts entities and relationships as structured JSON
3. OpenAI generates embeddings (text-embedding-3-small, 1536 dimensions) stored in pgvector
4. Upsert logic merges nodes (increment mention_count, update last_seen) and edges (increment weight)
5. Citations link nodes and edges back to source transcript chunks

### Node Types

person, concept, tool, framework, methodology, organization, book, paper

### Edge Types

discusses, uses, part_of, related_to, created_by, recommends, compares, mentioned_with

### Search

Hybrid retrieval combines vector similarity search with graph expansion. A query returns matching passages with similarity scores plus connected entities and relationships.

## Pricing

### Free ($0)

- Join or start one group (up to 12 members)
- Weekly sessions with transcription
- Knowledge graph access (visual + MCP read-only)
- Session search and archive
- Community feed access
- 20 requests/minute
- 1 token, up to 50 sessions

### Pro ($100/month per group)

- Everything in Free
- Full API access (read + write)
- MCP full access (read + write)
- 100 requests/minute
- Reporting and analytics
- Article publishing
- Hands-on onboarding
- Custom group branding
- 5 tokens, up to 50 members, 500 sessions

### Enterprise (custom pricing)

- Everything in Pro
- Multiple peer groups under one organization
- Cross-group knowledge graph
- Admin oversight and network dashboard
- SSO and advanced security
- 500 requests/minute
- 20 tokens, unlimited members and sessions

## Pages

- [Join Now](https://peeriodical.com/now) — How it works and how to join or start a group
- [Browse Groups](https://peeriodical.com/groups) — Directory of active peer groups
- [Community](https://peeriodical.com/community) — Cross-group activity feed
- [Peer Intelligence](https://peeriodical.com/peer-intelligence) — Knowledge graph and MCP capabilities
- [MCP Documentation](https://peeriodical.com/mcp-docs) — Setup guides for Claude Desktop, Cursor, Windsurf
- [API Documentation](https://peeriodical.com/api-docs) — REST API reference
- [Platform Overview](https://peeriodical.com/platform-overview) — Technical architecture and security
- [Pricing](https://peeriodical.com/pricing) — Plans and feature comparison
- [API Playground](https://peeriodical.com/playground) — Interactive API explorer
- [Calendar](https://peeriodical.com/calendar) — Upcoming sessions across groups

## Multi-Tenancy

Row-Level Security (RLS) enforces group isolation at the database level. Group A cannot access Group B's data. Each token is scoped to exactly one group.

## Open Standards

Peeriodical uses MCP (Model Context Protocol) as an open standard for AI tool integration. Any MCP-compatible client can connect to a group's knowledge base using a single bearer token.