Skip to content

self-coherence.md

Latest commit

 

History

History
118 lines (95 loc) · 4.72 KB

self-coherence.md

File metadata and controls

118 lines (95 loc) · 4.72 KB

HME

Hypermeta Ecstasy is the repo's self-coherence substrate. It wraps agent workflows with a proxy, event kernel, lifecycle hooks, KB retrieval, verifiers, metrics, and a small i/ command surface.

Read this before changing tools/HME/. Use self-coherence-full.md for the full architecture, event-kernel contract, state ownership registry, LIFESAVER rules, RAG stack, local LLM notes, and testing runbook.

What It Owns

  • Proxy: Claude/Anthropic and Codex/Responses middleware in tools/HME/proxy/.
  • Event kernel: portable lifecycle/tool dispatcher in tools/HME/event_kernel/.
  • Hooks: Claude Code and Codex lifecycle entrypoints in tools/HME/hooks/, routed through the event kernel.
  • Worker and tools: HME service in tools/HME/service/ and i/ wrappers in tools/HME/i/.
  • KB: Lance-backed knowledge in tools/HME/KB/.
  • Coherence: HCI verifiers, invariants, activity logs, and holograph snapshots under tools/HME/scripts/ and HME runtime metrics. Project artifacts are discovered through config/project-adapter.json.

Project Adapter

HME core is project-agnostic. Project facts live in config/project-adapter.json: source roots, project docs, pipeline commands, artifacts, optional capabilities, and health expectations. HME runtime metrics stay under tools/HME/runtime/metrics; project artifacts stay adapter-scoped. Project KB entries receive a project:<id> tag from the adapter.

For a new project, replace src/ and doc/composition.md, then run:

tools/HME/scripts/init-project-profile.js --name="My Project"
tools/HME/scripts/hme-doctor.py --portable

Logical i/<tool> commands remain stable. Physical shims live in tools/HME/i/; shell/proxy setup makes i/status, i/review, and related commands invocable without a root i/ directory.

Current Command Surface

Use native Read/Edit/Grep/Glob first; proxy middleware enriches or replaces those where HME needs to participate. Todos live in doc/templates/TODO.md -- a single status-code line grammar (see its header) that the agent edits directly; tools/HME/todo_engine applies timed status flips and archives fully-resolved sets to log/todo/. Use i/ commands for explicit HME workflows:

i/hme admin action=selftest
i/review mode=forget
i/learn query="coupling"
i/learn title="..." content="..." category=pattern
i/trace target=<module> mode=impact
i/status state
i/status timeline window=30m
i/why mode=block
i/policies list

Commands that only duplicated automatic native-tool enrichment have been retired. Do not add an i/ wrapper unless the user or agent needs to invoke the behavior deliberately.

Working Loop

  1. Check state with i/status state when context is unclear.
  2. Edit through native tools; HME enriches reads and edits automatically.
  3. Run i/review mode=forget after meaningful changes.
  4. Run the project pipeline when code behavior changed.
  5. Persist confirmed learning with i/learn.
  6. Run i/hme admin action=selftest after HME substrate changes.

If hooks, statusline, or autocommit look stale, run:

tools/HME/scripts/hme-doctor.py --hooks
tools/HME/scripts/sync-codex-settings.py

Codex hooks installed through ~/.codex/hooks.json are user hooks. If Codex reports that they need review, open /hooks once in the interactive CLI; the hme_codex provider proxy remains active for Codex traffic either way. sync-codex-settings.py also generates tools/HME/runtime/codex-model-catalog.json, points Codex at it with model_catalog_json, and sets model_context_window = 1050000. The generated catalog replaces Codex model base_instructions and model_messages.instructions_template with doc/templates/canonical-system-prompt.md, replaces personality_pragmatic with doc/templates/AGENTS.md, and sets every model context_window/max_context_window to 1050000.

Hard Style

  • Single source of truth first. If a string, route, rule, or tool invocation is repeated, consolidate it before expanding it.
  • Fail fast. Silent fallback is a bug unless the caller explicitly accepts best-effort behavior.
  • Hooks are host adapters, not business logic. Shared behavior belongs in the event kernel, proxy middleware, policies, or service modules.
  • Hook background work must detach stdio via _hme_bg*; lifecycle adapter starts/ends are mirrored by event_kernel/hook_watchdog.js.
  • Filesystem state must have an owner. Update state-files.json before adding a shared state writer.

Fast Links