agentic-stack-portable-brain

---
name: agentic-stack-portable-brain
description: Portable .agent/ folder (memory + skills + protocols) that plugs into Claude Code, Cursor, Windsurf, OpenCode, OpenClaw, Hermes, Pi, or DIY Python and keeps knowledge across harness switches.
triggers:
  - set up agentic stack for this project
  - install portable agent brain
  - add agent memory to my project
  - configure claude code with agentic stack
  - switch my agent to a different harness
  - set up persistent agent memory and skills
  - run the dream cycle for agent lessons
  - graduate or reject agent candidate lessons
---

# agentic-stack-portable-brain

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

## What agentic-stack does

`agentic-stack` gives any AI coding agent a **portable brain**: a `.agent/` folder containing four memory layers, a progressive-disclosure skill system, enforced permissions, and adapters for eight harnesses. When you switch from Claude Code to Cursor (or any other supported harness), the agent's accumulated knowledge travels with the project — no re-learning, no lost lessons.

### Core concepts

| Concept | Description |
|---|---|
| **Memory layers** | `working/` (session), `episodic/` (action log), `semantic/` (graduated lessons), `personal/` (preferences) |
| **Skills** | Markdown files with trigger matching; manifest always loads, full `SKILL.md` only when relevant |
| **Protocols** | Typed tool schemas, `permissions.md`, delegation contracts |
| **Review protocol** | `auto_dream.py` stages candidates mechanically; host agent reviews with CLI tools |
| **Harness adapters** | Thin shims per tool (CLAUDE.md, .windsurfrules, AGENTS.md, etc.) |

---

## Installation

### macOS / Linux (Homebrew)

