{"id":48915305,"url":"https://github.com/codejunkie99/agentic-stack","last_synced_at":"2026-04-22T07:00:48.427Z","repository":{"id":351570155,"uuid":"1211537500","full_name":"codejunkie99/agentic-stack","owner":"codejunkie99","description":"One brain, many harnesses. Portable .agent/ folder (memory + skills + protocols) that plugs into Claude Code, Cursor, Windsurf, OpenCode, OpenClaw, Hermes, or DIY Python — and keeps its knowledge when you switch.","archived":false,"fork":false,"pushed_at":"2026-04-20T08:50:18.000Z","size":5204,"stargazers_count":813,"open_issues_count":1,"forks_count":95,"subscribers_count":10,"default_branch":"master","last_synced_at":"2026-04-21T06:02:43.199Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codejunkie99.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-15T13:45:41.000Z","updated_at":"2026-04-21T05:52:54.000Z","dependencies_parsed_at":"2026-04-19T04:01:08.024Z","dependency_job_id":"aa6596d2-93de-44b3-9c60-93c955644d1c","html_url":"https://github.com/codejunkie99/agentic-stack","commit_stats":null,"previous_names":["codejunkie99/agentic-stack"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/codejunkie99/agentic-stack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codejunkie99%2Fagentic-stack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codejunkie99%2Fagentic-stack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codejunkie99%2Fagentic-stack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codejunkie99%2Fagentic-stack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codejunkie99","download_url":"https://codeload.github.com/codejunkie99/agentic-stack/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codejunkie99%2Fagentic-stack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32125094,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T00:31:26.853Z","status":"online","status_checked_at":"2026-04-22T02:00:05.693Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-17T02:00:54.970Z","updated_at":"2026-04-22T07:00:48.409Z","avatar_url":"https://github.com/codejunkie99.png","language":"Python","funding_links":[],"categories":["Design Primitives"],"sub_categories":["Skills \u0026 MCP"],"readme":"# agentic-stack\n\nFollow me on [@AV1DLIVE](https://twitter.com/AV1DLIVE) for updates/collabs on projects.\n\n[![GitHub release](https://img.shields.io/github/v/release/codejunkie99/agentic-stack)](https://github.com/codejunkie99/agentic-stack/releases)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n\n\u003e\u003e **Coded using Minimax-M2.7 in the Claude Code Harness. PR Review by Macroscope and Codex**\n\n\u003e **One brain, many harnesses.** A portable `.agent/` folder (memory + skills\n\u003e + protocols) that plugs into Claude Code, Cursor, Windsurf, OpenCode,\n\u003e OpenClaw, Hermes, Pi Coding Agent, or a DIY Python loop, and keeps\n\u003e its knowledge when you switch.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/demo.gif\" alt=\"agentic-stack demo\" width=\"880\"/\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/diagram.svg\" alt=\"agentic-stack architecture\" width=\"880\"/\u003e\n\u003c/p\u003e\n\n\nBased on the article:\n**[\"The Agentic Stack\"](https://x.com/Av1dlive/status/2044453102703841645?s=20)** · by [@AV1DLIVE](https://twitter.com/AV1DLIVE)\n\n\n## Quickstart\n\n### macOS / Linux\n\n```bash\n# tap + install (one-time — both lines required)\nbrew tap codejunkie99/agentic-stack https://github.com/codejunkie99/agentic-stack\nbrew install agentic-stack\n\n# drop the brain into any project — the onboarding wizard runs automatically\ncd your-project\nagentic-stack claude-code\n# or: cursor | windsurf | opencode | openclaw | hermes | pi | standalone-python\n```\n\n### Windows (PowerShell)\n\n```powershell\n# clone + run the native installer\ngit clone https://github.com/codejunkie99/agentic-stack.git\ncd agentic-stack\n.\\install.ps1 claude-code C:\\path\\to\\your-project\n```\n\n### Already installed?\n\n```bash\nbrew update \u0026\u0026 brew upgrade agentic-stack\n```\n\n### Clone instead?\n\n```bash\ngit clone https://github.com/codejunkie99/agentic-stack.git\ncd agentic-stack \u0026\u0026 ./install.sh claude-code         # mac / linux / git-bash\n# or on Windows PowerShell: .\\install.ps1 claude-code\n# adapters: claude-code | cursor | windsurf | opencode | openclaw | hermes | pi | standalone-python\n```\n\n## Onboarding wizard\n\nAfter the adapter is installed, a terminal wizard populates\n`.agent/memory/personal/PREFERENCES.md` — the **first file your AI reads\nat the start of every session** — and writes a feature-toggle file at\n`.agent/memory/.features.json`.\n\nSix preference questions (each skippable with Enter):\n\n| Question | Default |\n|---|---|\n| What should I call you? | *(skip)* |\n| Primary language(s)? | `unspecified` |\n| Explanation style? | `concise` |\n| Test strategy? | `test-after` |\n| Commit message style? | `conventional commits` |\n| Code review depth? | `critical issues only` |\n\nPlus one **Optional features** step (opt-in, off by default):\n\n| Feature | Default |\n|---|---|\n| Enable FTS memory search `[BETA]` | `no` |\n\n**Flags:**\n\n```bash\nagentic-stack claude-code --yes          # accept all defaults, beta off (CI/scripted)\nagentic-stack claude-code --reconfigure  # re-run the wizard on an existing project\n```\n\nEdit `.agent/memory/personal/PREFERENCES.md` any time to refine your\nconventions, or `.agent/memory/.features.json` to flip feature toggles.\n\n## Review protocol (host-agent CLI)\n\nThe nightly `auto_dream.py` cycle only **stages** candidate lessons. It\ndoes not mark anything accepted or modify semantic memory. Your host\nagent does the review in-session:\n\n```bash\n# list pending candidates, sorted by priority\npython3 .agent/tools/list_candidates.py\n\n# accept with rationale (required)\npython3 .agent/tools/graduate.py \u003cid\u003e --rationale \"evidence holds, matches PREFERENCES\"\n\n# reject with reason (required); preserves decision history\npython3 .agent/tools/reject.py \u003cid\u003e --reason \"too specific to generalize\"\n\n# requeue a previously-rejected candidate\npython3 .agent/tools/reopen.py \u003cid\u003e\n```\n\nGraduated lessons land in `semantic/lessons.jsonl` (source of truth) and\nare rendered to `semantic/LESSONS.md`. Rejected candidates retain full\ndecision history so recurring churn is visible, not fresh.\n\nSee [`docs/architecture.md`](docs/architecture.md) for the full lifecycle.\n\n---\n\n## What this is\n\nEvery guide shows the folder structure. This repo gives you the folder\nstructure **plus the files that actually go inside**: a working portable\nbrain with five seed skills, four memory layers, enforced permissions, a\nnightly staging cycle, host-agent review tools, and adapters for eight\nharnesses.\n\n- **Memory** — `working/`, `episodic/`, `semantic/`, `personal/`. Each\n  layer has its own retention policy. Query-aware retrieval (salience ×\n  relevance); nightly compression into reviewable candidates.\n- **Review protocol** — `auto_dream.py` stages candidate lessons\n  mechanically. Your host agent reviews them via CLI tools\n  (`graduate.py`, `reject.py`, `reopen.py`) and commits decisions with\n  a required rationale. No unattended reasoning, no provider coupling.\n- **Skills** — progressive disclosure. A lightweight manifest always\n  loads; full `SKILL.md` files only load when triggers match the task.\n  Every skill ships with a self-rewrite hook.\n- **Protocols** — typed tool schemas, a `permissions.md` that the\n  pre-tool-call hook enforces, and a delegation contract for sub-agents.\n\n## What's new in v0.6.0\n\n- **Pi Coding Agent adapter.** `./install.sh pi` drops `AGENTS.md` and\n  symlinks `.pi/skills` to `.agent/skills` so pi sees the full brain\n  with zero duplication. Safe to install alongside hermes/opencode\n  (they all read `AGENTS.md`; we skip the overwrite if one exists).\n- **OpenClient → OpenClaw.** Adapter renamed across the board.\n  Installed file changed: `.openclient-system.md` → `.openclaw-system.md`.\n  Breaking for existing OpenClient users — re-run `./install.sh openclaw`.\n\n## What's new in v0.5.0\n\n- **Host-agent review protocol.** Python handles filing (cluster, stage,\n  heuristic prefilter, decay). The host agent handles reasoning via\n  `list_candidates.py` / `graduate.py` / `reject.py` / `reopen.py`.\n  Graduation requires `--rationale` so rubber-stamping is structurally\n  impossible.\n- **Structured `lessons.jsonl` as source of truth.** `LESSONS.md` is\n  rendered from it. Hand-curated content above the sentinel is\n  preserved across renders; legacy bullets auto-migrate on first run.\n- **Content clustering.** Proper single-linkage Jaccard with bridge\n  merging. Pattern IDs derived from canonical claim + conditions, stable\n  across cluster-membership changes.\n- **[BETA] FTS5 memory search.** Opt-in full-text search over all\n  `.md` / `.jsonl` memory documents. Default **off**; enable during\n  onboarding or edit `.agent/memory/.features.json` directly.\n- **Windows-native installer.** `install.ps1` runs natively in\n  PowerShell; `install.sh` continues to work under Git Bash / WSL.\n\n\n## Memory search `[BETA]`\n\nOpt-in FTS5 keyword search over all memory documents:\n\n```bash\n# enable during onboarding (or set manually in .agent/memory/.features.json)\npython3 .agent/memory/memory_search.py \"deploy failure\"\npython3 .agent/memory/memory_search.py --status\npython3 .agent/memory/memory_search.py --rebuild\n```\n\nFalls back to **ripgrep** (`rg`) if installed, then to `grep` — both\nrestricted to `.md` / `.jsonl` so source files never pollute results.\nThe index is stored at `.agent/memory/.index/` and gitignored.\n\n## Repo layout\n\n```\n.agent/                         # the portable brain (same across harnesses)\n├── AGENTS.md                   # the map\n├── harness/                    # conductor + hooks (standalone path)\n├── memory/                     # working / episodic / semantic / personal\n│   ├── auto_dream.py           # staging-only dream cycle\n│   ├── cluster.py              # content clustering + pattern extraction\n│   ├── promote.py              # stage candidates\n│   ├── validate.py             # heuristic prefilter (length + exact duplicate)\n│   ├── review_state.py         # candidate lifecycle + decision log\n│   ├── render_lessons.py       # lessons.jsonl → LESSONS.md\n│   └── memory_search.py        # [BETA] FTS5 search (opt-in)\n├── skills/                     # _index.md + _manifest.jsonl + SKILL.md files\n├── protocols/                  # permissions + tool schemas + delegation\n└── tools/                      # host-agent CLI + memory_reflect + skill_loader\n    ├── list_candidates.py\n    ├── graduate.py\n    ├── reject.py\n    └── reopen.py\n\nadapters/                       # one small shim per harness\n├── claude-code/   (CLAUDE.md + settings.json hooks)\n├── cursor/        (.cursor/rules/*.mdc)\n├── windsurf/      (.windsurfrules)\n├── opencode/      (AGENTS.md + opencode.json)\n├── openclaw/      (system-prompt include)\n├── hermes/        (AGENTS.md)\n├── pi/            (AGENTS.md + .pi/skills symlink)\n└── standalone-python/  (DIY conductor entrypoint)\n\ndocs/                           # architecture, getting-started, per-harness\ninstall.sh                      # mac / linux / git-bash installer\ninstall.ps1                     # Windows PowerShell installer\nonboard.py                      # onboarding wizard entry point\nonboard_features.py             # .features.json read/write\nonboard_ui.py                   # ANSI palette, banner, clack-style layout\nonboard_widgets.py              # arrow-key prompts (text, select, confirm)\nonboard_render.py               # answers → PREFERENCES.md content\nonboard_write.py                # atomic file write with backup\n```\n\n## Supported harnesses\n\n| Harness | Config file it reads | Hook support |\n|---|---|---|\n| **Claude Code** | `CLAUDE.md` + `.claude/settings.json` | yes (PostToolUse, Stop) |\n| **Cursor** | `.cursor/rules/*.mdc` | no (manual reflect calls) |\n| **Windsurf** | `.windsurfrules` | no (manual reflect calls) |\n| **OpenCode** | `AGENTS.md` + `opencode.json` | partial (permission rules) |\n| **OpenClaw** | system-prompt include | varies by fork |\n| **Hermes Agent** | `AGENTS.md` (agentskills.io compatible) | partial (own memory) |\n| **Pi Coding Agent** | `AGENTS.md` + `.pi/skills/` | no (extension system) |\n| **Standalone Python** | `run.py` (any LLM) | yes (full control) |\n\n## Seed skills\n\n- **skillforge** — creates new skills from recurring patterns\n- **memory-manager** — runs reflection cycles, surfaces candidate lessons\n- **git-proxy** — all git ops, with safety constraints\n- **debug-investigator** — reproduce → isolate → hypothesize → verify\n- **deploy-checklist** — the fence between staging and production\n\n## How it compounds\n\n1. Skills log every action to episodic memory.\n2. `auto_dream.py` clusters recurring patterns into candidate lessons.\n3. The host agent reviews candidates with `graduate.py` / `reject.py`.\n4. Graduated lessons append to `lessons.jsonl`; `LESSONS.md` re-renders.\n5. Future sessions load query-relevant accepted lessons automatically.\n6. `on_failure` flags skills that fail 3+ times in 14 days for rewrite.\n7. `git log .agent/memory/` becomes the agent's autobiography.\n\n## Run the staging cycle nightly\n\n```bash\ncrontab -e\n0 3 * * * python3 /path/to/project/.agent/memory/auto_dream.py \u003e\u003e /path/to/project/.agent/memory/dream.log 2\u003e\u00261\n```\n\n`auto_dream.py` resolves its paths absolutely and performs only mechanical\nfile operations (cluster, stage, prefilter, decay). No git commits, no\nnetwork, no reasoning — safe to run unattended.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n## Credits\n\nDesign adapted from the author's article on building an agentic stack, plus\npatterns from Gstack, Claude Code's memory system, and conversations in\nthe agent-engineering community. Built with the hypothesis that\n**harness-agnosticism is the point**.\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=codejunkie99/agentic-stack\u0026type=Date)](https://star-history.com/#codejunkie99/agentic-stack\u0026Date)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodejunkie99%2Fagentic-stack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodejunkie99%2Fagentic-stack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodejunkie99%2Fagentic-stack/lists"}