colony-hermes 1.0.0__tar.gz

colony_hermes-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aevonix
+
+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.

colony_hermes-1.0.0/PKG-INFO

@@ -0,0 +1,368 @@
+Metadata-Version: 2.4
+Name: colony-hermes
+Version: 1.0.0
+Summary: Native Hermes general and memory adapters for a Colony sidecar
+License-Expression: MIT
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<0.29,>=0.27
+Requires-Dist: httpcore<2,>=1
+Requires-Dist: typer<1,>=0.12
+Requires-Dist: PyYAML<7,>=6
+Provides-Extra: test
+Requires-Dist: build>=1.2; extra == "test"
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: setuptools>=77; extra == "test"
+Requires-Dist: wheel; extra == "test"
+Dynamic: license-file
+
+# Native Hermes adapter distribution
+
+`colony-hermes` packages the existing general adapter and memory provider for
+installation into the Python environment that runs Hermes. The Colony sidecar
+is a separate service. The adapter does not install the sidecar, a context
+engine, a worker daemon, or operating-system services.
+
+Build from the repository root:
+
+```sh
+python -m pip install build
+python -m build
+```
+
+Install the resulting wheel with the Python interpreter that runs Hermes:
+
+```sh
+python -m pip install dist/colony_hermes-1.0.0-py3-none-any.whl
+```
+
+The wheel exposes `colony` through `hermes_agent.plugins` and `colony-memory`
+through `hermes_agent.memory_providers`. It maps the canonical source files in
+`plugins/hermes-plugin/` and `plugins/colony-memory/` to importable packages.
+Only `catalog.py` and `contract.py` from `hostworker/colony_hostworker/` are
+included in the adapter's private catalog package. Source-checkout plugin paths
+and the existing installer's copying behavior remain compatible.
+
+## Activation and current limits
+
+Installing the wheel makes the adapters discoverable. It does not change a
+Hermes profile, select a memory provider, or enable tools. Activation requires
+the existing general-adapter configuration, `plugins.enabled: [colony]`, and
+`memory.provider: colony-memory` in the selected private profile. Preserve
+other enabled plugins when editing that list. The existing coexistence settings
+are also required in the Hermes process environment:
+
+```sh
+COLONY_GENERAL_PLUGIN_ACTIVE=1
+COLONY_MEMORY_WORKER_TOOLS=0
+COLONY_MEMORY_TURN_WRITER=disabled
+```
+
+Configure the sidecar URL and contact through native `hermes memory setup`
+and matching `plugins.colony` configuration, and supply `COLONY_API_KEY` privately.
+Native setup stores non-secret fields in the selected profile's
+`colony-memory.json`, which overrides legacy `memory.config`. The
+general adapter needs a private writable turn outbox and verified participant
+bindings. Consequential tools retain their existing mediator requirements.
+This packaging change does not provision those dependencies.
+
+Do not silently replace a selected external memory provider. Existing
+directory installations also need explicit migration: Hermes gives directory
+memory providers precedence over pip providers, while a pip general plugin can
+override a same-name directory plugin. Remove or archive obsolete plugin
+directories only as part of an intentional profile migration.
+
+When the memory provider is selected, native CLI discovery exposes
+`hermes colony-memory status`, `goals`, `context`, and `sync`. These commands
+resolve the same selected profile settings and credentials as the provider;
+explicit URL/contact arguments remain available. The Typer app remains available
+to existing callers.
+
+Profile settings and handoff files stay scoped to the selected Hermes home.
+The provider remains attached through a sidecar startup outage and retries on
+later requests. Automatic profile activation remains follow-up work; packaging
+alone does not establish production readiness.
+
+## Durable source capture
+
+The native memory provider implements compression checkpoint API v2. Set
+`compression.checkpoint_required: true` to make Hermes retain its transcript
+when local checkpoint persistence fails. A successful checkpoint commits the
+normalized direct source messages into the same private SQLite outbox used by
+the general adapter. The callback then attempts delivery within 250 ms.
+Sidecar downtime leaves a pending durable record and permits compression;
+pending does not mean centrally recallable. Diagnostics expose checkpoint
+state. The ordinary turn writer and subsequent checkpoints drain that outbox.
+
+The outbox accepts at most 8 MiB of serialized data per record. Oversized or
+unserializable evidence fails explicitly without clipping it. System rows,
+tool wrappers, compression summaries and injected `api_content` are excluded.
+Direct message content, including media references, is retained. The general
+turn writer also retains complete messages instead of cutting at 2,000
+characters. New records require a `source_recorded` receipt before delivery is
+acknowledged, so an older sidecar cannot silently discard an unfamiliar
+checkpoint payload during an upgrade.
+
+The existing `/v2/host/turns/{turn_id}` endpoint stores direct source JSON and a
+lexical index transactionally in `turn-idempotency.db`. Checkpoints bypass
+ordinary interaction, affect, graph and initiative effects. Replays do not
+create another source. `occurred_at` is retained when supplied explicitly in
+context metadata; otherwise it is unknown. Server `ingested_at` is separate
+and is never treated as the date asserted by the conversation.
+
+`/v1/host/context/assemble` reads the source index after the existing exact
+viewer check. Ordinary attributed turns can be recalled across that person's
+sessions. Full-history checkpoints additionally require their original session,
+because the native history does not guarantee old per-message speaker
+attribution. Media references remain source data; only text is indexed. This
+is direct evidence recall, not an embedding migration or a belief contradiction
+engine.
+
+## Source erasure and replay
+
+`POST /v1/host/memory/sources/forget` accepts an authenticated contact and 1 to
+100 canonical source IDs. The existing MCP server exposes `colony_forget_sources`.
+Native Hermes committed memory removes also attempt an exact, session-bound
+`old_text` match, including when the general plugin owns ordinary turn writes.
+No match or multiple matches produces an explicit unmapped/ambiguous diagnostic;
+it never broadens a text search into deletion. IDs unknown to the central source
+store are rejected. Pending-only local evidence needs to be identified at its host.
+
+Erasure commits source-ID and exact-message hashes before cleaning linked graph
+summaries. Checkpoint copies are redacted within the same contact and session;
+unrelated messages remain. New graph summaries carry `source_uri=turn:<id>` and
+`source_turn_id`. Projection markers block late writes and reads while deletion
+is pending. The response separates source erasure from graph cleanup and host
+reconciliation. A repeated request retries the same derived cleanup targets.
+
+The host outbox migrates its existing v1 database transactionally to v2 with a
+separate contact-bound erasure watermark. Canonical turn/checkpoint delivery
+fetches `/v1/host/memory/sources/erasures` before PUT. A missing endpoint, outage,
+incomplete page or server history behind the host cursor holds replay. The host
+purges both pending payloads and delivered receipts, preserving unrelated pending
+messages as evidence-only checkpoints. Erased IDs cannot be enqueued again after
+reconciliation. This is not a model-generation counter. Generic caller-provided
+outbox delivery callbacks must use `ColonyClient.sync_turn(..., outbox=outbox)`
+to participate in reconciliation.
+
+This is scoped source erasure, not a claim of global forgetting. Native Hermes
+transcripts/API context, backups, prior graph records without source lineage,
+legacy shared facts, ToM, commitments, and other old derivative stores need their
+own erasure adapters. Offline hosts retain bytes until reconnecting; filesystem
+snapshots and physical-media remnants are outside this logical-delete contract.
+Erasure history must survive backup restores; replay detects an older watermark
+but cannot prove that a replaced server with reused sequence numbers is equivalent.
+
+## Qualification
+
+Pull-request CI keeps an exact qualified Hermes commit pinned. The separate
+`Latest Hermes compatibility` workflow runs daily and can be dispatched manually.
+It selects the latest published stable upstream release, records its exact Git
+commit and runs the same built-artifact/native-profile tests. It uses disposable
+profiles and controlled inference, without deployment credentials or a live
+agent. A compatibility failure leaves production and the qualified pin intact.
+
+When a new upstream release passes, update the pin in an ordinary reviewed
+change and qualify the deployment's actual channels and recovery before moving
+that deployment. The scheduled result catches upstream drift; it does not
+establish production readiness or automatically upgrade a running agent.
+
+The qualification target is Hermes v0.21.0, tag `v2026.8.31`, commit
+`29112bef099274229cadff79cdff7bf7b99c4b77`, tested on Python 3.12. The package
+allows Python 3.11 through 3.13; those other interpreters are not yet qualified.
+Other Hermes
+releases are unqualified until the native-loader checks pass against them.
+Hermes is installed separately; this package does not select or upgrade it.
+
+Install test dependencies into an isolated environment with the target Hermes
+checkout available, then run:
+
+```sh
+python -m pip install build pytest "setuptools>=77" wheel
+python -m pytest tests/hermes_adapter -q
+```
+
+The tests build a wheel and a source distribution, rebuild from the source
+distribution, install the wheel outside the checkout, and exercise the actual
+Hermes general and memory loaders. Native-loader tests require Hermes and
+are explicitly skipped when it is absent. No live sidecar, model endpoint,
+production profile, or channel is contacted.
+
+## Shared execution observations
+
+On the qualified Hermes v0.21.0 release (`v2026.8.31`, commit
+`29112bef0992`), set `plugins.colony.execution_registry_enabled: true` to
+publish native turn, API, tool and delegated-child lifecycle observations.
+This is opt-in for existing installations. The adapter credential must already
+have scoped `turns:write` and exact person grants; `context:read` grants access
+to the corresponding view. The legacy global bearer does not attest identities
+for this new surface. To observe trusted agent cron fires, include `cron` in
+the existing `attested_system_platforms` configuration; it is not enabled by
+the adapter's default `cli` binding. No network call is made during registration.
+
+Colony stores only execution IDs, participant/session linkage, channel, phase,
+tool name and observation times in the existing `turn-idempotency.db`. It does
+not copy prompts, tool arguments/results or task descriptions. Each hook has a
+400 ms network deadline and failures do not stop a turn. Ordinary use supplies
+new observations at API/tool boundaries; there is no heartbeat thread. After
+120 seconds without an observation, liveness is **unknown**, including during
+a long model response. A terminal native turn event closes its observation;
+late events cannot reopen it. Metadata older than seven days is hidden from
+the view and removed during subsequent observation writes.
+
+`GET /v1/host/executions?contact_id=<bound-person>&session_id=<session>` returns
+the scoped view with age, coverage and truncation fields. The owner, identified
+by server configuration and an existing exact person grant, can see registered
+turns across sessions. Other people can see only their own selected session;
+public/guest turns receive no automatic registry injection. The owner's normal
+context assembly includes up to eight observations when present.
+
+The native `subagent_start` event binds each executing child to the exact
+observed parent turn. Child observations inherit that participant and cannot
+broaden it. Observation does not grant tool authority; the separate enforcement
+below also works when observation is disabled. No model argument selects the
+writer or owner role.
+
+The view observes running Hermes turns, including agent cron fires and
+executing subagents, and reads claimed/running workers from the canonical task
+queue for the owner. It also reads native cron attempts, including script-only
+jobs, from one explicitly bound Hermes profile. The sidecar uses its private
+local-instance manifest or explicit `HERMES_HOME`; it never scans other profiles
+or assumes a default home. A conflicting binding is unavailable. The existing
+CLI-managed service supplies the same private home automatically.
+
+The cron projection reads `cron/executions.db` without importing or running the
+native scheduler, initializing its schema, or rewriting its status. It returns
+native execution/job IDs, a hashed source-home identity, optional job names,
+record timestamps and claimed/running status, plus a bounded day of recent
+completed/failed/unknown records. Prompts, scripts, output, errors and credentials
+are excluded. No observation writer or polling daemon is added. Native recorded
+running state has **unknown process liveness**, however recent it is. Only
+Hermes can reconcile abandoned attempts; completed records do not prove a
+third-party effect. Guests receive no native cron rows. Missing, incompatible
+or unreadable ledgers are explicitly unavailable, and `complete` is always
+false for the combined work view.
+
+Qualification fires a due native `no_agent` job in a disposable profile with
+`deliver=local`, observes the same execution ID during and after actual script
+completion, and checks the persisted output. This does not depend on an empty
+`enabled_toolsets`, which Hermes treats as its default tool selection. A separate
+installed-wheel test runs actual native parent and child turns with controlled
+inference, reads a neutral local file, delivers the asynchronous completion
+through the native CLI ownership filter, and resumes the parent. A foreign
+session cannot consume that completion; a guest child retains guest tool limits.
+These tests do not contact a model endpoint or a production profile.
+
+The view still does not cover queued children,
+unregistered external coding processes or every hardware service.
+It does not enforce atomic free-text conversational commitments. The optional
+[explicit shared undertaking](COMMITMENT-WORK.md) coordinates work against an
+existing person commitment ID in its durable store. Seeing concurrent work is a prerequisite
+for coordination, not a guarantee that promises cannot conflict.
+
+## Native tool authority
+
+On the qualified Hermes release, the general plugin enforces participant
+authority at native `tool_execution` middleware. Resolved owner turns and
+explicitly configured local system platforms retain native tools and existing
+Hermes toolset, approval and guardrail checks. Guests cannot directly invoke
+shell, files, network, devices, coding, delegation, native memory/session tools,
+or unknown plugin/MCP tools. The exact Colony tools keep their existing scoped
+read checks and action mediators. No arbitrary tool prefix or relationship
+score grants access.
+
+A native-tool request from a guest returns `requires_authorization`, with no
+effect and no approval created. The response directs the agent to an enabled
+Colony action request or the owner. It does not invent an approval request or
+permit a raw tool after conversational consent. Broader guest capabilities
+require a scoped mediated interface; this packet supplies none automatically.
+
+Authority uses the transport-resolved participant bound to the exact native
+session/task/turn, never fields in model arguments. A native child-spawn event
+binds the child to the exact parent's authority. Missing or conflicting parent
+bindings cannot acquire the local CLI system role. Native pre-API callbacks
+retain that binding across compression session rotation. Coding RPC calls use
+Hermes' propagated execution context, without a process-global last-owner or
+task-only lookup. Unavailable identity returns an explicit error because
+Hermes middleware exceptions otherwise fail open. Local trusted CLI remains
+available when contact resolution is offline; remote identity is not guessed.
+
+This is a boundary for model-requested tool dispatch while the general plugin
+is loaded. It does not sandbox trusted installed plugin code, remove private
+facts already present in old transcripts/system prompts, or replace the
+deployment's channel admission, secret isolation and consent policy. Native
+owner tools retain their existing consent behavior; they are not converted to
+Colony intents by this gate. Qualify both owner and guest messages before
+enabling a public channel.
+
+## Native post-turn review
+
+Hermes' automatic review reuses its parent's session ID without emitting a
+subagent-start event. The adapter captures the exact parent participant on the
+native caller thread and accepts inheritance only with Hermes' trusted review
+provenance, matching parent/session, and a distinct task/turn. Later speakers in
+the same session cannot upgrade a queued guest review. Reviews get a separate
+work record linked to their parent, do not replace the session's current speaker,
+and do not write their internal harness into ordinary conversation evidence.
+
+For owner/system reviews, `skill_manage` produces a proposal in Hermes' existing
+`pending/skills` store. Native curator ownership checks still apply. Foreground
+owner requests retain native behavior. The proposal is not an evaluated or
+activated improvement: an explicit operator or a separately configured task
+evaluator must use the native apply path. Mutation history and rollback remain
+in Hermes' skill ledger. No new consent transport or learning store is added.
+
+Installed-wheel qualification runs real native automatic review threads with
+controlled inference for owner and guest, including a later-owner race in the
+guest's session. It checks proposal persistence, exact inherited authority,
+separate work observation, absent harness capture, and explicit native
+apply/ledger rollback. It does not claim measured task improvement from that
+controlled model fixture.
+
+### Measured skill updates
+
+`python -m colony_hermes.review_evaluation --skill NAME --pending ID
+--oracle trusted_local_module:function` evaluates one explicitly selected,
+existing curator-owned `SKILL.md` proposal. It accepts native full-content
+edits or exact text patches, including a one-operation native batch. Text
+patches must match their captured original content without ambiguity unless
+native `replace_all` is explicit. Support-file changes, multiple-operation batches,
+new skills and unrelated proposals stay in Hermes' ordinary pending mechanism.
+The selected local oracle is trusted operator code, not a model tool or a
+model-selected command. It receives the playbook text and a phase and must bound
+its own task execution. It returns explicit case IDs and boolean outcomes.
+
+Baseline and candidate must run the same cases; every candidate case must pass
+and at least one must improve. The adapter records task evidence, the proposal
+hash, oracle identity and before/candidate files in the native skill ledger,
+then calls native apply. It repeats the task after activation, permitting
+additional held-out checks while requiring all original cases. A failed or
+unavailable initial check invokes native rollback. `--audit EVALUATION_ID` repeats
+an existing candidate check later, using the same oracle implementation. Once
+the ledger records a completed activation, an unavailable later audit records
+`unavailable` and retains the last qualified files. A completed task regression
+still invokes native rollback. Infrastructure failure is not a failed task case. This is
+an operator/cron entry point, not an additional background service.
+
+The proposal records its original file hash. A stale proposal or later owner
+edit is held rather than overwritten. A candidate ledger entry is written
+before apply and remains a recovery target if the process exits between apply
+and evaluation; retrying the pending ID resumes its post-check. Rollback checks
+all captured current files against the candidate snapshot first and restores
+only native skill files. It does not rewind memory, permissions or action
+records. These byte checks do not lock editors or foreign processes, so select
+a curator-owned path without another concurrent writer for automatic rollout.
+Native curation usage counters remain native telemetry after file rollback.
+
+Qualification tests exercise real pending files, native curator ownership,
+mutation/rollback and ledger recovery with controlled task outcomes. A selected
+oracle only establishes performance on its declared task cases. No evaluator
+or automatic rollout is enabled by default, and this contract does not qualify
+arbitrary code changes or prove general self-improvement.
+
+A disposable local-inference qualification also exercised an actual native
+review and exact text patch: its declared task scored 0/2 before, 2/2 with the
+candidate, and 2/2 after activation. An injected evaluator outage restored the
+original bytes through native rollback. This was a neutral fixture, not a live
+recurring skill or an observed spontaneous model regression.

