{"id":31684546,"url":"https://github.com/0xrelogic/cognio","last_synced_at":"2026-05-15T18:34:47.535Z","repository":{"id":318205871,"uuid":"1070331253","full_name":"0xReLogic/Cognio","owner":"0xReLogic","description":"Persistent semantic memory server for MCP - Give your AI long-term memory that survives across conversations. Lightweight Python server with SQLite storage and semantic search.","archived":false,"fork":false,"pushed_at":"2025-10-05T20:23:13.000Z","size":74,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-05T20:41:14.469Z","etag":null,"topics":["ai-memory","chatgpt","claude","copilot","embeddings","long-term-memory","machine-learning","mcp","mcp-server","model-context-protocol","nlp","semantic-search","sentence-transformers","vector-database"],"latest_commit_sha":null,"homepage":"https://github.com/0xReLogic/Cognio/blob/main/QUICKSTART.md","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0xReLogic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-05T18:03:43.000Z","updated_at":"2025-10-05T20:23:17.000Z","dependencies_parsed_at":"2025-10-05T20:41:17.113Z","dependency_job_id":null,"html_url":"https://github.com/0xReLogic/Cognio","commit_stats":null,"previous_names":["0xrelogic/cognio"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/0xReLogic/Cognio","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xReLogic%2FCognio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xReLogic%2FCognio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xReLogic%2FCognio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xReLogic%2FCognio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0xReLogic","download_url":"https://codeload.github.com/0xReLogic/Cognio/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xReLogic%2FCognio/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278909746,"owners_count":26066897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-memory","chatgpt","claude","copilot","embeddings","long-term-memory","machine-learning","mcp","mcp-server","model-context-protocol","nlp","semantic-search","sentence-transformers","vector-database"],"created_at":"2025-10-08T08:09:51.296Z","updated_at":"2026-05-15T18:34:47.529Z","avatar_url":"https://github.com/0xReLogic.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cognio\n\n\u003e Persistent semantic memory server for AI assistants via Model Context Protocol (MCP)\n\n[![CI/CD](https://github.com/0xReLogic/Cognio/actions/workflows/ci.yml/badge.svg)](https://github.com/0xReLogic/Cognio/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.118.0-009688.svg)](https://fastapi.tiangolo.com)\n\nCognio 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.\n\n**Built for:**\n- Personal knowledge base that grows over time\n- Multi-project context management\n- Research notes and learning journal\n- Conversation history with semantic retrieval\n\n## Features\n\n- **Semantic Search**: Find memories by meaning using sentence-transformers\n- **LEANN Vector Search (Optional)**: Lazy-built index with on-demand recomputation to reduce startup memory\n- **Multilingual Support**: Search in 100+ languages seamlessly\n- **Persistent Storage**: SQLite-based storage that survives across sessions\n- **Project Organization**: Organize memories by project and tags\n- **Auto-Tagging**: Automatic tag generation via LLM (GPT-4, Groq, etc)\n- **Text Summarization**: Extractive and abstractive summarization for long texts\n- **MCP Integration**: One-click setup for VS Code, Claude, Cursor, and more\n- **RESTful API**: Standard HTTP API with OpenAPI documentation\n- **Export Capabilities**: Export to JSON or Markdown format\n- **Docker Support**: Simple deployment with docker-compose\n\n## Quick Start\n\n### 1. Start the Server\n\n```bash\ngit clone https://github.com/0xReLogic/Cognio.git\ncd Cognio\ndocker-compose up -d\n```\n\nServer runs at `http://localhost:8080`\n\n### 2. Auto-Configure AI Clients\n\nThe MCP server automatically configures supported AI clients on first start:\n\n**Supported Clients:**\n- Claude Desktop\n- Claude Code (CLI)\n- VS Code (GitHub Copilot)\n- Cursor\n- Continue.dev\n- Cline\n- Windsurf\n- Kiro\n- Gemini CLI\n\n**Quick Setup:**\n\nRun the auto-setup script to configure all clients at once:\n```bash\ncd mcp-server\nnpm run setup\n```\n\nThis generates MCP configs for all 9 supported clients automatically.\n\n**Manual Configuration:**\n\nSee [mcp-server/README.md](mcp-server/README.md) for client-specific MCP configuration examples.\n\nOn first run, Cognio auto-generates `cognio.md` in your workspace with usage guide for AI tools.\n\n### 3. Test It\n\n```bash\n# Save a memory\ncurl -X POST http://localhost:8080/memory/save \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"text\": \"Docker allows running apps in containers\", \"project\": \"LEARNING\"}'\n\n# Search memories\ncurl \"http://localhost:8080/memory/search?q=containers\"\n```\n\nOr use naturally in your AI client:\n```\n\"Search my memories for Docker information\"\n\"Remember this: FastAPI is a modern Python web framework\"\n```\n\n### 4. Web UI Dashboard\n\nAccess the interactive memory dashboard:\n```\nhttp://localhost:8080/ui\n```\n\nFeatures:\n- Browse and search all memories\n- Add/edit memories with markdown preview\n- View statistics and insights\n- Organize by project and tags\n- Bulk operations (select, delete)\n- Dark/light theme toggle\n- Works locally and in Docker\n\nThe dashboard auto-detects the API server, so it works on localhost, Docker containers, and remote deployments.\n\n## Documentation\n\n- **[API Reference](docs/api.md)** - Complete endpoint documentation\n- **[Examples](docs/examples.md)** - Usage patterns and integrations\n- **[Quickstart](docs/quickstart.md)** - Installation and configuration\n\n## MCP Tools\n\nWhen using the MCP server, you have access to 11 specialized tools:\n\n| Tool | Description |\n|------|-------------|\n| `save_memory` | Save text with optional project/tags (auto-tagging enabled) |\n| `search_memory` | Semantic search with project filtering |\n| `list_memories` | List memories with pagination and filters |\n| `get_memory_stats` | Get storage statistics and insights |\n| `archive_memory` | Soft delete a memory (recoverable) |\n| `delete_memory` | Permanently delete a memory by ID |\n| `export_memories` | Export memories to JSON or Markdown |\n| `summarize_text` | Summarize long text (extractive or LLM-based) |\n| **`set_active_project`** | **Set active project context (auto-applies to all operations)** |\n| **`get_active_project`** | **View currently active project** |\n| **`list_projects`** | **List all available projects from database** |\n\n**Active Project Workflow:**\n```\n1. list_projects() → See: Helios-LoadBalancer (45), Cognio-Memory (23), ...\n2. set_active_project(\"Helios-LoadBalancer\")\n3. save_memory(\"Cache TTL is 300s\") → Auto-saves to Helios-LoadBalancer\n4. search_memory(\"cache settings\") → Auto-searches in Helios-LoadBalancer only\n5. list_memories() → Lists only Helios-LoadBalancer memories\n```\n\n**Project Isolation:**  \nAlways specify a `project` name OR use `set_active_project` to keep memories organized and prevent mixing contexts between different workspaces.\n\n## API Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/health` | Health check |\n| POST | `/memory/save` | Save new memory |\n| GET | `/memory/search` | Semantic/Hybrid search |\n| GET | `/memory/list` | List memories with filters |\n| DELETE | `/memory/{id}` | Delete memory by ID |\n| POST | `/memory/bulk-delete` | Bulk delete by project |\n| GET | `/memory/stats` | Get statistics |\n| GET | `/memory/export` | Export memories |\n| POST | `/memory/summarize` | Summarize long text |\n\nInteractive docs: http://localhost:8080/docs\n\n## Configuration\n\nEnvironment variables (see `.env.example`):\n\nCopy the example and edit your local overrides:\n\n```bash\ncp .env.example .env\n```\n\n```bash\n# Database\nDB_PATH=./data/memory.db\n\n# Embeddings\nEMBED_MODEL=all-MiniLM-L6-v2\nEMBED_DEVICE=cpu\nEMBEDDING_CACHE_PATH=./data/embedding_cache.pkl\n\n# API\nAPI_HOST=0.0.0.0\nAPI_PORT=8080\n# Optional API key for auth\nAPI_KEY=your-secret-key\n\n# Search\nDEFAULT_SEARCH_LIMIT=5\nSIMILARITY_THRESHOLD=0.4\nHYBRID_ENABLED=true\nHYBRID_MODE=rerank        # candidate | rerank\nHYBRID_ALPHA=0.6          # 0..1, higher = more semantic\nHYBRID_RERANK_TOPK=100    # rerank candidate pool size\n\n# LEANN vector search (optional)\nLEANN_ENABLED=false\nLEANN_INDEX_PATH=./data/leann/memories.leann\nLEANN_BACKEND=hnsw\nLEANN_LAZY_BUILD=true\nLEANN_RECOMPUTE_ON_SEARCH=true\nLEANN_WARMUP_ON_START=false\n\n# Summarization\nSUMMARIZATION_ENABLED=true\nSUMMARIZATION_METHOD=abstractive   # extractive | abstractive\nSUMMARIZATION_EMBED_MODEL=all-MiniLM-L6-v2\n\n# Auto-tagging (Optional)\nAUTOTAG_ENABLED=true\nLLM_PROVIDER=groq\nGROQ_API_KEY=your-groq-key\nGROQ_MODEL=openai/gpt-oss-120b\n# OPENAI_API_KEY=your-openai-api-key\n# OPENAI_MODEL=gpt-4o-mini\n\n# Performance\nMAX_TEXT_LENGTH=10000\nBATCH_SIZE=32\nSUMMARIZE_THRESHOLD=50\n\n# Logging\nLOG_LEVEL=info\n```\n\n**Auto-Tagging Models:**\n- `openai/gpt-oss-120b` - High quality \n- `gpt-4o-mini` - OpenAI, fast and cheap\n- `llama-3.3-70b-versatile` - Groq, balanced\n- `llama-3.1-8b-instant` - Groq, fastest\n\nSee `.env.example` for all available options and recommendations.\n\n## Project Structure\n\n```\ncognio/\n├── src/                # Core application\n│   ├── main.py         # FastAPI app\n│   ├── config.py       # Environment config\n│   ├── models.py       # Data schemas\n│   ├── database.py     # SQLite operations\n│   ├── embeddings.py   # Semantic search\n│   ├── memory.py       # Memory CRUD\n│   ├── autotag.py      # Auto-tagging\n│   └── utils.py        # Helpers\n│\n├── mcp-server/         # MCP integration\n│   ├── index.js        # MCP server\n│   └── package.json    # Dependencies\n│\n├── scripts/            # Utilities\n│   ├── setup-clients.js  # Auto-config AI clients\n│   ├── backup.sh       # Database backup\n│   └── migrate.py      # Schema migrations\n│\n├── tests/              # Test suite\n├── docs/               # Documentation\n└── examples/           # Usage examples\n```\n\n## Development\n\n```bash\n# Install dependencies\npoetry install\n\n# Run tests\npytest\n\n# Start development server\nuvicorn src.main:app --reload\n```\n\n## Tech Stack\n\n- **Backend**: Python 3.11+, FastAPI, Uvicorn\n- **Database**: SQLite with JSON support\n- **Embeddings**: sentence-transformers (paraphrase-multilingual-mpnet-base-v2, 768-dim)\n- **MCP Server**: Node.js, @modelcontextprotocol/sdk\n- **Auto-Tagging**: Api\n- **Testing**: pytest, pytest-asyncio, pytest-cov\n- **Deployment**: Docker, docker-compose\n\n## Performance\n\n| Operation | Time | Notes |\n|-----------|------|-------|\n| Save memory | ~20ms | Including embedding |\n| Search (1k memories) | ~15ms | Semantic similarity |\n| Search (10k memories) | ~50ms | Still fast |\n| Model load | ~3s | One-time on startup |\n\n## License\n\nMIT License - see [LICENSE](LICENSE)\n\n## Links\n\n- **Documentation**: [docs/](docs/)\n- **Issues**: [GitHub Issues](https://github.com/0xReLogic/Cognio/issues)\n- **Releases**: [GitHub Releases](https://github.com/0xReLogic/Cognio/releases)\n\n---\n\nBuilt for better AI conversations\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xrelogic%2Fcognio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0xrelogic%2Fcognio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xrelogic%2Fcognio/lists"}