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:

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:

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

npm install -g @mamdouh-aboammar/agent-kernel
agent-kernel --version
agent-kernel doctor

Run without a global install:

npx -y @mamdouh-aboammar/agent-kernel --version

Requires Node.js >=18.18.0.

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

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:

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:

agent-kernel link . --hooks

For an existing repository, prefer the safe installers first:

• docs/SAFE_LINKING.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:

agent-kernel init
agent-kernel update enable --agents claude,codex

Check the configured channel, which defaults to npm latest:

agent-kernel update status
agent-kernel update check

A trusted agent can then install the exact resolved version:

agent-kernel update apply --agent claude

Use another dist-tag or pin an exact semantic version:

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

agent-kernel dashboard

Generate only, choose another output, or request structured CLI output:

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

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:

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:

agent-kernel-agent-write session-start --agent cursor --project agent-kernel
agent-kernel-agent-write observe \
  --agent cursor \
  --session <session-id> \
  --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 <session-id>

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

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:

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:

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 and the canonical skills/architecture-guardian/ skill.

Failure Lessons

Capture the useful parts of a recurring failure:

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:

agent-kernel failure search ERR_MODULE_NOT_FOUND

Promote a recurring lesson into reviewable memory:

agent-kernel failure propose <failure-lesson-id> --as rule
agent-kernel inbox
agent-kernel approve <proposal-id> --publish

Promotion creates a pending proposal. It does not approve or publish memory automatically.

Read docs/FAILURE_LESSONS_PROTOCOL.md.

Retention, backup, and local reporting

Inspect local runtime retention before deleting anything:

agent-kernel retention status
agent-kernel retention status --older-than 30d --json

Preview and then apply raw-observation pruning:

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:

agent-kernel session compact <session-id> --dry-run --json
agent-kernel session compact <session-id> --json

Create a redacted backup and inspect it before import:

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:

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:

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.

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.

agent-kernel daemon start
agent-kernel daemon status
agent-kernel daemon stop

Runtime sessions can also be managed directly:

agent-kernel session start --agent claude-code --project .
agent-kernel session observe <session-id> --type command_failure --text 'npm test failed' --command 'npm test'
agent-kernel session observations <session-id> --type command_failure
agent-kernel session list
agent-kernel session show <session-id>
agent-kernel session end <session-id>

Request local context without starting the daemon:

agent-kernel context --query 'safe-link duplicate block' --file src/cli.mjs --budget 1200
agent-kernel context --query 'memory changes' --json

Runtime observations are evidence. They do not become approved memory unless a user promotes them through the normal proposal and approval flow.

Core command surface

agent-kernel init [--sync] [--enforce]
agent-kernel doctor [--runtime]
agent-kernel compile
agent-kernel sync
agent-kernel link [project] [--hooks]
agent-kernel remember <text> [--type rule] [--level critical] [--publish]
agent-kernel propose --from <agent> --text <text> --reason <reason>
agent-kernel inbox
agent-kernel approve <id> [--publish]
agent-kernel reject <id>
agent-kernel publish
agent-kernel validate
agent-kernel migrate json [--publish]
agent-kernel memory list|search|show
agent-kernel episode add|sync|search|show|stats|reindex
agent-kernel failure capture|learn|list|search|show|patterns|propose|propose-pattern|promote|validate
agent-kernel architecture init|discover|baseline|diff|check|reuse|contract|exception|policy|doctor
agent-kernel dashboard [--out file.html] [--project path] [--no-open|--open] [--json]
agent-kernel update status|check|enable|disable|channel|trust|revoke|apply
agent-kernel retention status|prune
agent-kernel export <file.json>
agent-kernel import <file.json>
agent-kernel view [sessions|failures|inbox|agents]
agent-kernel report <file.html>
agent-kernel context [--query text] [--file path] [--budget 1200]
agent-kernel daemon start|stop|restart|status
agent-kernel session start|end|list|show|observe|observations|compact
agent-kernel agent list|add|set|show|remove
agent-kernel project identify|list|show|set-id
agent-kernel commit link|list|show|context
agent-kernel enforce install
agent-kernel guard [--staged|--file path]
agent-kernel git-hook install [project]
agent-kernel mcp serve|config|install
agent-kernel start <claude|codex|cursor|antigravity|gemini> [project]
agent-kernel status [--runtime]

Public helper binaries:

agent-kernel-search
agent-kernel-claude-context-hook
agent-kernel-safe-link
agent-kernel-safe-git-hook
agent-kernel-agent-propose
agent-kernel-failure
agent-kernel-failure-hook
agent-kernel-daemon
agent-kernel-runtime-doctor
agent-kernel-session
agent-kernel-context
agent-kernel-mode
agent-kernel-agent-write
agent-kernel-architecture
agent-kernel-architecture-hook
agent-kernel
ak

Agent integrations

