Documentation

Attack Vectors

ShieldCortex is tested against 17 attack vectors. Every memory write is scanned for these patterns before storage.

Threats are BLOCKED or QUARANTINED — they never reach the database.

Memory System

ShieldCortex doesn't just protect memory — it provides a brain-like memory system that's smarter than most.

Memory Types

Intelligence Features

• Salience scoring — important memories surface, noise decays naturally
• Automatic consolidation — STM promotes to LTM based on importance and access frequency (like brain sleep)
• Temporal decay — memories fade over time but are reinforced on access. Category-specific thresholds protect architecture decisions and error fixes from deletion
• Spreading activation — accessing a memory primes related memories, making them easier to recall for 30 minutes
• Memory enrichment — important memories accumulate new context over time (up to 10KB) rather than creating duplicates
• Background brain worker — runs every 5-30 minutes to discover links, detect contradictions, and maintain the knowledge graph
• Knowledge graph — entity extraction and relationship linking across all memories
• Full-text search — FTS5-powered search across all memory content
• Auto-scoping — memories are automatically scoped per project directory

For the full deep dive on memory internals, see ARCHITECTURE.md.

MCP Tools

CLI Reference

Dashboard

Views: Shield (defence overview), Audit Log, Quarantine, Memories, 3D Brain, Knowledge Graph, Skills Scanner. See the Dashboard Guide for a full view-by-view walkthrough.

Auto-start on login

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

Cloud

ShieldCortex Cloud extends your local defence pipeline with centralised audit logs, team collaboration, and a hosted dashboard. Your local scans stay local — only metadata is synced.

Getting Started with Cloud

1. Choose your plan — start with Team on the pricing page for self-serve cloud sync, or contact sales@drakonsystems.com for Enterprise
2. Copy your API key — find it in the Cloud dashboard under Settings → API Keys
3. Configure locally — run the command below to connect your installation

That's it. From this point, every local scan automatically syncs audit metadata to your Cloud account.

Onboarding Team Members (OpenClaw)

Authentication

ShieldCortex Cloud supports two authentication methods:

All authenticated requests use the Authorization: Bearer <key> header.

API Reference

The Cloud API is available at https://api.shieldcortex.ai. All endpoints require a valid API key.

Example: Scan Content

The response includes a trust score, firewall result (ALLOW, QUARANTINE, or BLOCK), and any detected threats.

Cloud Sync

Once Cloud is enabled, every local scan automatically uploads audit metadata to your Cloud account. Here's what you need to know:

• Metadata only — no memory content ever leaves your machine. Only scan results, trust scores, and threat classifications are synced.
• Fire-and-forget — sync happens asynchronously and never blocks your agent. If the network is down, the scan still completes locally.
• Automatic — no code changes needed. Once configured, every addMemory() and MCP remember call syncs automatically.
• Configurable — settings stored in ~/.shieldcortex/config.json. Disable at any time with shieldcortex config --cloud-disable.

Team Management

Cloud teams let you share audit visibility across your organisation. Invite members from the Cloud dashboard under Settings → Team.

Each member gets their own API key scope, so audit logs are attributed to individual developers. Team invites require a paid plan — Pro or Team.

Agent Integrations

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

OpenClaw Real-time Plugin

For OpenClaw v2026.2.15+, the real-time plugin hooks directly into the LLM pipeline — scanning every input for threats and auto-extracting memories from outputs. All operations are fire-and-forget and never block your agent.

Installation

Install the hook and plugin natively with OpenClaw, or keep using the ShieldCortex wrapper on existing machines:

The hook comes from the main shieldcortex package. The real-time plugin comes from @drakon-systems/shieldcortex-realtime. Existing installs can still use shieldcortex openclaw install to migrate legacy hook layouts and clean up duplicates.

Requirements

• OpenClaw v2026.2.15+ — requires llm_input / llm_output plugin hooks
• ShieldCortex installed — globally (npm i -g shieldcortex) or locally at ~/ShieldCortex/
• mcporter — available via npx (used for MCP memory saves)

How It Differs from the Hook Integration

Audit Logs

Threat detections and memory extractions are logged to ~/.shieldcortex/audit/realtime-YYYY-MM-DD.jsonl. If Cloud sync is configured, threats are also posted to your Cloud dashboard.

Universal Memory Bridge

ShieldCortex can act as a security layer for any memory backend — not just its own. The ShieldCortexGuardedMemoryBridge wraps any external memory system with the full 6-layer defence pipeline.

import {
  ShieldCortexGuardedMemoryBridge,
  MarkdownMemoryBackend
} from 'shieldcortex';

const bridge = new ShieldCortexGuardedMemoryBridge(
  new MarkdownMemoryBackend('/path/to/MEMORY.md')
);

