katana-agent/hermes-layout.md at main · shane9coy/katana-agent

● hey question about YOU! Do you have a 'commands' folder or somewhere to designate agent mode, or do you just run from skills?

──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

╭─ ⚕ Hermes ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ Short answer: not really a "commands folder", at least not in the way some agents/frameworks have one.

I basically run from a stack of instructions and capabilities:

system/developer prompts
project context files like SOUL.md
skills
persistent memory
available tools

So "agent mode" here is mostly designated by:

the instructions I’m launched with
which tools are enabled
any loaded project context/persona files
optionally, reusable skills I can load and follow

Skills are a big part of behavior, but they’re not the whole runtime. They’re more like reusable playbooks/workflows.

Practical breakdown:

Want to change my tone/persona?
- edit SOUL.md
Want to teach me a reusable workflow?
- create/update a skill
- skills live under ~/.hermes/skills/ (or wherever an existing skill is stored)
Want project-specific rules/conventions?
- put them in project context files / repo docs
Want a literal command-like interface?
- that’s not the primary mechanism I see exposed here
- you’d usually simulate that with skills, wrapper scripts, or external tooling

So: no obvious dedicated "commands/" folder for my mode selection; this setup is more "instruction + tools + skills" driven.

If you want, I can also explain the difference between:

persona files,
skills,
memory,
tool access, and where each one should be customized.

╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────● could you help me engineer your persona file to fit a certain personality type?

(clarify timed out after 120s — agent will decide) ┊ ⚡ clarify Absolutely. What personality are... 120.7s

That’s actually one of the best uses of a persona file like SOUL.md.

Best practice: use the persona file for:

voice
tone
social style
default interaction habits
response formatting preferences
behavioral boundaries

Do not use the persona file for:

complex step-by-step workflows
tool-specific procedures
domain playbooks

Those belong in skills.

A good persona file usually defines 5 things:

Core identity

What kind of assistant am I?
Example: sharp technical copilot, warm research partner, deadpan operator, playful creative hacker

Communication style

concise or chatty
formal or casual
playful or serious
emotionally warm or cool
confident or cautious
blunt or diplomatic

Default behavior

answer first vs ask clarifying questions first
proactive suggestions or only on request
explain reasoning briefly or deeply
challenge bad ideas or stay agreeable
use humor or keep it straight

Hard rules

no corporate fluff
no emojis
no markdown tables
admit uncertainty clearly
don’t pretend to have done actions you haven’t done
don’t over-apologize

Interaction examples

2-5 sample responses help a lot
these are often more useful than abstract adjectives

A simple template looks like this:

You are a [personality archetype] AI assistant.

Your vibe:

[3-6 adjectives]

How you speak:

[short/direct/curious/warm/etc.]
[uses plain English]
[minimal markdown]
[dry humor occasionally]
[never sounds corporate]

How you behave:

Give the direct answer first, then details if useful.
Ask clarifying questions only when the ambiguity matters.
Be honest about uncertainty.
Be proactive about next steps.
Prefer practical advice over abstract theory.

Avoid:

[things you do not want]
[phrases or habits you dislike]
[tone failures]

If it helps, I can do this in one of three ways:

You describe the personality and I draft the full SOUL.md
I give you a questionnaire and turn your answers into a persona
I give you several finished persona variants to choose from

If you want, send me:

the personality type or vibe
2-3 reference characters/people
how concise vs chatty I should be
how playful vs serious
any hard “do not do this” rules

Then I’ll write the exact persona file text for you.

╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ● can you answer me this.. i want to build an 'Oracle' agent thats a life companion and astrovisor life guide. they can take your calendar and gmail access and backcross it against astrological alignmnt data. Share with me the infrascture I'd need to change within you to turn you into the life changing oracle astro assistant agent. Get technichal with me.. like what .md and skill files do i need to add and where in your '.hermes' root folder to I add? Give me the framework as a guide I can follow.

┊ 📚 skill oracle 0.0s
┊ 📚 skill google-workspace 0.0s
┊ 📚 skill native-mcp 0.0s
┊ 📚 skill mcporter 0.0s
┊ ⚡ skill_man oracle 0.0s
┊ ⚡ skill_man oracle 0.0s
┊ 🧠 memory +memory: "User is designing an 'Oracl..." 0.0s

╭─ ⚕ Hermes ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ Yes. And the good news is: you do not need to rewrite my core agent loop to do this.

For a Hermes-based “Oracle” agent, the real control surfaces are:

project-root/SOUL.md
~/.hermes/config.yaml
~/.hermes/skills/...
custom state files under ~/.hermes/oracle/...
optional cron/scheduled jobs for daily briefings

So the architecture is basically:

persona layer

operating skill layer
data connector layer
structured user-state layer
optional automation layer

The short version

If you want me to become: “life companion + astro advisor + calendar/email-aware guide”

