Architecture

Alfred has three independent capabilities: Workspace, Memory, and Agent Harness. Agent Harness is shaped by a harness-agnostic core, deny-by-default security, and evals-as-gate. This page explains why it is built the way it is, and what that means for your agents and skills.

Capability composition

The neutral packages/cli routes commands to public capability entrypoints. Workspace, Memory, and Agent Harness do not import each other's implementations or require peer services. Optional connections use explicitly configured public contracts. Selecting components does not wire credentials, MCP, or a session runtime.

Workspace owns SessionPort/SessionAdapter; Memory owns its persistence APIs; Agent Harness owns agent operations and harness integration. See Product capabilities for current implementation limits.

Hexagonal architecture

The Agent Harness family is split into a core and a set of adapters. The rule is enforced by the build, not by convention:

• packages/core imports nothing from packages/*-adapter.
• Adapters depend on core. They never redefine domain rules.
• The boundary is checked by scripts/validate-policies.mjs in CI.

Domain-driven design

The domain lives in .ai/domain/model.md. Entities, value objects, use cases, and ports are written in plain markdown so the agents themselves can read them.

The vocabulary is fixed:

• Agent — a role with a mode (primary or subagent).
• Skill — lazy-loaded instructions keyed by trigger.
• Harness — the runtime that hosts the agent (Pi, opencode, Codex, ...).
• PermissionPolicy — deny-by-default, protected paths, destructive commands.
• TraceEvent — the atomic unit of observability.
• EvalCase / Baseline — the regression gate.
• TemporaryAgent — a subagent with a lifecycle, never promoted without human approval.

The architecture kernel

Every agent reads the same kernel file at the top of its prompt. The kernel pins the rules the LLM cannot negotiate:

# Alfred kernel (excerpt)
1. Local-first. Deterministic local work before any provider call.
2. Deny by default. Protected paths require human approval.
3. No self-escalation. Agents do not broaden their own permissions.
4. Trace everything. Emit a TraceEvent per operation.
5. Evals gate everything. Run regression suite before declaring done.
6. Skills are lazy. Activate by trigger, never by file presence.
7. Specialists are temporary. Promotion requires a human.

Package layout

The legacy launcher paths under Memory are compatibility shims only. Standalone Memory does not import those product shims.

Everything is a trace

Every meaningful operation writes a TraceEvent into .ai/observability/generated/. The trace log is the source of truth for debugging, replaying, and reviewing agent behavior.

{"ts":"2026-06-30T18:02:11Z","kind":"provider.request","agent":"developer","decision":"local-only","avoided_cost_usd":0.002}
{"ts":"2026-06-30T18:02:14Z","kind":"permission.request","path":".ai/policies/security.md","decision":"deny","actor":"human"}
{"ts":"2026-06-30T18:02:18Z","kind":"eval.run","suite":"default","passed":14,"failed":0,"vs_baseline":"regression-safe"}

Local-first in practice

Before any provider call, Alfred's ProviderRequestPolicy runs a deterministic checklist:

1. Can a local capability answer this?
2. Can preprocessing reduce the payload?
3. What is the estimated token / cost impact?
4. Emit local-only, hybrid, or provider.
5. Trace the decision, including avoided cost.

Security, summarized

• Deny by default. Allowlists are explicit and minimal.
• Protected paths (.ai/, .opencode/, harnesses/) require human approval.
• Destructive commands (rm -rf, git reset --hard, ...) require human approval.
• Skills cannot override security policy. Only a human can.
• Adapters enforce policy. They do not own it.