Djinn

Djinn

> An @enchanter-ai product — algorithm-driven, agent-managed, self-learning.

Pins the original session intent, watches for long-horizon drift across /compact, and reasserts the goal when the agent diverges.

6 sub-plugins. 5 engines. 3 agents. 2 slash commands. Out-of-context anchor. One install.

> Turn 1, the developer says: "Add dark-mode support with a11y keyboard-trap tests." D1 Hunt-Szymanski LCS normalizes that into 9 anchor tokens and hashes them into state/anchor.json. Turns 2–37, D3 Vitter reservoir samples 32 turn-scores uniformly; D2 Baum-Welch HMM labels each turn ON_TASK / SIDEQUEST / LOST. Turn 38, /compact fires — compact-guard injects the anchor as a structural hint before the compaction model sees the context. Post-compact, the agent goes sideways into an unrelated toast notifier. Turn 41, drift-aligner's bootstrap 95% CI drops to (0.48, 0.41–0.55, N=32). stderr emits [Djinn] drift: preservation=0.48 (95% CI 0.41-0.55, N=32) kind=side_quest anchor=feature. Developer sees it, says "right, back to a11y." One line of stderr; zero token cost in-context; anchor never left state. > > Time: structurally guaranteed, zero per-turn LLM calls on the critical path. Developer effort: read one advisory.

TL;DR

In plain English: You asked for dark mode. Forty turns later the agent is confidently wiring up a toast notifier. Djinn flags the exact turn the session went sideways.

Technically: D1 Hunt-Szymanski LCS captures first-turn intent as a token-anchor persisted to state/anchor.json; D2 Baum-Welch HMM labels each subsequent turn ON_TASK / SIDEQUEST / LOST against that anchor; D3 Vitter reservoir keeps a bounded k=32 sample for D4 PageRank ranking and D5 Gauss posterior calibration. Every advisory carries (preservation_score, ci_low, ci_high, N) from a 1000-iteration non-parametric bootstrap — no N means no advisory.

---

Origin

Djinn takes its name from Ars Nouveau — a fey familiar bound to a Djinn Charm anchor that collects every drop from nearby mobs back to that fixed point, never wandering from it. That is literally the function of this plugin: bind the original session intent as an anchor, collect every agent turn's alignment signal back to that anchor, and reassert the bound goal the moment the agent drifts away from it.

The question this plugin answers: Am I still working on what you asked?

Who this is for

• Developers running multi-hour Claude Code sessions that cross /compact. The first-turn goal silently drops out of the middle of the context; Djinn keeps it pinned.
• Teams auditing whether an agent did the work that was requested, not merely work the agent was confident about.
• Anyone whose workflow has surfaced an agent that "fixed" a problem by changing something adjacent to the actual bug.

Not for:

• Single-turn prompts. If the session is short enough that drift cannot happen, Djinn is overhead.
• Token-level drift (read-loops, edit-reverts). That is Emu's territory — Djinn and Emu measure orthogonal signals and must not be merged.

Contents

