GameCult/Huginn
Watch
9
0
Fork
You've already forked Huginn
 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

Describe Huginn as the memory organ

Browse source 
README and AGENTS now state what Huginn is: the single writer of each
instance's mind as typed CultCache state, published over CultNet, depending
on Qdrant directly and refusing loudly without it. Generic .cc inspection is
CultCache Studio's. The docs name the Rust workspace, the F: drive body, and
the cut map that owns what each crate does next.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-09-16 15:12:18 +02:00
commit e20c786c96
2 changed files with 65 additions and 125 deletions
Download patch file Download diff file Expand all files Collapse all files

101
AGENTS.md
View file

@ -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.

89
README.md
View file

@ -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/`.