Agent Kernel

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:

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](./docs/INSTALLANDAGENT_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_LINKING.md)
• [docs/SAFE_GIT_HOOKS.md](./docs/SAFEGITHOOKS.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](./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](./docs/STATICMEMORYDASHBOARD.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  \
  --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/AGENTWRITEMODES.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](./docs/ARCHITECTURE_GUARDIAN.md) and the canonical [skills/architecture-guardian/](./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  --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/FAILURELESSONSPROTOCOL.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  --dry-run --json
agent-kernel session compact  --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](./docs/RETENTIONANDPORTABILITY.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  --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.