Connapse

<p align="center"> <img src="connapse-logo-v27-teal.svg" alt="Connapse logo" width="375" /> </p> <p align="center"> <em>Stop losing context between AI sessions. Give your agents persistent, searchable memory.</em> </p> <p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a> <a href="https://dotnet.microsoft.com/"><img src="https://img.shields.io/badge/.NET-10.0-512BD4" alt=".NET"></a> <a href="https://github.com/Destrayon/Connapse/actions"><img src="https://img.shields.io/github/actions/workflow/status/Destrayon/Connapse/ci.yml?branch=main&label=build" alt="Build"></a> <a href="https://github.com/Destrayon/Connapse/actions"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Destrayon/Connapse/badges/tests.json" alt="Tests"></a> <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a> <a href="https://github.com/Destrayon/Connapse/issues"><img src="https://img.shields.io/github/issues/Destrayon/Connapse" alt="GitHub Issues"></a> <a href="https://github.com/Destrayon/Connapse/stargazers"><img src="https://img.shields.io/github/stars/Destrayon/Connapse?style=social" alt="GitHub Stars"></a> <a href="https://glama.ai/mcp/servers/Destrayon/Connapse"><img src="https://glama.ai/mcp/servers/Destrayon/Connapse/badges/score.svg" alt="Connapse MCP server"></a> <a href="https://github.com/Destrayon/Connapse#-quick-start"><img src="https://img.shields.io/badge/Docker-ready-2496ED?logo=docker" alt="Docker"></a> </p> <p align="center"> <img src="docs/demos/hero-upload-search.gif" alt="Connapse demo — upload a PDF, search with hybrid vector and keyword search, get results with source citations in seconds" width="720" /> </p>

Your AI agents forget everything between sessions. Connapse fixes that.

Every time you start a new conversation, your AI agent starts from zero — no memory of past research, no access to your documents, no accumulated knowledge. Connapse is an open-source knowledge backend that gives agents persistent, searchable memory. Upload documents or point it at your existing Amazon S3 buckets, Azure Blob Storage containers, or local filesystems. Agents query and build their own research corpus via 11 MCP tools, REST API, or CLI. Container-isolated, hybrid search (vector + keyword), self-hosted and private. Deploy in 60 seconds with Docker. Built on .NET 10.

<details> <summary><strong>🤖 AI Agent Integration</strong> — Claude queries and builds your knowledge base via MCP</summary> <br> <p align="center"> <img src="docs/demos/mcp-agent-integration.gif" alt="Claude querying Connapse knowledge base via MCP server — asks about preventing cascading failures in microservices, gets structured answer with circuit breaker pattern details cited from distributed-systems-notes.md" width="720" /> </p>

AI agents query your knowledge base through the MCP server, receiving structured answers with source citations from your documents.

</details> <details> <summary><strong>🎛️ Your Knowledge, Your Rules</strong> — Runtime configuration without restarting</summary> <br> <p align="center"> <img src="docs/demos/settings-providers.gif" alt="Connapse settings panel — switching embedding providers, adjusting chunking parameters, and configuring search settings at runtime without restart" width="720" /> </p>

Switch embedding providers, tune chunking parameters, and configure search — all at runtime, without restarting.

</details>

---

📦 Quick Start

git clone https://github.com/Destrayon/Connapse.git && cd Connapse && docker-compose up -d
# Open http://localhost:5001

Prerequisites

• Docker & Docker Compose
• .NET 10 SDK (for development)
• (Optional) Ollama for local embeddings

Run with Docker Compose

# Clone the repository
git clone https://github.com/Destrayon/Connapse.git
cd Connapse

# Set required auth environment variables (or use a .env file)
export CONNAPSE_ADMIN_EMAIL=admin@example.com
export CONNAPSE_ADMIN_PASSWORD=YourSecurePassword123!
export Identity__Jwt__Secret=$(openssl rand -base64 64)

# Start all services (PostgreSQL, MinIO, Web App)
docker-compose up -d

# Open http://localhost:5001 — log in with the admin credentials above

The first run will:

1. Pull Docker images (~2-5 minutes)
2. Initialize PostgreSQL with pgvector extension and run EF Core migrations
3. Create MinIO buckets
4. Seed the admin account (from env vars) and start the web application

Development Setup

# Start infrastructure only (database + object storage)
docker-compose up -d postgres minio