| Agent or surface | Output or integration | |---|---| | Claude Code | CLAUDE.md, context and architecture hooks, MCP config, marketplace plugin metadata, repo-local skills | | Codex | AGENTS.md, .codex/AGENTS.md, .codex/config.toml, repo-local skills | | Cursor | .cursor/rules/00-agent-kernel.mdc | | OpenCode and AGENTS-compatible agents | AGENTS.md | | Antigravity | .agents/agents.md, .agents/skills/* | | Gemini CLI | GEMINI.md | | Skills.sh | SKILL.md, skills.sh.json, skills/architecture-guardian/SKILL.md |

Keep credentials and private MCP details in user-level configuration, not repo-local generated files.

Read docs/INTEGRATIONS.md for the support matrix and client-specific guides.

Safety model

• Agents may propose durable memory. Only reviewed user actions should approve and publish it.
• Unknown agents default to a transient read-only identity.
• Runtime capture and durable proposals use separate restricted helpers.
• Dashboard generation is local, read-only, adaptive, redacted, HTML-escaped, CSP-restricted, and atomic.
• Dashboard controls copy text only; the browser cannot execute approval or mutation commands.
• Dashboard output rejects symbolic and non-regular targets and symbolic existing parent directories.
• Updater governance changes require initialized state and preserve malformed configuration instead of overwriting it.
• Updater installation is disabled by default and requires an explicitly allowlisted agent identity.
• Updater trust and channel changes require terminal confirmation or an explicit reviewed --yes command.
• Selected lifecycle commands may refresh stale update metadata, but never install a package.
• Exact-version updater installs are verified and may roll back once on post-install failure.
• Failure Lessons capture evidence first. Promotion creates a pending proposal.
• Architecture policies, baselines, contracts, and exceptions are review artifacts.
• Review mode reports candidate blockers. Strict mode enforces reviewed blocking severities.
• Baseline findings remain visible but do not fail an unrelated change.
• Exceptions require scope, reason, owner, and expiry.
• Safe-link and safe Git hook installers preview changes and use managed markers.
• Portability exports redact known secret patterns and sensitive key names before writing.
• Critical rules should also be backed by permissions, guard checks, hooks, or CI.
• Repo-local configs must remain minimal, reviewable, and credential-free.
• Built-in guards cover dangerous recursive deletion, pipe-to-shell commands, permissive recursive chmod, force-push to protected branches, .git deletion, and common secret patterns.

Documentation map

Start with docs/README.md.

| Need | Read | |---|---| | Install and connect agents | docs/INSTALL_AND_AGENT_SETUP.md | | Inspect local memory and runtime state in a browser | docs/STATIC_MEMORY_DASHBOARD.md | | Configure trusted CLI updates | docs/UPDATES.md | | Understand the operating model | docs/OPERATING_MODEL.md | | Current repository architecture | docs/ARCHITECTURE_NOW.md | | Prevent AI-generated architecture drift | docs/ARCHITECTURE_GUARDIAN.md | | Architecture command reference | docs/architecture-guardian/COMMAND_REFERENCE.md | | Agent proposal trust boundary | docs/AGENT_PROPOSALS.md | | Agent runtime write modes | docs/AGENT_WRITE_MODES.md | | Retention, export, import, and reports | docs/RETENTION_AND_PORTABILITY.md | | Safe project linking | docs/SAFE_LINKING.md | | Safe Git hook installation | docs/SAFE_GIT_HOOKS.md | | Failure Lessons | docs/FAILURE_LESSONS_PROTOCOL.md | | MCP server | docs/MCP_SERVER.md | | Agent integrations | docs/INTEGRATIONS.md | | Troubleshoot setup or runtime issues | docs/TROUBLESHOOTING.md | | AI agent contributor runbook | docs/AGENT_RUNBOOK.md | | Knowledge Bundle plan | docs/BUNDLE_KB.md |

Planned: Knowledge Bundle

Knowledge Bundle is a planned sharing layer for approved memory, Failure Lessons, policies, skills, workflows, and selected episodes in a portable .akb file.

It is not part of the current v1.10.0 command surface. The proposed design remains review-first so a bundle cannot silently overwrite another user's approved memory.

Read docs/BUNDLE_KB.md.

Development

git clone https://github.com/imMamdouhaboammar/agent-kernel
cd agent-kernel

npm install
npm run build
npm test
npm run lint
npm run typecheck
npm run size
npm run publish:dry

Repository-defined validation includes version alignment, smoke tests, bin and mode linting, documentation link checks, TypeScript checks, and package previews.

Read CONTRIBUTING.md and AGENTS.md before changing runtime behavior.

Links

• npm: https://www.npmjs.com/package/@mamdouh-aboammar/agent-kernel
• Repository: https://github.com/imMamdouhaboammar/agent-kernel
• Issues: https://github.com/imMamdouhaboammar/agent-kernel/issues
• Releases: https://github.com/imMamdouhaboammar/agent-kernel/releases
• Skills.sh: https://skills.sh/imMamdouhaboammar/agent-kernel
• delegate-team integration: https://github.com/imMamdouhaboammar/delegate-team/blob/master/integrations/agent-kernel.md

License

MIT © Mamdouh Aboammar

Built by Mamdouh Aboammar for everyone who is tired of explaining the same standards to a new agent every morning.