<p align="center">
<pre>
    ,;;;,.
   ;;O  O;;
   `;    ;'
    `;;;;'
   ~~/  \~~
  ~/    _ \~
 ~/   (.) \~
~/ ~~~~~~~~\~
</pre>
</p>

<h1 align="center">Clewso 🧶👀</h1>
<h3 align="center">The Open Source Context Server for AI Agents.</h3>

<p align="center">
  <strong>Runs locally. Indexes your repo. 100% Privacy.</strong>
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue" alt="License"></a>
  <a href="https://github.com/clewnet/clewso/actions/workflows/ci.yml"><img src="https://github.com/clewnet/clewso/actions/workflows/ci.yml/badge.svg" alt="CI Status"></a>
  <a href="https://pypi.org/project/clewso/"><img src="https://img.shields.io/pypi/v/clewso.svg" alt="PyPI"></a>
  <img src="https://img.shields.io/badge/status-alpha-orange" alt="Status">
</p>

---

Clewso indexes your codebase and gives AI agents **structured, navigable context** by combining **vector search** (Qdrant) with **graph traversal** (Neo4j). It solves the "Lost in the Middle" problem so your agents actually understand your code.

## Engine vs. Platform

| Feature | Engine (Open Source) | Platform (Enterprise) |
| :--- | :--- | :--- |
| Scope | Single Repo | Multi-Repo / Fleet |
| Data | Local Neo4j + Qdrant | Global Knowledge Graph |
| Ingestion | `clew-ingestion` library | Platform Worker + Control Plane |
| Policy | None | Backstop API (SOC2/Compliance) |

**Engine** is what you're looking at — the full context server (API, MCP tools, ingestion library, PR review CLI), running on your machine, under your control. **Platform** extends Engine across teams: fleet-wide indexing via a distributed worker that consumes the published `clew-ingestion` library, and policy enforcement via the Backstop API. [Contact us](mailto:matt@matchdav.io) for Platform access.

## Quick Start

### Install

```bash
# pipx (recommended)
pipx install clewso

# or from source
git clone https://github.com/clewnet/clewso.git
cd clewso
pip install -e .
```

### Prerequisites

- **Python 3.10+**
- **Docker & Docker Compose**
- **Qdrant v1.13.0+**
- **Neo4j 5.16+**

### Configuration

```bash
cp example.env .env
```

Edit `.env` to set your embedding provider (OpenAI or Ollama) and store credentials. The defaults work with `docker-compose up -d`.

### Start the Engine

```bash
docker-compose up -d
```

This launches the API, Qdrant, Neo4j, and Redis locally.

### Ingest a Repository

Ingestion is handled by the `clew-ingestion` library. Run it via the bundled Docker service:

```bash
# Ingest a remote repository
docker-compose run --rm ingestion python -m clew_ingestion.ingest https://github.com/your/repo

# Ingest a local repository
docker-compose run --rm -v $(pwd):/app/repo ingestion python -m clew_ingestion.ingest /app/repo
```

