codejunkie99/agentic-stack

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.