Memory-aware management and safety framework for AI agents.
Your AI agents forget everything between sessions. AgentSentry gives them persistent memory, safety guardrails, and operational oversight — so every session builds on the last.
npm install @calabamatex/agentsentryOr clone and use directly:
git clone https://github.com/calabamatex/AgentSentry.git
cd AgentSentry/agent-sentry && npm install && npm run buildRequirements: Node.js >= 18
Dependencies: @modelcontextprotocol/sdk, better-sqlite3, uuid, zod
Optional: onnxruntime-node (for native ONNX embeddings — falls back to text search if absent). npm installs use noop embeddings by default; for semantic vector search, copy the models/ directory from the source repo or configure Ollama/OpenAI as the embedding provider.
AgentSentry is a local-first memory and safety layer for AI coding sessions. Primary integration: Claude Code. The MCP server interface enables compatibility with any MCP-compatible tool (Cursor, Codex, ChatGPT, GitHub Copilot, etc.).
What makes it different: AgentSentry remembers. Every decision, violation, incident, and handoff is captured to a vector-indexed memory store that survives across sessions. When a new session starts next week, it can ask "what went wrong the last time someone touched the payment system?" and get a ranked answer from weeks of operational history.
| Skill | What It Does |
|---|---|
| Save Points | Automatic git checkpoints at configurable intervals, branch-on-risk for dangerous operations |
| Context Health | Monitors token usage and conversation length, warns before context overflow, recommends session handoffs |
| Standing Orders | Lints and enforces rules files (CLAUDE.md, .cursorrules, etc.) for project convention compliance |
| Small Bets | Scores tasks by file count and complexity, flags oversized changes, enforces incremental delivery |
| Safety Checks | Scans for leaked secrets, validates permissions, blocks commits containing sensitive data |
| Directive Compliance | Ensures agent executes ACTION/RECOMMEND directives from hooks immediately (active at Level 3+) |
- Persistent Memory Store -- Vector-indexed database with semantic search. SQLite with JS cosine similarity locally, Supabase [experimental] for teams.
- MCP Server Interface -- All 5 core skills plus memory read/write exposed as 10 MCP tools. Works with any MCP-compatible client.
- Primitives Library -- 7 reusable management patterns (checkpoint-and-branch, risk-scoring, secret-detection, rules-validation, context-estimation, scaffold-update, event-capture).
- Auto-Classification -- Events enriched with tags, root cause hints, related event links, and severity context.
- Progressive Enablement -- 5 levels from beginner to advanced. Start simple, add capabilities when ready.
- Tracing -- Span-based tracing with OpenTelemetry-compatible context propagation
- Permissions -- File-level and command-level enforcement with allowlist/denylist
- Cost Management -- Per-session and monthly budget tracking with warn and hard-stop thresholds
- Audit Trail -- Append-only, hash-chained event log with semantic search (EU AI Act Article 12 compliant)
- Plugins -- 4 categories (monitors, auditors, dashboards, integrations) with templates and 11 validation checks
- Evals -- Built-in evaluation harness for testing safety rules against known attack patterns
npm install @calabamatex/agentsentryimport { MemoryStore, createProvider } from '@calabamatex/agentsentry';
const store = new MemoryStore({
provider: createProvider({ provider: 'sqlite', database_path: './ops.db' }),
});
await store.initialize();
// Capture an event
await store.capture({
timestamp: new Date().toISOString(),
session_id: 'session-001',
agent_id: 'agent-coder',
event_type: 'decision',
severity: 'low',
skill: 'save_points',
title: 'Chose JWT with refresh tokens for auth',
detail: 'Selected JWT with rotating refresh tokens for session management',
affected_files: ['src/auth/session.ts'],
tags: ['auth', 'architecture'],
metadata: {},
});
// Search history
const results = await store.search('authentication patterns');For any MCP-compatible client (Claude Code is the primary tested integration):
# Add AgentSentry as an MCP server
claude mcp add agent-sentry -- node agent-sentry/dist/src/mcp/server.jsOr in .cursor/mcp.json:
{
"mcpServers": {
"@calabamatex/agentsentry": {
"command": "node",
"args": ["agent-sentry/dist/src/mcp/server.js"]
}
}
}# Copy slash commands
cp -r agent-sentry/.claude/commands/agent-sentry/ .claude/commands/agent-sentry/Add to .claude/settings.json:
{
"hooks": {
"PreToolUse": [{ "command": "bash agent-sentry/scripts/permission-enforcer.sh" }],
"PostToolUse": [{ "command": "bash agent-sentry/scripts/post-write-checks.sh" }],
"SessionStart": [{ "command": "bash agent-sentry/scripts/session-start-checks.sh" }]
}
}bash agent-sentry/scripts/setup-wizard.shPrompts for your enablement level (1-5) and generates agent-sentry.config.json.
When running as an MCP server, AgentSentry exposes 10 tools:
| Tool | What It Does |
|---|---|
agent_sentry_check_git |
Git hygiene status -- uncommitted files, time since last commit, branch safety |
agent_sentry_check_context |
Context window usage, degradation signals, continue/refresh recommendation |
agent_sentry_check_rules |
Validates a proposed change against rules files, returns violations |
agent_sentry_size_task |
Risk score + decomposition recommendation for a task description |
agent_sentry_scan_security |
Scans for secrets and dangerous code patterns (SQL injection, eval, private keys) |
agent_sentry_capture_event |
Writes a decision, violation, or incident to persistent memory |
agent_sentry_search_history |
Semantic search across all stored operational events |
agent_sentry_recall_context |
Cross-session context recall -- finds relevant prior session data for current task |
agent_sentry_generate_handoff |
Generates a structured handoff message for session continuity |
agent_sentry_health |
Current health scores, KPIs, and skill-level status |
Security note (v0.6.0+): The MCP server now requires authentication by default. Set
AGENT_SENTRY_ACCESS_KEYto a strong random value to start the server. For local development, setAGENT_SENTRY_NO_AUTH=trueto disable authentication (unsafe — emits a stderr warning). The deprecatedAGENT_SENTRY_REQUIRE_AUTHvariable has been removed.
| Level | Name | What's Active | Setup Time |
|---|---|---|---|
| 1 | Safe Ground | save_points (full) | 5 min |
| 2 | Clear Head | + context_health (full) | 10 min |
| 3 | House Rules | + standing_orders (basic), + directive_compliance (full) | 15 min |
| 4 | Right Size | standing_orders → full, + small_bets (basic) | 15 min |
| 5 | Full Guard | small_bets → full, + proactive_safety (full) | 15 min |
Start at Level 1. Upgrade when ready. Each level builds on the last.
All settings in agent-sentry/agent-sentry.config.json:
| Section | Setting | Default(s) |
|---|---|---|
| enablement | level | 2 |
| memory | provider | sqlite |
| memory | embedding_provider | auto |
| save_points | auto_commit_after_minutes | 30 |
| save_points | auto_branch_on_risk_score | 8 |
| context_health | context_percent_critical | 80 |
| task_sizing | high_risk_threshold | 8 |
| security | block_on_secret_detection | true |
| budget | session_budget | $10 |
| budget | monthly_budget | $500 |
// Solo developer (default -- zero config):
{ "memory": { "provider": "sqlite", "database_path": "agent-sentry/data/ops.db" } }
// Team setup (shared memory) [experimental — not recommended for production]:
// Supabase provider reads credentials from environment variables:
// SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY
{ "memory": { "provider": "supabase" } }Note: Migration tooling between providers is planned for a future release.
Context health monitors token usage via message count and triggers a two-stage handoff when the context window fills up:
- 60% (warning): Claude is directed to call
agent_sentry_generate_handoffproactively with a session summary and remaining work items. This produces a complete handoff prompt. - 80% (critical): The session is blocked (
exit 2). A git-state-only handoff is auto-printed with branch, last commit, uncommitted changes, and a paste-ready continuation prompt. The user is prompted to start a fresh session. - After
/compact:message_countresets to 0. Context health monitoring resumes from zero.
Token estimation uses message count multiplied by tokens_per_message (default 4000, configurable). File scanning is not used — hooks cannot know which files Claude actually read into the context window.
Single-file HTML dashboard with no external dependencies. Adapts to your enablement level.
open agent-sentry/dashboard/agent-sentry-dashboard.html
# Or serve it:
npx serve agent-sentry/dashboard/Baseline performance on Node v22, darwin/arm64, 8 CPU / 16 GB:
| Operation | ops/sec |
|---|---|
| Insert | 30 |
| Search | 62 |
| Batch | 184 |
| Cache | 118 |
| Concurrent | 147 |
Run benchmarks locally:
npm run benchmark- Vector search uses linear cosine similarity (O(n)), suitable for up to ~10,000 events per store. An ANN/HNSW index is planned for a future release. Text-based fallback search is available when vector search is not configured.
- Supabase provider is experimental and not recommended for production use.
- Dashboard authentication uses a shared token; no user-level access control.
npm install # Install dependencies
npm run build # Compile TypeScript
npm test # Run all tests
npm run benchmark # Run performance benchmarksNote: The npm package source lives in
agent-sentry/. Run allnpmcommands from that directory.
agent-sentry/
src/
memory/ # MemoryStore, embeddings, providers, migrations
mcp/ # MCP server, 10 tools, transport, auth
primitives/ # 7 reusable management patterns
cli/ # CLI commands, TypeScript hook handlers
scripts/ # Thin wrapper hooks, setup wizard, validators
templates/ # CONTEXT.md, PLANNING.md, TASKS.md, WORKFLOW.md
dashboard/ # Single-file HTML monitoring dashboard
tracing/ # Span-based tracing
audit/ # Append-only hash-chained audit log
plugins/ # Templates and community plugins
evals/ # Safety rule evaluation harness
models/ # Bundled ONNX embedding model (~23MB)
npx @calabamatex/agentsentry init # Interactive project setup wizard
npx @calabamatex/agentsentry config # View or update agent-sentry.config.json
npx @calabamatex/agentsentry enable <level> # Set enablement level (1-5)
npx @calabamatex/agentsentry health # System health and embedding status
npx @calabamatex/agentsentry memory # Query persistent memory store
npx @calabamatex/agentsentry metrics # Session and cost metrics
npx @calabamatex/agentsentry dashboard # Launch monitoring dashboard
npx @calabamatex/agentsentry stream # Live event stream
npx @calabamatex/agentsentry plugin # Plugin management
npx @calabamatex/agentsentry handoff # Generate session handoff message
npx @calabamatex/agentsentry prune # Clean up old events from memory store
npx @calabamatex/agentsentry export # Export memory store data
npx @calabamatex/agentsentry import # Import memory store data/agent-sentry check-- Run all health and safety checks/agent-sentry audit-- Generate a full security audit report/agent-sentry scaffold-- Create planning and workflow files from templates
MIT -- see LICENSE for details.
- Getting Started Guide
- First Session Walkthrough
- API Reference
- Product Specification -- Full spec covering architecture, skills, memory, MCP, and integrations
- Architecture Evolution -- Design decisions and architectural history
- Implementation Guide -- Practical guide for managing AI agents
- Synopsis -- Non-technical project overview
- Memory Model -- Hash chains, search, and storage providers
- Enablement Model -- 5 levels with skill mapping
- MCP Integration -- Tools, transports, and auth
- Configuration Reference -- Every config option explained
- Dashboard Guide -- Monitoring dashboard and streaming
- Supabase Setup -- Remote storage for teams
- Troubleshooting -- Common issues and solutions
- Changelog -- Version history
- Contributing -- Development setup and PR process