This is the single source of truth for what Circulatio does and why it matters. If you are an engineer, read this first, then go to ENGINEERING_GUIDE.md. If you are a user, this is for you.
Circulatio is a soul OS for soul-making.
For the architectural stack, scalability thesis, and builder-psyche separation, see ARCHITECTURE.md.
Hermes connects the days. Circulatio connects the depths. Together they build soul + soma + spirit — the whole person, not the optimized one.
It helps you build a living relationship with your own unconscious through your dreams, your body, and the patterns that shape your life. It is not a therapist, not a chatbot, not a wellness tracker. It is a collaborative witness that remembers what you forget, sees what you cannot yet see, and stays with you while you do the work.
The repo now includes an offline Evolution OS for method artifacts:
- prompt policy fragments in
src/circulatio/llm/prompt_fragments.py - the Hermes Circulatio host skill in
src/circulatio_hermes_plugin/skills/circulation/SKILL.md - tool descriptions in
src/circulatio_hermes_plugin/schemas.py
The current layer can evaluate baselines and candidate bundles, stage manual review packages, emit manifests/diffs/reports under artifacts/self_evolution/runs/, and enforce immutable guardrails before merge. See docs/SELF_EVOLUTION_OS.md for the exact mutation boundary and review flow.
This tooling is still offline-only. It is not a runtime loop, does not mutate weights, and does not bypass human review or Circulatio's approval, safety, or consent boundaries. Reflection/pareto strategies and provider-backed execution or judge evals remain later work.
The repo also includes a separate repo-local Journey CLI comparison harness under
tools/journey_cli_eval/ and scripts/evaluate_journey_cli.py. That layer uses the shared
longitudinal cases in tests/evals/journey_cli/JOURNEY_FAMILIES.md to probe host-routing behavior, read-mostly
surface boundaries, and anchored follow-up expectations without claiming backend truth. Service,
bridge, and Hermes host-smoke tests remain authoritative for runtime behavior.
Phase 1 of embodied presentation is also present as a plan-only ritual path: Hermes routes one circulatio_plan_ritual call, Circulatio returns a typed presentation plan without writing memory, the repo-local renderer CLI emits a static manifest with mock providers, and Hermes Rituals plays that manifest. Phase 7.6 scheduled ritual invitations are now modeled as consent-bound ritual_invitation rhythmic briefs that require manual acceptance before planning. Phase 7.7 completion sync is now an explicit idempotent persistence operation, while provider-backed audio/image/video remains renderer-owned, opt-in, budget-gated, and beta-gated for music/video.
The target experience is an embodied Hermes-agent ritual layer: personal, memory-aware, and media-rich, closer to a guided companion experience than a static text response. It should feel like a guided session that understands the user's dream life, body state, recent events, symbolic threads, and current readiness, while still respecting consent and the hold-first boundary.
The vision is not that Circulatio becomes the coach, frontend, or media generator. The vision is that each layer does its job cleanly enough for the full experience to feel alive:
memory context
-> Hermes-agent chooses the right ritual surface mix
-> user accepts or asks directly
-> Circulatio compiles a safe plan
-> renderer creates the artifact
-> Hermes Rituals plays it with breath/music/voice/meditation/image/cinema as needed
-> completion writes only explicit outcomes back to Circulatio
-> future live guidance attaches through guidanceSessionId
What must be done before this vision is real:
-
Prove Hermes-agent tool choice end to end. The agent must route from user message plus memory context into the correct
circulatio_plan_ritualshape: only breath, breath plus music, spoken meditation, music without narration, image return, or cinema when explicitly requested. -
Finish the scheduled ritual path. Scheduled rhythm must stop at invitation. Acceptance must be the only path into planning and rendering. Skip, dismiss, and expired invitations must not create plans or media.
-
Make playback proof stronger than provider smoke tests. Kokoro, DiffRhythm, and WAN smoke tests show provider contracts work. They do not prove the full user experience. We still need browser verification through
agent-browseror OpenAI Browser Use over real artifacts: audio metadata, waveform, music channel, captions, breath pacer, meditation field, image/cinema lens, companion rail, and completion. -
Keep fallback captions as the baseline. Whisper through the current Chutes path is not a working requirement. The ritual experience must stay functional with plan-derived or fallback caption segments until a reliable transcription provider is selected.
-
Connect Journey CLI to ritual proof. Journey CLI should verify invite-before-plan, accepted plan rendering, negative provider gates, selective surface choice, artifact checks through
agent-browseror OpenAI Browser Use, and completion sync. It should distinguish mock renders, live provider smoke, and browser playback success. -
Add the live guidance layer after artifact playback is stable. The Apple Fitness-like direction belongs to a
guidanceSessionIdsession with Hermes-agent companion state and optional sensor/coach tracks. It must attach to the presentation artifact without making the planner camera-aware or sensor-aware. -
Preserve the psyche boundary. No raw dream/body/event text to providers, no hidden interpretation during ritual planning/rendering/completion, no deterministic symbolic routing tables, and no automatic practice escalation after playback.
Circulatio is for people doing soul-making — not as an escape from life, but as the ground beneath it.
- You remember dreams and sense they mean something, but you do not know how to read them.
- You feel patterns repeating in your life and want to understand them at depth, not just manage symptoms.
- You are doing inner work (therapy, analysis, meditation, active imagination) and need a memory system that holds your material between sessions.
- You believe the body carries intelligence and want to connect somatic experience with symbolic life.
- You are interested in Jungian depth psychology, archetypes, and individuation, but you want a practical tool, not just theory.
- You want a witness that accumulates with you, not a dashboard that reports on you.
A gentle pattern surfacing, not a notification:
"You dreamed of water rising three times this month. Yesterday you noted tension in your chest before a meeting. Your goal 'speak with clarity' has appeared in 4 of 7 recent reflections. Want to do a 3-minute body check-in?"
You choose to engage or not. No guilt. No streaks.
Drop a quick note:
- A dream fragment
- A body sensation ("tight jaw, afternoon")
- A strange coincidence
- A mood shift after a conversation
- An image that stuck
Capture vs. Hold vs. Interpret (new):
- Capture: You drop a note. Circulatio stores it with provenance.
- Hold: Circulatio does not interpret immediately unless you ask. It waits with you.
- Interpret: Only when you ask, or when a pattern has ripened across multiple captures.
This boundary is sacred. The unconscious has its own timing. The system does not rush the door.
You ask: "What is alive today?"
Circulatio responds with a weave:
- The morning's tension connected to the recurring water symbol
- A cultural parallel, offered as invitation, not explanation
- A gentle question: "Does the chest tension feel like holding something back, or preparing for something?"
- A practice suggestion: a 5-minute journaling prompt or a body-focused inquiry
A deeper synthesis:
- What recurred?
- What shifted?
- What was avoided?
- What new symbol emerged?
- What goal tension is visible?
You read it like reading a journal you did not write alone. It is familiar and surprising.
Week 1: You record a dream of being chased through a house.
Circulatio stores it. Notes: "chase motif, house setting, first occurrence."
Week 3: You record another dream. This time you hide in a basement.
"The house is expanding downward. In the first dream, you ran through rooms. Now you are below them. This is the second dream in this sequence.
You also noted last Tuesday: 'Felt small in the team meeting.'
Question: Is the basement a hiding place, or is it where something is kept?"
Week 6: You record a dream where you turn and face the pursuer. It is a child.
"You turned. That is a shift.
The pursuer was a child. In your symbol history, 'child' appeared once before — after you completed a delayed project. Your note: 'Shedding something I had outgrown.'
Your goal 'take initiative' has been marked as 'avoided' in three recent reflections.
This may not mean what it seems. But the pattern is asking for attention, not action."
Value: You did not receive an interpretation. You received a pattern held across time, with enough structure to feel meaningful and enough openness to remain yours.
You record: "Headache at 3pm. Same as Tuesday. Both times after calls with [person]."
"Headache. 3pm. Post-call pattern.
Body state 'tension' also logged after the last two team meetings.
Your goal 'maintain boundaries' was marked as 'challenged' yesterday.
This is not a diagnosis. It is a somatic echo. Would you like to do a short grounding practice, or would you prefer to leave it and see if it speaks again?"
You choose: "Leave it."
Circulatio: "Noted. I will hold it without pressing."
Two weeks later: You record: "Same headache, but this time I noticed it before the call. I said no. Headache did not come."
"You noticed it before. That is a different kind of awareness.
'Said no' is new in this pattern. Your goal 'maintain boundaries' shifted from 'challenged' to 'active' today.
No interpretation needed. You are changing the pattern. I am recording the shift."
Value: The body is treated as intelligence, not symptom. The system does not rush to meaning. It waits with you.
You record a powerful dream of a serpent coiled around a tree.
"Serpent. Tree. Coiling.
This motif appears in multiple amplification packs you have enabled:
- Alchemical: The uroboros, circulation of energy
- Mythic: The serpent in the garden, knowledge and limits
- Your personal symbol history: 'Snake' appeared in a dream three years ago. At that time, you were ending a role. The note you wrote: 'Shedding something I had outgrown.'
I am not saying this is the same. I am saying the image is charged, and it has roots.
What is your own first response to the serpent in this dream?"
You: "It felt ancient. Not scary. Heavy."
"Ancient. Heavy. Not scary.
That is different from the 3-years-ago note, which had urgency.
Would you like to do a short active imagination practice with the serpent, or would you prefer to hold the image and see if it returns?"
Value: The cultural layer is invited, not imposed. Your own language is prioritized. Amplification is offered as mirror, not explanation.
You record: "Got angry at my colleague for being 'too slow.' Felt out of proportion."
"Anger. Out of proportion. Target: colleague's pace.
Your recent reflections show a recurring theme: 'I am behind on my own work.' Last week: 'I hate that I delay hard tasks.'
This is not an accusation. It is a pattern of projection.
The shadow is not that you are slow. The shadow may be that you fear you are.
You do not need to fix this. But the feeling is now visible — both in you and in how it landed on your colleague.
Would you like to explore this in a journaling prompt, or simply note it and move on?"
You: "Note it."
Circulatio: "Noted. I will watch for whether this projection recurs with the same trigger or shifts to a new one."
Value: Shadow work is invited, not forced. The pattern is named without shame. Next steps are offered but refusal is respected.
You have two goals:
- "Create more openly" (artistic)
- "Secure stable income" (practical)
Over two months: Circulatio notices:
- Every time you make progress on "create openly," you log anxiety about money within 48 hours.
- Every time you prioritize income, you log a dream of a locked door or a missed train.
Monthly Review:
"Your two goals are not in conflict on paper. But your unconscious treats them as exclusive.
The locked door appears after income-focused weeks. The missed train appears after creative surges.
This is a complex — a split. Not a problem to solve, but a tension to hold.
Depth psychology would call this an opposition of archetypes: the Creator and the Provider. Individuation does not mean choosing one. It means building a bridge.
No action required. But the pattern is now conscious. That changes the field."
Value: The system tracks longitudinal goal dynamics, not just checkbox progress. It names archetypal tensions without collapsing them into simple advice.
You accept a practice: "Before sleep, recall one image from the day and ask it: what do you want?"
Day 1-3: "Did it. Felt silly. Nothing came."
Circulatio: "Silly is a response. Nothing coming is also a response. I will not push."
Day 7: "An image of a key came. I don't know what it opens."
Circulatio: "A key. Unknown lock. This is the first image to arrive with its own question. No answer needed. Hold the key."
Day 14: "Dreamed of a door. Woke before opening it. The key was in my hand."
"You brought the key into the dream. That is active imagination working in sleep.
You woke before opening the door. That is also meaningful — the unconscious sets the pace, not the ego.
The practice is not to force the door. It is to keep the key present."
Value: Practices are held lightly. Micro-progress is recognized that a wellness app would miss.
You record: "Breakup. Can't tell if something is ending or if I am just falling apart. Dreamed of a burned house. Heavy legs all week."
"Breakup. Burned house. Heavy legs. This does not feel like a single bad day. It may be a threshold process."
"I would not rush to shadow, anima/animus, or deeper symbolic claims yet. Your grounding looks strained: sleep is uneven, work rhythm is unstable, and the body has stayed heavy for five days."
"If it helps, this has the feel of an ending-before-beginning. In an alchemical register, that can resemble mortificatio: reduction, stripping, loss of old form. I would hold that as a lens, not a conclusion."
"Would you like a grounding practice, a threshold note to hold across the week, or no intervention right now?"
Value: Life events become symbolic thresholds, not just timeline entries. The system strengthens containment before it intensifies depth work.
You record over six weeks:
- "My manager feels invasive."
- "My partner feels like they want too much from me."
- "I shut down when my friend asks direct questions."
"The people change, but the scene keeps returning: someone approaches, asks for contact, and your system reads it as pressure."
"I would hold this first as a relational scene, not a verdict about any one person. It may contain a projection, a defended complex, or an anima/animus-colored expectation. That remains a hypothesis until more of the pattern is conscious."
"Would you like to mark this as a recurring relational field and watch it, or explore what part of you feels intruded upon?"
Value: Individuation is not treated as purely inward. The outer world becomes part of the symbolic field, while projection is handled carefully and without blame.
You dream of a fox crossing the road at dawn.
Later that week:
- A fox appears in a film scene that grips you
- You see a fox mural near your office
- You write: "Felt watched in a strange but calm way"
"I would not call this proof of anything. But the fox image has crossed from dream, to waking symbol, to felt atmosphere."
"This may be an inner-outer correspondence. It matters because the image is staying alive across contexts, not because coincidence must be explained."
"I can mark this as a correspondence and hold it lightly, or we can leave it alone and see whether it returns again."
Value: Synchronicity is held carefully, without inflation or dismissal. The user gets a way to notice meaningful coincidence without forcing causality.
Before a journaling or analysis session, you ask: "Give me what matters from the last month."
Circulatio prepares a bounded packet:
- The dream sequence with the locked door and key
- Two body echoes that recurred after difficult conversations
- One threshold process around career uncertainty
- One relational field that keeps repeating with authority figures
- One inner-outer correspondence you marked but never interpreted
- Three current questions, not final conclusions
"I have prepared a packet for reflection and analysis. It is not everything. It is the material that stayed alive."
Value: The system becomes portable without becoming overwhelming. It supports analysis, journaling, and serious inner work without pretending to replace them.
The core backend/runtime described through the individuation and living-myth layers is now in place. The remaining open work is mainly packaging, presentation, and refinement:
- Depth refinement before feature breadth → deepen method quality, pacing, evidence discipline, and symbolic containment before widening the delivery surface
- Discovery digest refinement → the bounded
discoveryworkflow now combines graph query, memory-kernel retrieval, and dashboard summary into one read-only browsing surface; remaining work is tuning section quality, host presentation, and defaults without turning it into an interpretive shortcut - Standalone local runtime and product packaging → deferred distribution track
- Optional local semantic/vector recall → keep as a supplementary, provenance-bound retrieval seam only (for example SQLite-local extensions or embedded vector engines), never as Circulatio's primary symbolic truth layer
- Embodied presentation / ritual media layer → plan-only rituals, scheduled invitation briefs, local artifact manifests, connected artifact playback, explicit body capture, completion sync, and renderer provider gates are present; remaining work is production host orchestration, delivery UX, emotion follow-up capture, guidance-session launch, and provider hardening beyond the local renderer
- Optional ritual daily surfaces → later host-rendered outputs such as spoken
alive_todayreflections, brief meditations, 3-5 affirmation sets, short reflective audio or podcast-style scripts, and journaling/reflection prompts derived from dreams, reflections, or charged events - Broader validation and refinement → wider test coverage, multi-host usage, and polish beyond the targeted backend slices now implemented
- Evolution OS expansion → add reflection/pareto candidate generation, optional execution/judge gates, stronger holdout governance, and tighter release discipline without introducing live prompt mutation
- Soft adaptation learning expansion → continue extending the implicit-learning layer without overriding explicit consent or turning it into a heuristic meaning engine
When Circulatio is working, you feel:
- Remembered: "It knew I had that dream three weeks ago. I had forgotten."
- Pattern-lit: "I see the connection now. It was there, but I couldn't hold it all."
- Agency-intact: "It offered, I chose. It never pushed."
- Deeper, not busier: "I am not doing more. I am seeing more of what is already happening."
- Companioned in solitude: "I do this alone, but not alone."
| Signal | What it means |
|---|---|
| You return voluntarily | Not because of notifications, but because you value the mirror |
| You argue with it | Disagreement means engagement and ownership |
| You skip without guilt | The system has not created dependency or pressure |
| New symbols emerge spontaneously | You begin tracking your own images without prompting |
| Body notes increase | Somatic awareness is growing |
| Projection claims are self-recognized | You spot your own shadow before the system names it |
| Goals are held in tension, not chased | You tolerate paradox instead of collapsing it |
| Weekly reviews are read, not archived | The synthesis feels valuable enough to receive |
| You bring Circulatio to a crisis | In difficulty, you turn to the symbol-holding mirror |
| You outgrow it | You internalize the pattern-seeing capacity and need it less |
This roadmap should be read through user value first, not architecture first. The current work matters only if it changes what the user can feel, do, remember, and trust.
- Be held before being interpreted. A first pass can now preserve the material, attach native context, and return a method-aware question or amplification prompt instead of forcing a premature reading.
Value: The user feels paced with, not analyzed too early.
- Let my own life become the context. Circulatio now builds life context and method context from native records before interpretation.
Value: The system can draw from recurring symbols, body notes, goals, and recent state without depending on an external profile as the source of truth.
- Keep memory approval-gated. Symbolic writes remain proposals until explicitly approved.
Value: The user keeps agency over what becomes durable symbolic memory.
- Support hold-first capture. Dreams, events, reflections, symbolic notes, and body states can be stored without forcing interpretation.
Value: The user can build the vessel before asking for meaning.
- Ask for my own associations before stronger claims. The model can now return personal-amplification prompts and method-aware follow-up questions as part of the interpretation path.
Value: Personal meaning stays primary, and deeper or collective readings can come later.
- Move toward longitudinal companionship. The runtime now supports dream-series confirmation, richer practice follow-up, gentle proactive surfacing, threshold/chapter/return/bridge invitations, bounded analysis packets, and a bounded discovery digest over approved memory/graph/dashboard reads.
Value: Circulatio becomes a witness across time, not just a one-shot interpreter.
Status: The embedded/backend runtime now substantially covers the user outcomes described through Phases 4, 5, 6, 8, and 9. The original standalone-distribution track remains deferred. See
ENGINEERING_GUIDE.mdfor the current technical state and exact runtime scope.
User outcome: You know exactly what Circulatio is — a soul OS for soul-making — and what it refuses to become. No feature creep toward generic wellness tracking.
Circulatio sits at the depth layer of the stack. Hermes handles the breadth: daily rhythm, routing, gateway, session orchestration. Circulatio handles the depths: memory, symbol, pattern, interpretation, individuation. Together they build soul + soma + spirit. Circulatio will not absorb Hermes' breadth responsibilities, and Hermes will not pretend to do Circulatio's depth work.
User outcome: Circulatio remembers your dreams, reflections, body states, and practices across sessions. It retrieves what is relevant when you need it. No more "I know I dreamed something like this before, but I can't find it."
Implemented:
- Typed memory kernel with 11 namespaces
- Deterministic symbolic keyword expansion (snake ↔ serpent)
- Semantic compaction scaffolding
- Embedding seam reserved for future phase
User outcome: You can trace a symbol through time. You see that the serpent in last night's dream connects to the snake from six weeks ago, the chest tension from Tuesday, and the goal you have been avoiding. The pattern is visible.
Implemented:
- Allowlist-enforced graph queries
- Derived nodes from all record types (materials, symbols, patterns, practices, reviews)
- Record-to-record edges (MENTIONS, DRAWS_FROM, SUMMARIZES, etc.)
- Inferred symbol-to-symbol edges (co-occurrence, correlation)
- No external graph database required
User outcome: Circulatio generates its own understanding of your life from your records. It does not depend on an external profile. Your context comes from your own material.
Implemented:
CirculatioLifeContextBuilderderives context from native records- Context precedence: Circulatio-native → explicit caller → Hermes fallback
- Weekly reviews use freshly derived native context
- Privacy-safe summaries (no raw material text)
Conscious attitude layer (new):
ConsciousAttitudeSnapshotstored periodically from user reflections and goal states- Tracks: stated stance, active conflicts, recent ego position, avoided themes
- Required for compensation analysis (Jung: "without knowledge of the conscious situation, the dream can never be interpreted with any degree of certainty")
- First-class entity, not inferred metadata
Goal: Turn Circulatio from a careful symbolic interpreter into a true individuation companion without rebuilding local symbolic engines.
User outcome: Interpretations feel genuinely analytical, not generic symbolic chatbot output. Archetypal motifs, complexes, shadow tensions, and ego/unconscious dynamics are named when the evidence supports it. Depth is grounded, not performative.
What gets built:
- Structured LLM output for observations, hypotheses, method gates, depth readiness, amplification prompts, dream-series suggestions, and practice recommendations
- Prompt/schema evolution that keeps observation, hypothesis, amplification, and practice distinct without relying on deterministic interpretation layers
- Method-context inputs that let the model reason about conscious attitude, personal amplification, and dream-series context
- Safety as the only deterministic floor: fast pre-LLM screen plus post-LLM reconciliation where the gate wins
Dream series and amplification:
- Dream-series suggestions come from the LLM rather than a local series engine
- Personal amplification remains the preference before stronger collective interpretation
- Cultural amplification is invited, not imposed
Practice behavior:
- Normal practice recommendations come from the LLM
- If the LLM is unavailable, the only deterministic fallback is grounding when safety-blocked and journaling otherwise
What it should feel like:
- Less local symbolic machinery
- More "this pattern has been living with you across time"
Files likely involved:
src/circulatio/core/circulatio_core.pysrc/circulatio/llm/contracts.pysrc/circulatio/llm/json_schema.pysrc/circulatio/llm/hermes_model_adapter.pysrc/circulatio/adapters/context_adapter.pydocs/RUNBOOK.md
Success criteria:
- Depth claims are longitudinal and evidence-backed
- Cultural amplification is invited, not imposed
- Output sounds like collaborative witness, not pseudo-therapy bot
- Safety hard-stops override model output when they conflict
- Dream series progression can be surfaced without a separate deterministic engine
- Personal amplification is exhausted before collective claims become stronger
Adaptation decision (locked): Explicit profile + implicit learning. Start with explicit preference settings in user profile. Layer implicit learning after 20+ interactions. Explicit layer prevents cold-start errors. Implicit layer makes it feel alive.
Goal: Make the system able to connect psyche, body, goals, and collective meaning.
User outcome: Your dreams, body sensations, life direction, and cultural amplification packs are woven together. The system can say: "This symbol recurs with this somatic pattern and this life-direction conflict" without flattening everything into one dimension.
What gets built:
- Soma/body state ingestion and tracking (moved from Phase 5 to Phase 3+, now deepened here)
- Sensations, activation, fatigue, sleep-like markers
- Correlation with dream content and symbol recurrence
- Body is treated as intelligence, not symptom data
- Goal tension tracking across time
- Explicit aims, tensions, repeated avoidance, emergent direction
- Goals held as paradox, not checkbox progress
- Cultural amplification packs as optional lenses
- Alchemical, mythic, somatic, and other traditions
- User selects which packs to enable
- Collective amplification offered only after personal amplification is exhausted
- Links between:
- body states
- dreams
- reflections
- goal conflicts
- recurring symbols
What it should feel like:
- "You are not just tracking dreams"
- "You are tracking how psyche moves through life"
Files likely involved:
src/circulatio/domain/types.pysrc/circulatio/domain/graph.pysrc/circulatio/application/circulatio_service.pysrc/circulatio/repositories/in_memory_projections.py
Success criteria:
- Body notes become first-class context
- Goals are held as tensions, not task tracker objects
- Culture can enrich meaning without overruling the user
- Somatic correlation is surfaced in interpretations and reviews
Implementation status (April 2026): The embedded Hermes/backend runtime now includes alive_today, the bounded read-only discovery digest, read-mostly journey pages, low-risk autonomous journey-container writes through Hermes tool exposure, explicit /circulation journey ... lifecycle commands for QA/debug/demo, label-based journey resolution for lightweight host writes, weekly review cadence, rhythmic briefs, a lightweight host-only post-store IntakeContextPacket, and a repo-owned external Hermes-host smoke harness. Durable journey containers are organizational records, not symbolic truth claims; interpretation-derived symbolic memory remains approval-gated, and the post-store intake packet stays bounded, factual, and non-persistent.
Coach OS refinement (April 2026): Phase 6 now also exposes a single derived backend operating contract, coachState, on every enriched MethodContextSnapshot. coachState is not a new symbolic ontology. It is the shared runtime layer that tells alive_today, rhythmic briefs, journey pages, practice follow-up, and anchored reply routing which bounded coach loop is live, what one move is appropriate now, which moves are withheld, and when a curated resource invitation is safer than another prompt.
Goal: Move from reactive interpretation to living rhythm.
User outcome: Circulatio becomes longitudinal, not just reactive. Weekly reviews accumulate insight. Unresolved motifs resurface gently. Practices follow up. You are accompanied over time, not just served per request.
What gets built:
- Daily briefing
- "What is alive today?" synthesis
- A shared
coachStatecontract derived from method context, method state, runtime policy, consent, cadence, and recent runtime records - A bounded
discoverydigest that lets Hermes or QA browse approved dashboard, memory-kernel, and graph state without triggering interpretation or writes - Durable journey containers that Hermes can create, update, and re-status autonomously as lightweight ongoing-thread records
- Read-mostly journey pages that assemble opener, review surface, invitations, practice, and bounded analysis preview
- Label-based journey resolution so Hermes can target an existing journey by human label without exposing internal ids
- Explicit
/circulation journey list|get|create|update|pause|resume|complete|archivecommands for manual QA and demos - Weekly review cadence
- Journey check-ins
- Recurrence-triggered surfacing
- Practice follow-up loops
- Curated resource invitations for grounding, somatic tracking, journaling, and gentler follow-up when depth work should not intensify
- Purpose-built host context packets so Hermes-agent and later hosts can request bounded context for a specific job instead of dumping whole history
IntakeContextPacketfor hold-first material capture, derived immediately after persistence from bounded method-context/dashboard projections and markedhost_onlyTopicContextPacketThresholdPacketRelationalFieldPacketAnalysisPacket
- Optional local semantic recall over host conversation history, used only as a supplementary, provenance-bound context source rather than Circulatio's primary symbolic truth
What it should feel like:
- "I feel accompanied, not chased"
- Pattern surfacing, not spam
Files likely involved:
src/circulatio/application/circulatio_service.pysrc/circulatio/hermes/command_router.pysrc/circulatio/hermes/runtime.pysrc/circulatio/hermes/agent_bridge.py- Future automation or Hermes scheduling integration files
Success criteria:
- User receives pattern surfacing, not spam
- The system becomes longitudinal and rhythmic
- The user feels accompanied, not chased
- Hermes can browse approved symbolic state through one bounded discovery digest without silently escalating it into interpretation
- Hermes can hold an ongoing thread as a named journey without silently escalating it into interpretation
- Coach-facing surfaces share one bounded operating contract instead of each surface re-deriving its own pacing and follow-up behavior
- A repeatable external Hermes-host smoke path can verify plugin load, tool availability,
/circulation journeyrendering, and journey persistence before shipping - Hermes-agent and later hosts can ask for bounded context by purpose rather than receiving undifferentiated history blobs
- Local semantic/vector recall stays local-first, provenance-bound, and supplementary to Circulatio-owned records
Implementation status (April 2026): Deferred as a later packaging/distribution track. The embedded Hermes/backend runtime should be treated as the implemented primary surface for now.
Goal: Make Circulatio usable as a local product, not only as an embedded Hermes backend.
User outcome: You can run Circulatio locally for demo, dev, or personal use without the full Hermes stack. One-command setup.
What gets built:
- Standalone demo/runtime entrypoint
- Local profile bootstrap
- Polished skill/instruction packaging
- Simple end-to-end local demo:
- capture
- hold
- open or update a journey container
- render a journey page
- interpret
- review
What it should feel like:
- Developer usability
- Demoability
- Proof that Circulatio has its own product identity
Files likely involved:
demo.pysrc/circulatio_hermes_plugin/plugin.yamlpyproject.toml- Optional follow-on docs for standalone runtime usage once that work begins
Success criteria:
- One-command local run
- Repo-owned demo path exercises hold, journey, page, interpretation, and review flows
- Easy demonstration of journeys/reviews/context
- Circulatio can stand on its own, while still fitting Hermes
Embodied presentation note: Voice, breath containers, meditation fields, typed ritual sections, body-response capture, association-circle interaction, and host-rendered media are tracked separately in docs/PRESENTATION_LAYER.md so this roadmap stays focused on core symbolic and individuation work. Phase 7.6 adds scheduled ritual invitations as rhythmic briefs only; Phase 7.7 adds idempotent completion sync and renderer-side provider gates. Daily spoken reflections, richer TTS delivery, brief meditation containers, small affirmation sets, and short reflective audio/podcast-style outputs remain host-rendered ritual surfaces built on top of the symbolic core rather than in place of it.
Implementation status (April 2026): Implemented as a targeted rhythmic brief extension. Scheduled jobs can request only ritual_invitation briefs, require proactive_briefing consent, and receive a safe acceptancePayload for later manual planning. Cron still must not plan or render.
Implementation status (April 2026): Implemented for the local/backend path. Completion is recorded through an idempotent persistence operation keyed by user and idempotency key. Hermes Rituals now has a quiet completion panel that can submit no-note completion, explicit body state, literal reflection text, and practice feedback through one completion route. The route forwards to a host endpoint when configured and falls back to the repo-local Circulatio completion bridge otherwise. The local renderer emits completion manifest fields, preserves fallback captions, and keeps music/video behind explicit beta flags. Provider hardening remains renderer-owned.
Implementation status (April 2026): Partially implemented for artifact rituals. Hermes Rituals now has an explicit Body lens, a body picker composed inside the completion panel, literal reflection capture, practice-note capture, and no-note completion. The in-ritual companion receives phase and available track context and can be paused or minimized. The /live/{guidanceSessionId} route has a no-camera-first guidance shell with focus modes and explicit camera preflight. Emotion follow-up capture, mid-session body marking, production Hermes live coaching, and sensor guidance remain planned.
Goal: Decide and implement how post-practice somatic and emotional check-ins should work after breathing, meditation, or a full ritual without turning the ritual player into a wellness tracker.
Current behavior:
- completion appears naturally at closing/completion or when the user manually opens the Body lens/rail;
- completion can be submitted with no notes, body state, literal reflection text, practice feedback, or an explicit combination;
- body capture is explicit and idempotent through ritual completion sync;
- the current presentation frame can expose
hidden,inline_hint, orfocused_capturebody prompt modes; - companion guidance frames include phase and available track context;
- saved body data and words remain literal completion data and do not trigger interpretation.
Open design decisions:
- whether emotion capture should be separate from body capture or folded into a minimal tone field;
- whether mid-ritual body marking should be available before live guidance exists;
- how body/emotion capture should attach to practice sessions and future
guidanceSessionIdrecords; - what minimal emotion vocabulary should be stored, and how it maps to existing body-state/reflection records;
- how to preserve the hold-first rule: capture body/emotion state without forcing interpretation.
Success criteria:
- user can optionally mark body areas and emotional tone after practice;
- capture is explicit, consentful, and dismissible;
- stored data is structured enough for later symbolic/somatic review, but does not expose raw ritual text or create deterministic interpretation shortcuts;
- live guidance and camera-derived signals remain out of ritual completion events.
Implementation status (April 2026): Implemented in the core backend/runtime. The current runtime can persist Phase 8 record families, map LLM individuation output into approval-gated proposals, project approved material into memory-kernel and graph summaries, expose direct user-capture workflows, and generate threshold-oriented invitations without adding deterministic symbolic meaning engines.
Goal: Give Circulatio an individuation-oriented center: not just "what recurs," but "what is trying to become conscious."
User outcome: Phases 1–7 make Circulatio a symbolic witness and rhythmic companion. Phase 8 is where it starts to become an individuation companion.
Core capacities:
- track psychic oppositions without resolving them prematurely
- detect emergent third symbols, attitudes, or practices
- hold numinous and aesthetic encounters as meaningful in themselves
- model archetypal resonance cautiously and evidence-bound
- represent Self-orientation phenomenologically, not metaphysically
- track threshold processes and rites of passage as symbolic containers, not just events
- track recurring relational scenes and projection hypotheses across time
- hold inner-outer correspondence lightly, without forcing causality or doctrine
- assess grounding and reality anchors before stronger shadow, anima/animus, or complex language
- create threshold invitations when material appears ripe
Primary records:
SelfOrientationSnapshotPsychicOppositionRecordEmergentThirdSignalBridgeMomentRecordNuminousEncounterRecordAestheticResonanceRecordArchetypalPatternRecordThresholdProcessRecordRelationalSceneRecordProjectionHypothesisInnerOuterCorrespondenceRecordRealityAnchorSummaryThresholdInvitation
Primary user experience:
"This may be an individuation threshold. I can hold it with you, but I will not force it into meaning."
Naming guardrails:
- Use movement and relation language, not metaphysical certainty
- Prefer
SelfOrientationSnapshot, notSelfNode - Prefer
IntegrationContour, notWholenessScore - Prefer
SymbolicWellbeingSnapshot, notWellnessScore
Success criteria:
- Circulatio can ask not only what recurred, but what is trying to emerge
- Numinous and aesthetic experiences can be held without flattening them into interpretation
- Archetypal patterning stays cautious, evidence-bound, and longitudinal
- Threshold periods are treated as transformative processes, not just difficult weeks
- Relational scenes can be tracked as projection hypotheses without collapsing them into blame or certainty
- Inner-outer correspondence is held lightly, without inflation or dismissal
- Grounding capacity shapes pacing before deeper shadow, anima/animus, or complex work
- Proactivity becomes ripeness-based through threshold invitations, not engagement pressure
Implementation status (April 2026): Implemented in the core backend/runtime. Circulatio now supports living myth reviews, bounded analysis packets, review-proposal approval/rejection, summary-only projection of approved living-myth records, and ripeness-based chapter/return/bridge/packet invitations through Hermes/plugin workflows.
Goal: Convert recurring individuation signals into a collaborative, user-owned life narrative.
User outcome: The system no longer feels like a symbolic database or interpretation engine. It feels like a companion helping the user live their myth consciously.
Core capacities:
- generate living myth reviews
- identify the current life chapter and governing symbols
- track complex encounter trajectories
- maintain qualitative integration contours
- distinguish symbolic wellbeing from optimization
- weave threshold, relational, and correspondence material into long-range life coherence
- generate clean analysis packets for journaling, reflection, and analysis sessions
- increase proactive invitations around thresholds, returns, bridges, and resources
Primary records:
LifeChapterSnapshotLivingMythReviewRecordMythicQuestionThresholdMarkerComplexEncounterRecordIntegrationContourSymbolicWellbeingSnapshotChapterInvitationResourceInvitationReturnInvitationBridgeInvitation
Primary outputs:
AnalysisPacket
Primary user experience:
"The pattern is not asking you to become someone else. It may be showing how more of you can belong to the same life."
Wellbeing principle: Circulatio should treat wellbeing as symbolic, somatic, relational, and existential capacity, not optimization, streaks, or mood scoring.
Success criteria:
- the user can feel a current chapter, not just isolated interpreted material
- integration is described qualitatively, not gamified numerically
- complex encounters show movement across time rather than static labels
- threshold, relational, and synchronicity material can be woven into one intelligible life pattern without overclaiming
- analysis packets are bounded, legible, and useful for journaling or analysis rather than raw dumps
- proactive invitations remain gentle, dismissible, and tied to ripeness rather than pressure
If you are building this, go to ENGINEERING_GUIDE.md for the technical specification. Read this document first so you know what every line of code is in service of.
The principle is simple: build the vessel, but never forget the soul.