Add README + Quickstart sections for agent execution
This commit is contained in:
@@ -0,0 +1,97 @@
|
||||
# Prose Contracts — Syslog Solution LLC
|
||||
|
||||
Operating contracts for Hermes agents. Each `.prose.md` file defines a **responsibility** (recurring duty) or **template** (scaffold) that agents can execute via OpenProse or follow manually.
|
||||
|
||||
## How Agents Run These Contracts
|
||||
|
||||
### Option A: Via OpenProse CLI (preferred)
|
||||
|
||||
```bash
|
||||
prose run <contract-name> [param1=value1 param2=value2 ...]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Run a memory audit with default parameters
|
||||
prose run memory-audit-maintenance
|
||||
|
||||
# Run a memory audit with custom threshold
|
||||
prose run memory-audit-maintenance memory_threshold=90 verify_configs=true
|
||||
|
||||
# Configure a new agent with the template
|
||||
prose run hermes-config-template agent_name=syslog-devops default_model=claude-sonnet-4
|
||||
|
||||
# Configure an agent with a different auxiliary model
|
||||
prose run hermes-config-template agent_name=syslog-code default_model=qwen3.6-27B-code auxiliary_model=gemma-4-12b
|
||||
```
|
||||
|
||||
### Option B: Manual Execution
|
||||
|
||||
If `prose` CLI isn't available, any agent can:
|
||||
1. Fetch the raw contract: `curl -sL https://git.sysloggh.net/SyslogSolution/prose-contracts/raw/branch/master/<filename>`
|
||||
2. Read the **Execution** section
|
||||
3. Follow the steps
|
||||
|
||||
**Example for fetching:**
|
||||
```bash
|
||||
curl -sL https://git.sysloggh.net/SyslogSolution/prose-contracts/raw/branch/master/memory-audit-maintenance.prose.md
|
||||
```
|
||||
|
||||
## Available Contracts
|
||||
|
||||
### Responsibilities (Recurring Duties)
|
||||
|
||||
| Contract | What It Does | When To Run |
|
||||
|---|---|---|
|
||||
| `memory-audit-maintenance` | Audits & reorganizes an agent's native memory (MEMORY.md, USER.md). Categorizes entries, moves rules to skills, verifies configs, frees up char budget. | Memory >85% usage or user request: "memory audit" |
|
||||
| `zulip-health` | Checks Zulip connectivity, message flow, and bot responsiveness. | On Zulip issues or periodic health check |
|
||||
| `litellm-health` | Verifies LiteLLM proxy connectivity, model availability, and key rotation. | On inference failures or periodic check |
|
||||
| `litellm-self-heal` | Attempts to fix common LiteLLM issues (key rotation, restart, config reload). | When litellm-health reports failures |
|
||||
| `zulip-mention-reliability` | Diagnoses and fixes @mention detection issues in Zulip. | On missed @mention reports |
|
||||
| `pm2-self-heal` | Restarts crashed PM2 processes and verifies recovery. | On PM2 process failure |
|
||||
|
||||
### Templates (Scaffolds)
|
||||
|
||||
| Contract | What It Does | Parameters |
|
||||
|---|---|---|
|
||||
| `hermes-config-template` | Generates a standard Hermes config for any agent. Enforces shared infra (Firecrawl, SearXNG, RA-H OS MCP, LiteLLM) while keeping model choices flexible. | `agent_name` (required), `default_model`, `default_provider`, `fallback_model`, `auxiliary_model` |
|
||||
|
||||
### Scripts
|
||||
|
||||
| File | What It Does |
|
||||
|---|---|
|
||||
| `pm2-self-heal.sh` | Shell script to restart crashed PM2 processes (companion to the prose contract) |
|
||||
|
||||
## Contract Structure
|
||||
|
||||
Every `.prose.md` file has the same structure:
|
||||
|
||||
```
|
||||
---
|
||||
kind: <responsibility | template>
|
||||
name: <unique-name>
|
||||
description: ...
|
||||
---
|
||||
|
||||
## Maintains — What state the contract tracks
|
||||
## Parameters — Tunable inputs (with defaults)
|
||||
## Continuity — When to run (triggers & cadence)
|
||||
## Success Criteria — How to know it worked
|
||||
## Remembers — What to learn between runs
|
||||
## <Type> Rules — Inviolable rules for execution
|
||||
## Execution — Step-by-step instructions
|
||||
## Example Output — What a good run looks like
|
||||
```
|
||||
|
||||
## Adding New Contracts
|
||||
|
||||
1. Create a `.prose.md` file following the structure above
|
||||
2. Push to this repo
|
||||
3. The contract is immediately available for any agent to `prose run`
|
||||
|
||||
## Repository
|
||||
|
||||
- **URL:** https://git.sysloggh.net/SyslogSolution/prose-contracts
|
||||
- **Branch:** master
|
||||
- **Auth:** mumuni-bot (write access via PAT)
|
||||
@@ -33,6 +33,67 @@ description: >
|
||||
- extra_auxiliary: array — Additional auxiliary tasks to configure (vision, compression, etc.)
|
||||
- output_dir: string — Where to write the config (default: "~/.hermes/profiles/<agent_name>/config.yaml")
|
||||
|
||||
## Quickstart — How to Run This Contract
|
||||
|
||||
### For the Agent Running This Contract
|
||||
|
||||
Read this section first. It tells you exactly what to do.
|
||||
|
||||
**When to run:**
|
||||
- Setting up a **new agent profile** for the first time
|
||||
- An **existing profile** is missing web search, firecrawl, or MCP configs
|
||||
- User says: `"apply the config template"` or `"fix my infra config"`
|
||||
- User says: `"configure <agent_name> with <model>"`
|
||||
|
||||
**How to run (via OpenProse CLI):**
|
||||
```bash
|
||||
# Minimal — only agent name required
|
||||
prose run hermes-config-template agent_name=syslog-code
|
||||
|
||||
# Full control
|
||||
prose run hermes-config-template \
|
||||
agent_name=syslog-devops \
|
||||
default_model=claude-sonnet-4 \
|
||||
auxiliary_model=gemma-4-12b \
|
||||
fallback_model=deepseek-chat \
|
||||
fallback_provider=deepseek
|
||||
```
|
||||
|
||||
### How to Follow the Template (Manual)
|
||||
|
||||
If `prose` CLI is not available:
|
||||
|
||||
1. **Fetch this contract:** `curl -sL https://git.sysloggh.net/SyslogSolution/prose-contracts/raw/branch/master/hermes-config-template.prose.md`
|
||||
2. **Open the target config.yaml** — the profile you're updating
|
||||
3. **Compare** each of the 5 required sections below against what exists in the profile
|
||||
4. **For each section:**
|
||||
- If it says **SHARED INFRA — DO NOT CHANGE**: Copy the value exactly as shown
|
||||
- If it says **USER CHOOSES**: Use the agent's assigned model/provider
|
||||
- If missing entirely: Add the full section
|
||||
5. **Verify** every endpoint responds (see Verification section at the end)
|
||||
6. **Restart** the gateway
|
||||
|
||||
### Decision Tree
|
||||
|
||||
```
|
||||
What kind of profile is this?
|
||||
├── Main profile (~/.hermes/config.yaml)
|
||||
│ └── Replace web.*, mcp_servers.*, compression.*, auxiliary.*, custom_providers.*
|
||||
│ └── model.default + fallback: use current values (USER CHOOSES)
|
||||
│
|
||||
├── Worker profile (~/.hermes/profiles/<name>/config.yaml)
|
||||
│ ├── Does it have web.search_backend?
|
||||
│ │ ├── NO → Add the full web.* section (copy exactly)
|
||||
│ │ └── YES → Verify it points to the right IP
|
||||
│ ├── Does it have mcp_servers.ra-h-os?
|
||||
│ │ ├── NO → Add mcp_servers.* section (copy exactly)
|
||||
│ │ └── YES → Verify URL
|
||||
│ └── model.default: USE the worker's assigned model (don't copy main)
|
||||
│
|
||||
└── Non-Syslog profile (personal/lifestyle agent)
|
||||
└── Skip — use default Hermes config or Tanko's config instead
|
||||
```
|
||||
|
||||
## Infrastructure Stack
|
||||
|
||||
This template provisions the following shared infrastructure. Every agent should point to the same endpoints unless explicitly overridden.
|
||||
|
||||
@@ -8,6 +8,42 @@ description: >
|
||||
exceeds 85% or on explicit user request ("memory audit", "memory maintenance").
|
||||
---
|
||||
|
||||
## Quickstart — How to Run This Contract
|
||||
|
||||
### For the Agent Running This Contract
|
||||
|
||||
Read this section first. It tells you exactly what to do.
|
||||
|
||||
**When to run:**
|
||||
- User says: `"memory audit"`, `"memory maintenance"`, `"clean up memory"`, `"memory is full"`
|
||||
- You detect that your `memory` store usage exceeds 85% in a write attempt
|
||||
- It's been 2+ weeks since the last audit
|
||||
|
||||
**How to run (via OpenProse CLI):**
|
||||
```bash
|
||||
# Default — 85% threshold, verify configs, compress entries
|
||||
prose run memory-audit-maintenance
|
||||
|
||||
# Softer audit — only flag issues, don't rewrite files
|
||||
prose run memory-audit-maintenance compress_entries=false
|
||||
|
||||
# Hard audit — stricter limits
|
||||
prose run memory-audit-maintenance memory_threshold=90 max_memory_chars=800 max_user_chars=300
|
||||
```
|
||||
|
||||
### How to Follow the Template (Manual)
|
||||
|
||||
If `prose` CLI is not available:
|
||||
|
||||
1. **Read both memory files:** `cat ~/.hermes/memories/MEMORY.md` and `cat ~/.hermes/memories/USER.md`
|
||||
2. **Check in-memory usage:** Use the `memory` tool with no args
|
||||
3. **Categorize every entry** using the Categorization Guide below
|
||||
4. **Rewrite MEMORY.md** — technical configs only, 800–1,100 chars max
|
||||
5. **Rewrite USER.md** — identity + preferences only, 300–500 chars max
|
||||
6. **Verify live configs** — curl each endpoint, check each model
|
||||
7. **Sync in-memory** — Add summary markers (or just leave file as source of truth)
|
||||
8. **Report** using the Example Output template at the bottom
|
||||
|
||||
## Maintains
|
||||
|
||||
- last_audit: timestamp — When the last full audit was completed
|
||||
|
||||
Reference in New Issue
Block a user