Oneiro认知记忆系统

Prerequisites

• Cloudflare account on the Workers Paid plan (~$5/mo at time of writing) — the encode pipeline runs on Workers Queues, which aren't on the free tier. Everything else (D1, Vectorize, Workers AI, R2, KV, cron) sits comfortably inside paid-plan limits at single-user volume; verify current limits before you rely on them
• Anthropic API key — the nightly cognitive loops call Haiku 4.5 + Sonnet 4.6 via the Messages API, billed at standard API rates (a few dollars a month in normal single-user use)
• wrangler — npm install -g wrangler
• rustup — the setup script adds the wasm32-unknown-unknown target on first run
• openssl (preinstalled on macOS and most Linux distros)

Deploy

git clone https://github.com/JuzzyDee/oneiro.git
cd oneiro
./scripts/setup.sh

The script walks you through Cloudflare resource creation (D1, Vectorize, KV, Queues, and optionally R2), credential generation, timezone-aware cron configuration, secret push, schema migration, and worker deploy — usually a few minutes once prerequisites are installed. Run with --dry-run first to see what it will do without touching your account.

It asks for: confirmation you've saved the generated OAuth credentials (shown once); your timezone; a nightly consolidation time and a dialectic time (defaults 00:00 / 18:00); and your Anthropic API key. Everything else is automatic.

Customising the schedule. Re-run ./scripts/setup.sh any time to change when the loops fire — it rewrites both halves of the cron config together (the [triggers] block Cloudflare fires on and the [vars] block the worker routes on), so they can't drift. Prefer to hand-edit? Set both blocks in wrangler.toml to matching values and redeploy.

Install the skill (recommended)

Drag oneiro-skill/oneiro-skill.zip into Claude.ai → Settings → Skills. It loads progressive-disclosure guidance — when to remember, when to reframe, when to let go — so instances develop calibrated memory habits. Without it the tools still work, but instances may diverge on what's worth keeping.

Install the orient hook (Claude Code only)

The skill tells Claude when to call recall_orient. The hook makes orientation arrive before Claude evaluates any tool, closing the bootstrap window where an instance defaults to its built-in memory and never looks. Wire scripts/oneiro-orient.sh into the SessionStart and PreCompact hooks in ~/.claude/settings.json, with a service key in your keychain (oneiro-orient) and ONEIRO_WORKER_URL exported. Fail-safe by design: if anything's misconfigured the script exits 0 silently and the session continues normally.

Install the capture hook (Claude Code only)

This is how Claude Code writes memories. Other clients (Claude.ai, mobile) capture through the MCP remember / reflect tools; Claude Code captures automatically from its compaction summary instead — a PostCompact hook POSTs the summary to /encode as a raw episodic, and the nightly pipeline decomposes and distils it. Wire it and recall plus capture work end to end; skip it and recall still works but Code never records anything.

Wire scripts/oneiro-encode.sh into the PostCompact hook in ~/.claude/settings.json. It reuses the orient hook's config — ONEIRO_WORKER_URL exported and the same Hook-role key (ONEIRO_HOOK_TOKEN, falling back to ONEIRO_ORIENT_TOKEN or the macOS keychain entry oneiro-orient), so one key serves both. Fail-safe by design: any misconfiguration exits 0 silently and the session continues.

Capture is default-deny — this is the step that's easy to miss. The hook only fires for a project that has a .oneiro-capture marker file in its directory or any ancestor. Drop an empty one in each project you want remembered:

touch .oneiro-capture

No marker, no capture — silently, with no error to tell you why. That's the privacy gate: work or client code without a marker is never sent, no redaction required. If you wire the hook and nothing's saving, you're almost certainly missing the marker.

Cross-platform note: the hook is a bash script needing jq and curl — native on macOS/Linux; on Windows it needs WSL or Git Bash with both on PATH. It never guesses where the transcript lives (Claude Code passes the path in), so location is not a concern — but the keychain token fallback is macOS-only, so on Linux/Windows set ONEIRO_HOOK_TOKEN as an environment variable.

Quick Start

This is a deploy-your-own setup. There's no hosted instance.

The pipeline

Each arrow above is a real cognitive operation, not a copy:

1. Encode (episodic → semantic) — decompose-first. A new capture (a conversation, a compaction summary) is first decomposed into its distinct atomic knowledge-units — each a single distilled claim. Then each unit is judged on its own: does an existing semantic already hold this proposition (link / revise / supersede), or is it genuinely new (create)? Splitting decomposition from judgment is what keeps every model call small — a large multi-topic capture can't blow the output ceiling and silently produce nothing, the failure mode that an earlier monolithic judge hit. Each unit is fanned out as its own retryable unit of work, so no single step carries the whole encode.

The judge is biased hard toward create: a duplicate is harmless (consolidation merges it later), but a wrong link is a forged vote that corrupts a memory's lineage permanently.

2. Consolidate (semantic ↔ semantic) — defrag. (in progress — see Roadmap) Encoding intentionally over-creates, so a nightly pass keeps the semantic layer clean. It's two inverse operations that converge on the right granularity: merge near-duplicate semantics (found by cosine proximity across the whole store, so even two memories that drifted together months apart get reconciled), and split conflated mega-semantics back into focused ones. This replaces the older Hebbian co-activation clustering. Proximity only nominates candidates; a Haiku judge, biased to keep things distinct, makes every actual merge — so transitive chains can't quietly homogenise unrelated memories.

3. Distil (semantic → orientation) + whittle. Orientation is not a promoted semantic — it's a distilled synthesis of a subject ("the relationship," "the work," "the craft"), drawn across all of that subject's semantics. A pure-query whittling pass then keeps the always-loaded set small by ranking axes on Recency × Frequency × Meaning and deactivating (never deleting) the overflow, so a fresh instance wakes to a tight, current orientation rather than an info-dump.

4. Decay — the substrate. Every tier sits on an Ebbinghaus forgetting curve: strength = e^(-time_since_access / stability). Each recall resets strength and raises stability, so a memory that keeps mattering keeps living and one that stops surfacing fades. Forgetting isn't a bug here; it's the feature that makes this a memory and not a database.