For ongoing updates, configure [webhook-driven incremental sync](#webhook-driven-incremental-sync).

### Use the CLI

```bash
# Analyze staged changes
clewso review --staged

# Analyze a PR (for CI/CD)
clewso review --pr --output markdown

# Configure editor AI agents (Claude Code, Cursor, Copilot, etc.)
clewso setup-editor

# Help
clewso --help
```

## Architecture

```mermaid
graph TD
    subgraph Engine
        API[Clew API] --> Qdrant[(Qdrant)]
        API --> Neo4j[(Neo4j)]
        MCP[MCP Server] --> API
        CLI[clewso CLI] --> API
        Ingest[clew-ingestion] --> Qdrant
        Ingest --> Neo4j
    end

    Agent[AI Agent] -->|MCP Protocol| MCP
    Webhook[GitHub / GitLab Webhook] -->|HMAC-signed| API
    
    subgraph Platform
        ControlPlane[Clew Control Plane]
        Worker[Clew Platform Worker] -->|Consumes| Ingest
        ControlPlane -.->|Manages| Worker
    end
```

## Features

| Feature | Description |
|---------|-------------|
| **Hybrid Search** | Vector similarity + graph traversal |
| **MCP Integration** | Works with Claude, Cursor, and custom agents |
| **PR Review CLI** | `clewso review --pr` — risk analysis and dependency graphs for staged changes and PRs |
| **Zero-Touch Ingestion** | Git URL → automatic indexing via `clew-ingestion` |
| **Mermaid Diagrams** | Visual dependency graphs from `explore_module` |
| **Deep Graph Traversal** | Multi-hop dependency analysis (Depth 1–3) |
| **Source Reader** | Secure file content retrieval API |
| **Incremental Sync** | Webhook-driven updates — sync in seconds, not minutes |

## MCP Tools

Clewso exposes three tools via the [Model Context Protocol](https://modelcontextprotocol.io/):

| Tool | Description |
|------|-------------|
| `search_codebase` | Semantic code search |
| `explore_module` | Traverse dependencies with Mermaid graphs |
| `verify_concept` | Validate assumptions against codebase |

### Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "clewso": {
      "command": "poetry",
      "args": ["run", "start"],
      "cwd": "/absolute/path/to/packages/clew-mcp",
      "env": {
        "CONTEXT_ENGINE_API_URL": "http://localhost:8000"
      }
    }
  }
}
```

Or use the CLI to auto-configure your editor:

```bash
clewso setup-editor claude-code
```

## GitHub Integration

Add context-aware PR analysis to your CI pipeline using the `clewso` CLI:

```yaml
# .github/workflows/clew-pr-analysis.yml
- name: Clewso PR Review
  run: clewso review --pr --output markdown >> $GITHUB_STEP_SUMMARY
  env:
    CLEW_API_URL: ${{ secrets.CLEW_API_URL }}
```

The `clewso review --pr` command diffs against `origin/main`, queries the Clewso API for dependency impact, and outputs a structured risk report. A reference workflow is included at `.github/workflows/clew-pr-analysis.yml`.

## Database Setup

Clewso automatically creates the required Neo4j schema on startup. No manual migration is needed.

**Auto-created constraints:**
- `file_repo_path_unique` — ensures `(repo_id, path)` uniqueness for Files
- `codeblock_unique` — ensures `(repo_id, file_path, name)` uniqueness for CodeBlocks

**Auto-created indexes:**
- `file_repo_id`, `codeblock_repo_id`, `module_repo_id`, `function_repo_id`

Verify with:

```bash
docker exec clewso-neo4j cypher-shell -u neo4j -p password "SHOW CONSTRAINTS;"
docker exec clewso-neo4j cypher-shell -u neo4j -p password "SHOW INDEXES;"
```

## Webhook-Driven Incremental Sync

Keep your index current with GitHub/GitLab webhooks. Clewso processes only changed files, reducing sync from minutes to seconds.

- **Selective processing** — only added/modified/removed files
- **HMAC signature verification** — secure webhook endpoints
- **Deduplication** — prevents duplicate processing via Redis
- **Smart fallback** — auto full-sync for large changesets (>100 files)

See [Webhook Setup](docs/webhooks.md) for configuration details.

## Documentation

- [API Contract](docs/api-contract.md)
- [MCP Tools](docs/mcp-tools.md)
- [Architecture](specs/architecture.md)
- [ADRs](docs/adr/)
- [Troubleshooting](docs/troubleshooting.md)
- [Migration Guide](docs/migration-guide.md)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. All contributions are subject to the [AGPL-3.0](LICENSE) license.

## License

Clewso is dual-licensed under [AGPL-3.0](LICENSE) and a commercial license. See [LICENSING.md](LICENSING.md) for details.