// Every write is scanned before it reaches your backend
const result = await bridge.save({
  title: 'Database config',
  content: 'Using PostgreSQL with connection pooling'
});

Built-in adapters: MarkdownMemoryBackend (any Markdown file), OpenClawMarkdownBackend (OpenClaw MEMORY.md format). Implement the ExternalMemoryBackend interface for custom backends. See the OpenClaw guide for full details.

Claude Code

Full hooks + MCP server integration:

Claude.ai (Skill)

Install ShieldCortex as a Claude.ai skill for persistent memory in the web interface:

1. Download the skills/shieldcortex/ folder from GitHub
2. Zip the folder
3. In Claude.ai, go to Settings > Capabilities > Skills and upload the zip

The skill teaches Claude when and how to use ShieldCortex's MCP tools — remembering decisions, recalling context, scanning for threats, and managing the knowledge graph.

VS Code (GitHub Copilot) & Cursor

One command configures the ShieldCortex MCP server for both editors:

This writes the MCP server config to each editor's user-level settings. Restart the editor after running.

Codex CLI & Codex VS Code

One command registers ShieldCortex for Codex in both the CLI and the VS Code extension:

Codex CLI and the Codex VS Code extension share the same ~/.codex/config.toml on the same machine, so one install covers both.

Library API (v2.10.0+)

Import individual functions — no side effects, no server started:

import {
  addMemory,
  runDefencePipeline,
  scanSkill,
  extractFromMemory,
  consolidate,
  initDatabase
} from 'shieldcortex';

// Initialise the database
initDatabase('/path/to/memories.db');

// Add a memory (automatically passes through defence pipeline)
addMemory({
  title: 'API uses OAuth2',
  content: 'The payment API requires OAuth2 bearer tokens',
  category: 'architecture',
  importance: 'high',
  project: 'my-project'
});

// Scan untrusted content before processing
const result = runDefencePipeline(untrustedContent, 'Email Import', {
  type: 'external',
  identifier: 'email-scanner'
});

if (result.allowed) {
  // Safe to process
}

// Extract knowledge graph entities
const { entities, triples } = extractFromMemory(
  'Database Migration',
  'We switched from MySQL to PostgreSQL for the auth service',
  'architecture'
);

70 named exports covering defence, memory, knowledge graph, skill scanning, and audit. See the full list in the v2.10.0 changelog.

REST API

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

Python SDK

The official Python SDK for the ShieldCortex Cloud API. Scan content through the defence pipeline from any Python application — with built-in support for CrewAI and LangChain.

Installation

Requires Python 3.9+. Available on PyPI. Source on GitHub.

How It Works

The Python SDK sends content to the ShieldCortex Cloud API for scanning. Use it as a security gate between your AI agent and its memory store:

Quick Start

from shieldcortex import ShieldCortex

client = ShieldCortex(api_key="sc_live_...")

# Scan content before storing in your agent's memory
result = client.scan("user input to remember")

if result.allowed:
    save_to_memory(result)  # safe — store it
else:
    print(f"Blocked: {result.firewall.reason}")
    print(f"Threats: {result.firewall.threat_indicators}")

Async Support

from shieldcortex import AsyncShieldCortex

async with AsyncShieldCortex(api_key="sc_live_...") as client:
    result = await client.scan("user input here")

CrewAI Integration

Add a security gate between your CrewAI agent and its memory store. The guard scans all content before it's saved:

from shieldcortex import ShieldCortex
from shieldcortex.integrations.crewai import ShieldCortexMemoryGuard, MemoryBlockedError

client = ShieldCortex(api_key="sc_live_...")
guard = ShieldCortexMemoryGuard(client, mode="strict")

try:
    guard.check("content to remember")
    # Safe — save to memory store
except MemoryBlockedError as e:
    print(f"Blocked: {e.result.firewall.reason}")

LangChain Integration

Automatically scan all LLM inputs and outputs as they flow through your chain:

from shieldcortex import AsyncShieldCortex
from shieldcortex.integrations.langchain import ShieldCortexCallbackHandler

client = AsyncShieldCortex(api_key="sc_live_...")
handler = ShieldCortexCallbackHandler(client, raise_on_block=True)

# Scans inputs on chain start, outputs on LLM end, and tool I/O
llm = ChatOpenAI(callbacks=[handler])

Full API Coverage

The Python SDK covers all ShieldCortex Cloud API endpoints:

Both sync (ShieldCortex) and async (AsyncShieldCortex) clients are available with identical APIs. See the full Python SDK README for complete documentation.

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

OpenClaw Auto-Memory

Auto-memory extraction at session end is off by default. Keyword triggers (remember this:, don't forget:) always work regardless of this setting.

Set in ~/.shieldcortex/config.json or via CLI: shieldcortex config --openclaw-auto-memory. These settings can also be adjusted from the OpenClaw Memory Panel in the local dashboard.

Environment Variables