# codejunkie99/agentic-stack architecture

> Architecture diagram of the GitHub repository codejunkie99/agentic-stack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codejunkie99/agentic-stack
- Repository: https://github.com/codejunkie99/agentic-stack

## Overview

1. **Core shape: a portable `.agent/` brain**
   The repository’s central artifact is a reusable `.agent/` directory that travels with a project. It holds memory, skills, protocols, and supporting tools so the same “brain” can be installed into different coding-agent harnesses without losing state.

2. **Two major control planes**
   There are two top-level control surfaces:
   - the **harness manager** (`harness_manager/`, `install.sh`, `install.ps1`) that installs and maintains adapter-specific wiring
   - the **agent runtime** (`.agent/`) that contains memory, skills, hooks, and recall/learning utilities used during sessions

3. **Adapter layer: one manifest per harness**
   `adapters/` contains small per-harness shims for Claude Code, Cursor, Windsurf, OpenCode, Copilot CLI, Gemini, Hermes, Pi, Codex, Antigravity, OpenClaw, and a standalone Python loop. Each adapter declares how the host harness should load the portable brain via files like `CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, `.windsurfrules`, or harness-specific JSON/config files.

4. **Installer and lifecycle management**
   `install.sh` and `install.ps1` are thin entrypoints into the Python CLI in `harness_manager/cli.py`. That backend applies adapter manifests, tracks state, supports safe removal, audits installations, performs upgrades, and reconstructs manifest state when needed. The design boundary is clear: adapter-owned files vs skeleton-owned `.agent` infrastructure vs user-owned memory.

5. **Memory system: four layers with different retention**
   The portable memory lives under `.agent/memory/` and is split into:
   - **personal** preferences
   - **working** current project context
   - **episodic** raw session/activity logs
   - **semantic** accepted durable lessons and domain knowledge  
   This separation is important for architecture diagrams because it defines the retention and promotion path from temporary activity to long-term memory.

6. **Memory compaction and review pipeline**
   `auto_dream.py` runs a nightly mechanical cycle that clusters episodic data, stages candidate lessons, and applies decay/prefiltering. It does not make semantic decisions itself. Human/host-agent review happens separately through CLI tools like `graduate.py`, `reject.py`, `reopen.py`, and `retract_lesson.py`, which append audit history and update semantic memory.

7. **Recall path during sessions**
   Session-time retrieval is query-aware: the brain reads personal preferences first, then surfaces relevant semantic lessons and working context to the harness. `recall.py`, `show.py`, and `memory_search.py` support this retrieval surface, while `brain_bridge.py` optionally delegates cross-project recall to the external Brain service.

8. **Skills as progressive-disclosure behavior modules**
   Seed skills live in `.agent/skills/` and are indexed by `_index.md` and `_manifest.jsonl`. The model is “always load a lightweight manifest, load full `SKILL.md` only when relevant.” This makes skills a behavior layer distinct from memory: skills describe how to act; memory describes what has been learned.

9. **Protocol enforcement and safety boundary**
   `.agent/protocols/` contains typed tool schemas, delegation guidance, and permission rules. The pre-tool-call hook enforces `permissions.md`, so the architecture has an explicit boundary between allowed and disallowed tool actions before execution, not after the fact.

10. **Hook-based instrumentation**
   The `harness/` layer provides shared hook logic for supported harnesses. Hooks capture post-tool activity, failures, provenance, and episodic I/O. Some adapters wire richer hooks than others, but the common purpose is to log actions into memory and enforce policy consistently across harnesses.

11. **Local data layer: cross-harness observability**
   Separate from memory, the `data-layer` capability aggregates local operational telemetry across all harnesses sharing the same `.agent/`. `data_layer_export.py` produces dashboard-ready outputs such as `dashboard.html`, terminal summaries, daily reports, KPI summaries, token/cost estimates, cron timelines, and harness-mix views. Inputs include local JSONL feeds for cron runs, harness events, and category rules.

12. **Data flywheel: approved runs become training artifacts**
   The `data-flywheel` path is another isolated export pipeline. Approved, redacted runs are transformed into trace records, context cards, eval cases, training-ready JSONL, and readiness metrics. This is explicitly local-only and model-agnostic: it prepares artifacts for future use but does not train or send data externally.

13. **Transfer and upgrade flows**
   The `transfer` wizard packages selected memory and skills into a portable bundle for another harness or project, with secret-like content blocking and SHA verification on import. `upgrade` and `doctor` handle safe refresh and validation of installed `.agent` infrastructure without overwriting user memory or adapter-specific settings.

14. **Optional external and beta integrations**
   Two integrations affect architecture but are optional:
   - **Brain**: an external git-backed long-term memory CLI/MCP server bridged through `agentic-stack brain ...` and `.agent/tools/brain_bridge.py`
   - **tldraw**: an opt-in visual canvas skill with local snapshot storage and adapter-specific MCP wiring  
   These are extensions around the core portable brain, not dependencies of the core system.

15. **Repository support surfaces**
   `docs/` explains the lifecycle and per-harness wiring, `schemas/` defines the shapes of data-layer and flywheel artifacts, `examples/` provides sanitized sample inputs, and `tests/` validates adapters, hooks, memory behavior, and transfer/upgrade flows. Together they reinforce that this repo is a platform for portable agent state, not a single application.

Main entry points: [`harness_manager/cli.py`](https://github.com/codejunkie99/agentic-stack/blob/master/harness_manager/cli.py) (CLI), [`.agent/harness/conductor.py`](https://github.com/codejunkie99/agentic-stack/blob/master/.agent/harness/conductor.py) (Conductor), [`.agent/tools`](https://github.com/codejunkie99/agentic-stack/blob/master/.agent/tools) (Tools), [`.agent/memory`](https://github.com/codejunkie99/agentic-stack/blob/master/.agent/memory) (Memory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_harness_manager["Harness Manager"]
  node_n_hm_cli["CLI<br/>[cli.py]"]
  node_n_hm_state[("State<br/>[state.py]")]
  node_n_hm_upgrade["Upgrade<br/>lifecycle<br/>[upgrade.py]"]
  node_n_hm_transfer["Transfer<br/>bundle<br/>[transfer_bundle.py]"]
  node_n_hm_doctor["Doctor<br/>validation<br/>[doctor.py]"]
end

subgraph group_group_agent_runtime["Agent Runtime"]
  node_n_agent_conductor["Conductor<br/>runtime core<br/>[conductor.py]"]
  node_n_agent_pretool["Pre-tool<br/>policy hook<br/>[pre_tool_call.py]"]
  node_n_agent_postexec["Post-exec<br/>hook<br/>[post_execution.py]"]
  node_n_agent_memory[("Memory<br/>[memory]")]
  node_n_agent_dream["Dream<br/>compaction<br/>[auto_dream.py]"]
  node_n_agent_recall["Recall<br/>retrieval<br/>[memory_search.py]"]
  node_n_agent_promote["Promote<br/>review<br/>[promote.py]"]
  node_n_agent_skills["Skills<br/>behavior layer<br/>[skills]"]
  node_n_agent_tools["Tools<br/>utilities<br/>[tools]"]
  node_n_agent_protocols["Protocols<br/>policy schemas<br/>[protocols]"]
end

subgraph group_group_adapters["Adapters"]
  node_n_adapt_claude["Claude Code<br/>adapter manifest<br/>[adapter.json]"]
  node_n_adapt_cursor["Cursor<br/>adapter manifest<br/>[adapter.json]"]
  node_n_adapt_windsurf["Windsurf<br/>adapter manifest<br/>[adapter.json]"]
  node_n_adapt_copilot["Copilot CLI<br/>adapter manifest<br/>[adapter.json]"]
  node_n_adapt_python["Python Loop<br/>standalone adapter<br/>[run.py]"]
end

subgraph group_group_support["Support"]
  node_n_docs_arch["Architecture<br/>docs<br/>[architecture.md]"]
  node_n_schemas_dl["Data Schemas<br/>json schemas"]
  node_n_examples_dl["Examples<br/>sample data"]
end

node_n_hm_cli -->|"reads/writes"| node_n_hm_state
node_n_hm_cli -->|"invokes"| node_n_hm_upgrade
node_n_hm_cli -->|"invokes"| node_n_hm_transfer
node_n_hm_cli -->|"invokes"| node_n_hm_doctor
node_n_hm_cli -->|"applies"| node_n_adapt_claude
node_n_hm_cli -->|"applies"| node_n_adapt_cursor
node_n_hm_cli -->|"applies"| node_n_adapt_windsurf
node_n_hm_cli -->|"applies"| node_n_adapt_copilot
node_n_hm_cli -->|"supports"| node_n_adapt_python
node_n_agent_conductor -->|"enforces"| node_n_agent_pretool
node_n_agent_conductor -->|"logs"| node_n_agent_postexec
node_n_agent_conductor -->|"uses"| node_n_agent_memory
node_n_agent_dream -->|"compacts"| node_n_agent_memory
node_n_agent_recall -->|"queries"| node_n_agent_memory
node_n_agent_promote -->|"updates"| node_n_agent_memory
node_n_agent_tools -->|"exposes"| node_n_agent_recall
node_n_agent_tools -->|"exposes"| node_n_agent_promote
node_n_agent_tools -->|"loads"| node_n_agent_skills
node_n_agent_tools -->|"consults"| node_n_agent_protocols
node_n_agent_tools -->|"exports"| node_n_schemas_dl
node_n_agent_tools -->|"demonstrates"| node_n_examples_dl
node_n_adapt_claude -->|"boots"| node_n_agent_conductor
node_n_adapt_cursor -->|"boots"| node_n_agent_conductor
node_n_adapt_windsurf -->|"boots"| node_n_agent_conductor
node_n_adapt_copilot -->|"boots"| node_n_agent_conductor
node_n_adapt_python -->|"runs"| node_n_agent_conductor
node_n_docs_arch -->|"describes"| node_n_hm_cli
node_n_docs_arch -->|"describes"| node_n_agent_memory
node_n_docs_arch -->|"documents"| node_n_adapt_claude

click node_n_hm_cli "https://github.com/codejunkie99/agentic-stack/blob/master/harness_manager/cli.py"
click node_n_hm_state "https://github.com/codejunkie99/agentic-stack/blob/master/harness_manager/state.py"
click node_n_hm_upgrade "https://github.com/codejunkie99/agentic-stack/blob/master/harness_manager/upgrade.py"
click node_n_hm_transfer "https://github.com/codejunkie99/agentic-stack/blob/master/harness_manager/transfer_bundle.py"
click node_n_hm_doctor "https://github.com/codejunkie99/agentic-stack/blob/master/harness_manager/doctor.py"
click node_n_agent_conductor "https://github.com/codejunkie99/agentic-stack/blob/master/.agent/harness/conductor.py"
click node_n_agent_pretool "https://github.com/codejunkie99/agentic-stack/blob/master/.agent/harness/hooks/pre_tool_call.py"
click node_n_agent_postexec "https://github.com/codejunkie99/agentic-stack/blob/master/.agent/harness/hooks/post_execution.py"
click node_n_agent_memory "https://github.com/codejunkie99/agentic-stack/blob/master/.agent/memory"
click node_n_agent_dream "https://github.com/codejunkie99/agentic-stack/blob/master/.agent/memory/auto_dream.py"
click node_n_agent_recall "https://github.com/codejunkie99/agentic-stack/blob/master/.agent/memory/memory_search.py"
click node_n_agent_promote "https://github.com/codejunkie99/agentic-stack/blob/master/.agent/memory/promote.py"
click node_n_agent_skills "https://github.com/codejunkie99/agentic-stack/blob/master/.agent/skills"
click node_n_agent_tools "https://github.com/codejunkie99/agentic-stack/blob/master/.agent/tools"
click node_n_agent_protocols "https://github.com/codejunkie99/agentic-stack/blob/master/.agent/protocols"
click node_n_adapt_claude "https://github.com/codejunkie99/agentic-stack/blob/master/adapters/claude-code/adapter.json"
click node_n_adapt_cursor "https://github.com/codejunkie99/agentic-stack/blob/master/adapters/cursor/adapter.json"
click node_n_adapt_windsurf "https://github.com/codejunkie99/agentic-stack/blob/master/adapters/windsurf/adapter.json"
click node_n_adapt_copilot "https://github.com/codejunkie99/agentic-stack/blob/master/adapters/copilot-cli/adapter.json"
click node_n_adapt_python "https://github.com/codejunkie99/agentic-stack/blob/master/adapters/standalone-python/run.py"
click node_n_docs_arch "https://github.com/codejunkie99/agentic-stack/blob/master/docs/architecture.md"
click node_n_schemas_dl "https://github.com/codejunkie99/agentic-stack/tree/master/schemas/data-layer"
click node_n_examples_dl "https://github.com/codejunkie99/agentic-stack/tree/master/examples/data-layer"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_hm_cli,node_n_hm_state,node_n_hm_upgrade,node_n_hm_transfer,node_n_hm_doctor toneBlue
class node_n_agent_conductor,node_n_agent_pretool,node_n_agent_postexec,node_n_agent_memory,node_n_agent_dream,node_n_agent_recall,node_n_agent_promote,node_n_agent_skills,node_n_agent_tools,node_n_agent_protocols toneAmber
class node_n_adapt_claude,node_n_adapt_cursor,node_n_adapt_windsurf,node_n_adapt_copilot,node_n_adapt_python toneMint
class node_n_docs_arch,node_n_schemas_dl,node_n_examples_dl toneRose
```

