Quick Start

Fresh Install

# Install

npm install -g shieldcortex

# Auto-detect your agent and configure

npx shieldcortex setup

# Restart your agent and approve the MCP server

Migrating from Claude Cortex

# Non-destructive — copies your database, updates settings

npx shieldcortex migrate

# Restart Claude Code

Your existing memories are preserved. The original database stays intact at ~/.claude-cortex/ for rollback.

Verify Installation

npx shieldcortex doctor

How It Works

Automatic Memory (via Hooks)

When you run npx shieldcortex setup, hooks are installed for your agent platform. For Claude Code, three hooks are configured:

Hook	Fires When	What It Does
SessionStart	Session begins	Loads project context from memory
PreCompact	Before context compaction	Extracts important content before it's lost
SessionEnd	Session exits	Saves decisions, fixes, and learnings

Defence Pipeline

Every addMemory() call runs through:

Trust scoring — source gets a trust score (user=1.0 down to agent=0.1)
Firewall scan — content checked for injection, encoding, privilege escalation
Sensitivity classification — detects secrets, PII, credentials
Fragmentation analysis — cross-references with recent memories for assembly patterns
Audit logging — full record regardless of outcome
Decision — ALLOW, QUARANTINE, or BLOCK

MCP Tools

Tool	Description
remember	Store a memory (optional — hooks do this automatically)
recall	Search memories by query, category, or tags
forget	Delete memories
get_context	Get relevant project context
memory_stats	View memory statistics
scan_memories	Scan existing memories for threats
audit_query	Query the defence audit trail
quarantine_review	Review quarantined memories
defence_stats	Threat counts, trust distribution
graph_query	Traverse the knowledge graph
graph_entities	List known entities
graph_explain	Find paths between entities

CLI Reference

npx shieldcortex setup # Auto-detect agent + configure hooks

npx shieldcortex migrate # Migrate from Claude Cortex

npx shieldcortex doctor # Check installation health

npx shieldcortex --dashboard # Start dashboard + API

npx shieldcortex --version # Show version

npx shieldcortex service install # Auto-start on login

npx shieldcortex graph backfill # Extract entities from existing memories

npx shieldcortex clawdbot install # Install OpenClaw hook

npx shieldcortex uninstall # Full uninstall

Dashboard

npx shieldcortex --dashboard

# Dashboard: http://localhost:3030

# API: http://localhost:3001

Views: Knowledge Graph, Memory Browser, Insights, 3D Brain Visualization.

Auto-start on login

npx shieldcortex service install # Enable

npx shieldcortex service uninstall # Disable

npx shieldcortex service status # Check

Works on macOS (launchd), Linux (systemd), and Windows.

Agent Integrations

ShieldCortex works with any AI agent that has persistent memory. Here's how to integrate with popular platforms.

OpenClaw

Native hook support — install with a single command:

npx shieldcortex clawdbot install

# Restart OpenClaw to activate the defence layer

Moltbot

Add ShieldCortex as a Moltbot plugin:

npx shieldcortex moltbot install

Claude Code

Full hooks + MCP server integration:

npx shieldcortex setup # Auto-detects Claude Code

LangChain / AutoGPT / CrewAI / Custom Agents

Use the npm API to wrap any memory backend:

import { ShieldCortex } from 'shieldcortex';

const shield = new ShieldCortex({ db: '~/.shieldcortex/memories.db' });

// Wrap your memory writes
const result = await shield.addMemory({
  content: memoryText,
  source: 'agent',        // 'user' | 'agent' | 'tool' | 'external'
  project: 'my-project',
  category: 'learning'
});

if (result.blocked) {
  console.warn('Memory blocked:', result.reason);
}

// Secure recall
const memories = await shield.recall({
  query: 'deployment config',
  limit: 10
});

The API handles all defence layers automatically — firewall, trust scoring, sensitivity classification, and audit logging.

REST API

For non-Node.js agents, use the HTTP API when the dashboard is running:

# Start the API server

npx shieldcortex --dashboard

# Add a memory

curl -X POST http://localhost:3001/api/memory \

-H "Content-Type: application/json" \

-d '{"content":"...","source":"agent"}'

Configuration

Use with npx (no global install)

Create .mcp.json in your project directory:

{
  "mcpServers": {
    "memory": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "shieldcortex"]
    }
  }
}

Custom database location

Default: ~/.shieldcortex/memories.db

npx shieldcortex --db /path/to/custom.db

Environment Variables

Variable	Default	Description
PORT	3001	API server port
CORTEX_CORS_ORIGINS	localhost:3030,localhost:3000	Allowed CORS origins

Documentation