diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..73dd1e9 --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1 @@ +github: MikeSquared-Agency diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..0519988 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,18 @@ +--- +name: Bug Report +about: Report a bug in Cortex +labels: bug +--- + +## Description + +## Steps to reproduce + +## Expected behaviour + +## Actual behaviour + +## Environment +- Cortex version: +- OS: +- Install method (cargo/binary/docker): diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..09d5439 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,11 @@ +--- +name: Feature Request +about: Suggest a feature for Cortex +labels: enhancement +--- + +## Problem + +## Proposed solution + +## Alternatives considered diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..0e67dfc --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,9 @@ +## What this PR does + +## Related spec/issue + +## Checklist +- [ ] Tests pass (`cargo test --workspace`) +- [ ] Clippy clean (`cargo clippy --workspace`) +- [ ] Docs updated (if user-facing change) +- [ ] CHANGELOG updated (if notable change) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index cc9d57a..110ca4f 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -213,3 +213,19 @@ jobs: run: cd sdks/typescript && npm ci && npm run build && npm publish --access public env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + + publish-mcp-bridge: + name: Publish MCP bridge to npm + runs-on: ubuntu-latest + needs: github-release + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 20 + registry-url: https://registry.npmjs.org + - name: Publish + working-directory: mcp-bridge + run: npm publish --access public + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} diff --git a/CLAUDE.md b/CLAUDE.md index ab12040..768a6fd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -130,3 +130,15 @@ and best practices for keeping the graph clean. Start every session with: `cortex_briefing(agent_id="YOUR_AGENT_ID", compact=true)` The rest of this CLAUDE.md is for developers working on the Cortex codebase itself. + +## Using Cortex as an MCP server + +The native MCP server is in `crates/cortex-server/src/mcp/mod.rs`. +It implements 7 tools via stdio JSON-RPC transport. + +The MCP server runs in two modes: +- **Library mode** (default): opens the redb database directly. Fastest. +- **Proxy mode** (`--server`): connects to a running gRPC server. + +The Node.js bridge in `mcp-bridge/` proxies to the HTTP API for environments +without the Rust binary. diff --git a/README.md b/README.md index ccc049e..3ff122d 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,12 @@ # Cortex +[![CI](https://github.com/MikeSquared-Agency/cortex/actions/workflows/ci.yml/badge.svg)](https://github.com/MikeSquared-Agency/cortex/actions/workflows/ci.yml) +[![Release](https://img.shields.io/github/v/release/MikeSquared-Agency/cortex)](https://github.com/MikeSquared-Agency/cortex/releases/latest) +[![crates.io](https://img.shields.io/crates/v/cortex-memory.svg)](https://crates.io/crates/cortex-memory) +[![PyPI](https://img.shields.io/pypi/v/cortex-memory.svg)](https://pypi.org/project/cortex-memory/) +[![npm](https://img.shields.io/npm/v/@cortex-memory/client.svg)](https://www.npmjs.com/package/@cortex-memory/client) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) + **Self-organizing graph memory for AI agents. One binary. Zero dependencies.** Cortex is an embedded temporal graph memory that auto-links knowledge, decays what's irrelevant, detects contradictions, and synthesises context briefings on demand. Think SQLite, but for agent memory. @@ -64,6 +71,109 @@ cortex briefing my-agent --scope shared cortex trust ``` +## Use with AI Agents (MCP) + +Cortex speaks MCP natively. One command gives your AI agent persistent, +self-organizing memory. + +### Claude Code + +```bash +# Start Cortex in the background +cortex serve & + +# Add to Claude Code +claude mcp add cortex -- cortex mcp +``` + +Claude Code now has 7 memory tools: `cortex_store`, `cortex_search`, +`cortex_recall`, `cortex_briefing`, `cortex_traverse`, `cortex_relate`, +`cortex_observe`. + +### Cursor + +Add to `.cursor/mcp.json`: + +```json +{ + "mcpServers": { + "cortex": { + "command": "cortex", + "args": ["mcp"] + } + } +} +``` + +### Windsurf + +Add to your MCP config: + +```json +{ + "mcpServers": { + "cortex": { + "command": "cortex", + "args": ["mcp"] + } + } +} +``` + +### VS Code (Copilot) + +Add to `.vscode/mcp.json`: + +```json +{ + "servers": { + "cortex": { + "command": "cortex", + "args": ["mcp"] + } + } +} +``` + +### Without installing the binary + +Use the Node.js bridge (no Rust needed): + +```bash +npx cortex-mcp-bridge +``` + +Or with a remote Cortex server: + +```json +{ + "mcpServers": { + "cortex": { + "command": "node", + "args": ["/path/to/cortex-mcp-bridge.js"], + "env": { + "CORTEX_URL": "http://your-server:9091" + } + } + } +} +``` + +### What your agent gets + +| Tool | Purpose | +|------|---------| +| `cortex_store` | Remember facts, decisions, goals, events, patterns | +| `cortex_search` | Semantic search by meaning | +| `cortex_recall` | Hybrid search (semantic + graph structure) | +| `cortex_briefing` | "What do I need to know?" context document | +| `cortex_traverse` | Explore how concepts connect in the graph | +| `cortex_relate` | Explicitly link related knowledge | +| `cortex_observe` | Record performance metrics for prompt selection | + +The briefing tool supports scope: `agent` (default), `shared` (cross-agent), +or `unified` (multi-agent overview for orchestrators). + ### Prompt Management Cortex includes a built-in prompt versioning system with branching, inheritance, and context-aware selection. @@ -124,6 +234,7 @@ let results = cx.search("authentication", 5)?; ## Documentation - **[Quick Start](docs/getting-started/quickstart.md)** +- **[MCP Setup](docs/guides/mcp-setup.md)** -- Claude Code, Cursor, Windsurf, VS Code - **[Configuration Reference](docs/reference/config.md)** - **[CLI Reference](docs/reference/cli.md)** - **[Python SDK](docs/reference/python-sdk.md)** diff --git a/docs/assets/social-preview.png b/docs/assets/social-preview.png new file mode 100644 index 0000000..d215332 Binary files /dev/null and b/docs/assets/social-preview.png differ diff --git a/docs/assets/social-preview.svg b/docs/assets/social-preview.svg new file mode 100644 index 0000000..78362ae --- /dev/null +++ b/docs/assets/social-preview.svg @@ -0,0 +1,120 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + CORTEX + + + Self-organizing graph memory for AI agents + + + One binary · Zero dependencies · Auto-linking · Temporal validity · Trust from topology + diff --git a/docs/guides/mcp-setup.md b/docs/guides/mcp-setup.md new file mode 100644 index 0000000..a57e85f --- /dev/null +++ b/docs/guides/mcp-setup.md @@ -0,0 +1,257 @@ +# MCP Setup Guide + +Cortex includes a native MCP server that runs in library mode: it opens +the database directly with no network hop. This makes it faster than +MCP servers that proxy through HTTP. + +## Prerequisites + +Install Cortex: + +```bash +curl -sSf https://raw.githubusercontent.com/MikeSquared-Agency/cortex/main/install.sh | sh +``` + +Initialise a project (creates cortex.toml): + +```bash +cortex init +``` + +## Option A: Direct binary (recommended) + +The `cortex mcp` command starts an MCP server using stdio transport. +It opens the redb database directly in library mode. + +### Claude Code + +```bash +claude mcp add cortex -- cortex mcp +``` + +To use a specific data directory: + +```bash +claude mcp add cortex -- cortex mcp --data-dir /path/to/data +``` + +To connect to a running Cortex server instead of opening the DB directly: + +```bash +cortex serve & +claude mcp add cortex -- cortex mcp --server http://localhost:9090 +``` + +### Cursor + +Create or edit `.cursor/mcp.json` in your project root: + +```json +{ + "mcpServers": { + "cortex": { + "command": "cortex", + "args": ["mcp"] + } + } +} +``` + +### Windsurf + +Add to your Windsurf MCP configuration: + +```json +{ + "mcpServers": { + "cortex": { + "command": "cortex", + "args": ["mcp"] + } + } +} +``` + +### VS Code (GitHub Copilot) + +Create `.vscode/mcp.json`: + +```json +{ + "servers": { + "cortex": { + "command": "cortex", + "args": ["mcp"] + } + } +} +``` + +### OpenCode / Gemini CLI + +Add to your MCP config file: + +```json +{ + "mcpServers": { + "cortex": { + "command": "cortex", + "args": ["mcp"] + } + } +} +``` + +## Option B: Node.js bridge (no Rust needed) + +The MCP bridge is a standalone Node.js script that proxies MCP requests +to a running Cortex HTTP server. Use this when you can't install the +Rust binary or want to connect to a remote server. + +```bash +# Start Cortex server +cortex serve + +# In another terminal, or via MCP config: +node mcp-bridge/cortex-mcp-bridge.js +``` + +MCP config: + +```json +{ + "mcpServers": { + "cortex": { + "command": "node", + "args": ["mcp-bridge/cortex-mcp-bridge.js"], + "env": { + "CORTEX_URL": "http://localhost:9091" + } + } + } +} +``` + +For a remote server: + +```json +{ + "env": { + "CORTEX_URL": "https://cortex.example.com", + "CORTEX_AUTH_TOKEN": "your-token-here" + } +} +``` + +## Option C: Docker + +```bash +docker run -d --name cortex -p 9090:9090 -p 9091:9091 \ + -v cortex-data:/data mikesquared/cortex:latest + +# Then use the Node.js bridge to connect +CORTEX_URL=http://localhost:9091 node mcp-bridge/cortex-mcp-bridge.js +``` + +## Available MCP tools + +### cortex_store + +Store knowledge in the graph. + +Parameters: +- `kind` (string): fact, decision, goal, event, pattern, observation, or any custom kind +- `title` (string, required): short summary +- `body` (string): full content +- `tags` (array): tags for categorisation +- `importance` (number): 0.0-1.0, affects ranking and decay resistance + +### cortex_search + +Semantic search by meaning. Returns nodes ranked by embedding similarity. + +Parameters: +- `query` (string, required): what to search for +- `limit` (integer): max results (default 10) + +### cortex_recall + +Hybrid search combining semantic similarity with graph structure. +Better than cortex_search when you need contextually related information. + +Parameters: +- `query` (string, required): what to recall +- `limit` (integer): max results +- `hops` (integer): graph traversal depth (default 2) + +### cortex_briefing + +Generate a structured context document for an agent. Use at session start +to load relevant context. + +Parameters: +- `agent_id` (string, required): which agent's perspective +- `compact` (boolean): dense format for smaller context windows +- `scope` (string): "agent" (default), "shared" (cross-agent), or "unified" +- `agents` (array): agent IDs for unified scope + +### cortex_traverse + +Explore connections from a node in the graph. + +Parameters: +- `node_id` (string, required): starting node +- `depth` (integer): how many hops (default 2) +- `relations` (array): filter by relation types + +### cortex_relate + +Create an explicit relationship between two nodes. + +Parameters: +- `from` (string, required): source node ID +- `to` (string, required): target node ID +- `relation` (string): relationship type (default "relates_to") +- `weight` (number): relationship strength 0.0-1.0 + +### cortex_observe + +Record a performance observation for prompt selection feedback. + +Parameters: +- `agent_id` (string, required): observing agent +- `variant_id` (string): prompt variant UUID +- `sentiment_score` (number): -1.0 to 1.0 +- `task_outcome` (string): success, failure, partial + +## Best practices + +1. **Start every session with a briefing**: `cortex_briefing(agent_id="your-agent", compact=true)` +2. **Store decisions with rationale**: include why, not just what +3. **Use importance scores**: 0.9 for architectural decisions, 0.3 for ephemeral observations +4. **Tag consistently**: tags enable cross-cutting queries +5. **Let the auto-linker work**: don't manually link everything; store facts and let Cortex discover connections + +## Troubleshooting + +### "command not found: cortex" + +The binary isn't in your PATH. Either: +- Run the install script again: `curl -sSf ... | sh` +- Or specify the full path in your MCP config: `"command": "/usr/local/bin/cortex"` + +### MCP server starts but tools don't appear + +Check that the data directory exists and is writable: +```bash +cortex mcp --data-dir ./data 2>/dev/null +# Should output MCP JSON-RPC on stdout +``` + +### "Database not found" + +Run `cortex init` first, or specify `--data-dir` pointing to an existing Cortex project. + +### Tools are slow on first use + +The embedding model downloads on first use (~80MB). Subsequent starts are instant. diff --git a/mcp-bridge/package.json b/mcp-bridge/package.json new file mode 100644 index 0000000..936ce89 --- /dev/null +++ b/mcp-bridge/package.json @@ -0,0 +1,14 @@ +{ + "name": "cortex-mcp-bridge", + "version": "0.3.0", + "description": "MCP bridge for Cortex graph memory (no Rust needed)", + "bin": { + "cortex-mcp-bridge": "./cortex-mcp-bridge.js" + }, + "license": "MIT", + "repository": { + "type": "git", + "url": "https://github.com/MikeSquared-Agency/cortex" + }, + "keywords": ["mcp", "cortex", "memory", "ai-agents", "model-context-protocol"] +}