ShieldCortex — Persistent Memory & Security for AI Agents

Give your agent a brain that persists between sessions and protect it from memory poisoning attacks.

Safety & Scope

This skill documents a local memory/security tool. It does not auto-install packages or silently execute shell commands.
Any install command shown here is a manual setup step for the user to approve and run explicitly.
Local ShieldCortex usage does not require credentials. API keys are optional and only needed for ShieldCortex Cloud.
Only scan instruction files or other prompts when the user has named the path or clearly asked for that review.
shieldcortex install writes local MCP configuration; it does not deploy a remote service or request background privileges.

When to Use This Skill

You want to remember things between sessions (decisions, preferences, architecture, context)
You need to recall relevant past context at the start of a session
You want knowledge graph extraction from memories (entities, relationships)
You need to protect memory from prompt injection or poisoning attacks
You want credential leak detection in memory writes
You want to audit what has been stored in and retrieved from memory
You want to scan instruction files (SKILL.md, .cursorrules, CLAUDE.md) for threats

Setup

Install the npm package globally, then configure the MCP server, only when the user explicitly wants ShieldCortex enabled:

npm install -g shieldcortex
shieldcortex install

Python SDK also available:

pip install shieldcortex

Core Workflow

Session Start

At the start of every session, retrieve prior context:

Call start_session to begin a new session and get relevant memories
Or call get_context with a query describing the current task

Remembering

Call remember immediately when any of these happen:

Architecture decisions — "We're using PostgreSQL for the database"
Bug fixes — capture root cause and solution
User preferences — "Always use TypeScript strict mode"
Completed features — what was built and why
Error resolutions — what broke and how it was fixed
Project context — tech stack, key patterns, file structure

Parameters:

title (required): Short summary
content (required): Detailed information
category: architecture, pattern, preference, error, context, learning, todo, note
importance: low, normal, high, critical
project: Scope to a specific project (auto-detected if omitted)
tags: Array of tags for categorisation

Recalling

Call recall to search for past memories:

mode: "search" — query-based semantic search (default)
mode: "recent" — most recent memories
mode: "important" — highest-salience memories

Filter by category, tags, project, or type (short_term, long_term, episodic).

Forgetting

Call forget to remove outdated or incorrect memories:

Delete by id for a specific memory
Delete by query to match content
Always use dryRun: true first to preview what will be deleted
Use confirm: true for bulk deletions

Session End

Call end_session with a summary to trigger memory consolidation. This promotes short-term memories to long-term and runs decay on old, unaccessed memories.

Knowledge Graph

ShieldCortex automatically extracts entities and relationships from memories.

graph_query — traverse from an entity, returns connected entities up to N hops
graph_entities — list known entities, filter by type (person, tool, concept, file, language, service, pattern)
graph_explain — find the path connecting two entities

Use the knowledge graph to understand relationships between concepts, technologies, and decisions across the project.

Memory Intelligence

consolidate — merge duplicate/similar memories, run decay. Use dryRun: true to preview
detect_contradictions — find conflicting memories (e.g., "use Redis" vs "don't use Redis")
get_related — find memories connected to a specific memory ID
link_memories — create explicit relationships (references, extends, contradicts, related)
memory_stats — view total counts, category breakdown, decay stats

Security & Defence

Every memory write passes through a 6-layer defence pipeline:

Input Sanitisation — strips control characters and null bytes
Pattern Detection — regex matching for known injection patterns
Semantic Analysis — embedding similarity to attack corpus
Structural Validation — JSON/format integrity checks
Behavioural Scoring — anomaly detection over time
Credential Leak Detection — blocks API keys, tokens, private keys (25+ patterns, 11 providers)

Iron Dome

Behavioural security layer that controls what agents can do, not just what they remember:

iron_dome_activate — activate with a profile: school, enterprise, personal, or paranoid
iron_dome_status — check active profile, trusted channels, and approval rules
iron_dome_check — gate an action (e.g., send_email, delete_file) before execution
iron_dome_scan — scan text for prompt injection patterns

Profiles control action gates (what actions require approval), channel trust (which instruction sources are trusted), and approval rules.

Security Tools

audit_query — query the forensic audit log of all memory operations
defence_stats — view defence system statistics (blocks, allows, quarantines)
quarantine_review — review and manage quarantined memories (list, approve, reject)
scan_memories — scan existing memories for signs of poisoning
scan_skill — scan an instruction file for hidden threats (SKILL.md, .cursorrules, CLAUDE.md, etc.)

Universal Memory Bridge

ShieldCortex can act as a security layer for any memory backend — not just its own. Use ShieldCortexGuardedMemoryBridge to wrap any memory system with the full defence pipeline:

import { ShieldCortexGuardedMemoryBridge, MarkdownMemoryBackend } from 'shieldcortex';

const bridge = new ShieldCortexGuardedMemoryBridge({
  backend: new MarkdownMemoryBackend('~/.my-memories/'),
});

// All writes pass through the 6-layer defence pipeline
await bridge.write({ title: 'Decision', content: 'Use PostgreSQL' });

Built-in backends: MarkdownMemoryBackend, OpenClawMarkdownBackend. Implement the backend interface for custom storage. ShieldCortex does not auto-discover remote backends or obtain their credentials; the host application must wire that in explicitly.

Project Scoping

set_project — switch active project context
get_project — show current project scope
Use project: "*" for global/cross-project memories

Best Practices

Remember immediately — call remember right after a decision is made or a bug is fixed, not at the end of the session
Use categories — architecture, pattern, preference, error, context, learning
Set importance — mark critical decisions as importance: "critical" so they resist decay
Recall at session start — always call get_context or start_session first
End sessions properly — call end_session with a summary to trigger consolidation
Review contradictions — periodically run detect_contradictions to catch conflicting information
Scope by project — memories are automatically scoped to the current project directory

Troubleshooting

Memory not found in recall:

Try mode: "search" with different query phrasing
Check set_project — you may be searching the wrong project scope
Use includeDecayed: true to find memories that have faded

Memory blocked by firewall:

The defence pipeline detected a potential threat (injection, credential leak)
Check audit_query for the specific block reason
Review with quarantine_review if it was a false positive
Avoid including literal API keys or tokens in memory content

Consolidation removing memories:

Run consolidate with dryRun: true first to preview
Mark important memories as importance: "critical" to prevent decay
Access memories regularly — recall boosts activation and prevents decay

OpenClaw Auto-Memory

When using the OpenClaw hook, auto-memory extraction is off by default. Enable it to automatically extract memories from session output:

shieldcortex config --openclaw-auto-memory

When enabled, the system deduplicates against recent memories to avoid storing duplicates. Configure with:

openclawAutoMemory — enable/disable (default: false)
openclawAutoMemoryDedupe — deduplicate against existing memories (default: true)
openclawAutoMemoryNoveltyThreshold — similarity threshold for deduplication (default: 0.88)
openclawAutoMemoryMaxRecent — number of recent memories to check (default: 300)

shieldcortex

Safety Notice

Copy this and send it to your AI assistant to learn