cortexdb-mcp 0.2.1__tar.gz → 0.3.0__tar.gz

cortexdb_mcp-0.3.0/.gitignore

@@ -0,0 +1,71 @@
+# Rust
+/target
+**/*.rs.bk
+
+# Environment / secrets
+.env
+.env.local
+.env*.local
+*.pem
+*.key
+.npmrc
+
+# SQLite database
+*.sqlite
+*.sqlite-wal
+*.sqlite-shm
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Data directories
+cortexdb_data*/
+/data/
+# Per-bench tenant stores (RocksDB + Tantivy + HNSW state; regeneratable per run)
+/data_*/
+# Experimental per-branch stores (not tracked on this branch but left gitignored
+# so checkout from other branches doesn't surface them in git status)
+/event_memory_store/
+/llm_cache/
+
+# Benchmark inputs and per-run outputs (kept local, regenerated each run)
+benchmarks/longmemeval/data/
+benchmarks/longmemeval/server_results/
+benchmarks/longmemeval/fast_results/
+benchmarks/longmemeval/micro_results/
+benchmarks/longmemeval/server_logs/
+benchmarks/longmemeval/*.log
+benchmarks/locomo/locomo_results*.json
+benchmarks/locomo/server_results/
+benchmarks/locomo/*.log
+/answer_out.json
+
+# Local Claude Code state
+.claude/
+.tmp/
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+venv/
+
+# Node
+node_modules/
+dist/
+.next/
+
+# Egg info
+*.egg-info/
+
+# Scratch/debug text files at root
+/*.txt
+/*.log

{cortexdb_mcp-0.2.1 → cortexdb_mcp-0.3.0}/Dockerfile

@@ -1,12 +1,12 @@
-FROM python:3.12-slim
-
-WORKDIR /app
-
-COPY pyproject.toml README.md ./
-COPY cortexdb_mcp/ cortexdb_mcp/
-
-RUN pip install --no-cache-dir .
-
-ENV CORTEXDB_URL=https://api.cortexdb.ai
-
-CMD ["cortexdb-mcp"]
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY pyproject.toml README.md ./
+COPY cortexdb_mcp/ cortexdb_mcp/
+
+RUN pip install --no-cache-dir .
+
+ENV CORTEXDB_URL=https://api.cortexdb.ai
+
+CMD ["cortexdb-mcp"]

{cortexdb_mcp-0.2.1 → cortexdb_mcp-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexdb-mcp
-Version: 0.2.1
+Version: 0.3.0
 Summary: MCP Server for CortexDB — expose memory operations to AI agents
 License-Expression: MIT
 Requires-Python: >=3.10
@@ -15,31 +15,33 @@ Description-Content-Type: text/markdown
 
 MCP (Model Context Protocol) server that gives AI tools persistent long-term memory via CortexDB. Works with Claude Desktop, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible client.
 
+> **0.3.0 rewrites the server against the v1 CortexDB API.** Default surface is now `https://api-v1.cortexdb.ai`. The server **auto-signs-up anonymously** on first launch — no API key required.
+
 ## Quick Start
 
 ```bash
-# Install
-pip install -e .
+# Install (the PyPI name is `cortexdb-mcp`)
+pip install cortexdb-mcp
 
-# Or with uvx (no install needed)
-uvx --from . cortexdb-mcp
+# Then run with zero config:
+cortexdb-mcp
 ```
 
-Set your environment variables:
-
-```bash
-export CORTEXDB_URL="https://api.cortexdb.ai"
-export CORTEXDB_API_KEY="cx_live_your_key_here"
-```
+That's it. On first launch the server hits `POST /v1/auth/signup`, mints a free-tier PASETO token + scope for itself, and caches them under `~/.config/cortexdb-mcp/state.json` (Linux/macOS) or `%APPDATA%\cortexdb-mcp\state.json` (Windows). Re-launches reuse the cached identity until the token expires (7 days).
 
-Run:
+To target a custom deployment or pre-existing identity, set any of:
 
 ```bash
-cortexdb-mcp
+export CORTEXDB_URL="https://api-v1.cortexdb.ai"   # base URL
+export CORTEXDB_API_KEY="v4.public..."             # PASETO bearer token
+export CORTEXDB_ACTOR="user:alice"                 # ActorId, sent as X-Cortex-Actor
+export CORTEXDB_SCOPE="org:acme/user:alice"        # default scope path
 ```
 
 ## IDE Setup
 
+Most clients just need a single line — the auto-signup handles the rest.
+
 ### Claude Desktop
 
 Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
@@ -48,11 +50,7 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o
 {
   "mcpServers": {
     "cortexdb": {
-      "command": "cortexdb-mcp",
-      "env": {
-        "CORTEXDB_URL": "https://api.cortexdb.ai",
-        "CORTEXDB_API_KEY": "cx_live_your_key_here"
-      }
+      "command": "cortexdb-mcp"
     }
   }
 }
@@ -66,11 +64,7 @@ Edit `~/.claude/mcp.json`:
 {
   "mcpServers": {
     "cortexdb": {
-      "command": "cortexdb-mcp",
-      "env": {
-        "CORTEXDB_URL": "https://api.cortexdb.ai",
-        "CORTEXDB_API_KEY": "cx_live_your_key_here"
-      }
+      "command": "cortexdb-mcp"
     }
   }
 }
@@ -84,11 +78,7 @@ Edit `~/.cursor/mcp.json`:
 {
   "mcpServers": {
     "cortexdb": {
-      "command": "cortexdb-mcp",
-      "env": {
-        "CORTEXDB_URL": "https://api.cortexdb.ai",
-        "CORTEXDB_API_KEY": "cx_live_your_key_here"
-      }
+      "command": "cortexdb-mcp"
     }
   }
 }
@@ -104,11 +94,7 @@ Edit `~/.codeium/windsurf/mcp_config.json`:
 {
   "mcpServers": {
     "cortexdb": {
-      "command": "cortexdb-mcp",
-      "env": {
-        "CORTEXDB_URL": "https://api.cortexdb.ai",
-        "CORTEXDB_API_KEY": "cx_live_your_key_here"
-      }
+      "command": "cortexdb-mcp"
     }
   }
 }
@@ -122,11 +108,21 @@ Add to `.vscode/mcp.json` in your project or `~/.vscode/mcp.json` globally:
 {
   "servers": {
     "cortexdb": {
-      "command": "cortexdb-mcp",
-      "env": {
-        "CORTEXDB_URL": "https://api.cortexdb.ai",
-        "CORTEXDB_API_KEY": "cx_live_your_key_here"
-      }
+      "command": "cortexdb-mcp"
+    }
+  }
+}
+```
+
+### Windows tip
+
+On Windows, MCP clients sometimes need the absolute path:
+
+```json
+{
+  "mcpServers": {
+    "cortexdb": {
+      "command": "C:\\Python310\\Scripts\\cortexdb-mcp.exe"
     }
   }
 }
@@ -136,43 +132,43 @@ Add to `.vscode/mcp.json` in your project or `~/.vscode/mcp.json` globally:
 
 ### Memory Operations
 
-| Tool | Description |
-|------|-------------|
-| `memory_store` | Store a new memory with optional source, type, tags, TTL |
-| `memory_search` | Search memories using natural language (hybrid retrieval) |
-| `memory_forget` | Delete memories with audit trail (GDPR-compliant) |
-| `get_context` | Deep contextual retrieval combining search + graph |
-| `advanced_search` | Search with structured filters (source, type, time range) |
-
-### Episode Management
-
-| Tool | Description |
-|------|-------------|
-| `memory_list` | List episodes with pagination and type filter |
-| `memory_get` | Get a specific episode by ID |
-| `memory_update` | Update episode content or metadata |
-| `memory_delete` | Delete a specific episode by ID |
-| `memory_bulk_delete` | Bulk delete with query matching and dry-run support |
-
-### Knowledge Graph
-
-| Tool | Description |
-|------|-------------|
-| `entity_list` | List entities (people, services, projects, concepts) |
-| `entity_get` | Get entity details including relationships and recent episodes |
-| `entity_edges` | Get all relationships for an entity |
-| `entity_link` | Create a relationship between two entities |
+| Tool | Maps to | Description |
+|------|---------|-------------|
+| `memory_store` | `POST /v1/experience` | Store a new memory. Source/tags/type become labels. |
+| `memory_search` | `POST /v1/recall` | Search memories using natural language. |
+| `memory_forget` | `POST /v1/forget` | Delete memories. With `query`, narrows by subject. |
+| `get_context` | `POST /v1/recall` (holistic) | Deep context with facts + beliefs. |
+| `advanced_search` | `POST /v1/recall` + temporal | Search with structured filters (time / source / type). |
+
+### Event CRUD
+
+| Tool | Maps to | Description |
+|------|---------|-------------|
+| `memory_list` | `GET /v1/events` | List events in scope, paginated. |
+| `memory_get` | `GET /v1/events/{id}` | Fetch a single event (used for citations). |
+| `memory_delete` | `POST /v1/forget` (memory_ids) | Delete one event by id. |
+| `memory_bulk_delete` | `POST /v1/forget` or `/v1/erasures/preview` | Bulk delete with dry-run support. |
+
+### Knowledge Graph (facts-backed in v1)
+
+| Tool | Maps to | Description |
+|------|---------|-------------|
+| `entity_list` | `GET /v1/facts` | List fact subjects, ranked by count. |
+| `entity_get` | `GET /v1/facts?subject=…` | Fact lineage for a subject. |
+| `entity_edges` | `GET /v1/facts?subject=…` | Predicate/object pairs for an entity. |
+| `entity_link` | `POST /v1/experience` | Store a sentence the extractor will turn into a fact. |
 
 ### Admin & Observability
 
-| Tool | Description |
-|------|-------------|
-| `health_check` | Check CortexDB server health |
-| `get_usage` | View usage stats and tier limits |
-| `get_insights` | Generate proactive insights (incident spikes, gaps, risks) |
-| `get_ontology` | View entity types and relationship types |
-| `export_data` | Export memories as JSON |
-| `import_data` | Import memories from JSON |
+| Tool | Maps to | Description |
+|------|---------|-------------|
+| `health_check` | `GET /v1/auth/whoami` | Verify the bearer + reach the deployment policy. |
+| `get_usage` | `GET /v1/auth/whoami` + headers | Tier, rate limit, token expiry. |
+| `get_insights` | (in-process) | Proactive insights derived from stored episodes. |
+
+### Removed from 0.3.0
+
+`memory_update`, `export_data`, `import_data`, `get_ontology` — v1 has no direct equivalents. Updates: store a new event; bulk import: see `/v1/import` directly with the v1 envelope shape; ontology: not part of the v1 surface.
 
 ## Resources