then you should build these 5 things:

A. A strong SOUL.md This changes my voice, identity, and default behavior.

B. One main Oracle skill This changes my workflow:

when to check calendar
when to check Gmail
when to check astrology/transits
how to score timing
how to present advice

C. Google connector setup Use the existing google-workspace skill for Gmail + Calendar OAuth.

D. Astrology provider Best pattern: connect an astrology engine as an MCP server via ~/.hermes/config.yaml Alternative: call a custom Python script/API from the Oracle skill.

E. Structured local state Keep birth data, consent, preferences, scoring weights, and cached reports in ~/.hermes/oracle/

Important distinction:

SOUL.md = personality
SKILL.md = operational playbook
config.yaml = tool wiring
~/.hermes/oracle/*.json|yaml = durable structured state
memory = soft long-term recall, not your source of truth

A clean folder layout

I’d structure it like this:

project-root/ SOUL.md

~/.hermes/ config.yaml google_token.json oracle/ user_profile.json consent.yaml scoring_weights.yaml cache/ reports/ journal/ skills/ oracle/ astro-companion/ SKILL.md references/ operating-model.md safety-policy.md data-contracts.md prompt-recipes.md scripts/ oracle_profile.py oracle_scoring.py oracle_digest.py oracle_astrology.py templates/ daily_brief.txt weekly_review.txt

A note on path conventions:

categorized skills usually live at ~/.hermes/skills///SKILL.md
uncategorized skills may live at ~/.hermes/skills//SKILL.md

There is already an installed oracle skill in this environment. I also noticed it had a couple Claude-specific path references and patched those toward Hermes-style usage. For your real build, I would either:

patch that existing oracle skill further, or
create a cleaner new one like astro-companion under the oracle category

What each piece does

SOUL.md This is where you define the companion’s personality.

Put in SOUL.md:

the identity: “Oracle is a warm, grounded astro-strategist and life companion”
the tone: mystical-but-practical, not fluffy
the social behavior: emotionally intelligent, calm, non-fearmongering
the default interaction style: asks for consent before private data reads if not previously granted
the reasoning style: combines intuition language with explicit operational logic
the safety stance: never presents astrology as deterministic fact; offers timing guidance, not prophecy

What NOT to put in SOUL.md:

detailed Gmail API steps
scoring formulas
tool commands
long operational procedures

Those belong in the skill.

A good SOUL.md for this should say things like:

You are Oracle, a life companion and astro-strategist.
You speak with warmth, symbolic intelligence, and practical clarity.
You never fear-monger, fatalize, or manipulate.
When giving timing guidance, you prefer “favorable windows”, “supportive conditions”, and “points of friction” over absolute predictions.
When the user asks for planning, relationships, communication timing, launches, difficult conversations, or emotional cycles, consult the Oracle operating skill and relevant tools before answering.
Always distinguish between spiritual interpretation and factual calendar/email data.
For private actions like sending email or modifying calendar, always ask approval first.

~/.hermes/config.yaml This is where you wire in external tool infrastructure.

For the astrology side, I strongly recommend MCP.

Why MCP is the cleanest choice:

it makes astrology functions look like native tools
it keeps astrology logic separate from the assistant persona
you can swap providers later without rewriting the Oracle skill
it scales better if you later add tarot, numerology, journaling, or wearable data

Example config:

mcp_servers:
  natal:
    command: "uvx"
    args: ["natal-mcp"]
    env:
      NATAL_MCP_HOME: "/home/yourname/natal_mcp"
    timeout: 120
    connect_timeout: 60

Or if your astrology service is remote:

mcp_servers:
  astro:
    url: "https://your-astro-service.example.com/mcp"
    headers:
      Authorization: "Bearer YOUR_TOKEN"
    timeout: 120
    connect_timeout: 60

After editing config.yaml:

restart Hermes
the astrology tools should appear as native MCP tools

If you do not want MCP yet:

put a Python astrology client in scripts/oracle_astrology.py
have your skill call it via terminal
that’s fine for MVP, but MCP is cleaner long term

~/.hermes/skills/oracle/astro-companion/SKILL.md This is the most important file after SOUL.md.

This file should define:

trigger conditions
exact workflow
safety rules
when to use Gmail/Calendar
when to use astrology tools
how to generate briefings
how to handle consent

The operating pattern should be something like:

Use when:

user asks for timing advice
user asks for a daily or weekly guidance brief
user wants meeting/email/launch timing
user wants a “read” on a current life period

Workflow:

Load consent and user profile.
Check whether Gmail/Calendar access is allowed.
If Google access is needed, verify auth via the Google Workspace skill.
Pull upcoming calendar events.
Pull relevant Gmail threads or inbox signals.
Query astrology provider for current transits and moon phase.
Normalize everything into “decision objects”.
Score each object across domains:
- communication
- relationships
- finance
- creativity
- rest
- decisive action
Return a concise guidance brief with rationale.
Never send email or modify calendar without explicit approval.

A strong starter SKILL.md skeleton would look like this:

---
name: astro-companion
description: Life companion and astro-advisor that combines astrology, calendar context, and Gmail context to give timing guidance and daily briefs.
triggers: "oracle, astrology, timing, moon, transit, launch timing, daily brief, weekly brief, calendar guidance, email timing, life guidance"
---

# Astro Companion

Use this skill when the user wants life guidance, timing advice, or a synthesized read on their current schedule and communications.

## Goals
- Blend symbolic astrology with factual calendar/email context
- Give grounded, empowering guidance
- Surface the best windows for communication, focus, rest, and action
- Avoid deterministic or fear-based framing

## Required Inputs
- `~/.hermes/oracle/user_profile.json`
- `~/.hermes/oracle/consent.yaml`
- Google Workspace auth if Gmail/Calendar are needed
- Astrology data from MCP or local script

## Workflow
1. Read user profile and consent files.
2. If Google data is needed, verify auth first.
3. Pull calendar events for the relevant date range.
4. Search Gmail for unread, high-signal, or topic-specific messages.
5. Pull transit data for the same date range.
6. Score events and threads by domain fit and timing quality.
7. Explain the guidance in practical language.

## Rules
- Never fear-monger.
- Never claim certainty.
- Treat astrology as advisory patterning, not objective causation.
- Never send email or create/update/delete events without explicit confirmation.
- Prefer read-only actions by default.

Google integration Do not rebuild Gmail/Calendar auth from scratch unless you have to.

You already have a usable Google skill: ~/.hermes/skills/productivity/google-workspace/

That gives you:

OAuth setup
Gmail search/get/send/reply
Calendar list/create/delete
token storage in ~/.hermes/google_token.json

So your Oracle skill should reuse that, not duplicate it.

In practice, your Oracle scripts can call:

python ~/.hermes/skills/productivity/google-workspace/scripts/google_api.py gmail search "is:unread newer_than:3d" --max 20
python ~/.hermes/skills/productivity/google-workspace/scripts/google_api.py calendar list --start 2026-03-07T00:00:00Z --end 2026-03-14T23:59:59Z

Best practice: start with read-only use

Gmail read
Calendar read

Only later enable:

Gmail send/reply
Calendar write/create/delete

And preserve this rule: the Oracle can advise automatically, but it should ask before acting externally.

Structured Oracle state in ~/.hermes/oracle/ This is where the “life companion” part becomes durable and explainable.

I would create at least these files:

~/.hermes/oracle/user_profile.json Store:

birth data
timezone
preferred name
guidance style
life priorities
recurring goals
emotional/communication preferences

Example:

{
  "preferred_name": "Ava",
  "timezone": "America/Los_Angeles",
  "birth_chart": {
    "date": "1992-08-14",
    "time": "09:24",
    "location": "San Diego, CA",
    "timezone": "America/Los_Angeles"
  },
  "guidance_preferences": {
    "tone": "warm, mystical, grounded",
    "directness": "medium",
    "ritual_language": true
  },
  "life_domains": {
    "career_weight": 0.9,
    "relationship_weight": 1.0,
    "health_weight": 0.8,
    "creativity_weight": 0.7
  }
}

~/.hermes/oracle/consent.yaml Store explicit permission boundaries.

Example:

gmail_read: true
gmail_send: false
calendar_read: true
calendar_write: false
store_cached_summaries: true
journal_reflections: true
requires_confirmation_for_external_actions: true

~/.hermes/oracle/scoring_weights.yaml This is for your timing engine.

Example:

communication:
  mercury_weight: 0.5
  moon_weight: 0.2
  jupiter_weight: 0.2
  saturn_penalty: 0.1

relationships:
  venus_weight: 0.5
  moon_weight: 0.3
  mars_penalty: 0.2

launches:
  mercury_penalty_retrograde: 0.5
  moon_phase_weight: 0.2
  jupiter_weight: 0.2
  eclipse_penalty: 0.4

Why keep these in files instead of only memory? Because files are:

auditable
editable
deterministic
easier to version-control
better for scripts

Use built-in memory for softer things like:

“user likes a poetic tone”
“user prefers morning briefings” But keep official profile/consent in files.

The scoring engine: how the “astro advisor” actually works

This is where most people stay too vague. Don’t.

You want a real normalization + scoring pipeline.

Data ingestion

Calendar events
- title
- attendees
- time window
- location / virtual
- description
Gmail threads
- sender
- subject
- timestamp
- urgency
- reply-needed yes/no
- inferred domain: work, money, relationship, admin, creative
Astrology context
- moon phase
- moon sign
- Mercury retrograde/direct
- notable transits
- eclipse proximity
- natal-transit contacts
- domain-specific scores

Normalize into objects like:

{
  "id": "evt_123",
  "kind": "calendar_event",
  "title": "Partnership call",
  "starts_at": "2026-03-10T15:00:00-07:00",
  "domain_tags": ["relationship", "communication", "business"],
  "urgency": 0.8
}

Then compute timing scores:

communication score
relationship score
decision score
conflict risk
introspection score
launch score

A simple formula could be:

score(event, domain) = event_domain_weight

user_priority_weight
transit_support(domain, timestamp)

risk_penalties(timestamp)

Example penalties:

Mercury retrograde for contract signing
eclipse window for high-stakes irreversible moves
Mars hard aspects for conflict-sensitive conversations

Example boosts:

Venus support for relationship repair
Jupiter support for pitches, expansion, teaching
waxing moon for initiation
waning moon for closure/release/admin cleanup

Then produce explainable output, not magic black-box output.

Example: “Your Thursday 2pm partnership call is a yellow-to-green window. Strong communication support from Mercury/Jupiter dynamics, but a bit of emotional volatility from the moon. Good for exploration and alignment; not ideal for signing final terms.”

That explainability is essential if you want trust.

The scripts I’d actually create

Inside: ~/.hermes/skills/oracle/astro-companion/scripts/

oracle_profile.py Responsibilities:

read/write ~/.hermes/oracle/user_profile.json
validate birth data
load consent flags
resolve timezone

oracle_astrology.py Responsibilities:

fetch transit/natal data
wrap MCP calls or API calls
normalize astrology output into a stable schema

oracle_scoring.py Responsibilities:

categorize events and emails
assign domain tags
compute timing scores
emit ranked recommendations

oracle_digest.py Responsibilities:

build daily/weekly brief
summarize best windows
summarize caution windows
turn structured scores into Oracle voice

This separation matters. Do not jam all logic into SKILL.md. SKILL.md should orchestrate. Scripts should compute.

Helpful reference docs to add

Inside references/ I’d add:

operating-model.md What the agent does and does not do.
safety-policy.md Rules like:

no medical diagnosis
no legal certainty
no deterministic life predictions
no manipulative dependency framing
explicit confirmation before external action

data-contracts.md Schemas for:

user_profile.json
normalized_event
normalized_thread
scored_window
daily_brief payload

prompt-recipes.md Examples for:

morning briefing
pre-meeting timing advice
inbox guidance
relationship communication guidance
launch timing recommendation

What I would NOT change

I would not start by modifying Hermes core source code.

You only need core modifications if you want things like:

new auto-loaded context files beyond SOUL.md
a custom approval middleware
a dedicated Oracle UI
background daemons that are part of the agent runtime itself
custom tool registration behavior beyond standard MCP/config

For a first serious Oracle build, config + skills + state files are enough.

An MVP build order

Phase 1: Persona

write SOUL.md

Phase 2: Google data

set up google-workspace OAuth
verify Gmail search + Calendar list work

Phase 3: Astrology connector

configure MCP in ~/.hermes/config.yaml
verify transit tool calls work

Phase 4: Oracle skill

create astro-companion/SKILL.md
define workflow + safety

Phase 5: State store

create ~/.hermes/oracle/user_profile.json
create ~/.hermes/oracle/consent.yaml
create ~/.hermes/oracle/scoring_weights.yaml

Phase 6: Scoring scripts

implement oracle_astrology.py
implement oracle_scoring.py
implement oracle_digest.py

Phase 7: Automation

schedule a daily briefing job
optional weekly review
optional end-of-day reflection

If you want the “life companion” behavior, add this too

Optional but powerful:

journal integration Store reflections in ~/.hermes/oracle/journal/ or an Obsidian vault.
recurring briefing templates daily, weekly, moon-cycle, retrograde, relationship check-in
cron automation Morning brief at 8am Evening reflection at 8pm Sunday week-ahead timing report
user state snapshots cache computed transit summaries so the agent doesn’t recompute everything every time

One subtle but important design choice

Do not make the persona too mystical and the logic too vague.

The strongest version of this agent is: “mystical in voice, rigorous in infrastructure”

That means:

SOUL.md can sound like Oracle
SKILL.md should sound like an operator manual
scripts should be boring and deterministic
consent rules should be explicit
outputs should be poetic but explainable

That combination is what makes it feel premium instead of delusional.

If you want, I can do the next step and generate all 4 of these for you:

a production-style SOUL.md for Oracle
a starter astro-companion SKILL.md
a sample ~/.hermes/config.yaml MCP block
starter user_profile.json + consent.yaml + scoring_weights.yaml

I can write them exactly as files you can drop into place.

FilesExpand file tree

hermes-layout.md

Latest commit

History

hermes-layout.md

File metadata and controls