@connorhatcher/obversational-memory

Core Observational Memory package for both stateful and stateless host integrations.

Two Integration Paths

Stateful

Use ObservationalMemory when OM should own storage-backed lifecycle orchestration.

import { ObservationalMemory } from '@connorhatcher/obversational-memory'

Stateless

Use runCompactionCycle when your host runtime already controls session lifecycle and just needs OM extraction + reflection.

import { runCompactionCycle } from '@connorhatcher/obversational-memory'

Delegate LLM Pattern

Wrap host SDK callbacks with DelegateLLMClient:

import { DelegateLLMClient } from '@connorhatcher/obversational-memory'

const llm = new DelegateLLMClient(async (prompt, systemPrompt, settings) => {
  return hostComplete(prompt, systemPrompt, settings)
})

This keeps host auth/session concerns in the plugin while reusing OM pipelines.

Stateless Contract for Plugins

runCompactionCycle returns StatelessCompactionResult with stable metadata in result.meta:

• schemaVersion
• observerRan
• reflectorRan
• messageTokenCount
• observationTokenCount

Use these fields for plugin status output and telemetry.

Core-Host Parity Boundary

To keep behavior aligned across OpenCode, pi-code, and future hosts:

• Core owns threshold semantics (shareTokenBudget, blockAfter, reflection fallback rules).
• Hosts should reuse core helpers instead of re-implementing formulas:
  • computeEffectiveThresholds
  • resolveBlockThreshold
• Host integrations should focus on conversion, scheduling, and UI, while leaving compaction threshold logic to core.