## Components

### Harness Manager

Install, maintain, upgrade, and transfer the portable brain across host harnesses.

- [CLI](https://github.com/codejunkie99/agentic-stack/blob/master/harness_manager/cli.py): manager cli · Entry point for install, audit, remove, upgrade, and transfer operations. · `harness_manager/cli.py`
- [State](https://github.com/codejunkie99/agentic-stack/blob/master/harness_manager/state.py): install state · Tracks installed harness state and manifest reconstruction. · `harness_manager/state.py`
- [Upgrade](https://github.com/codejunkie99/agentic-stack/blob/master/harness_manager/upgrade.py): lifecycle · Safely refreshes installed infrastructure without overwriting user memory. · `harness_manager/upgrade.py`
- [Transfer](https://github.com/codejunkie99/agentic-stack/blob/master/harness_manager/transfer_bundle.py): bundle · Builds portable bundles for moving selected memory and skills to another host. · `harness_manager/transfer_bundle.py`
- [Doctor](https://github.com/codejunkie99/agentic-stack/blob/master/harness_manager/doctor.py): validation · Checks installation health and adapter wiring. · `harness_manager/doctor.py`

### Agent Runtime

The portable .agent brain: memory, skills, protocols, hooks, and session-time tools.

- [Conductor](https://github.com/codejunkie99/agentic-stack/blob/master/.agent/harness/conductor.py): runtime core · Coordinates runtime behavior and session orchestration inside .agent. · `.agent/harness/conductor.py`
- [Pre-tool](https://github.com/codejunkie99/agentic-stack/blob/master/.agent/harness/hooks/pre_tool_call.py): policy hook · Enforces permissions before tool execution. · `.agent/harness/hooks/pre_tool_call.py`
- [Post-exec](https://github.com/codejunkie99/agentic-stack/blob/master/.agent/harness/hooks/post_execution.py): hook · Captures tool outcomes, provenance, and episodic I/O after execution. · `.agent/harness/hooks/post_execution.py`
- [Memory](https://github.com/codejunkie99/agentic-stack/blob/master/.agent/memory): memory system · Stores personal, working, episodic, and semantic memory layers. · `.agent/memory`
- [Dream](https://github.com/codejunkie99/agentic-stack/blob/master/.agent/memory/auto_dream.py): compaction · Clusters episodic logs and stages candidate lessons for review. · `.agent/memory/auto_dream.py`
- [Recall](https://github.com/codejunkie99/agentic-stack/blob/master/.agent/memory/memory_search.py): retrieval · Session-time retrieval of preferences, lessons, and working context. · `.agent/memory/memory_search.py`
- [Promote](https://github.com/codejunkie99/agentic-stack/blob/master/.agent/memory/promote.py): review · Moves reviewed learning from candidates into semantic memory. · `.agent/memory/promote.py`
- [Skills](https://github.com/codejunkie99/agentic-stack/blob/master/.agent/skills): behavior layer · Progressive-disclosure skill manifests and SKILL.md content. · `.agent/skills`
- [Tools](https://github.com/codejunkie99/agentic-stack/blob/master/.agent/tools): utilities · Session utilities for recall, learning, exports, and external bridges. · `.agent/tools`
- [Protocols](https://github.com/codejunkie99/agentic-stack/blob/master/.agent/protocols): policy schemas · Tool schemas, delegation guidance, and permission rules. · `.agent/protocols`

### Adapters

Per-harness wiring that loads the .agent brain into each host environment.

- [Claude Code](https://github.com/codejunkie99/agentic-stack/blob/master/adapters/claude-code/adapter.json): adapter manifest · Host wiring for Claude Code via CLAUDE.md and settings. · `adapters/claude-code/adapter.json`
- [Cursor](https://github.com/codejunkie99/agentic-stack/blob/master/adapters/cursor/adapter.json): adapter manifest · Host wiring for Cursor via .cursor rules. · `adapters/cursor/adapter.json`
- [Windsurf](https://github.com/codejunkie99/agentic-stack/blob/master/adapters/windsurf/adapter.json): adapter manifest · Host wiring for Windsurf via rules files. · `adapters/windsurf/adapter.json`
- [Copilot CLI](https://github.com/codejunkie99/agentic-stack/blob/master/adapters/copilot-cli/adapter.json): adapter manifest · Host wiring for Copilot CLI and hook configuration. · `adapters/copilot-cli/adapter.json`
- [Python Loop](https://github.com/codejunkie99/agentic-stack/blob/master/adapters/standalone-python/run.py): standalone adapter · Standalone Python runtime for running the agent outside a host harness. · `adapters/standalone-python/run.py`

### Support

Documentation, schemas, and examples that describe and validate the platform.

- [Architecture](https://github.com/codejunkie99/agentic-stack/blob/master/docs/architecture.md): docs · Explains the repo's main runtime and installation model. · `docs/architecture.md`
- [Data Schemas](https://github.com/codejunkie99/agentic-stack/tree/master/schemas/data-layer): json schemas · Defines data-layer artifact shapes and dashboard outputs. · `schemas/data-layer`
- [Examples](https://github.com/codejunkie99/agentic-stack/tree/master/examples/data-layer): sample data · Redacted sample inputs for data-layer and flywheel pipelines. · `examples/data-layer`

## Connections

- CLI → State: reads/writes · Persists install state and reconstructs manifests.
- CLI → Upgrade: invokes · Runs upgrade workflow from the central CLI.
- CLI → Transfer: invokes · Creates portable transfer bundles.
- CLI → Doctor: invokes · Validates installation health and wiring.
- CLI → Claude Code: applies · Installs adapter-owned host files.
- CLI → Cursor: applies · Installs adapter-owned host files.
- CLI → Windsurf: applies · Installs adapter-owned host files.
- CLI → Copilot CLI: applies · Installs adapter-owned host files.
- CLI → Python Loop: supports · Maintains standalone execution mode.
- Conductor → Pre-tool: enforces · Applies permission checks before tool use.
- Conductor → Post-exec: logs · Feeds post-action instrumentation into memory.
- Conductor → Memory: uses · Reads and updates portable memory state.
- Dream → Memory: compacts · Promotes episodic data into candidate lessons.
- Recall → Memory: queries · Retrieves preferences, semantic lessons, and working context.
- Promote → Memory: updates · Moves reviewed learnings into semantic memory.
- Tools → Recall: exposes · Provides recall surface for sessions.
- Tools → Promote: exposes · Provides review and graduation utilities.
- Tools → Skills: loads · Supports skill discovery and loading.
- Tools → Protocols: consults · Uses schemas and permissions for execution boundaries.
- Tools → Data Schemas: exports · Produces dashboard and telemetry artifacts.
- Tools → Examples: demonstrates · Uses sanitized inputs for export pipelines.
- Claude Code → Conductor: boots · Loads the portable brain into Claude Code.
- Cursor → Conductor: boots · Loads the portable brain into Cursor.
- Windsurf → Conductor: boots · Loads the portable brain into Windsurf.
- Copilot CLI → Conductor: boots · Loads the portable brain into Copilot CLI.
- Python Loop → Conductor: runs · Direct standalone execution path.
- Architecture → CLI: describes · Documents lifecycle and installation flows.
- Architecture → Memory: describes · Explains layered memory architecture.
- Architecture → Claude Code: documents · Covers per-harness adapter wiring.