deepagent-hermes 0.1.0__tar.gz

deepagent_hermes-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: |
+          uv pip install --system -e ".[dev]"
+
+      - name: Lint
+        run: |
+          ruff check .
+          ruff format --check .
+
+      - name: Test
+        run: |
+          pytest -ra --cov=deepagent_hermes --cov-report=term-missing
+
+  smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - uses: astral-sh/setup-uv@v3
+      - name: Install
+        run: uv pip install --system -e ".[dev]"
+      - name: Smoke import
+        run: python -c "from deepagent_hermes import create_hermes_agent, HermesConfig; print('OK')"
+      - name: --show-config
+        run: deepagent-hermes --show-config

deepagent_hermes-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,23 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install build
+        run: pip install build
+      - name: Build wheel + sdist
+        run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

deepagent_hermes-0.1.0/.gitignore

@@ -0,0 +1,64 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+*.egg
+build/
+dist/
+.eggs/
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Virtual environments (central per coding.md, but defensive)
+.venv/
+venv/
+ENV/
+env/
+
+# Tests / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# Hermes runtime artifacts (when running from the repo)
+.deepagent-hermes/
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+.skills_prompt_snapshot.json
+
+# Secrets
+.env
+.env.local
+*.pem
+*.key
+honcho.json
+config.local.yaml
+
+# Logs
+*.log
+logs/
+
+# OS
+.AppleDouble
+.LSOverride
+Icon
+
+# uv
+uv.lock

