# reqall.net — System Documentation

## What is reqall.net?

reqall.net is a **persistent semantic knowledgebase for AI agents**. It provides long-term memory that agents can read and write through the Model Context Protocol (MCP) or a REST API. Humans manage and visualize the knowledge through a web dashboard.

The core idea: agents discover prior decisions, specifications, bugs, and architecture notes via semantic search, and store new findings for future retrieval — across sessions, tools, and projects.

## Architecture Overview

```
┌─────────────────┐     ┌──────────────────┐     ┌────────────────┐
│  MCP Clients    │     │  REST API        │     │  Web Dashboard │
│  (Claude Code,  │────▶│  Clients         │────▶│  (Browser)     │
│   Claude Desktop│     │  (Cursor, etc.)  │     │                │
│   Claude.ai)    │     │                  │     │                │
└────────┬────────┘     └────────┬─────────┘     └───────┬────────┘
         │                       │                       │
         │ MCP (JSON-RPC)        │ REST (JSON)           │ REST (JSON)
         │ OAuth 2.1 Bearer      │ API Key Bearer        │ Session Cookie
         ▼                       ▼                       ▼
┌────────────────────────────────────────────────────────────────────┐
│                     reqall.net Server                               │
│                                                                    │
│  POST /mcp          — MCP JSON-RPC handler                        │
│  /api/v1/projects   — Project CRUD                                │
│  /api/v1/records    — Record CRUD                                 │
│  /api/v1/links      — Link CRUD                                   │
│  /api/v1/graph      — Graph traversal                             │
│  /api/v1/keys       — API key management                         │
│  /api/v1/changes    — Change detection                            │
│  /api/v1/billing    — Subscription management                     │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
┌────────────────────────────────────────────────────────────────────┐
│  Database + Vector Search + Embedding Service                      │
└────────────────────────────────────────────────────────────────────┘
```

## Data Model

### Projects

Projects are containers for records. They are scoped to a user and typically named using `org/repo` format to match git remotes (e.g. `acme/widget`). For monorepo subdirectories, use path format (e.g. `acme/widget/frontend`).

| Field        | Type      | Description                              |
|-------------|-----------|------------------------------------------|
| `id`        | integer   | Auto-generated primary key               |
| `name`      | string    | Unique per user, e.g. `org/repo`         |
| `created_at`| timestamp | Creation time                            |
| `updated_at`| timestamp | Last modification time                   |

### Records

Records are the core knowledge units. Each record has a kind, title, optional body, and status. Content is automatically embedded into a vector for semantic search.

| Field        | Type      | Description                              |
|-------------|-----------|------------------------------------------|
| `id`        | integer   | Auto-generated primary key               |
| `project_id`| integer   | Foreign key to project                   |
| `kind`      | enum      | `issue`, `spec`, `arch`, `test`, `todo`  |
| `title`     | string    | Short summary (max 500 chars)            |
| `body`      | string    | Detailed content (max 32,000 chars)      |
| `status`    | enum      | `open`, `resolved`, `archived`, `active`, `inactive` |
| `vector`    | vector    | Embedding vector (auto-generated)        |
| `created_at`| timestamp | Creation time                            |
| `updated_at`| timestamp | Last modification time                   |

**Record Kinds:**

- `issue` — Bugs, tasks, problems to fix
- `spec` — Requirements, decisions, acceptance criteria
- `arch` — Architecture notes, design patterns, system structure
- `test` — Test scenarios, test plans, validation criteria
- `todo` — Planned work, next steps, action items

**Record Statuses:**

- `open` — Active, unresolved (default for new records)
- `resolved` — Completed, fixed
- `archived` — No longer relevant but preserved
- `active` — Currently in use (for specs, arch)
- `inactive` — Deprecated or superseded

### Links

Links are directed relationships between any two entities (records or projects). They form a knowledge graph that supports impact analysis and dependency tracking.

| Field          | Type    | Description                                     |
|---------------|---------|--------------------------------------------------|
| `id`          | integer | Auto-generated primary key                       |
| `source_id`   | integer | Source entity ID                                 |
| `source_table`| enum    | `records` or `projects`                          |
| `target_id`   | integer | Target entity ID                                 |
| `target_table`| enum    | `records` or `projects`                          |
| `relationship`| enum    | `blocks`, `implements`, `tests`, `parent`, `related` |

**Relationship Types:**

- `blocks` — Source must be resolved before target can proceed
- `implements` — Source realizes/implements target's specification
- `tests` — Source validates/tests target
- `parent` — Source contains target (hierarchical)
- `related` — General association

## Authentication

reqall.net supports three authentication methods, all mapping to a single user account:

### 1. MCP OAuth 2.1 (Claude Code, Claude Desktop, Claude.ai)

Standard OAuth 2.1 with PKCE. MCP clients handle the flow automatically.

- Discovery: `GET /.well-known/oauth-authorization-server`
- Protected resource: `GET /.well-known/oauth-protected-resource`
- Authorization: `GET /oauth/authorize`
- Token exchange: `POST /oauth/token`
- Dynamic client registration: `POST /oauth/register`
- Token format: Bearer token in `Authorization` header

### 2. CLI Plugin Auth (Cursor, Copilot, Gemini)

Polling-based flow via `npx @reqall/auth`:

1. CLI initiates auth, opens browser for Google OAuth consent
2. CLI polls until authorization completes
3. Returns an API key (`rq_...`) to configure in the plugin

### 3. Manual API Keys

Generate keys in the dashboard (Keys tab). Keys use the `rq_` prefix. Pass in the `Authorization: Bearer rq_...` header.

## Key Behaviors

### Semantic Search

All record content (title + body) is automatically embedded. Search queries are embedded at query time and matched using cosine similarity. Results are ranked by similarity score.

### Automatic Deduplication

When creating a new record, the system checks for existing records in the same project with the same kind and ≥85% cosine similarity. If a match is found, the existing record is updated instead of creating a duplicate. This means agents can freely upsert records without worrying about creating duplicates.

### Impact Analysis

The `impact` tool/endpoint performs recursive graph traversal from a starting entity, following outgoing links up to N hops (default 5). This answers "what would be affected if this changes?" — useful for understanding downstream dependencies before making changes.

### Real-time Sync

The dashboard receives real-time updates. When any agent or API client modifies data, all connected dashboard sessions refresh automatically.

## Plans and Billing

| Plan       | Write Access | Limits                                      |
|-----------|-------------|-----------------------------------------------|
| Free Trial | Yes (7 days) | Full access during trial                     |
| Pro ($39/mo)| Yes         | 1 GB storage + 250,000 requests included      |
| Expired Trial | Read-only | Search and read still work                  |

Overages (Pro plan): $9/GB/month storage, $0.001/request beyond included allotment.

## Common Agent Workflows

### Store a finding

```
1. upsert_project("org/repo")          → get project_id
2. upsert_record(project_id, kind="issue", title="...", body="...")
   → auto-embeds, auto-deduplicates
```

### Retrieve context before working

```
1. search("authentication flow changes")  → ranked results
2. get_record(id)                          → full details
3. list_links(entity_id=id)               → related records
```

### Track dependencies

```
1. upsert_link(source_id=A, target_id=B, relationship="blocks")
2. impact(entity_id=B)                     → downstream effects
```

### Organize knowledge

```
1. list_projects()                         → discover projects
2. list_records(project_id=X, kind="spec") → enumerate specs
3. upsert_record(id=Y, status="resolved") → mark complete
```