```bash
brew tap codejunkie99/agentic-stack https://github.com/codejunkie99/agentic-stack
brew install agentic-stack

cd your-project
agentic-stack claude-code   # or: cursor | windsurf | opencode | openclaw | hermes | pi | standalone-python

Windows (PowerShell)

git clone https://github.com/codejunkie99/agentic-stack.git
cd agentic-stack
.\install.ps1 claude-code C:\path\to\your-project

Clone and install manually

git clone https://github.com/codejunkie99/agentic-stack.git
cd agentic-stack

# macOS / Linux / Git Bash
./install.sh claude-code /path/to/your-project

# Windows PowerShell
.\install.ps1 claude-code C:\path\to\your-project

Supported harness names

claude-code | cursor | windsurf | opencode | openclaw | hermes | pi | standalone-python

Upgrade

brew update && brew upgrade agentic-stack

---

Onboarding wizard

The wizard runs automatically after adapter installation and writes:

• .agent/memory/personal/PREFERENCES.md — first file the AI reads each session
• .agent/memory/.features.json — feature toggles

# accept all defaults silently (CI / scripted environments)
agentic-stack claude-code --yes

# re-run wizard on an existing project
agentic-stack claude-code --reconfigure

Wizard questions

Question	Default
What should I call you?	(skip)
Primary language(s)?	unspecified
Explanation style?	concise
Test strategy?	test-after
Commit message style?	conventional commits
Code review depth?	critical issues only

Manual preference editing

# Edit preferences any time
$EDITOR .agent/memory/personal/PREFERENCES.md

# Toggle features
$EDITOR .agent/memory/.features.json

.features.json example:

{
  "fts_memory_search": false
}

---

Key CLI commands

Review protocol (host-agent tools)

# List pending candidate lessons, sorted by priority
python3 .agent/tools/list_candidates.py

# Accept a candidate (--rationale required — rubber-stamping is structurally impossible)
python3 .agent/tools/graduate.py <id> --rationale "evidence holds, matches PREFERENCES"

# Reject a candidate (--reason required; decision history preserved)
python3 .agent/tools/reject.py <id> --reason "too specific to this repo to generalize"

# Requeue a previously-rejected candidate
python3 .agent/tools/reopen.py <id>

Memory search [BETA]

# Enable during onboarding or toggle manually in .features.json, then:
python3 .agent/memory/memory_search.py "deploy failure"
python3 .agent/memory/memory_search.py --status
python3 .agent/memory/memory_search.py --rebuild

Falls back to ripgrep → grep when FTS5 index is not enabled. Index stored at .agent/memory/.index/ (gitignored).

Nightly staging cycle (cron)

# Add to crontab: runs at 03:00 daily, safe to run unattended
crontab -e
# Paste:
0 3 * * * python3 /absolute/path/to/project/.agent/memory/auto_dream.py >> /absolute/path/to/project/.agent/memory/dream.log 2>&1

auto_dream.py only does mechanical work: cluster, stage, prefilter, decay. No git commits, no network calls, no LLM reasoning.

---

Repository layout

.agent/
├── AGENTS.md                   # the map every harness reads
├── harness/                    # conductor + hooks (standalone path)
├── memory/
│   ├── working/                # session-scoped scratch
│   ├── episodic/               # action log (all skill events)
│   ├── semantic/
│   │   ├── lessons.jsonl       # source of truth for graduated lessons
│   │   └── LESSONS.md          # rendered from lessons.jsonl
│   ├── personal/
│   │   └── PREFERENCES.md      # loaded first every session
│   ├── auto_dream.py           # nightly staging cycle
│   ├── cluster.py              # Jaccard single-linkage clustering
│   ├── promote.py              # stage candidates
│   ├── validate.py             # heuristic prefilter
│   ├── review_state.py         # candidate lifecycle + decision log
│   ├── render_lessons.py       # lessons.jsonl → LESSONS.md
│   └── memory_search.py        # [BETA] FTS5 search
├── skills/
│   ├── _index.md               # always-loaded lightweight manifest
│   ├── _manifest.jsonl         # trigger → skill mapping
│   └── *.SKILL.md              # full skill files (lazy-loaded)
├── protocols/
│   ├── permissions.md          # enforced by pre-tool-call hook
│   ├── tool-schemas/           # typed schemas per tool
│   └── delegation.md           # sub-agent contract
└── tools/
    ├── list_candidates.py
    ├── graduate.py
    ├── reject.py
    ├── reopen.py
    ├── memory_reflect.py
    └── skill_loader.py

adapters/
├── claude-code/    # CLAUDE.md + .claude/settings.json (PostToolUse, Stop hooks)
├── cursor/         # .cursor/rules/*.mdc
├── windsurf/       # .windsurfrules
├── opencode/       # AGENTS.md + opencode.json
├── openclaw/       # .openclaw-system.md
├── hermes/         # AGENTS.md
├── pi/             # AGENTS.md + .pi/skills symlink → .agent/skills
└── standalone-python/  # run.py DIY conductor

---

Seed skills (shipped with every install)

Skill	Purpose
skillforge	Creates new skills from recurring patterns
memory-manager	Runs reflection cycles, surfaces candidate lessons
git-proxy	All git ops with safety constraints
debug-investigator	Reproduce → isolate → hypothesize → verify loop
deploy-checklist	Gate between staging and production

---

Code examples

Python: running the staging cycle programmatically

import subprocess
import sys
from pathlib import Path

def run_dream_cycle(project_root: str) -> None:
    dream_script = Path(project_root) / ".agent" / "memory" / "auto_dream.py"
    log_path = Path(project_root) / ".agent" / "memory" / "dream.log"

    if not dream_script.exists():
        raise FileNotFoundError(f"auto_dream.py not found at {dream_script}")

    with log_path.open("a") as log_file:
        result = subprocess.run(
            [sys.executable, str(dream_script)],
            stdout=log_file,
            stderr=log_file,
            cwd=project_root,
        )

    if result.returncode != 0:
        print(f"Dream cycle exited with code {result.returncode}. Check {log_path}")
    else:
        print("Dream cycle complete.")

run_dream_cycle("/path/to/your-project")

Python: reading feature toggles

import json
from pathlib import Path

def get_features(project_root: str) -> dict:
    features_path = Path(project_root) / ".agent" / "memory" / ".features.json"
    if not features_path.exists():
        return {}
    with features_path.open() as f:
        return json.load(f)

def is_fts_enabled(project_root: str) -> bool:
    return get_features(project_root).get("fts_memory_search", False)

# Usage
if is_fts_enabled("."):
    print("FTS memory search is active")

Python: querying memory search programmatically

import subprocess
import sys
from pathlib import Path

def search_memory(project_root: str, query: str) -> str:
    search_script = Path(project_root) / ".agent" / "memory" / "memory_search.py"
    result = subprocess.run(
        [sys.executable, str(search_script), query],
        capture_output=True,
        text=True,
        cwd=project_root,
    )
    return result.stdout

hits = search_memory(".", "deploy failure")
print(hits)

Python: reading graduated lessons from lessons.jsonl

import json
from pathlib import Path

def load_lessons(project_root: str) -> list[dict]:
    lessons_path = Path(project_root) / ".agent" / "memory" / "semantic" / "lessons.jsonl"
    if not lessons_path.exists():
        return []
    lessons = []
    with lessons_path.open() as f:
        for line in f:
            line = line.strip()
            if line:
                lessons.append(json.loads(line))
    return lessons

for lesson in load_lessons("."):
    print(lesson.get("claim"), "—", lesson.get("graduated_at"))

Python: standalone harness entrypoint pattern

# adapters/standalone-python/run.py pattern
import os
from pathlib import Path

AGENT_ROOT = Path(__file__).parent.parent.parent / ".agent"
PREFERENCES = AGENT_ROOT 

---

*Content truncated.*