deepagent_hermes-0.1.0/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+All notable changes to `deepagent-hermes` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-06-02
+
+Initial public release. A faithful reproduction of [Nous Research's Hermes Agent](https://github.com/nousresearch/hermes-agent) on top of LangGraph + [`deepagents`](https://github.com/langchain-ai/deepagents) + [`langgraph-stream-parser`](https://github.com/dkedar7/langgraph-stream-parser).
+
+### Highlights
+
+- **Closed reflection→skill-creation loop.** After ~10 tool-using turns the review subagent fires, inspects the conversation, and writes/patches a `SKILL.md` to the user's library. Verified live against Anthropic.
+- **Frozen-snapshot memory.** `MEMORY.md` + `USER.md` loaded once at session start; mid-session writes hit disk but don't change the system prompt, so the prefix cache stays warm.
+- **FTS5 session search.** SQLite-backed store at `<HERMES_HOME>/state.db` with `messages_fts` (unicode61) + `messages_fts_trigram` (CJK) virtual tables; `session_search` tool with DISCOVERY / SCROLL / BROWSE modes.
+- **agentskills.io spec compliance.** Bundled library validator enforces the spec verbatim; `skill_view` does progressive disclosure.
+- **`langgraph-stream-parser` host-family compatible.** Adopt this agent in any `deepagent-*` host (cowork-dash / deepagent-lab / deepagent-code / deepagent-vscode) with `DEEPAGENT_AGENT_SPEC=deepagent_hermes.agent:graph`. No host code changes.
+
+### What ships
+
+- **Agent factory** `create_hermes_agent()` wiring a 14-middleware stack: `PluginEventBus`, `IterationBudgetMiddleware`, `PromptAssemblyMiddleware`, `SkillLoaderMiddleware`, `MemoryToolMiddleware`, `HermesStateRecorderMiddleware`, `ReflectionMiddleware`, `CuratorMiddleware`, deepagents' `TodoListMiddleware` / `FilesystemMiddleware` / `SubAgentMiddleware`, `HermesCompressionMiddleware`, `AnthropicCachingS3Middleware`, `PatchToolCallsMiddleware`.
+- **Three-layer system prompt** (stable / context / volatile) with a byte-stable date-only line so the prefix cache survives the whole day.
+- **`system_and_3` Anthropic prompt caching** strategy: system + last 3 messages, total 4 breakpoints (under the per-request cap).
+- **13-section compression summary template** with anti-thrash skip when consecutive passes yield < 10%.
+- **Iteration budget** (default 90 parent, 50 subagent), with `execute_code` as a refund-tool by default.
+- **Three review prompts** (memory / skills / combined) for the reflection fork plus a curator prompt for the weekly consolidation pass.
+- **33-toolset registry** with 30s `check_fn` TTL cache.
+- **Six terminal-environment backends:**
+  - `LocalEnvironment` — full subprocess impl (Windows-aware: detects Git Bash on PATH).
+  - `DockerEnvironment` — container-per-session via `docker run --rm`.
+  - `SshEnvironment` — paramiko-based with reconnect-on-broken-pipe.
+  - `SingularityEnvironment` — `singularity` / `apptainer` auto-detected.
+  - `DaytonaEnvironment`, `ModalEnvironment` — lazy SDK imports with defensive attribute probing; raise informative `ImportError` when the SDK is missing.
+- **Cron daemon** (`python -m deepagent_hermes.cron`) with the 30-field Hermes job JSON shape, three deliverers (`local`, `stdout`, `agentmail`).
+- **Plugin loader** with 4 discovery sources (bundled / user / project / pip entry-points) and a `PluginEventBus` middleware that wires 13 of 17 documented lifecycle hooks.
+- **CLI** with v1-essential slash commands: `/new` / `/reset` / `/compress` / `/stop` / `/help` / `/quit` / `/model` / `/config` / `/skills` / `/cron` / `/curator` / `/memory` / `/tools` / `/toolsets` / `/verbose` / `/yolo` / `/reload`.
+- **26 bundled skills** copied from `nousresearch/hermes-agent` (MIT, attributed in [`NOTICE`](./NOTICE)) covering software-development, github, research, data-science, mlops, productivity, note-taking.
+
+### Stream-parser extractors (upstreamed)
+
+Four new built-in extractors landed in `langgraph-stream-parser` v0.2.x:
+
+- `SkillManageExtractor` (`skill_event`)
+- `SkillViewExtractor` (`skill_loaded`)
+- `CompressionExtractor` (`compression_summary`)
+- `MemoryExtractor` (`memory_updated`)
+
+Hosts surface these as inline events alongside agent text.
+
+### Configuration
+
+Layered resolver: `defaults < deepagent-hermes.toml < DEEPAGENT_HERMES_* env < CLI overrides`. Inherits the `langgraph-stream-parser` `HostConfig` for the cross-host keys. `deepagent-hermes --show-config` dumps every value with its source.
+
+### Test posture
+
+398 tests pass, 3 skipped (Docker / Singularity gated by binary presence; one Honcho test redundant when the SDK is installed). Live smokes cover a single-turn round-trip, a 5-turn reflection-trigger trace, a 12-turn substantive arc (memory writes verified end-to-end across 3 distinct topics), and host-adoption through `deepagent-code`'s config.
+
+### Platform-forced divergences from Hermes
+
+(documented in [`SPEC.md` §1](./SPEC.md))
+
+- `langgraph-checkpoint-sqlite` added as required dep (langgraph only ships `InMemorySaver`).
+- `BaseStore` has no FTS5 — we implement `SqliteFtsStore(BaseStore)` ourselves with Hermes's verbatim schema.
+- `deepagents.create_deep_agent` is bypassed because it always prepends `BASE_AGENT_PROMPT` and appends user middleware *after* the defaults — we own the stack via `langchain.agents.create_agent` directly.
+
+### Bugs caught + fixed during pre-release dogfood
+
+Each of these surfaced live and the fix is in tree:
+
+- **Anthropic `cache_control` per-request cap.** The parent `AnthropicPromptCachingMiddleware.model_settings["cache_control"]` nudge causes langchain-anthropic to tag the tools block; combined with our explicit system + last-3 tags that's 5 breakpoints, over the cap. Dropped the model_settings line.
+- **Middleware state-update silently dropped.** Returning `{"session_id": ...}` from `before_agent` had no effect because the field wasn't in any merged `state_schema`. Fixed by per-middleware `state_schema` TypedDict extensions on the recorder, reflection, budget, and skills-loader middleware.
+- **Parallel-write `InvalidUpdateError`.** Once the schemas were declared, parent + subagent writes in the same superstep crashed without an explicit reducer. Fixed by annotating counter/string fields with `Annotated[T, last_write_wins]` and the skills-loader lists/dicts with union/merge reducers.
+- **`LangGraph` coerces `NotRequired[int]` to 0 at schema-merge time.** The budget seed's `if current is None: seed` was a no-op; budget started exhausted. Fixed with `if not current: seed`.
+- **Workspace virtual-mode layering.** Agent wrote `/workspace/foo.py` which resolved to the literal `C:\workspace\foo.py` outside the sandbox. Fixed by `FilesystemBackend(virtual_mode=True)`.
+- **Review subagent had no tools.** Even when reflection fired, the subagent couldn't act because its tool list was empty. Fixed by passing `skill_tools + memory tool` through `build_review_subagent(tools=...)`.
+
+### Known limitations / deferred to v0.2.x
+
+- **Honcho user-model provider** is implemented against the real `honcho-ai>=2.0,<3` SDK but ships as an `[honcho]` optional dep; needs an account + key to actually wire up.
+- **Daytona / Modal backends** are lazy-SDK with explicit `TODO(*-api-verify)` markers on every uncertain SDK shape; should be verified against real accounts before v0.2.
+- **4 of 17 plugin lifecycle hooks** are middleware-unreachable in v0.1 (`on_session_reset`, `subagent_stop`, `pre_gateway_dispatch`, gateway-only hooks) — documented in `PluginEventBus.__doc__`.
+- **`mypy --strict`** not run end-to-end (would surface trivial Annotated quirks + incomplete langchain stubs). `ruff check` is clean.
+- **Self-evolution integration** is docs-only — the offline DSPy/GEPA → PR pipeline ships separately under `deepagent-hermes-self-evolve` when needed.
+
+### Acknowledgments
+
+Nous Research is the originator of the design ideas reproduced here. Their `hermes-agent` (MIT) is the source of truth for the architecture, prompt structures, configuration defaults, file formats, and the 26 bundled SKILL.md files — see [`NOTICE`](./NOTICE) for full attribution.
+
+[0.1.0]: https://github.com/dkedar7/deepagent-hermes/releases/tag/v0.1.0

deepagent_hermes-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kedar Dabhadkar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

deepagent_hermes-0.1.0/NOTICE

@@ -0,0 +1,54 @@
+deepagent-hermes
+Copyright (c) 2026 Kedar Dabhadkar
+
+This project is a faithful reproduction of the design ideas in Nous Research's
+Hermes Agent (https://github.com/nousresearch/hermes-agent), released by Nous
+Research under the MIT License.
+
+The following design decisions, prompt structures, configuration defaults, file
+formats, and architectural patterns are adapted directly from the Hermes Agent
+codebase (v0.15.1):
+
+- The closed reflection loop with 10-iteration / 10-turn nudge intervals.
+- The three-layer (stable / context / volatile) system prompt assembly with
+  byte-stable prefix-cache discipline.
+- The "system_and_3" Anthropic prompt-caching strategy.
+- The 13-section context-compression summary template.
+- The 90 / 50 parent / subagent iteration budget defaults.
+- The frozen-snapshot pattern for MEMORY.md / USER.md files (loaded once at
+  session start, mid-session writes do not change the system prompt).
+- The agentskills.io–compatible SKILL.md format and progressive-disclosure
+  loading via skill_view.
+- The SQLite FTS5 schema with messages_fts (unicode61) and messages_fts_trigram
+  (CJK) virtual tables, BM25 ranking, and the DISCOVERY / SCROLL / BROWSE
+  session_search modes.
+- The cron job JSON shape including the skills / script / no_agent /
+  context_from / enabled_toolsets fields, the 60-second tick interval, and the
+  [SILENT] suppression marker.
+- The 4-source plugin discovery order (bundled, user, project, pip entry-points)
+  and the 17 lifecycle-hook names.
+- The curator skill-lifecycle state machine (active → stale at 30 days →
+  archived at 90 days; pinned skills immune).
+
+Where prompt text is reproduced verbatim, the source file in the Hermes Agent
+repository is cited inline in the corresponding .md file under prompts/.
+
+Nous Research is the originator of these ideas; this project's contribution is
+the reproduction on a different framework substrate (LangGraph + deepagents +
+langgraph-stream-parser instead of Hermes's native runtime).
+
+In addition to the design adaptations above, the v0.1.0a1 release bundles 26
+SKILL.md files copied verbatim from the Hermes Agent ``skills/`` directory
+under the following categories: software-development, github, research,
+data-science, mlops, productivity, and note-taking. Each SKILL.md retains its
+original frontmatter, including the ``author`` field crediting the original
+contributor(s) and the ``license: MIT`` field. The bundled set is a curated
+subset chosen to align with this project owner's stated use cases; the full
+Hermes skill catalog (90+ skills in ``skills/`` plus 86+ in
+``optional-skills/``) is available at
+https://github.com/nousresearch/hermes-agent/tree/main/skills.
+
+Some bundled skills were originally adapted by Hermes Agent from upstream
+sources (e.g. the ``systematic-debugging`` skill is credited as "adapted from
+obra/superpowers" in its own frontmatter). Those upstream attributions are
+preserved verbatim in the corresponding SKILL.md files.

deepagent_hermes-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: deepagent-hermes
+Version: 0.1.0
+Summary: Closed-loop reflection / skill creation agent on LangGraph + deepagents. Faithful reproduction of Nous Research's Hermes Agent.
+Project-URL: Homepage, https://github.com/dkedar7/deepagent-hermes
+Project-URL: Repository, https://github.com/dkedar7/deepagent-hermes
+Project-URL: Issues, https://github.com/dkedar7/deepagent-hermes/issues
+Author-email: Kedar Dabhadkar <kdabhadk@gmail.com>
+License: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: agents,deepagents,hermes,langgraph,reflection,skills
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: croniter>=2.0
+Requires-Dist: deepagents>=0.6
+Requires-Dist: langchain-anthropic>=0.3
+Requires-Dist: langchain>=1.0
+Requires-Dist: langgraph-checkpoint-sqlite>=2.0
+Requires-Dist: langgraph-stream-parser<0.3,>=0.2
+Requires-Dist: langgraph>=1.0
+Requires-Dist: python-frontmatter>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Provides-Extra: daytona
+Requires-Dist: daytona-sdk>=0.10; extra == 'daytona'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: honcho
+Requires-Dist: honcho-ai<3,>=2.0; extra == 'honcho'
+Provides-Extra: modal
+Requires-Dist: modal>=0.64; extra == 'modal'
+Provides-Extra: ssh
+Requires-Dist: paramiko>=3.0; extra == 'ssh'
+Description-Content-Type: text/markdown
+
+# deepagent-hermes
+
+A faithful reproduction of [Nous Research's Hermes Agent](https://github.com/nousresearch/hermes-agent) on top of LangGraph + [`deepagents`](https://github.com/langchain-ai/deepagents) + [`langgraph-stream-parser`](https://github.com/dkedar7/langgraph-stream-parser).
+
+**Status: pre-alpha (v0.1.0a0).** Spec at [SPEC.md](./SPEC.md). Code is scaffolded; most subsystems work end-to-end but the bundled-skills library is empty and 5 of 6 terminal backends are stubs.
+
+## What it is
+
+A `deepagents`-built agent with a **closed reflection→skill-creation loop**:
+
+- After ~10 tool-using iterations, a review subagent runs in the background, writes/patches a `SKILL.md` capturing the pattern it just exercised, and ships it to a skill library.
+- Next session, the agent reads the library at startup, sees the new skill's description in its system prompt, and can `skill_view(name)` to load the full body on demand (progressive disclosure per the [agentskills.io spec](https://agentskills.io/specification.md)).
+- A weekly **curator** consolidates skills into umbrellas and archives stale ones.
+- A **frozen-snapshot memory** (`MEMORY.md` + `USER.md`) preserves prefix-cache hits for the entire session.
+- **FTS5 session search** indexes every past conversation in a local SQLite DB.
+- Optional **Honcho user model** for dialectic cross-session user profiling.
+
+Designed to be loaded into the existing `deepagent-*` host family ([`deepagent-code`](https://github.com/dkedar7/deepagent-code), [`deepagent-lab`](https://github.com/dkedar7/deepagent-lab), [`cowork-dash`](https://github.com/dkedar7/cowork-dash), [`deepagent-vscode`](https://github.com/dkedar7/deepagent-vscode)) without UI changes — set `DEEPAGENT_AGENT_SPEC=deepagent_hermes.agent:graph` in any of them.
+
+## Installation
+
+```bash
+# central venv per the deepagent-* convention
+uv venv "$env:USERPROFILE\.venvs\deepagent-hermes"
+. "$env:USERPROFILE\.venvs\deepagent-hermes\Scripts\Activate.ps1"
+
+# while langgraph-stream-parser v0.2.0 is unreleased, install editable
+uv pip install -e "..\langgraph-stream-parser"
+
+uv pip install -e .
+
+# optional extras
+uv pip install -e ".[honcho]"     # Honcho user-model provider
+uv pip install -e ".[modal]"      # Modal sandbox backend
+uv pip install -e ".[daytona]"    # Daytona sandbox backend
+uv pip install -e ".[dev]"        # tests + lint
+```
+
+## Quick start
+
+```bash
+# show resolved config + sources
+deepagent-hermes --show-config
+
+# interactive chat
+deepagent-hermes chat
+
+# from inside chat:
+#   /skills            list available skills
+#   /model anthropic:claude-haiku-4-5-20251001    switch models
+#   /memory            dump current memory snapshot
+#   /compress          force context compression
+#   /quit
+```
+
+## Load into an existing host
+
+Any `deepagent-*` host with `langgraph-stream-parser>=0.2` host conventions can run this agent:
+
+```bash
+# deepagent-code
+DEEPAGENT_AGENT_SPEC="deepagent_hermes.agent:graph" deepagent-code
+
+# deepagent-lab — set the same in deepagents.toml under [agent]
+echo 'spec = "deepagent_hermes.agent:graph"' >> deepagents.toml
+deepagent-lab
+```
+
+## Configuration
+
+`deepagent-hermes.toml` (project) or `~/.deepagent-hermes/config.toml` (global). Layered resolution: `defaults < TOML < DEEPAGENT_HERMES_* env < CLI overrides`. See [SPEC §2](./SPEC.md#2-configuration) for every field; `deepagent-hermes --show-config` prints the resolved value + source of each.
+
+## Architecture
+
+See [SPEC.md](./SPEC.md) for the full 21-section requirements doc. Top-level layout:
+
+- `src/deepagent_hermes/agent.py` — the compiled graph (entry point for hosts)
+- `src/deepagent_hermes/config.py` — `HermesConfig(HostConfig)` resolver
+- `src/deepagent_hermes/state.py` — `HermesState` (extends `AgentState`)
+- `src/deepagent_hermes/reflection.py` — closed-loop middleware + review subagent
+- `src/deepagent_hermes/skills/` — SkillLibrary, loader, tools
+- `src/deepagent_hermes/memory/` — frozen-snapshot memory + provider ABC
+- `src/deepagent_hermes/store/sqlite_fts.py` — `BaseStore` with FTS5
+- `src/deepagent_hermes/search/session_search.py` — `session_search` tool
+- `src/deepagent_hermes/compression.py` — `HermesCompressionMiddleware`
+- `src/deepagent_hermes/caching.py` — `AnthropicCachingS3Middleware`
+- `src/deepagent_hermes/budget.py` — `IterationBudgetMiddleware`
+- `src/deepagent_hermes/tools/` — registry + 33 toolsets + 6 terminal envs
+- `src/deepagent_hermes/cron/` — daemon + `cronjob` tool
+- `src/deepagent_hermes/plugins/` — discovery + lifecycle hooks
+- `src/deepagent_hermes/cli.py` — `deepagent-hermes` entry point
+- `prompts/` — verbatim/paraphrased system-prompt building blocks
+
+## Status by subsystem
+
+| Subsystem | Status |
+|---|---|
+| Config + state + agent factory | working |
+| Reflection loop (10-iter trigger, subagent review) | working |
+| Skill library + agentskills.io validator | working |
+| Skill loader (`@dynamic_prompt`) | working |
+| `skill_view` / `skill_manage` / `skills_list` tools | working |
+| Frozen-snapshot memory (MEMORY.md / USER.md) | working |
+| SQLite FTS5 store + `session_search` (3 modes) | working |
+| Honcho provider | stub (extras-gated) |
+| Iteration budget middleware | working |
+| Compression middleware (13-section template) | working |
+| Anthropic `system_and_3` caching strategy | working |
+| Tool registry + 33-toolset enum | working |
+| `LocalEnvironment` terminal backend | working |
+| Docker / SSH / Daytona / Modal / Singularity backends | stubs (`NotImplementedError`) |
+| Cron daemon + `cronjob` tool | basic (local delivery only) |
+| Plugin loader (4 discovery sources) | working (5 of 17 hooks) |
+| CLI + v1-essentials slash commands | working |
+| Curator (skill lifecycle) | basic |
+| Self-evolution integration | docs only (separate offline repo) |
+| Bundled skills | none — ship your own under `~/.deepagent-hermes/skills/` |
+
+## License
+
+MIT. See [LICENSE](./LICENSE). This project is a faithful reproduction of the design ideas in Nous Research's Hermes Agent — see [NOTICE](./NOTICE) for attribution.

deepagent_hermes-0.1.0/README.md

@@ -0,0 +1,121 @@
+# deepagent-hermes
+
+A faithful reproduction of [Nous Research's Hermes Agent](https://github.com/nousresearch/hermes-agent) on top of LangGraph + [`deepagents`](https://github.com/langchain-ai/deepagents) + [`langgraph-stream-parser`](https://github.com/dkedar7/langgraph-stream-parser).
+
+**Status: pre-alpha (v0.1.0a0).** Spec at [SPEC.md](./SPEC.md). Code is scaffolded; most subsystems work end-to-end but the bundled-skills library is empty and 5 of 6 terminal backends are stubs.
+
+## What it is
+
+A `deepagents`-built agent with a **closed reflection→skill-creation loop**:
+
+- After ~10 tool-using iterations, a review subagent runs in the background, writes/patches a `SKILL.md` capturing the pattern it just exercised, and ships it to a skill library.
+- Next session, the agent reads the library at startup, sees the new skill's description in its system prompt, and can `skill_view(name)` to load the full body on demand (progressive disclosure per the [agentskills.io spec](https://agentskills.io/specification.md)).
+- A weekly **curator** consolidates skills into umbrellas and archives stale ones.
+- A **frozen-snapshot memory** (`MEMORY.md` + `USER.md`) preserves prefix-cache hits for the entire session.
+- **FTS5 session search** indexes every past conversation in a local SQLite DB.
+- Optional **Honcho user model** for dialectic cross-session user profiling.
+
+Designed to be loaded into the existing `deepagent-*` host family ([`deepagent-code`](https://github.com/dkedar7/deepagent-code), [`deepagent-lab`](https://github.com/dkedar7/deepagent-lab), [`cowork-dash`](https://github.com/dkedar7/cowork-dash), [`deepagent-vscode`](https://github.com/dkedar7/deepagent-vscode)) without UI changes — set `DEEPAGENT_AGENT_SPEC=deepagent_hermes.agent:graph` in any of them.
+
+## Installation
+
+```bash
+# central venv per the deepagent-* convention
+uv venv "$env:USERPROFILE\.venvs\deepagent-hermes"
+. "$env:USERPROFILE\.venvs\deepagent-hermes\Scripts\Activate.ps1"
+
+# while langgraph-stream-parser v0.2.0 is unreleased, install editable
+uv pip install -e "..\langgraph-stream-parser"
+
+uv pip install -e .
+
+# optional extras
+uv pip install -e ".[honcho]"     # Honcho user-model provider
+uv pip install -e ".[modal]"      # Modal sandbox backend
+uv pip install -e ".[daytona]"    # Daytona sandbox backend
+uv pip install -e ".[dev]"        # tests + lint
+```
+
+## Quick start
+
+```bash
+# show resolved config + sources
+deepagent-hermes --show-config
+
+# interactive chat
+deepagent-hermes chat
+
+# from inside chat:
+#   /skills            list available skills
+#   /model anthropic:claude-haiku-4-5-20251001    switch models
+#   /memory            dump current memory snapshot
+#   /compress          force context compression
+#   /quit
+```
+
+## Load into an existing host
+
+Any `deepagent-*` host with `langgraph-stream-parser>=0.2` host conventions can run this agent:
+
+```bash
+# deepagent-code
+DEEPAGENT_AGENT_SPEC="deepagent_hermes.agent:graph" deepagent-code
+
+# deepagent-lab — set the same in deepagents.toml under [agent]
+echo 'spec = "deepagent_hermes.agent:graph"' >> deepagents.toml
+deepagent-lab
+```
+
+## Configuration
+
+`deepagent-hermes.toml` (project) or `~/.deepagent-hermes/config.toml` (global). Layered resolution: `defaults < TOML < DEEPAGENT_HERMES_* env < CLI overrides`. See [SPEC §2](./SPEC.md#2-configuration) for every field; `deepagent-hermes --show-config` prints the resolved value + source of each.
+
+## Architecture
+
+See [SPEC.md](./SPEC.md) for the full 21-section requirements doc. Top-level layout:
+
+- `src/deepagent_hermes/agent.py` — the compiled graph (entry point for hosts)
+- `src/deepagent_hermes/config.py` — `HermesConfig(HostConfig)` resolver
+- `src/deepagent_hermes/state.py` — `HermesState` (extends `AgentState`)
+- `src/deepagent_hermes/reflection.py` — closed-loop middleware + review subagent
+- `src/deepagent_hermes/skills/` — SkillLibrary, loader, tools
+- `src/deepagent_hermes/memory/` — frozen-snapshot memory + provider ABC
+- `src/deepagent_hermes/store/sqlite_fts.py` — `BaseStore` with FTS5
+- `src/deepagent_hermes/search/session_search.py` — `session_search` tool
+- `src/deepagent_hermes/compression.py` — `HermesCompressionMiddleware`
+- `src/deepagent_hermes/caching.py` — `AnthropicCachingS3Middleware`
+- `src/deepagent_hermes/budget.py` — `IterationBudgetMiddleware`
+- `src/deepagent_hermes/tools/` — registry + 33 toolsets + 6 terminal envs
+- `src/deepagent_hermes/cron/` — daemon + `cronjob` tool
+- `src/deepagent_hermes/plugins/` — discovery + lifecycle hooks
+- `src/deepagent_hermes/cli.py` — `deepagent-hermes` entry point
+- `prompts/` — verbatim/paraphrased system-prompt building blocks
+
+## Status by subsystem
+
+| Subsystem | Status |
+|---|---|
+| Config + state + agent factory | working |
+| Reflection loop (10-iter trigger, subagent review) | working |
+| Skill library + agentskills.io validator | working |
+| Skill loader (`@dynamic_prompt`) | working |
+| `skill_view` / `skill_manage` / `skills_list` tools | working |
+| Frozen-snapshot memory (MEMORY.md / USER.md) | working |
+| SQLite FTS5 store + `session_search` (3 modes) | working |
+| Honcho provider | stub (extras-gated) |
+| Iteration budget middleware | working |
+| Compression middleware (13-section template) | working |
+| Anthropic `system_and_3` caching strategy | working |
+| Tool registry + 33-toolset enum | working |
+| `LocalEnvironment` terminal backend | working |
+| Docker / SSH / Daytona / Modal / Singularity backends | stubs (`NotImplementedError`) |
+| Cron daemon + `cronjob` tool | basic (local delivery only) |
+| Plugin loader (4 discovery sources) | working (5 of 17 hooks) |
+| CLI + v1-essentials slash commands | working |
+| Curator (skill lifecycle) | basic |
+| Self-evolution integration | docs only (separate offline repo) |
+| Bundled skills | none — ship your own under `~/.deepagent-hermes/skills/` |
+
+## License
+
+MIT. See [LICENSE](./LICENSE). This project is a faithful reproduction of the design ideas in Nous Research's Hermes Agent — see [NOTICE](./NOTICE) for attribution.