• [How It Works](#how-it-works)
• [What Makes Djinn Different](#what-makes-djinn-different)
• [The Full Lifecycle](#the-full-lifecycle)
• [Install](#install)
• [Quickstart](#quickstart)
• [6 Sub-Plugins, 3 Agents, 5 Engines](#6-sub-plugins-3-agents-5-engines)
• [What You Get Per Session](#what-you-get-per-session)
• [Roadmap](#roadmap)
• [The Science Behind Djinn](#the-science-behind-djinn)
• [vs Everything Else](#vs-everything-else)
• [Agent Conduct (12 Modules)](#agent-conduct-12-modules)
• [Architecture](#architecture)
• [Acknowledgments](#acknowledgments)
• [Versioning & release cadence](#versioning--release-cadence)
• [Contributing](#contributing)
• [Citation](#citation)
• [License](#license)

How It Works

Djinn runs a five-engine pipeline that treats intent preservation as out-of-context anchoring → deterministic per-turn scoring → structurally-guaranteed compaction survival → cross-session Bayesian calibration. The premise: every production approach to LLM intent preservation has a documented failure mode, and each one shares a common shape — putting the anchor in-context or asking the agent to self-report.

Source: [docs/assets/pipeline.mmd](docs/assets/pipeline.mmd) · Regeneration command in [docs/assets/README.md](docs/assets/README.md).

1. Anchor lives out-of-context. intent-anchor writes the first-turn goal to state/anchor.json on SessionStart. It is never re-echoed into the prompt mid-session; mid-context repetition lives in the recall valley (Liu et al. "Lost in the Middle", NAACL 2024) and buys zero recall.
2. Deterministic per-turn measurement. drift-aligner runs D1 Hunt-Szymanski LCS + D2 Baum-Welch HMM + D3 Vitter reservoir on every PostToolUse. No LLM judgment is in the measurement path. A drifted agent confidently self-reports as on-task (Shinn et al. Reflexion 2023); deterministic compute is the only honest signal.
3. Structural compaction survival. compact-guard injects the anchor as a hint before the compaction model runs. Survival is not up to the compactor's recency bias — it is structurally guaranteed by the hook lifecycle.
4. Cross-session calibration. drift-learning folds each completed session's summary statistics into a per-(intent-type × developer) drift-signature posterior via D5 Gauss Accumulation. A "research" session earns a wider tolerated drift band than a "bugfix" session.
5. Honest-numbers advisories. Every advisory carries (preservation_score, ci_low, ci_high, N) from a non-parametric bootstrap over the D3 reservoir. No N → no advisory. The Haiku validator enforces the tuple shape.

What Makes Djinn Different

Anchor is structural state, not in-context text

LangChain ConversationBufferMemory drops old turns including the first-turn goal. Manual CoT goal-repetition places reminders into the recall valley. Djinn's anchor is a file on disk, hashed at SessionStart, reinjected exactly once at PreCompact. Compaction cannot silently drop it; repetition cannot fall into mid-context noise.

Measurement is deterministic

ReAct and Reflexion ask the suspect. GPT-as-judge / Claude-as-judge single-model pipelines agree with the agent because of shared priors, not truth. Djinn's D1 LCS, D2 HMM, D3 reservoir, D4 PageRank, and D5 EMA are all deterministic stdlib-only compute. LLM judgment is isolated to the orchestrator Opus agent's final advisory verdict — never in the scoring path.

DAG edges are provable, not inferred

LlamaIndex / LangChain vector-RAG over history retrieves similar turns, which is not intent-preserving turns. Two drifted agents can mutually retrieve each other's drift as "relevant context". D4 PageRank ranks by DEMONSTRATED influence on output — DAG edges are file-touch overlaps, not cosine similarity.

Honest numbers, or no numbers

Every drift advisory carries (preservation_score, ci_low, ci_high, N) from a 1000-iteration bootstrap. If `N = 5">

Orthogonal to Emu, not overlapping

Emu measures token economy drift (A1 Markov on tool patterns — read-loops, edit-reverts). Djinn measures semantic intent drift (D1 LCS on goal-tokens). A session can have a green Markov state and ample token runway while having silently redirected to a task the user never asked for. The two signals are orthogonal; subscribing to emu.checkpoint.saved enriches Djinn's signal but does not replace it.

The Full Lifecycle

A session flows top-to-bottom through four hook phases plus two developer-invoked skills.

Source: [docs/assets/lifecycle.mmd](docs/assets/lifecycle.mmd) · Regeneration command in [docs/assets/README.md](docs/assets/README.md).

| Phase | Event | Sub-plugin | Engines | Output | |-------|-------|------------|---------|--------| | Capture | SessionStart | intent-anchor | D1 + D3 | state/anchor.json; djinn.intent.captured | | Refresh | UserPromptSubmit | intent-anchor | D1 | appended refresh_delta; djinn.intent.refreshed | | Align | PostToolUse | drift-aligner | D1 + D2 + D3 | state/reservoir.json, state/states.jsonl; djinn.drift.detected | | Guard | PreCompact | compact-guard | D1 | stdout hint injection; djinn.compact.intent-hint.injected | | Learn | PreCompact | drift-learning | D5 | state/posteriors.json, state/learnings.jsonl | | Audit | /rank | utterance-rank | D4 | PageRank of utterance DAG | | Re-pin | /reorient | intent-reorient | — | fresh anchor, archived old anchor |

Every phase is advisory-only and fail-open. No phase blocks tool completion or model inference.

Install

Djinn ships as a 7-plugin marketplace (6 sub-plugins + 1 meta). The full meta-plugin lists all six as dependencies, so a single install pulls in the whole pipeline.

In Claude Code (recommended):

/plugin marketplace add enchanter-ai/djinn
/plugin install full@djinn

Claude Code resolves the dependency list and installs all 6 sub-plugins. Verify with /plugin list.

Cherry-pick individual sub-plugins if you only want part of the pipeline — e.g. /plugin install intent-anchor@djinn captures the anchor without running per-turn alignment. Missing-engine degradation is graceful: drift-aligner is a no-op without an anchor, compact-guard is a no-op without an anchor, drift-learning is a no-op without a reservoir.

Quickstart

git clone https://github.com/enchanter-ai/djinn
cd djinn
./scripts/bootstrap.sh    # canonical first command — installs vis sibling

Without ./scripts/bootstrap.sh, conduct imports will silently miss and Claude Code's @-loader will fail-soft. Always bootstrap first.

6 Sub-Plugins, 3 Agents, 5 Engines

| Sub-plugin | Owns | Trigger | Agent | |------------|------|---------|-------| | [intent-anchor](plugins/intent-anchor/) | D1 + D3 anchor capture | hook-driven (SessionStart + UserPromptSubmit) | — | | [drift-aligner](plugins/drift-aligner/) | D1 + D2 + D3 per-turn alignment | hook-driven (PostToolUse) | aligner (Haiku), topic-tagger (Sonnet) | | [compact-guard](plugins/compact-guard/) | D1 intent-hint injection | hook-driven (PreCompact) | — | | [utterance-rank](plugins/utterance-rank/) | D4 PageRank | skill-invoked (/rank) | — | | [drift-learning](plugins/drift-learning/) | D5 Gauss Accumulation | hook-driven (PreCompact) | — | | [intent-reorient](plugins/intent-reorient/) | manual re-pin + Opus orchestrator | skill-invoked (/reorient) | orchestrator (Opus) |

Plus full/ — the meta-plugin dependency manifest that pulls all six in via one install.

Slash commands:

| Command | Function | Agent tier | |---------|----------|------------| | /rank | On-demand PageRank over the session utterance DAG | — (deterministic) | | /reorient | Manual override of the session anchor | Opus (orchestrator) |

What You Get Per Session

Every PostToolUse feeds three state files (reservoir, states log, posterior book); PreCompact folds a session summary into the cross-session posterior. All writes go through the atomic shared/scripts/state_io.atomic_write_json helper.

Source: [docs/assets/state-flow.mmd](docs/assets/state-flow.mmd) · Regeneration command in [docs/assets/README.md](docs/assets/README.md).

plugins/intent-anchor/state/
└── anchor.json                session-intent anchor + refresh_deltas (captured once per session)

plugins/drift-aligner/state/
├── reservoir.json             Vitter Algorithm R bounded-memory sample (k=32) of turn-score records
└── states.jsonl               append-only HMM observation log (tool, topic, score per turn)

plugins/drift-learning/state/
├── posteriors.json            per-(intent-type × developer) drift-signature posterior (D5 EMA)
└── learnings.jsonl            per-session append-only summary (backtesting source)

plugins/utterance-rank/state/
└── last-rank.json             most recent /rank output

plugins/intent-reorient/state/
└── archive/                   archived anchors from prior /reorient invocations

Events published on the djinn.* namespace (Phase-1 file-tail fallback via shared publish.py):

• djinn.intent.captured — {session_id, anchor_text, anchor_hash, intent_type, captured_at}
• djinn.drift.detected — {session_id, preservation_score, ci_low, ci_high, N, turn, drift_kind}
• djinn.compact.intent-hint.injected — {session_id, hint_text, anchor_hash, pre_compact_turn_count}
• djinn.intent.refreshed — {session_id, new_anchor_delta, turn}

Optional subscriptions (Phase-2 enrichment): emu.checkpoint.saved, crow.change.classified.

Roadmap

Tracked in [docs/ROADMAP.md](docs/ROADMAP.md) and the shared [ecosystem map](docs/ecosystem.md). For upcoming work specific to Djinn, see issues tagged roadmap.

The Science Behind Djinn

Full derivations live in [docs/science/README.md](docs/science/README.md). Each engine cites its founding paper in its docstring.

| ID | Engine | Reference | |----|--------|-----------| | D1 | Hunt-Szymanski LCS Alignment | Hunt J.W. and Szymanski T.G. (1977), "A fast algorithm for computing longest common subsequences", CACM 20(5):350-353 | | D2 | Baum-Welch HMM Task-Boundary Inference | Baum L.E. and Welch L. (1970), "An inequality and associated maximization technique in statistical estimation for probabilistic functions of Markov processes" | | D3 | Vitter Reservoir Sampling — Algorithm R | Vitter J.S. (1985), "Random sampling with a reservoir", TOMS 11(1):37-57 | | D4 | PageRank Utterance-DAG Ranking | Brin S. and Page L. (1998), "The anatomy of a large-scale hypertextual Web search engine", Stanford InfoLab | | D5 | Gauss Accumulation — Intent-Type Drift Signature | Gauss C.F. (1809), Theoria Motus Corporum Coelestium |

vs Everything Else

| Approach | Failure mode in production | Djinn counter | |---|---|---| | LangChain ConversationBufferMemory / LlamaIndex memory | Drops old turns; first-turn goal is mid-context by turn 40 and silently falls into the recall valley | Anchor is out-of-context state; survives arbitrary compaction | | LangChain summary memory | Summarization is lossy; detail-specific intent ("with a11y attrs") rarely survives many rounds | D1 LCS operates on the ORIGINAL anchor, never a summary | | LlamaIndex retrievers / vector-RAG over history | Retrieves similar turns, not relevant-to-original-intent turns — agents can retrieve each other's drift | D4 PageRank on file-touch DAG — edges are provable, not inferred | | Manual CoT goal-repetition | Mid-context reminders live in the recall valley; cost tokens, buy zero reliable preservation | Anchor reinjected ONLY at PreCompact, structurally anchored to the forgetting moment | | OpenAI Custom GPTs / system-prompt pinning | Rigid — doesn't absorb constraint deltas the developer adds mid-session | UserPromptSubmit appends deltas with a drift_kind label; never replaces | | Claude Code /compact / ChatGPT auto-summary | Compactor recency-weights; first-turn goal silently drops; 10–20% session-abandonment correlates | compact-guard injects anchor BEFORE compactor runs — survival is lifecycle-guaranteed | | ReAct / Reflexion / solo self-critique | Drifted agent confidently self-reports as on-task | Djinn never asks the agent; deterministic D1+D2+D4+D5 only | | BabyAGI / AutoGPT / MetaGPT planning | Plan drifts from goal independently; compounds | Djinn doesn't plan. It anchors and measures. | | GPT-4-as-judge / Claude-as-judge single-model | Single-family judge correlates with single-family agent via shared priors, not truth | LLM judgment isolated to the Opus orchestrator's final verdict — never in the scoring path | | Emu (sibling) misused as intent-preservation | A1 Markov catches token-level drift; session can be green on tool patterns and silently redirected | Djinn measures semantic intent — orthogonal signal, coexists with Emu |

Agent Conduct (12

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: enchanter-ai
• Source: enchanter-ai/djinn
• License: MIT

Install and usage instructions live in the source repository linked above.