Skip to content

Commit f4ffef0

Browse files
erikhowardclaude
erikhoward
and
claude
committed
docs: add examples for Cortex usage
Add examples directory with: - cli-basics: Common CLI usage patterns - claude-desktop: MCP integration with Claude Desktop (standalone) - go-client: Programmatic usage as a Go library The Claude Desktop example shows Cortex usage outside of PetalFlow. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 84592d6 commit f4ffef0

6 files changed

Lines changed: 751 additions & 0 deletions

File tree

‎examples/README.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Cortex Examples
2+
3+
This directory contains examples demonstrating how to use Cortex in various scenarios.
4+
5+
## Examples
6+
7+
| Example | Description |
8+
|---------|-------------|
9+
| [cli-basics](./cli-basics/) | Command-line usage patterns for common tasks |
10+
| [claude-desktop](./claude-desktop/) | Integration with Claude Desktop via MCP |
11+
| [go-client](./go-client/) | Using Cortex programmatically as a Go library |
12+
13+
## Quick Start
14+
15+
Before running these examples, ensure Cortex is installed:
16+
17+
```bash
18+
# Download from releases
19+
curl -LO https://github.com/petal-labs/cortex/releases/latest/download/cortex_0.1.0_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m).tar.gz
20+
tar -xzf cortex_*.tar.gz
21+
sudo mv cortex_*/cortex /usr/local/bin/
22+
23+
# Verify installation
24+
cortex --version
25+
```
26+
27+
## Use Cases
28+
29+
### Personal Knowledge Base
30+
31+
Store and search your notes, documents, and research:
32+
33+
```bash
34+
cortex knowledge ingest --collection notes --title "Meeting Notes" --file notes.md
35+
cortex knowledge search "action items from last meeting"
36+
```
37+
38+
### Agent Memory
39+
40+
Give AI agents persistent memory across sessions:
41+
42+
```bash
43+
# Start MCP server for your agent
44+
cortex serve --namespace my-agent
45+
```
46+
47+
### Development Context
48+
49+
Track project state and context across coding sessions:
50+
51+
```bash
52+
cortex context set "current_task" "implementing user auth"
53+
cortex context set "project_status" '{"phase": "development", "sprint": 3}'
54+
```

