# Agent Kernel > Local governance, memory, failure lessons, and architecture guardrails for Claude Code, Codex, Cursor, Gemini CLI, and other AI coding agents. - **Type:** MCP server - **Install:** `agentstack add mcp-immamdouhaboammar-agent-kernel` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [imMamdouhaboammar](https://agentstack.voostack.com/s/immamdouhaboammar) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [imMamdouhaboammar](https://github.com/imMamdouhaboammar) - **Source:** https://github.com/imMamdouhaboammar/agent-kernel - **Website:** https://www.npmjs.com/package/@mamdouh-aboammar/agent-kernel ## Install ```sh agentstack add mcp-immamdouhaboammar-agent-kernel ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About Agent Kernel Local memory, trust boundaries, and architecture controls for the AI coding agents you already use. Install once. Give Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Antigravity, and AGENTS.md-compatible tools one shared source of truth for repository rules, user preferences, workflows, debugging lessons, architecture policies, and generated agent instructions. Current stable release: v1.10.0 Trust-aware agent proposals and runtime capture, transaction-safe project linking, worktree-safe Git hooks, retention and portability, trusted CLI updates, Architecture Guardian, and local reporting. --- ## Why install Agent Kernel AI coding agents are useful, but most sessions still begin with missing context. The agent forgets repository rules, repeats old mistakes, runs commands you already rejected, or produces working code that quietly weakens the architecture. Agent Kernel adds a small local operating layer around those tools. | Recurring problem | What Agent Kernel provides | |---|---| | You repeat the same rules in every prompt | Durable local memory compiled into agent-readable files | | Claude, Codex, Cursor, and Gemini drift from each other | One source of truth distributed to each supported surface | | The same build or test failure returns | Failure Lessons with command, error, root cause, fix, and evidence | | AI-generated code creates hidden dependency drift | Architecture Guardian with maps, policies, contracts, baselines, exceptions, and reports | | An agent creates a second service or validator that already exists | Reuse-first symbol search before new capabilities are introduced | | Agents identify useful rules but should not save them silently | A pending proposal inbox with explicit user approval | | Existing AGENTS.md, CLAUDE.md, or Git hooks may be damaged | Dry-run-first, marker-aware, atomic installers | | Local runtime evidence grows indefinitely | Retention status, explicit pruning, deterministic compaction, and local reports | | You need to move local state safely | Redacted exports, review-first imports, and replacement backups | | You need to inspect everything already stored | One adaptive, read-only static HTML dashboard with copy-assisted review commands | | Installed agent tooling drifts behind a reviewed release channel | Cached update checks, agent notifications, explicit allowlists, exact-version installation, verification, and rollback | | You do not want a hosted platform | A Node CLI, local JSON files, optional hooks, optional MCP, and zero runtime dependencies | The practical result is simple: keep using your current agents without making every session relearn the same standards, failures, and architecture boundaries. --- ## What Agent Kernel is Agent Kernel is not another coding agent. It does not replace Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Antigravity, or any AGENTS.md-compatible tool. It sits around them as a local governance layer: ```text your rules, preferences, workflows, project notes, policies, failure lessons, and reviewed architecture constraints -> local Agent Kernel JSON and project-local architecture state -> compile, safe-link, hooks, MCP, retention, dashboard, updates, and conformance checks -> AGENTS.md, CLAUDE.md, GEMINI.md, Cursor rules, Codex files, dashboards, reports -> agents start with better context and clearer boundaries ``` The approval boundary stays explicit: ```text agent notices a durable lesson -> agent captures evidence or creates a pending proposal -> user reviews the inbox, dashboard, policy, contract, baseline, exception, or updater trust change -> user approves only what should last or which agent may update the CLI -> Agent Kernel publishes guidance or enforces the reviewed boundary ``` Autopilot here means repeated context and checking work can be automated. Approval remains user-owned. --- ## Lightweight by design Agent Kernel is currently: - one npm package - a local `~/.agent-kernel/` home - project-local `.agent-kernel/architecture/` state when Architecture Guardian is used - JSON-first storage - generated Markdown and config surfaces - optional Git and Claude hooks - optional local stdio MCP server - optional local daemon for live context capture - optional static read-only memory dashboard - optional agent-approved CLI updater - zero runtime npm dependencies It is not: - a hosted memory service - a database server - a cloud account - a background daemon by default - a browser administration API - a silent updater on every command - a replacement for tests, CI, code review, or architecture decisions - a secret store --- ## Install ```bash npm install -g @mamdouh-aboammar/agent-kernel agent-kernel --version agent-kernel doctor ``` Run without a global install: ```bash npx -y @mamdouh-aboammar/agent-kernel --version ``` Requires Node.js `>=18.18.0`. Read [`docs/INSTALL_AND_AGENT_SETUP.md`](./docs/INSTALL_AND_AGENT_SETUP.md) for the complete setup path. --- ## Fastest safe setup Use this flow for an existing repository. It previews changes, preserves hand-written instructions, and writes Agent Kernel content only inside managed blocks. ```bash cd ~/Projects/YourProject agent-kernel init --sync --enforce agent-kernel compile agent-kernel-safe-link . --dry-run agent-kernel-safe-link . agent-kernel-safe-git-hook . --dry-run agent-kernel-safe-git-hook . agent-kernel doctor ``` Typical project-local outputs: ```text AGENTS.md # AGENTS-compatible guidance CLAUDE.md # Claude Code guidance .cursor/rules/00-agent-kernel.mdc # Cursor rule .codex/AGENTS.md # Codex guidance .codex/config.toml # Codex config .agents/agents.md # Antigravity-style guidance .agents/skills/README.md # Antigravity-style skills index GEMINI.md # Gemini CLI guidance .git/hooks/pre-commit # Optional staged-file guard ``` For a clean or controlled project, the direct path is also available: ```bash agent-kernel link . --hooks ``` For an existing repository, prefer the safe installers first: - [`docs/SAFE_LINKING.md`](./docs/SAFE_LINKING.md) - [`docs/SAFE_GIT_HOOKS.md`](./docs/SAFE_GIT_HOOKS.md) --- ## Trusted CLI updates Initialize Agent Kernel, then enable agent-approved mode once and define the identities that may apply an update: ```bash agent-kernel init agent-kernel update enable --agents claude,codex ``` Check the configured channel, which defaults to npm `latest`: ```bash agent-kernel update status agent-kernel update check ``` A trusted agent can then install the exact resolved version: ```bash agent-kernel update apply --agent claude ``` Use another dist-tag or pin an exact semantic version: ```bash agent-kernel update channel next agent-kernel update channel 2.0.0-beta.1 ``` When agent-approved mode is enabled, `doctor`, `start`, `compile`, `sync`, and `status` opportunistically refresh a stale update cache at most once per configured interval. The refresh never installs a package, is skipped for `--json`, and does not fail the requested lifecycle command when npm is unavailable. Other commands read cached state only. Existing Claude, Codex, Cursor, Antigravity, and Gemini guidance files receive the cached notice after successful update, init, compile, sync, or link commands. A malformed managed marker causes that file to be skipped rather than truncated. The apply path authorizes the agent before npm runs, installs an exact version without shell interpolation, verifies the reported CLI version, runs health and compile commands, and attempts one rollback when post-install verification fails. A valid prior cache remains available when a later registry refresh fails. All updater actions write bounded audit records without npm output, environment dumps, or credentials. Read [`docs/UPDATES.md`](./docs/UPDATES.md) before enabling agent-approved installation. --- ## Local memory dashboard Generate one adaptive HTML snapshot of the Agent Kernel state already stored on the machine and open it in the default browser: ```bash agent-kernel dashboard ``` Generate only, choose another output, or request structured CLI output: ```bash agent-kernel dashboard --no-open agent-kernel dashboard --out ./agent-kernel-dashboard.html --no-open agent-kernel dashboard --json agent-kernel dashboard --json --open agent-kernel dashboard --project /path/to/repository ``` The stable default file is `~/.agent-kernel/reports/dashboard.html`. Empty sections are omitted. Available sections include proposal lifecycle history, memories, rules, skill triggers, policies, episodes, Failure Lessons, sessions, agents, projects, commit links, updater status, retention, bounded audit history, and the selected project's Architecture Guardian summary. Pending cards expose copy-only text for `inbox`, `approve --publish`, and `reject`. The browser cannot execute those commands or mutate Agent Kernel state. The self-contained page uses no remote assets or network requests, HTML-escapes stored content, redacts sensitive values, replaces absolute paths with neutral labels, and applies a restrictive Content Security Policy. Output is atomic. Symbolic or non-regular targets and symbolic existing parents are rejected. If the operating system browser cannot open, the generated file remains valid. Read [`docs/STATIC_MEMORY_DASHBOARD.md`](./docs/STATIC_MEMORY_DASHBOARD.md) for the complete privacy and browser boundary. --- ## Trust-aware agent writes Agent Kernel separates durable memory proposals from ephemeral runtime capture. | Trust level | Read | Capture sessions | Propose memory | Direct approved memory | |---|---:|---:|---:|---:| | `read-only` | yes | no | no | no | | `capture-only` | yes | yes | no | no | | `propose-only` | yes | yes | yes | no | | `trusted-local` | yes | yes | yes | limited governed actions only | Unknown agents receive a transient `read-only` identity. A denied lookup does not silently register the agent. Inspect or set a mode explicitly: ```bash agent-kernel-agent-write mode list agent-kernel-agent-write mode get cursor agent-kernel-agent-write mode set cursor capture-only ``` Create a pending memory proposal from an allowed agent: ```bash agent-kernel-agent-propose \ --from codex \ --reason 'The user corrected this workflow twice.' \ --text 'Always run the documented verification command before claiming completion.' ``` Capture runtime evidence without publishing durable memory: ```bash agent-kernel-agent-write session-start --agent cursor --project agent-kernel agent-kernel-agent-write observe \ --agent cursor \ --session \ --type test_failure \ --command 'npm test' \ --exit-code 1 \ --text 'The smoke suite failed during command routing.' agent-kernel-agent-write session-end --agent cursor --session ``` Both helpers reject unknown or duplicate options, ambiguous text sources, invalid fields, and unsafe identifiers before invoking the core runtime. Structured output is available with `--json`. Read: - [`docs/AGENT_PROPOSALS.md`](./docs/AGENT_PROPOSALS.md) - [`docs/AGENT_WRITE_MODES.md`](./docs/AGENT_WRITE_MODES.md) --- ## Architecture Guardian Architecture Guardian prevents working code from hiding structural regressions. It maps source dependencies, checks reviewed boundaries, searches existing capabilities, distinguishes old debt from new violations, and can block writes outside an active change contract. Start in review mode: ```bash cd ~/Projects/YourProject agent-kernel architecture init . # Review and edit .agent-kernel/architecture/policy.json agent-kernel architecture policy validate . agent-kernel architecture discover . --json agent-kernel architecture baseline . --json ``` Before a non-trivial change: ```bash agent-kernel architecture contract init . \ --task 'Add subscription cancellation' \ --owner billing \ --allow 'src/billing/**,test/billing/**' \ --expect 'src/billing/cancel-subscription.ts,test/billing/cancel-subscription.test.ts' \ --tests 'cancel active subscription,idempotent cancellation' agent-kernel architecture reuse 'cancel subscription' . --json agent-kernel architecture check . --json ``` Use strict mode for a blocking local or CI gate: ```bash agent-kernel architecture check . --base origin/master --strict --json ``` Architecture Guardian includes: - source-root-scoped architecture maps - local dependency and circular dependency detection - layer and forbidden dependency policies - external package evidence and allow or deny policies - active change contracts for files, dependencies, and test expectations - baseline classification so old debt is not blamed on a new change - scoped exceptions with owner, reason, and expiry - reuse-first search across existing symbols - review and strict modes - Claude `PreToolUse` scope enforcement for Write, Edit, and MultiEdit - fail-closed handling for malformed governance state - iterative graph traversal for large dependency graphs - standard-library false-positive controls for Node, Python, and Go Read [`docs/ARCHITECTURE_GUARDIAN.md`](./docs/ARCHITECTURE_GUARDIAN.md) and the canonical [`skills/architecture-guardian/`](./skills/architecture-guardian/) skill. --- ## Failure Lessons Capture the useful parts of a recurring failure: ```bash agent-kernel failure capture \ --from claude \ --type test-failure \ --command 'npm test' \ --exit-code 1 \ --text 'ERR_MODULE_NOT_FOUND' \ --root-cause 'A Node ESM import path omitted its explicit extension.' \ --fix 'Add the explicit extension to the relative import.' ``` Search before retrying: ```bash agent-kernel failure search ERR_MODULE_NOT_FOUND ``` Promote a recurring lesson into reviewable memory: ```bash agent-kernel failure propose --as rule agent-kernel inbox agent-kernel approve --publish ``` Promotion creates a pending proposal. It does not approve or publish memory automatically. Read [`docs/FAILURE_LESSONS_PROTOCOL.md`](./docs/FAILURE_LESSONS_PROTOCOL.md). --- ## Retention, backup, and local reporting Inspect local runtime retention before deleting anything: ```bash agent-kernel retention status agent-kernel retention status --older-than 30d --json ``` Preview and then apply raw-observation pruning: ```bash agent-kernel retention prune --older-than 30d --dry-run agent-kernel retention prune --older-than 30d --force ``` Compact one session without deleting its raw log: ```bash agent-kernel session compact --dry-run --json agent-kernel session compact --json ``` Create a redacted backup and inspect it before import: ```bash agent-kernel export ./agent-kernel-backup.json --redact --include-observations agent-kernel import ./agent-kernel-backup.json --inspect --json ``` Normal imports create pending proposals. Explicit replacement creates a local backup before replacing managed state: ```bash agent-kernel import ./agent-kernel-backup.json --to inbox agent-kernel import ./agent-kernel-backup.json --replace ``` Inspect local state, open the adaptive dashboard, or create a script-free report: ```bash agent-kernel view agent-kernel view failures agent-kernel dashboard agent-kernel report ./agent-kernel-report.html ``` Exports, dashboards, and reports remain local files. Review them before sharing or committing them. Read [`docs/RETENTION_AND_PORTABILITY.md`](./docs/RETENTION_AND_PORTABILITY.md). --- ## Optional live runtime Agent Kernel can run a small local daemon when you explicitly need live session evidence and context calls. It is stopped by default and binds to `127.0.0.1` unless you override it. ```bash agent-kernel daemon start agent-kernel daemon status agent-kernel daemon stop ``` Runtime sessions can also be managed directly: ```bash agent-kernel session start --agent claude-code --project . agent-kernel session observe --type command_ … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [imMamdouhaboammar](https://github.com/imMamdouhaboammar) - **Source:** [imMamdouhaboammar/agent-kernel](https://github.com/imMamdouhaboammar/agent-kernel) - **License:** MIT - **Homepage:** https://www.npmjs.com/package/@mamdouh-aboammar/agent-kernel Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-immamdouhaboammar-agent-kernel - Seller: https://agentstack.voostack.com/s/immamdouhaboammar - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.