colony_hermes-1.0.0/README.md

@@ -0,0 +1,172 @@
+# Colony
+
+Persistent memory and shared work for a personal agent, using your own models.
+
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![CI](https://github.com/Aevonix/ColonyAI/actions/workflows/ci.yml/badge.svg)](https://github.com/Aevonix/ColonyAI/actions/workflows/ci.yml)
+
+Colony runs beside [Hermes](https://github.com/NousResearch/hermes-agent).
+Hermes handles conversations, tools, scheduling and delegation. Colony retains
+what happened, assembles relevant evidence before a turn, and shares commitments
+and work across sessions. Your private deployment supplies its identity,
+credentials, channels and hardware adapters.
+
+Colony 1.0 supports native Hermes attachment, durable source memory, scoped
+recollection and shared work. Optional image and semantic projections, a bounded
+working perspective, and evaluated native skill updates extend that core. These
+paths have executable qualifications; model quality and each deployment's
+configuration still determine their results.
+
+The lightweight installation starts with memory and observation. Extended
+autonomy loops, public channels, voice systems and hardware need explicit
+deployment integration and their own behavioral checks. Version 1.0 does not
+claim complete autonomy, a complete view of every process, or subjective feelings.
+
+## Start with Hermes
+
+The qualified runtime is Hermes 0.21.0. Use its Python interpreter for attachment;
+Python 3.12 is exercised by native integration CI. One local OpenAI-compatible
+chat endpoint is sufficient. The lightweight profile needs no Docker, Neo4j,
+embedding model or external account.
+
+Install from this checkout to use the changes described here:
+
+```bash
+python -m pip install . ./sidecar
+colony init --hermes-python /path/to/hermes/.venv/bin/python
+```
+
+The wizard selects a Hermes home, asks for your name, agent name and model, and
+creates private state outside Git. It preserves existing identity, channels and
+model settings. Replacing an incumbent memory provider is an explicit choice.
+It attaches the canonical installed adapter when its bytes match, or installs
+profile directory adapters when no native package is present. It neither
+patches Hermes core nor restarts an existing gateway.
+
+Accept the wizard's startup option, or run:
+
+```bash
+colony --instance /path/to/private/colony start --detach
+colony --instance /path/to/private/colony status
+```
+
+Start a new Hermes session, give it a harmless fact, then ask for that fact in a
+second session. The [setup guide](docs/LOCAL-HERMES-SETUP.md) explains existing
+profiles, unattended flags, startup and recovery. The minimum profile remembers
+and observes. Consequential background execution requires deliberate setup.
+For login startup and automatic process recovery, stop a detached instance and
+run `colony --instance /path/to/private/colony service install`, then
+`colony --instance /path/to/private/colony service start`. Linux systemd user
+services and macOS LaunchAgents use the selected environment and private state.
+This follows the user session's lifetime, not a guarantee of operation before
+login. See the setup guide for status, stop, uninstall and recovery.
+
+## What the active paths provide
+
+- **Automatic recollection.** The native memory provider requests context for
+  the current participant, session and question before inference. A durable
+  outbox captures ordinary turns; retry does not create another source.
+- **Scoped source recall.** Authenticated participants can recall their own
+  canonical evidence without the legacy graph runtime. Optional semantic
+  projections find retained passages and image descriptions, then resolve them
+  back to current sources before selection. [Source retrieval](docs/SOURCE-SEMANTIC-RECALL.md)
+- **Evidence that outlives a model.** Original messages, timestamps, provenance
+  and derived claims persist independently of inference weights. Corrections
+  and conflicting claims remain inspectable. [Source claims](docs/SOURCE-CLAIMS.md)
+- **Selective factual learning.** One extractor promotes useful, quoted
+  assertions. Routine logs remain source history, without duplicate graph
+  summaries or automatic contact-knowledge guesses. [Memory quality](docs/MEMORY-QUALITY.md)
+- **Images with origins.** Retained image bytes and model-generated descriptions
+  stay distinct. Recollection can include the description and a scoped reference
+  to its source. This does not imply reliable understanding of every image.
+  [Image memory](docs/SOURCE-IMAGES.md)
+- **Shared work.** Sessions can observe commitments and claim work through one
+  persistent registry. Another session sees who holds it. A lease coordinates
+  work; it cannot by itself make an external side effect exactly once.
+  [Commitment work](docs/COMMITMENT-WORK.md)
+- **Replaceable search indexes.** Optional Lance indexes record embedding
+  identity and rebuild into a separate generation. Interrupted rebuilds resume;
+  incompatible or unknown vectors are not compared. Canonical evidence remains
+  available through lexical recall. [Embedding generations](docs/EMBEDDING-GENERATIONS.md)
+- **Source-linked forgetting.** Erasure fences source evidence immediately and
+  removes linked fact, graph and vector projections. Cleanup status is explicit.
+  Unlinked historical records, host transcripts and backups require additional
+  reconciliation. [Derived fact lineage](docs/TOM-SOURCE-LINEAGE.md)
+- **Inspectable priorities.** Source-backed owner corrections and measured
+  outcomes can change optional research ordering. The dated attention snapshot
+  records the evidence and applied weights. This is a bounded working
+  perspective, not a claim of subjective feelings.
+  [Working perspective](docs/WORKING-PERSPECTIVE.md)
+- **Evaluated skill updates.** Native Hermes review can stage a proposal for an
+  existing skill. An explicitly selected task evaluator compares the current
+  skill and candidate, verifies activation and uses native rollback for a
+  measured regression. Deployments supply their own task cases and activation
+  policy. [Native skill review](docs/HERMES-ADAPTER.md#measured-skill-updates)
+- **Source recovery.** Backups capture consistent individual SQLite databases
+  and the original images owned by their source ledger. Restore verifies the
+  captured images and restores SQLite through its backup API. Coverage and
+  cross-store limits are explicit. [Memory recovery](docs/SOURCE-MEMORY-RECOVERY.md)
+
+## Architecture and extension
+
+One sidecar owns canonical state and a bounded context selector. SQLite supports
+the minimum deployment. Neo4j remains the extended deployment's legacy memory
+store; Lance is a replaceable search projection. Legacy graph records are not
+yet fully reconstructible from canonical sources. There is no database service
+per cognitive feature.
+
+The Hermes adapter uses native plugin and memory-provider contracts. Other hosts
+can use the HTTP API, with participant identity supplied by an authenticated
+adapter. Device protocols, continuous audio, camera capture and private identity
+belong in deployment adapters rather than public cognition code.
+
+Named model roles choose eligible local endpoints and fallbacks. Runtime reload,
+configured endpoint advertisements and completion availability let later requests
+follow changed bindings. Changing a processor does not replace the agent's
+memories or identity. Automatic fleet enrollment, capacity scheduling and empirical
+model selection remain separate work.
+[Function routing](docs/FUNCTION-ROUTING.md)
+
+See [architecture and ownership](docs/ARCHITECTURE.md) before adding a component.
+Every addition should close an observable loop, have one state owner, and reuse
+Hermes facilities where they already fit. Self and relationships are explicit
+state, not evidence of subjective feelings. Relationship scores must not grant
+privileged capabilities.
+
+## Operation and limits
+
+Consequential actions need owner authorization. Authorization belongs to the
+work being approved; losing a notification should not discard a build or its
+result. The lightweight installer does not enable external-effect workers.
+Existing extended deployments must inspect their actual resolved configuration
+at `GET /v1/host/autonomy/posture` before enabling another loop.
+
+The [known gaps](docs/KNOWN-GAPS.md) inventory includes legacy components that
+are partial, dormant or awaiting replacement. They are outside the supported
+core until their deployment loops are qualified. Shared observations do not
+prevent every conflicting promise; a selected skill evaluator does not establish
+general self-improvement. Source forgetting does not rewrite arbitrary old
+transcripts, unlinked paraphrases or backups. See the
+[native request boundary](docs/NATIVE-REQUEST-ERASURE.md) for its exact scope.
+
+## Development
+
+Install the sidecar development dependencies, then run its tests from `sidecar`:
+
+```bash
+python -m pip install -e './sidecar[dev]'
+cd sidecar
+python -m pytest -q tests colony_sidecar
+```
+
+`tests/hermes_adapter` qualifies built packages against the pinned native
+Hermes runtime. Its controlled model fixture verifies integration, not model
+quality. Deployment acceptance also needs real inference, source receipts,
+cross-session behavior and recovery with the actual configuration.
+
+Keep personal data, endpoint coordinates, secrets and deployment configuration
+out of public examples, commits and test artifacts.
+
+## License
+
+[MIT](LICENSE). Optional dependencies retain their own licenses.