‎examples/claude-desktop/README.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# Using Cortex with Claude Desktop
2+
3+
This example shows how to integrate Cortex with [Claude Desktop](https://claude.ai/download) using the Model Context Protocol (MCP).
4+
5+
## Overview
6+
7+
Claude Desktop supports MCP servers, allowing Claude to use Cortex's memory capabilities directly in your conversations. This gives Claude:
8+
9+
- **Persistent conversation memory** across chat sessions
10+
- **Knowledge retrieval** from your documents
11+
- **Workflow context** that persists between tasks
12+
- **Entity memory** for tracking people, projects, and concepts
13+
14+
## Setup
15+
16+
### 1. Install Cortex
17+
18+
```bash
19+
# macOS (Apple Silicon)
20+
curl -LO https://github.com/petal-labs/cortex/releases/latest/download/cortex_0.1.0_darwin_arm64.tar.gz
21+
tar -xzf cortex_0.1.0_darwin_arm64.tar.gz
22+
sudo mv cortex_0.1.0_darwin_arm64/cortex /usr/local/bin/
23+
24+
# macOS (Intel)
25+
curl -LO https://github.com/petal-labs/cortex/releases/latest/download/cortex_0.1.0_darwin_amd64.tar.gz
26+
tar -xzf cortex_0.1.0_darwin_amd64.tar.gz
27+
sudo mv cortex_0.1.0_darwin_amd64/cortex /usr/local/bin/
28+
```
29+
30+
### 2. Configure Claude Desktop
31+
32+
Edit your Claude Desktop configuration file:
33+
34+
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
35+
36+
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
37+
38+
Add the Cortex MCP server:
39+
40+
```json
41+
{
42+
"mcpServers": {
43+
"cortex": {
44+
"command": "cortex",
45+
"args": ["serve", "--namespace", "claude-desktop"]
46+
}
47+
}
48+
}
49+
```
50+
51+
### 3. Restart Claude Desktop
52+
53+
Quit and reopen Claude Desktop. You should see Cortex tools available in the tools menu.
54+
55+
## Configuration Options
56+
57+
### Basic Configuration
58+
59+
```json
60+
{
61+
"mcpServers": {
62+
"cortex": {
63+
"command": "cortex",
64+
"args": ["serve"]
65+
}
66+
}
67+
}
68+
```
69+
70+
### With Custom Data Directory
71+
72+
```json
73+
{
74+
"mcpServers": {
75+
"cortex": {
76+
"command": "cortex",
77+
"args": ["serve", "--namespace", "claude"],
78+
"env": {
79+
"CORTEX_DATA_DIR": "/path/to/your/cortex/data"
80+
}
81+
}
82+
}
83+
}
84+
```
85+
86+
### With Iris Embedding Service
87+
88+
If you're running an [Iris](https://github.com/petal-labs/iris) embedding service:
89+
90+
```json
91+
{
92+
"mcpServers": {
93+
"cortex": {
94+
"command": "cortex",
95+
"args": ["serve", "--namespace", "claude"],
96+
"env": {
97+
"IRIS_ENDPOINT": "http://localhost:8000"
98+
}
99+
}
100+
}
101+
}
102+
```
103+
104+
## Available Tools
105+
106+
Once configured, Claude will have access to these tools:
107+
108+
### Conversation Memory
109+
- `conversation_append` - Save messages to memory
110+
- `conversation_history` - Retrieve past conversations
111+
- `conversation_search` - Search conversation history
112+
- `conversation_summarize` - Summarize long conversations
113+
114+
### Knowledge Store
115+
- `knowledge_ingest` - Add documents to knowledge base
116+
- `knowledge_search` - Search your documents
117+
- `knowledge_collections` - Manage document collections
118+
119+
### Workflow Context
120+
- `context_get` / `context_set` - Store and retrieve key-value data
121+
- `context_list` - List stored context
122+
- `context_merge` - Merge context with strategies
123+
124+
### Entity Memory
125+
- `entity_query` - Look up entities by name
126+
- `entity_search` - Semantic search across entities
127+
- `entity_relationships` - Get entity connections
128+
129+
## Example Prompts
130+
131+
Once Cortex is connected, try these prompts:
132+
133+
**Build a knowledge base:**
134+
> "Ingest this document into my 'research' collection and remember the key points."
135+
136+
**Search your knowledge:**
137+
> "Search my knowledge base for information about machine learning optimization."
138+
139+
**Track project context:**
140+
> "Remember that I'm working on the authentication feature for Project X."
141+
142+
**Recall past conversations:**
143+
> "What did we discuss last week about the database schema?"
144+
145+
## Pre-loading Knowledge
146+
147+
You can pre-load documents before starting Claude Desktop:
148+
149+
```bash
150+
# Ingest your project documentation
151+
cortex knowledge ingest-dir \
152+
--collection "project-docs" \
153+
--dir ~/projects/myapp/docs \
154+
--pattern "*.md" \
155+
--namespace claude-desktop
156+
157+
# Add important reference materials
158+
cortex knowledge ingest \
159+
--collection "references" \
160+
--title "API Guidelines" \
161+
--file ~/docs/api-guidelines.md \
162+
--namespace claude-desktop
163+
```
164+
165+
## Troubleshooting
166+
167+
### Cortex tools not appearing
168+
169+
1. Check that Cortex is in your PATH: `which cortex`
170+
2. Verify the config file syntax is valid JSON
171+
3. Check Claude Desktop logs for errors
172+
4. Restart Claude Desktop completely
173+
174+
### Connection errors
175+
176+
1. Ensure no other process is using Cortex
177+
2. Check file permissions on the data directory
178+
3. Try running `cortex serve` manually to see errors
179+
180+
### Data not persisting
181+
182+
1. Verify the namespace matches between CLI and config
183+
2. Check that the data directory is writable
184+
3. Ensure you're not running multiple instances with different data dirs

‎examples/claude-desktop/claude_desktop_config.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"mcpServers": {
3+
"cortex": {
4+
"command": "cortex",
5+
"args": ["serve", "--namespace", "claude-desktop"]
6+
}
7+
}
8+
}

0 commit comments

Comments
 (0)