colony

name	colony
version	0.2.0
description	Colony cognitive memory provider for Hermes. Injects commitments, affect, facts, patterns, and world model into Hermes conversations and syncs turns back for extraction. Exposes Colony tools (colony_check_commitments, colony_list_goals, colony_write_memory, etc.) and lifecycle hooks for session rotation, memory mirroring, and pre-compression.
author	Aevonix

Colony Hermes Integration Suite

Mounts Colony's cognitive infrastructure as three Hermes plugins:

1. Memory Provider (~/.hermes/plugins/memory/colony/)
2. Context Engine (~/.hermes/plugins/context_engine/colony/)
3. General Plugin (~/.hermes/plugins/colony/)

Quick Start

cd ColonyAI/plugins/hermes-memory
./install.sh

Then add to ~/.hermes/config.yaml:

memory:
  provider: colony
  config:
    url: "http://127.0.0.1:7777"
    api_key: "${COLONY_API_KEY}"
    contact_id: "default"

context_engine: colony

plugins:
  colony:
    url: "http://127.0.0.1:7777"
    api_key: "${COLONY_API_KEY}"
    contact_id: "default"

Restart Hermes.

Memory Provider

prefetch()

Before each turn, calls Colony's /v1/host/context/assemble and injects the returned sections (commitments, affect state, shared facts, patterns, surprises, world model entities) as a <memory-context> block.

sync_turn()

After each turn, POSTs the user message and assistant response to Colony's /v1/host/turns/sync for extraction of commitments, affect, and facts. Non-blocking (daemon thread per Hermes threading contract).

get_tool_schemas() / handle_tool_call()

Exposes Colony tools to the LLM:

• colony_check_commitments — Check active commitments for the current contact
• colony_get_affect — Get current affect state (valence/arousal)
• colony_get_facts — Retrieve shared facts about a contact
• colony_get_patterns — Get detected behavioral patterns
• colony_write_memory — Persist a fact/insight to Colony
• colony_list_goals — List user goals with status and progress
• colony_record_affect — Record an emotional state event
• colony_search_memory — Search Colony's memory graph

Lifecycle Hooks

• on_session_switch() — Handles session rotation, clears cache on reset
• on_turn_start() — Called at the start of each turn
• on_memory_write() — Mirrors built-in memory writes back to Colony
• on_pre_compress() — Fires a signal ingest before context compression discards old messages
• on_session_end() — Flushes pending context and fires a best-effort final sync

Config Schema

Implements get_config_schema() and save_config() for the hermes memory setup wizard.

Context Engine

Replaces Hermes's built-in compressor with Colony-aware summarization:

• should_compress() — Checks token count against threshold
• compress() — Calls Colony's reasoning loop to produce a cognitive summary, preserving commitments and facts while discarding noise. Falls back to local compression if Colony is unreachable.

General Plugin

Native Tools

Registers additional Colony tools via ctx.register_tool():

• colony_memory_search
• colony_list_goals
• colony_get_briefing
• colony_record_insight
• colony_query_entities
• colony_task_complete
• colony_task_snooze
• colony_task_dismiss
• colony_initiative_feedback

WebSocket Event Subscriber

Connects to Colony's /v1/host/events WebSocket, caches the most recent events per type, and injects them via the pre_llm_call hook.

Slash Commands

• /colony status — Sidecar health + capabilities
• /colony goals — Active goals list
• /colony context — Fetch cognitive context
• /colony events — Recent cached events
• /colony sync — Force a turn sync

CLI Commands

• hermes colony status
• hermes colony goals
• hermes colony context
• hermes colony sync

Requirements

• Colony sidecar running at the configured URL
• httpx Python package
• websockets Python package (general plugin only)

What It Does

If the sidecar is unreachable, all calls degrade silently. No errors are raised for transient failures.