# Shieldcortex

> Persistent memory system with security for AI agents. Remembers decisions, preferences, architecture, and context across sessions with knowledge graphs, decay, contradiction detection, and a 6-layer defence pipeline with Iron Dome behavioural protection. Use when asked to "remember this", "what do we know about", "recall context", "scan for threats", "run security audit", "check memory stats", or when starting a new session and needing prior context.

- Skill: `javimosch/shieldcortex` (Agent Skill)
- Install (CLI): `npx skillmds@latest add javimosch/shieldcortex`
- Raw SKILL.md: https://api.skillmd.com/api/skills/javimosch/shieldcortex/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: MIT
- Author: javimosch (https://skillmd.com/u/javimosch)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/javimosch/shieldcortex

---


# 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:

```bash
npm install -g shieldcortex
shieldcortex install
```

Python SDK also available:

```bash
pip install shieldcortex
```

## Core Workflow

### Session Start

At the start of every session, retrieve prior context:

1. Call `start_session` to begin a new session and get relevant memories
2. 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:

1. Input Sanitisation — strips control characters and null bytes
2. Pattern Detection — regex matching for known injection patterns
3. Semantic Analysis — embedding similarity to attack corpus
4. Structural Validation — JSON/format integrity checks
5. Behavioural Scoring — anomaly detection over time
6. 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:

```javascript
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

1. **Remember immediately** — call `remember` right after a decision is made or a bug is fixed, not at the end of the session
2. **Use categories** — architecture, pattern, preference, error, context, learning
3. **Set importance** — mark critical decisions as `importance: "critical"` so they resist decay
4. **Recall at session start** — always call `get_context` or `start_session` first
5. **End sessions properly** — call `end_session` with a summary to trigger consolidation
6. **Review contradictions** — periodically run `detect_contradictions` to catch conflicting information
7. **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:

```bash
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)

## Links

- npm: https://www.npmjs.com/package/shieldcortex
- PyPI: https://pypi.org/project/shieldcortex
- GitHub: https://github.com/Drakon-Systems-Ltd/ShieldCortex
- Website: https://shieldcortex.ai