AgentSentry v0.5.0-beta

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.

---

Install

npm install @calabamatex/agentsentry

Or clone and use directly:

git clone https://github.com/calabamatex/AgentSentry.git
cd AgentSentry/agent-sentry && npm install && npm run build

Requirements: 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.

---

What AgentSentry Does

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.

---

Features

Core Skills

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+)

Memory & Intelligence

• 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.

Advanced Capabilities

• 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

---

Quick Start

Option 1: npm Package

npm install @calabamatex/agentsentry

import { 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');

Option 2: MCP Server

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.js

Or in .cursor/mcp.json:

{
  "mcpServers": {
    "@calabamatex/agentsentry": {
      "command": "node",
      "args": ["agent-sentry/dist/src/mcp/server.js"]
    }
  }
}

Option 3: Claude Code Hooks

# 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" }]
  }
}

Setup Wizard

bash agent-sentry/scripts/setup-wizard.sh

Prompts for your enablement level (1-5) and generates agent-sentry.config.json.

---

MCP Tools

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_KEY to a strong random value to start the server. For local development, set AGENT_SENTRY_NO_AUTH=true to disable authentication (unsafe — emits a stderr warning). The deprecated AGENT_SENTRY_REQUIRE_AUTH variable has been removed.

---

Progressive Enablement

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.

---

Configuration

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

Memory Providers

// 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 Details

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_handoff proactively 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_count resets 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.

---

Dashboard

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/

---

Benchmarks

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

---

Known Limitations

• 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.

---

Development

npm install        # Install dependencies
npm run build      # Compile TypeScript
npm test           # Run all tests
npm run benchmark  # Run performance benchmarks

---

Project Structure

Note: The npm package source lives in agent-sentry/. Run all npm commands 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)

---

CLI Commands

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

Slash Commands

• /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

---

License

MIT -- see LICENSE for details.

---

Links

• 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