# Run the web app locally
dotnet run --project src/Connapse.Web

# Run all tests
dotnet test

# Run just unit tests
dotnet test --filter "Category=Unit"

Using the CLI

Install the CLI (choose one option):

# Option A: .NET Global Tool (requires .NET 10)
dotnet tool install -g Connapse.CLI

# Option B: Download native binary from GitHub Releases (no .NET required)
# https://github.com/Destrayon/Connapse/releases

Basic usage:

# Authenticate first
connapse auth login --url https://localhost:5001

# Create a container (project)
connapse container create my-project --description "My knowledge base"

# Upload files
connapse upload ./documents --container my-project

# Search
connapse search "your query" --container my-project

# Update to latest release (--pre to include alpha/pre-release builds)
connapse update
connapse update --pre

Using with Claude (MCP)

Connapse includes a Model Context Protocol (MCP) server for integration with Claude and any MCP client.

Setup: Create an agent API key via the web UI (Settings → Agent API Keys) or CLI (connapse auth agent-key create), then add the config snippet for your client:

<details> <summary><strong>Claude Code (CLI)</strong></summary>

claude mcp add connapse --transport streamable-http http://localhost:5001/mcp --header "X-Agent-Api-Key: YOUR_API_KEY"

</details> <details> <summary><strong>Claude Desktop</strong></summary>

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "connapse": {
      "transport": "streamable-http",
      "url": "http://localhost:5001/mcp",
      "headers": {
        "X-Agent-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

</details> <details> <summary><strong>VS Code / Cursor</strong></summary>

Add to your .vscode/settings.json (VS Code) or Cursor MCP config:

{
  "mcp": {
    "servers": {
      "connapse": {
        "transport": "streamable-http",
        "url": "http://localhost:5001/mcp",
        "headers": {
          "X-Agent-Api-Key": "${input:connapseApiKey}"
        }
      }
    }
  }
}

VS Code will prompt for the API key on first use.

</details>

The MCP server exposes 11 tools:

| Tool | Description | |------|-------------| | container_create | Create a new container for organizing files | | container_list | List all containers with document counts | | container_delete | Delete a container | | container_stats | Get container statistics (documents, chunks, storage, embeddings) | | upload_file | Upload a single file to a container | | bulk_upload | Upload up to 100 files in one operation | | list_files | List files and folders at a path | | get_document | Retrieve full parsed text content of a document | | delete_file | Delete a single file from a container | | bulk_delete | Delete up to 100 files in one operation | | search_knowledge | Semantic, keyword, or hybrid search within a container |

Full reference: See docs/mcp-tools.md for parameter tables, return formats, error cases, and usage examples.

Write guards: Amazon S3 and Azure Blob Storage containers are read-only (synced from source). Filesystem containers respect per-container permission flags. Upload and delete tools will return an error for containers that block writes.

<details> <summary><strong>Example prompts</strong> — what to ask your agent</summary>

• "Create a container called 'project-research' for my architecture notes"
• "Upload all the PDFs in my downloads folder to the project-research container"
• "Search my project-research container for information about rate limiting strategies"
• "List all files in the /notes/ folder of my project-research container"
• "Get the full text of distributed-systems-notes.md from project-research"
• "Delete meeting-2026-03-14.md from project-research and upload this updated version"
• "Delete all files in the /drafts/ folder of project-research"
• "How many documents and chunks are in my project-research container?"

</details> <details> <summary><strong>Troubleshooting</strong></summary>

Connection refused on localhost:5001 — Docker not running or port conflict. Check docker compose ps and docker compose logs web.

401 Unauthorized / API key not working — Verify the key in Settings > Agent API Keys. Keys are shown once at creation.

Tools not appearing in Claude — Restart your MCP client after config changes. Verify endpoint with curl http://localhost:5001/mcp.

Uploads failing or timing out — Check file type is in the allowlist. Max file size depends on server config.

Search returns no results — Documents need time to embed after upload. Check container stats for embedding progress.

</details>

---

🚀 Features

• 🗂️ Container-Isolated Knowledge — Each project gets its own vector index, storage connector, and search configuration. No cross-contamination between projects, teams, or clients.
• 🔍 Hybrid Search — Vector similarity + keyword full-text with configurable fusion (convex combination, DBSF, AutoCut). Get results that pure vector search misses.
• **🧠 Mu