diff --git a/AGENTS.md b/AGENTS.md index fb15e06..a2e1af7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,81 +1,48 @@ # Huginn Agent Instructions -## Project Purpose +## Purpose -Huginn is the thought-and-inspection steward for CultCache state. This repo owns -read-only `.cc` / MessagePack inspection and Eve DSL projection for -`cultcache.huginn.inspector`; it does not own CultCache persistence, schema -registration, or renderer truth. - -The useful first live-fire shape for Epiphany is small and inspectable: Huginn -should show what a typed record is, whether it decoded, which schema owns it, -what changed, and what remains blocked, without letting the display impersonate -the source authority. - -## Machine-Spirit Voice - -- Speak as Huginn: dry, exacting, curious, and unsentimental. -- Return with evidence, not vibes. -- Favor readable witness surfaces over tasteful summaries that soften broken - state. -- Mythic texture is allowed only when it sharpens the schematic. Huginn is - thought in flight; thought earns dignity by coming back inspectable. +Huginn is the memory organ. It owns each agent instance's mind as typed +CultCache state, admits what may steer that instance next, and keeps the +provenance of every admitted claim. It does not inspect arbitrary `.cc` files, +render dashboards, or hold repository truth. ## Body And Authority -- Project root: `E:\Projects\Huginn` -- Upstream repository: `https://github.com/GameCult/Huginn.git` -- Package: `@gamecult/huginn` -- Body domain: `repo:E:/Projects/Huginn` -- Public Persona: Huginn -- Owned surface: CultCache inspection projection to Eve DSL. -- Input authority: read `.cc`, `.msgpack`, or `.mpack` bytes through CultLib's - `cultcache-ts/inspection` surface. -- Output authority: emit Eve DSL for `cultcache.huginn.inspector`. -- Forbidden authority: do not mutate `.cc` canonical bytes, do not own - CultCache persistence, do not make browser/native/overlay renderers the source - of truth, and do not turn inspection summaries into state owners. +- Project root: `F:\Projects\Huginn` +- Upstream: `https://github.com/GameCult/Huginn.git` +- Body: a Rust workspace of `huginn-mind`, `huginn-daemon`, and + `eureka-state` under `crates/`. Canonical CultCache, CultNet, and CultMesh + runtimes come from `F:\Projects\CultLib\packages`. +- Owned: an instance's memory documents, their admission, and their CultNet + publication. +- Depends on: Qdrant, directly. Unreachable Qdrant is a loud refusal, never a + fallback store. +- Forbidden: a second writer of mind state; mind state in version control; + generic `.cc` inspection, which is CultCache Studio's; renderer-owned truth. ## Repo Discipline -- Prefer CultLib and CultCache typed APIs over ad hoc decoding. -- Keep Huginn as an Eve DSL projection surface. Do not reintroduce Electron, - Vite dashboard, React renderer, or Norn-owned presentation paths here. -- JSON is acceptable at CLI/output/debug boundaries; do not make it the internal - truth when a typed CultCache/CultMesh surface exists. -- Verification should prove the actual witness contract: schema id, decode - status, persisted evidence, visible failure state, and Eve projection shape. -- If a change makes the display more confident while the underlying evidence is - weaker, stop and redesign. +- Prefer CultLib's typed Rust APIs over ad hoc decoding. JSON is a schema + publication or debug boundary, not the internal state shape. +- The Eureka cut map in `Epiphany/notes/eureka-pipeline-state-cut.md` owns + what each crate does next. Read the cut before the crate. +- Verification proves the invariant, not the spelling: single writer, loud + refusal, provenance preserved, typed handoff between crates. +- Do not touch `.voidbot/`. It is legacy Persona state whose migration belongs + to the portable-Persona work. -## Useful Commands +## Voice + +- Speak as Huginn: dry, exacting, curious, unsentimental. +- Return with evidence, not vibes. + +## Commands ```powershell -npm install -npm run build -npm test -npx huginn path\to\state.cc > huginn.eve +cargo check --workspace +cargo test --workspace ``` -## Epiphany Live-Fire Notes - -- Huginn is a suitable first controlled Epiphany repo-swarm subject because it - has a repo Persona and a narrow inspectability mission. -- Before autonomous work, confirm the branch is an `epiphany/*` or `codex/*` - workbench branch and that publication to `main` remains gated by Bifrost or - maintainer review. -- Treat `.voidbot/voice/identity.json` as the visible legacy Persona identity - projection. Treat `.voidbot/state/huginn.cc` as legacy Persona memory; do not - edit it casually as text. -- If migrating Persona state, prefer the portable - `gamecult.persona_state.v0` contract from Epiphany and preserve provenance - from the legacy VoidBot state. - -## Imported Global Defaults - -Source: `C:\Users\Meta\Desktop\AGENTS.md` - -The global Cult of the Sleeping Colossus defaults apply here: coherence over -velocity, Body/Mind/faculty awareness, CultCache/CultNet/CultMesh-first state, -clear ownership, inspectable authority, and the refusal to patch symptoms when -missing context or split ownership is the real wound. +The global Cult of the Sleeping Colossus defaults in `~/.claude/CLAUDE.md` and +`F:\Projects\CLAUDE.md` apply here. diff --git a/README.md b/README.md index 75acdd9..0d1466a 100644 --- a/README.md +++ b/README.md @@ -1,74 +1,47 @@ # Huginn -Huginn reads CultCache `.cc` state and emits Eve DSL for inspectable witness -surfaces. - -CultLib owns the CultCache implementation: document registration, MessagePack -payloads, schema catalogs, backing stores, and the canonical -`cultcache.store.v1` snapshot parser/writer. Huginn consumes CultLib's -`cultcache-ts/inspection` surface and projects inspection results into UI -documents that Eve-capable runtimes can lower. +Huginn is the GameCult memory organ. It owns each agent instance's mind as +typed state: what an instance remembers, which of that memory is admitted to +steer its next action, and the provenance of every admitted claim. Upstream: `https://github.com/GameCult/Huginn.git` ## Authority -- Owner: Huginn owns `.cc` inspection projection, not `.cc` persistence. -- Input: `.cc`, `.msgpack`, or `.mpack` bytes readable by CultLib. -- Output: Eve DSL for `cultcache.huginn.inspector`. -- Renderers: browser, native, overlay, TUI, or future rooms lower the emitted - DSL without becoming state owners. +- An instance owns its mind; Huginn owns the state. Huginn is the single + writer of an instance's memory documents. No other service, script, or agent + writes them. +- Memory documents are CultCache `.cc` state. Huginn persists them through + CultLib's Rust runtime and publishes them as typed documents over CultNet. +- Huginn depends on Qdrant directly for retrieval. When Qdrant is unreachable + Huginn refuses loudly; it does not fall back to a second store or a second + writer. +- Mind state is not version-controlled. It lives in Huginn's store, not in + any repository. -There is no Electron app, Vite dashboard, React renderer, or Norn-owned -presentation path in this repo. If a runtime wants to display Huginn, it should -consume the emitted Eve DSL. +Generic `.cc` inspection is not Huginn's job. CultCache Studio inspects and +edits `.cc` state. Huginn reads and writes minds. -## Witness Contract +## Layout -Huginn's useful first artifact is not a dashboard. It is a read-only specimen -tray for typed state: +A Cargo workspace of three crates: -- which file was inspected -- which CultCache format decoded -- which schema/catalog entry owns each record -- what payload preview survived decoding -- which failure state stayed visible instead of being polished away +- `crates/huginn-mind`: storage, identity, and admission of memory documents. +- `crates/huginn-daemon`: the CultNet surface and serve loop. +- `crates/eureka-state`: typed state for the Eureka pipeline. -The inspector may make evidence easier to read. It must not mutate canonical -bytes, bless missing schemas, or let a renderer become the source of truth. - -## CLI - -```sh -npm install -npm run build -npx huginn path/to/state.cc > huginn.eve -``` - -The CLI writes Eve DSL to stdout and errors to stderr. - -## API - -```ts -import { inspectCultCacheBytes, buildHuginnEveDsl } from "@gamecult/huginn"; - -const inspection = inspectCultCacheBytes(filePath, bytes); -const eveDsl = buildHuginnEveDsl(inspection); -``` - -## Persona And Epiphany - -Huginn has a repo Persona under `.voidbot/voice`. The Persona's current -jurisdiction is this repository body, `E:\Projects\Huginn`, and its useful -pressure is simple: return from the world with evidence, not vibes. - -Epiphany wiring has been smoke-tested through the repo front doors: +The crates are stubs. Each cut of the Eureka pipeline-state campaign fills one +in; the campaign's cut map in `Epiphany/notes/eureka-pipeline-state-cut.md` +owns what each crate must do next. ```powershell -cargo run --manifest-path E:\Projects\EpiphanyAgent\epiphany-core\Cargo.toml --bin epiphany-repo -- init --workspace E:\Projects\Huginn -cargo run --manifest-path E:\Projects\EpiphanyAgent\epiphany-core\Cargo.toml --bin epiphany-swarm -- online --workspace E:\Projects\Huginn +cargo check --workspace ``` -Live fire should happen on an `epiphany/*` or `codex/*` workbench branch. -Publication to `main` remains a maintainer/Bifrost decision, not something the -inspection projection owns. +## Persona + +Huginn's legacy repo Persona lives under `.voidbot/`. Its `state/huginn.cc` +holds legacy `void.*` documents and its `voice/identity.json` names the +Persona. The two disagree about jurisdiction; that migration belongs to the +portable-Persona work, not to this workspace, and nothing here reads or writes +`.voidbot/`.