Cognio

Persistent semantic memory server for AI assistants via Model Context Protocol (MCP)

Cognio is a Model Context Protocol (MCP) server that provides persistent semantic memory for AI assistants. Unlike ephemeral chat history, Cognio stores context permanently and enables semantic search across conversations.

Built for:

• Personal knowledge base that grows over time

• Multi-project context management

• Research notes and learning journal

• Conversation history with semantic retrieval

Features

• Semantic Search: Find memories by meaning using sentence-transformers

• LEANN Vector Search (Optional): Lazy-built index with on-demand recomputation to reduce startup memory

• Multilingual Support: Search in 100+ languages seamlessly

• Persistent Storage: SQLite-based storage that survives across sessions

• Project Organization: Organize memories by project and tags

• Auto-Tagging: Automatic tag generation via LLM (GPT-4, Groq, etc)

• Text Summarization: Extractive and abstractive summarization for long texts

• MCP Integration: One-click setup for VS Code, Claude, Cursor, and more

• RESTful API: Standard HTTP API with OpenAPI documentation

• Export Capabilities: Export to JSON or Markdown format

• Docker Support: Simple deployment with docker-compose

Quick Start

1. Start the Server

git clone https://github.com/0xReLogic/Cognio.git
cd Cognio
docker-compose up -d

Server runs at http://localhost:8080

2. Auto-Configure AI Clients

The MCP server automatically configures supported AI clients on first start:

Supported Clients:

• Claude Desktop

• Claude Code (CLI)

• VS Code (GitHub Copilot)

• Cursor

• Continue.dev

• Cline

• Windsurf

• Kiro

• Gemini CLI

Quick Setup:

Run the auto-setup script to configure all clients at once:

cd mcp-server
npm run setup

This generates MCP configs for all 9 supported clients automatically.

Manual Configuration:

See mcp-server/README.md for client-specific MCP configuration examples.

On first run, Cognio auto-generates cognio.md in your workspace with usage guide for AI tools.

3. Test It

# Save a memory
curl -X POST http://localhost:8080/memory/save \
  -H "Content-Type: application/json" \
  -d '{"text": "Docker allows running apps in containers", "project": "LEARNING"}'

# Search memories
curl "http://localhost:8080/memory/search?q=containers"

Or use naturally in your AI client:

"Search my memories for Docker information"
"Remember this: FastAPI is a modern Python web framework"

4. Web UI Dashboard

Access the interactive memory dashboard:

http://localhost:8080/ui

Features:

• Browse and search all memories

• Add/edit memories with markdown preview

• View statistics and insights

• Organize by project and tags

• Bulk operations (select, delete)

• Dark/light theme toggle

• Works locally and in Docker

The dashboard auto-detects the API server, so it works on localhost, Docker containers, and remote deployments.

Documentation

• API Reference - Complete endpoint documentation

• Examples - Usage patterns and integrations

• Quickstart - Installation and configuration

MCP Tools

When using the MCP server, you have access to 11 specialized tools:

Active Project Workflow:

1. list_projects() → See: Helios-LoadBalancer (45), Cognio-Memory (23), ...
2. set_active_project("Helios-LoadBalancer")
3. save_memory("Cache TTL is 300s") → Auto-saves to Helios-LoadBalancer
4. search_memory("cache settings") → Auto-searches in Helios-LoadBalancer only
5. list_memories() → Lists only Helios-LoadBalancer memories

Project Isolation:
Always specify a project name OR use set_active_project to keep memories organized and prevent mixing contexts between different workspaces.

API Endpoints

Interactive docs: http://localhost:8080/docs

Configuration

Environment variables (see .env.example):

Copy the example and edit your local overrides:

cp .env.example .env

# Database
DB_PATH=./data/memory.db

# Embeddings
EMBED_MODEL=all-MiniLM-L6-v2
EMBED_DEVICE=cpu
EMBEDDING_CACHE_PATH=./data/embedding_cache.pkl

# API
API_HOST=0.0.0.0
API_PORT=8080
# Optional API key for auth
API_KEY=your-secret-key

# Search
DEFAULT_SEARCH_LIMIT=5
SIMILARITY_THRESHOLD=0.4
HYBRID_ENABLED=true
HYBRID_MODE=rerank        # candidate | rerank
HYBRID_ALPHA=0.6          # 0..1, higher = more semantic
HYBRID_RERANK_TOPK=100    # rerank candidate pool size

# LEANN vector search (optional)
LEANN_ENABLED=false
LEANN_INDEX_PATH=./data/leann/memories.leann
LEANN_BACKEND=hnsw
LEANN_LAZY_BUILD=true
LEANN_RECOMPUTE_ON_SEARCH=true
LEANN_WARMUP_ON_START=false

# Summarization
SUMMARIZATION_ENABLED=true
SUMMARIZATION_METHOD=abstractive   # extractive | abstractive
SUMMARIZATION_EMBED_MODEL=all-MiniLM-L6-v2

# Auto-tagging (Optional)
AUTOTAG_ENABLED=true
LLM_PROVIDER=groq
GROQ_API_KEY=your-groq-key
GROQ_MODEL=openai/gpt-oss-120b
# OPENAI_API_KEY=your-openai-api-key
# OPENAI_MODEL=gpt-4o-mini

# Performance
MAX_TEXT_LENGTH=10000
BATCH_SIZE=32
SUMMARIZE_THRESHOLD=50

# Logging
LOG_LEVEL=info

Auto-Tagging Models:

• openai/gpt-oss-120b - High quality

• gpt-4o-mini - OpenAI, fast and cheap

• llama-3.3-70b-versatile - Groq, balanced

• llama-3.1-8b-instant - Groq, fastest

See .env.example for all available options and recommendations.

Project Structure

cognio/
├── src/                # Core application
│   ├── main.py         # FastAPI app
│   ├── config.py       # Environment config
│   ├── models.py       # Data schemas
│   ├── database.py     # SQLite operations
│   ├── embeddings.py   # Semantic search
│   ├── memory.py       # Memory CRUD
│   ├── autotag.py      # Auto-tagging
│   └── utils.py        # Helpers
│
├── mcp-server/         # MCP integration
│   ├── index.js        # MCP server
│   └── package.json    # Dependencies
│
├── scripts/            # Utilities
│   ├── setup-clients.js  # Auto-config AI clients
│   ├── backup.sh       # Database backup
│   └── migrate.py      # Schema migrations
│
├── tests/              # Test suite
├── docs/               # Documentation
└── examples/           # Usage examples

Development

# Install dependencies
poetry install

# Run tests
pytest

# Start development server
uvicorn src.main:app --reload

Tech Stack

• Backend: Python 3.11+, FastAPI, Uvicorn

• Database: SQLite with JSON support

• Embeddings: sentence-transformers (paraphrase-multilingual-mpnet-base-v2, 768-dim)

• MCP Server: Node.js, @modelcontextprotocol/sdk

• Auto-Tagging: Api

• Testing: pytest, pytest-asyncio, pytest-cov

• Deployment: Docker, docker-compose

Performance

License

MIT License - see LICENSE

Links

• Documentation: docs/

• Issues: GitHub Issues

• Releases: GitHub Releases

Built for better AI conversations