@remnic/core 1.1.1 → 1.1.3

package/dist/types.d.ts

@@ -1,3 +1,54 @@
+/**
+ * dreams-ledger.ts — per-phase telemetry for the Dreams consolidation pipeline.
+ *
+ * Every scheduled or manual phase run appends one JSONL entry to
+ *   <memoryDir>/state/dreams-ledger.jsonl
+ *
+ * The entry records which phase ran, how long it took, and a small
+ * itemsProcessed counter so `remnic dreams status` can aggregate the last
+ * 24-hour window without scanning the full memory corpus.
+ *
+ * This module is intentionally side-effect-free on import (no fs calls at
+ * module load time) so tests can import it without touching the filesystem.
+ */
+/** The three named phases of the Dreams consolidation pipeline. */
+type DreamsPhase = "lightSleep" | "rem" | "deepSleep";
+/** Aggregated stats for a single phase over a time window. */
+interface DreamsPhaseStatus {
+    phase: DreamsPhase;
+    /** Number of phase runs in the window. */
+    runCount: number;
+    /** Total wall-clock milliseconds across all runs in the window. */
+    totalDurationMs: number;
+    /** Total items processed across all runs in the window. */
+    totalItemsProcessed: number;
+    /** ISO-8601 timestamp of the most recent completed run, or null if none. */
+    lastRunAt: string | null;
+    /** Duration of the most recent run in ms, or null if none. */
+    lastDurationMs: number | null;
+}
+/** Shape returned by `getDreamsStatus` — the canonical telemetry response. */
+interface DreamsStatusResult {
+    /** ISO-8601 start of the query window (inclusive). */
+    windowStart: string;
+    /** ISO-8601 end of the query window (exclusive). */
+    windowEnd: string;
+    /** Per-phase summaries, always present for all three phases. */
+    phases: {
+        lightSleep: DreamsPhaseStatus;
+        rem: DreamsPhaseStatus;
+        deepSleep: DreamsPhaseStatus;
+    };
+}
+/** Public result shape — identical to what HTTP, MCP, and CLI surfaces expose. */
+interface DreamsRunResult {
+    phase: DreamsPhase;
+    dryRun: boolean;
+    durationMs: number;
+    itemsProcessed: number;
+    notes?: string;
+}
+
 type ReasoningEffort = "none" | "low" | "medium" | "high";
 type TriggerMode = "smart" | "every_n" | "time_based";
 type SignalLevel = "none" | "low" | "medium" | "high";
@@ -12,6 +63,20 @@ type IdentityInjectionMode = "recovery_only" | "minimal" | "full";
 type CaptureMode = "implicit" | "explicit" | "hybrid";
 type MemoryOsPresetName = "conservative" | "balanced" | "research-max" | "local-llm-heavy";
 type ExtractionPassSource = "base" | "proactive";
+/**
+ * Scope classification for extracted facts (issue #XXX).
+ *
+ * - `"project"` — knowledge specific to one codebase: file paths, environment
+ *   configs, deployment details, project-specific workarounds, team/stakeholder
+ *   info tied to one project.
+ * - `"global"` — knowledge that applies across projects: core framework bugs,
+ *   library behavior, API patterns, user preferences, tool configurations,
+ *   general coding patterns, infrastructure knowledge.
+ *
+ * Default is `"project"` when a coding context is active, `"global"` when no
+ * coding context is present.
+ */
+type MemoryScope = "project" | "global";
 type SlotMismatchMode = "error" | "warn" | "silent";
 type CodexCompactionFlushMode = "signal" | "heuristic" | "auto";
 type DreamingNarrativePromptStyle = "reflective" | "diary" | "analytical";
@@ -48,6 +113,41 @@ interface RecallTierExplain {
         lineRange?: [number, number];
     }>;
 }
+/**
+ * Recall disclosure depth (issue #677).  Selects how much content each
+ * recall result returns:
+ *
+ * - `"chunk"`   — semantic chunk excerpt (cheapest; default).
+ * - `"section"` — full markdown section / memory body (current pre-#677 behavior).
+ * - `"raw"`     — raw transcript / archive excerpts from `lcm/` when present.
+ *
+ * Disclosure is **orthogonal** to the retrieval-tier ladder
+ * (`RetrievalTier` / `RETRIEVAL_TIERS`).  The tier ladder controls *which
+ * pipeline stage served a result*; disclosure controls *how deep into the
+ * underlying memory the result reaches*.  A request can mix any retrieval
+ * tier with any disclosure depth.
+ *
+ * Default is `"chunk"` when the caller omits the field; this preserves the
+ * existing recall behavior because callers that did not request a disclosure
+ * level continue to receive the same chunk-shaped previews they always had.
+ * Surfaces (CLI / HTTP / MCP) and downstream telemetry are wired in later
+ * PRs of #677.
+ */
+type RecallDisclosure = "chunk" | "section" | "raw";
+/**
+ * Ordered list of disclosure levels, cheapest to most expensive.  Used for
+ * validation, escalation policy comparisons, and future telemetry rollups.
+ * Treat this as the single source of truth — do not hard-code disclosure
+ * strings elsewhere.
+ */
+declare const RECALL_DISCLOSURE_LEVELS: readonly RecallDisclosure[];
+/**
+ * Default disclosure level when a caller omits `disclosure`.  Set to `chunk`
+ * so callers that did not opt in to deeper disclosure see the same
+ * preview-shaped behavior as before #677.
+ */
+declare const DEFAULT_RECALL_DISCLOSURE: RecallDisclosure;
+declare function isRecallDisclosure(value: unknown): value is RecallDisclosure;
 interface RecallSectionConfig {
     id: string;
     enabled?: boolean;
@@ -131,11 +231,33 @@ interface NativeKnowledgeOpenClawWorkspaceConfig {
     excludeGlobs: string[];
     sharedSafeGlobs: string[];
 }
+/**
+ * OpenClaw SecretRef shape (issue #757).
+ *
+ * OpenClaw resolves these at runtime via its built-in secret resolver
+ * (e.g. exec providers like `kc_*` for macOS Keychain). Plugins receive
+ * the raw object in `pluginConfig` and must call the gateway's resolver
+ * before using the value. Standalone Remnic does NOT resolve SecretRefs;
+ * operators must use plain strings or `${ENV_VAR}` expansion instead.
+ */
+interface SecretRef {
+    source: string;
+    provider?: string;
+    id?: string;
+    command?: unknown;
+    [key: string]: unknown;
+}
+type AgentAccessAuthToken = string | SecretRef;
 interface AgentAccessHttpConfig {
     enabled: boolean;
     host: string;
     port: number;
-    authToken?: string;
+    /**
+     * Bearer token. Either a literal string (env-expanded) or an unresolved
+     * SecretRef object preserved verbatim from openclaw.json — resolved at
+     * service-start time via {@link resolveAgentAccessAuthToken}.
+     */
+    authToken?: AgentAccessAuthToken;
     principal?: string;
     maxBodyBytes: number;
 }
@@ -149,6 +271,104 @@ interface DreamingConfig {
     narrativePromptStyle: DreamingNarrativePromptStyle;
     watchFile: boolean;
 }
+/**
+ * Light-sleep phase config (issue #678 PR 2/4).
+ *
+ * Groups existing top-level lifecycle-policy gates under a unified namespace.
+ * When `dreams.phases.lightSleep.*` keys are set they WIN over the legacy
+ * top-level keys; the legacy keys remain readable for backward compatibility.
+ *
+ * Light sleep: recent activity scoring + clustering (tier-routing value score,
+ * observation ledger, buffer state — `runLifecyclePolicyPass` in orchestrator).
+ */
+interface DreamsLightSleepConfig {
+    /** Phase master switch. Mirrors `lifecyclePolicyEnabled` when not set explicitly. */
+    enabled: boolean;
+    /** Minimum interval between light-sleep passes in milliseconds. */
+    cadenceMs: number;
+    /** Value score above which a memory is treated as hot. Mirrors `lifecyclePromoteHeatThreshold`. */
+    promoteHeatThreshold: number;
+    /** Value score below which a memory starts to decay. Mirrors `lifecycleStaleDecayThreshold`. */
+    staleDecayThreshold: number;
+    /** Value score below which a memory is eligible for archive. Mirrors `lifecycleArchiveDecayThreshold`. */
+    archiveDecayThreshold: number;
+    /** Whether stale memories are filtered from recall. Mirrors `lifecycleFilterStaleEnabled`. */
+    filterStaleEnabled: boolean;
+}
+/**
+ * REM phase config (issue #678 PR 2/4).
+ *
+ * Groups existing top-level semantic-consolidation and supersession gates.
+ * When `dreams.phases.rem.*` keys are set they WIN over the legacy top-level
+ * keys.
+ *
+ * REM: cross-session synthesis, supersession resolution, semantic consolidation
+ * (`runSemanticConsolidation` in orchestrator).
+ */
+interface DreamsRemConfig {
+    /** Phase master switch. Mirrors `semanticConsolidationEnabled` when not set explicitly. */
+    enabled: boolean;
+    /**
+     * How often the REM pass runs, in milliseconds.
+     * Derived from `semanticConsolidationIntervalHours` (×3 600 000) when not set explicitly.
+     */
+    cadenceMs: number;
+    /** Cosine-similarity threshold for cluster membership. Mirrors `semanticConsolidationThreshold`. */
+    similarityThreshold: number;
+    /** Minimum cluster size before consolidation runs. Mirrors `semanticConsolidationMinClusterSize`. */
+    minClusterSize: number;
+    /** Max cluster operations per run. Mirrors `semanticConsolidationMaxPerRun`. */
+    maxPerRun: number;
+    /** Minimum gap between consolidation passes (ms). Mirrors `consolidationMinIntervalMs`. */
+    minIntervalMs: number;
+}
+/**
+ * Deep-sleep phase config (issue #678 PR 2/4).
+ *
+ * Groups existing versioning and tier-migration gates.
+ * When `dreams.phases.deepSleep.*` keys are set they WIN over the legacy
+ * top-level keys.
+ *
+ * Deep sleep: promotion to durable memory, hot→cold tier migration,
+ * page-version snapshots, archive (`engram-nightly-governance` cron,
+ * `tier-migration.ts`, `page-versioning.ts`, `hygiene.ts`).
+ */
+interface DreamsDeepSleepConfig {
+    /**
+     * Phase master switch. No single direct legacy mirror; defaults false unless
+     * an existing deep-sleep surface such as nightly governance auto-registration,
+     * tier migration, or page versioning is explicitly enabled. Set to `false`
+     * to disable those surfaces without removing legacy config keys.
+     */
+    enabled: boolean;
+    /** True only when dreams.phases.deepSleep.enabled was explicitly configured. */
+    enabledExplicitlySet?: boolean;
+    /**
+     * Minimum interval between deep-sleep passes in milliseconds.
+     * Informational only in PR 2; PR 4 will wire this into the cron scheduler.
+     */
+    cadenceMs: number;
+    /** Enable page-version snapshots on every overwrite. Mirrors `versioningEnabled`. */
+    versioningEnabled: boolean;
+    /** Max snapshots per page. Mirrors `versioningMaxPerPage`. */
+    versioningMaxPerPage: number;
+}
+/**
+ * Unified dreams phases config block (issue #678 PR 2/4).
+ *
+ * Operators set `dreams.phases.{lightSleep,rem,deepSleep}.*` in their plugin
+ * config. Values under this block WIN over the equivalent legacy top-level keys
+ * when both are set. Legacy keys continue to be parsed so existing configs do
+ * not need to change.
+ *
+ * This block is intentionally separate from `DreamingConfig` which controls the
+ * diary surface (`surfaces/dreams.ts`) — a different feature. See docs/dreams.md.
+ */
+interface DreamsPhasesConfig {
+    lightSleep: DreamsLightSleepConfig;
+    rem: DreamsRemConfig;
+    deepSleep: DreamsDeepSleepConfig;
+}
 /** Procedural memory (issue #519): mining + recall gates. All sub-features default off. */
 interface ProceduralConfig {
     enabled: boolean;
@@ -191,6 +411,17 @@ interface CodingModeConfig {
      * issue #569; declared here so the schema ships in one slice.)
      */
     branchScope: boolean;
+    /**
+     * When true (default), project-scoped and branch-scoped sessions include
+     * the root/default namespace in their read fallbacks so globally useful
+     * memories remain visible from any project. When false, project-scoped
+     * sessions only see their own namespace (strict isolation).
+     *
+     * CLAUDE.md #30: configuration gate for the recall fan-out to the root
+     * namespace. Does not affect writes — those always go to the project
+     * namespace only.
+     */
+    globalFallback: boolean;
 }
 /**
  * Session-scoped coding context. Produced by `resolveGitContext()` in the
@@ -401,6 +632,21 @@ interface PluginConfig {
      * Default false — enable explicitly after bench validation.
      */
     recallDirectAnswerEnabled: boolean;
+    /**
+     * Disclosure auto-escalation policy (issue #677 PR 4/4).  When set to
+     * `"auto"`, recalls without an explicit caller-supplied disclosure
+     * escalate from `chunk` to `section` if the top-K confidence falls
+     * below {@link recallDisclosureEscalationThreshold}.  `raw` is never
+     * auto-selected — it requires an explicit caller request.  Default
+     * `"manual"` preserves pre-#677 behavior.
+     */
+    recallDisclosureEscalation: "manual" | "auto";
+    /**
+     * Top-K confidence threshold (in `[0, 1]`) below which auto-escalation
+     * promotes `chunk` → `section`.  Only consulted when
+     * {@link recallDisclosureEscalation} is `"auto"`.  Default `0.5`.
+     */
+    recallDisclosureEscalationThreshold: number;
     /**
      * Graph-based retrieval tier via Personalized PageRank (issue #559 PR 4).
      * When true, recall builds a retrieval graph from memory frontmatter
@@ -542,11 +788,40 @@ interface PluginConfig {
     activeRecallAttachRecallExplain: boolean;
     activeRecallAllowChainedActiveMemory: boolean;
     dreaming: DreamingConfig;
+    /**
+     * Unified dreams-phases config block (issue #678 PR 2/4).
+     * Groups existing lifecycle, REM, and deep-sleep gates under one namespace.
+     * Values here WIN over equivalent legacy top-level keys when set. See docs/dreams.md.
+     */
+    dreamsPhases: DreamsPhasesConfig;
     procedural: ProceduralConfig;
+    /**
+     * At-rest encryption configuration (issue #690 PR 3/4).
+     *
+     * When `secureStoreEnabled` is true, `StorageManager` reads and
+     * writes memory files through the `secure-fs` encryption layer.
+     * The store must be unlocked via `remnic secure-store unlock` before
+     * any recall or store operations will succeed.
+     *
+     * When `secureStoreEncryptOnWrite` is true (the default when enabled),
+     * every new memory write is encrypted. Set to false to pause new
+     * encryptions while still being able to decrypt existing files.
+     */
+    secureStoreEnabled: boolean;
+    /** Encrypt new writes when the secure-store is unlocked. Default true. */
+    secureStoreEncryptOnWrite: boolean;
     codingMode: CodingModeConfig;
     heartbeat: HeartbeatConfig;
     slotBehavior: SlotBehaviorConfig;
     codexCompat: CodexCompatConfig;
+    /**
+     * When true (default), the extraction prompt instructs the LLM to classify
+     * each fact as `"project"` or `"global"` scope. Global-scoped facts are
+     * promoted to the shared namespace so they are visible across all projects.
+     * When false, all facts go to whatever namespace the session is in (pre-
+     * scope-classification behavior). Rule 30: configuration gate.
+     */
+    extractionScopeClassificationEnabled: boolean;
     /** Enable the LLM-as-judge fact-worthiness gate on extracted facts. Default false (opt-in). */
     extractionJudgeEnabled: boolean;
     /** Model override for the judge LLM. Empty string means use the local model. */
@@ -657,6 +932,82 @@ interface PluginConfig {
      * `chooseConsolidationOperator`.  Issue #561 PR 3.
      */
     operatorAwareConsolidationEnabled: boolean;
+    /**
+     * When true, the pattern-reinforcement maintenance job runs on its
+     * configured cadence and clusters duplicate non-procedural memories
+     * by normalized content.  Clusters with `>= patternReinforcementMinCount`
+     * members produce a canonical (most-recent) memory tagged with
+     * `reinforcement_count` + `last_reinforced_at`; the older duplicates
+     * are marked `superseded` and pointed at the canonical.  Default
+     * `false` — opt-in until bench validation lands.
+     */
+    patternReinforcementEnabled: boolean;
+    /**
+     * Minimum interval (ms) between pattern-reinforcement runs.  Default
+     * `7 * 24 * 60 * 60 * 1000` (7 days).  Set to `0` to disable cadence
+     * gating (useful for tests / manual invocation).
+     */
+    patternReinforcementCadenceMs: number;
+    /**
+     * Minimum cluster size before pattern reinforcement promotes a
+     * canonical and supersedes duplicates.  Default `3`.  Clamped to
+     * `>= 2` at config-parse time — a "cluster of 1" is just a single
+     * memory and a "cluster of 0" is meaningless.
+     */
+    patternReinforcementMinCount: number;
+    /**
+     * Memory categories the pattern-reinforcement job considers.
+     * Default `["preference", "fact", "decision"]`.  The job
+     * intentionally skips procedural memories so it stays disjoint from
+     * the procedural mining pipeline.
+     */
+    patternReinforcementCategories: string[];
+    /** issue #687 PR 3/4: opt-in recall score boost for reinforced memories. Default false. */
+    reinforcementRecallBoostEnabled: boolean;
+    /** Score bonus per unit of reinforcement_count. Range [0, 1]. Default 0.05. */
+    reinforcementRecallBoostWeight: number;
+    /** Maximum additive reinforcement boost per result. Range [0, 1]. Default 0.3. */
+    reinforcementRecallBoostMax: number;
+    /**
+     * Async peer profile reasoner — issue #679 PR 2/5.
+     *
+     * Default `false` (opt-in). When enabled, the reasoner runs after
+     * `runSemanticConsolidation` (the REM phase of the dreams pipeline)
+     * and updates per-peer profile.md files with provenance-tagged
+     * field updates derived from the peer's interaction log.
+     */
+    peerProfileReasonerEnabled: boolean;
+    /**
+     * Model identifier used by the peer profile reasoner. Logged for
+     * telemetry only — actual dispatch is via the same FallbackLlmClient
+     * the orchestrator uses for semantic consolidation. Default `gpt-5.2`.
+     */
+    peerProfileReasonerModel: string;
+    /**
+     * Minimum new interaction-log entries a peer must accumulate since
+     * the previous reasoner run before being processed again. Default 5.
+     * Setting to 0 forces every run to consider every peer.
+     */
+    peerProfileReasonerMinInteractions: number;
+    /**
+     * Hard cap on the total number of profile fields the reasoner will
+     * apply across all peers in a single run. Default 8.
+     */
+    peerProfileReasonerMaxFieldsPerRun: number;
+    /**
+     * When true, inject the active peer's profile fields into the recall
+     * context as a "## Peer Profile" section. Default false (opt-in,
+     * Gotcha #30/#48 — least-privileged default). Requires the session's
+     * peer ID to be registered via `setPeerIdForSession` before recall.
+     */
+    peerProfileRecallEnabled: boolean;
+    /**
+     * Maximum number of peer profile fields to inject per recall. Only
+     * the most-recently-updated N fields are included to keep the context
+     * budget predictable. Default 5. Setting to 0 disables field
+     * injection even when `peerProfileRecallEnabled` is true.
+     */
+    peerProfileRecallMaxFields: number;
     creationMemoryEnabled: boolean;
     memoryUtilityLearningEnabled: boolean;
     promotionByOutcomeEnabled: boolean;
@@ -1060,6 +1411,33 @@ interface PluginConfig {
     graphLateralInhibitionBeta: number;
     /** Number of top competing nodes considered for inhibition (default 7). */
     graphLateralInhibitionTopM: number;
+    /** Enable the periodic graph-edge confidence decay job. Default false (opt-in). */
+    graphEdgeDecayEnabled: boolean;
+    /** Cadence in milliseconds at which the cron triggers the decay job. Default 7d. */
+    graphEdgeDecayCadenceMs: number;
+    /** Decay window passed through to `decayEdgeConfidence`. Default 90 days. */
+    graphEdgeDecayWindowMs: number;
+    /** Per-window confidence drop. Default 0.1. */
+    graphEdgeDecayPerWindow: number;
+    /** Floor confidence will not decay below. Default 0.1. */
+    graphEdgeDecayFloor: number;
+    /** Confidence threshold for the "below visibility" telemetry counter. Default 0.2. */
+    graphEdgeDecayVisibilityThreshold: number;
+    /**
+     * Issue #681 PR 3/3 — minimum edge confidence required for an edge to be
+     * traversed during spreading activation. Edges with `confidence` below this
+     * floor are pruned and contribute neither activation nor downstream
+     * neighbors. Legacy edges without `confidence` are treated as 1.0 so they
+     * always pass the floor. Range `[0, 1]`; default `0.2`.
+     */
+    graphTraversalConfidenceFloor: number;
+    /**
+     * Issue #681 PR 3/3 — number of PageRank-style refinement iterations applied
+     * on top of the BFS spreading-activation scores. Each iteration redistributes
+     * a node's confidence-weighted activation along its outgoing edges. Set to 0
+     * to disable refinement and use raw BFS scores. Default `8`.
+     */
+    graphTraversalPageRankIterations: number;
     temporalMemoryTreeEnabled: boolean;
     tmtHourlyMinMemories: number;
     tmtSummaryMaxTokens: number;
@@ -1084,6 +1462,7 @@ interface PluginConfig {
     /** Briefing configuration knobs — see BriefingConfig for field docs. */
     briefing: BriefingConfig;
     codex: CodexConnectorConfig;
+    connectors: LiveConnectorsConfig;
     /** Enable the MECE taxonomy knowledge directory. Default false. */
     taxonomyEnabled: boolean;
     /** Auto-regenerate RESOLVER.md when taxonomy changes. Default true. */
@@ -1263,6 +1642,126 @@ interface CodexConnectorConfig {
      */
     codexHome: string | null;
 }
+/**
+ * Container for live-connector config blocks (issue #683 PR 2/N).
+ *
+ * Lives at `connectors.*` rather than the top level so future connectors
+ * (Notion, Gmail, GitHub) can slot in without bloating `PluginConfig`.
+ *
+ * Every child block must default to `enabled: false` per CLAUDE.md gotcha
+ * #30 (escape hatch by default) and gotcha #48 (least-privileged enum
+ * defaults). Concrete connectors are also expected to short-circuit at
+ * registration time when their credentials are not populated.
+ */
+interface LiveConnectorsConfig {
+    /** Google Drive live connector (issue #683 PR 2/N). */
+    googleDrive: GoogleDriveLiveConnectorConfig;
+    /** Notion live connector (issue #683 PR 3/N). */
+    notion: NotionLiveConnectorConfig;
+    /** Gmail live connector (issue #683 PR 4/6). */
+    gmail: GmailLiveConnectorConfig;
+    /** GitHub live connector (issue #683 PR 5/6). */
+    github: GitHubLiveConnectorConfig;
+}
+/**
+ * Operator-facing config for the Google Drive live connector. The connector
+ * module itself defines a separate, *validated* `GoogleDriveConnectorConfig`
+ * shape (frozen, post-validation). This interface is the pre-validation
+ * shape that `parseConfig` round-trips through.
+ *
+ * `clientId` / `clientSecret` / `refreshToken` are stored as strings here so
+ * the schema can ship in `openclaw.plugin.json` and operators can populate
+ * them from a secret store (e.g. an env-substituted plist or systemd
+ * EnvironmentFile). They MUST NEVER be committed to source. The repo-wide
+ * privacy policy in CLAUDE.md applies.
+ */
+interface GoogleDriveLiveConnectorConfig {
+    /** Master gate. Default false — operators must opt in explicitly. */
+    enabled: boolean;
+    /** OAuth2 client id. Populate from a secret store; never commit. */
+    clientId: string;
+    /** OAuth2 client secret. Populate from a secret store; never commit. */
+    clientSecret: string;
+    /** OAuth2 refresh token. Populate from a secret store; never commit. */
+    refreshToken: string;
+    /** Poll interval in ms. Default 300000 (5 min); min 1000; max 86400000 (24h). */
+    pollIntervalMs: number;
+    /** Optional folder-id scope. Empty array = all accessible files. */
+    folderIds: string[];
+}
+/**
+ * Operator-facing config for the Notion live connector (issue #683 PR 3/N).
+ * The connector module defines a separate validated `NotionConnectorConfig`
+ * shape (frozen, post-validation). This interface is the pre-validation shape
+ * that `parseConfig` round-trips through.
+ *
+ * `token` is stored as a string here so operators can populate it from a
+ * secret store (e.g. an env-substituted plist or systemd EnvironmentFile).
+ * It MUST NEVER be committed to source. The repo-wide privacy policy in
+ * CLAUDE.md applies.
+ */
+interface NotionLiveConnectorConfig {
+    /** Master gate. Default false — operators must opt in explicitly. */
+    enabled: boolean;
+    /** Notion integration token. Starts with `secret_`. Populate from a secret store; never commit. */
+    token: string;
+    /** Array of Notion database ids to import pages from. Empty = connector is a no-op. */
+    databaseIds: string[];
+    /** Poll interval in ms. Default 300000 (5 min); min 1000; max 86400000 (24h). */
+    pollIntervalMs: number;
+}
+/**
+ * Operator-facing config for the Gmail live connector (issue #683 PR 4/6).
+ * The connector module defines a separate validated `GmailConnectorConfig`
+ * shape (frozen, post-validation). This interface is the pre-validation shape
+ * that `parseConfig` round-trips through.
+ *
+ * OAuth2 credentials are stored as strings here so operators can populate
+ * them from a secret store (e.g. env-substituted plist or systemd
+ * EnvironmentFile). They MUST NEVER be committed to source. The repo-wide
+ * privacy policy in CLAUDE.md applies.
+ */
+interface GmailLiveConnectorConfig {
+    /** Master gate. Default false — operators must opt in explicitly. */
+    enabled: boolean;
+    /** OAuth2 client id. Populate from a secret store; never commit. */
+    clientId: string;
+    /** OAuth2 client secret. Populate from a secret store; never commit. */
+    clientSecret: string;
+    /** OAuth2 refresh token issued for the Gmail scope. Populate from a secret store; never commit. */
+    refreshToken: string;
+    /** Gmail userId. Defaults to "me" (the authenticated user). */
+    userId: string;
+    /** Gmail search query applied in addition to the watermark filter. Default "in:inbox". */
+    query: string;
+    /** Poll interval in ms. Default 300000 (5 min); min 1000; max 86400000 (24h). */
+    pollIntervalMs: number;
+}
+/**
+ * Operator-facing config for the GitHub live connector (issue #683 PR 5/6).
+ * The connector module defines a separate validated `GitHubConnectorConfig`
+ * shape (frozen, post-validation). This interface is the pre-validation shape
+ * that `parseConfig` round-trips through.
+ *
+ * `token` is stored as a string here so operators can populate it from a
+ * secret store (e.g. an env-substituted plist or systemd EnvironmentFile).
+ * It MUST NEVER be committed to source. The repo-wide privacy policy in
+ * CLAUDE.md applies.
+ */
+interface GitHubLiveConnectorConfig {
+    /** Master gate. Default false — operators must opt in explicitly. */
+    enabled: boolean;
+    /** GitHub personal access token. Populate from a secret store; never commit. */
+    token: string;
+    /** GitHub login of the user whose comments will be imported. Required. */
+    userLogin: string;
+    /** Repos to poll in "owner/repo" format. Empty = connector is a no-op. */
+    repos: string[];
+    /** Poll interval in ms. Default 300000 (5 min); min 1000; max 86400000 (24h). */
+    pollIntervalMs: number;
+    /** Whether to fetch Discussion comments in addition to issue/PR comments. Default false. */
+    includeDiscussions: boolean;
+}
 interface BootstrapOptions {
     dryRun?: boolean;
     sessionsDir?: string;
@@ -1387,7 +1886,16 @@ interface BufferSurpriseEvent {
     turnCountInWindow: number;
 }
 /** Memory status for lifecycle management */
-type MemoryStatus = "active" | "pending_review" | "rejected" | "quarantined" | "superseded" | "archived";
+type MemoryStatus = "active" | "pending_review" | "rejected" | "quarantined" | "superseded" | "archived"
+/**
+ * Operator explicitly forgot the memory (issue #686 PR 4/6).  Soft
+ * delete: the file stays on disk and a page-version snapshot is kept
+ * so the act is reversible during a configurable retention window
+ * (default 90 days), but the memory is excluded from recall, browse,
+ * and entity attribution.  After the retention window passes, a
+ * future maintenance cron will hard-delete forgotten memories.
+ */
+ | "forgotten";
 type LifecycleState = "candidate" | "validated" | "active" | "stale" | "archived";
 type VerificationState = "unverified" | "user_confirmed" | "system_inferred" | "disputed";
 type PolicyClass = "ephemeral" | "durable" | "protected";
@@ -1419,7 +1927,7 @@ interface MemoryFrontmatter {
     expiresAt?: string;
     /** IDs of parent memories this was derived from (lineage tracking) */
     lineage?: string[];
-    /** Memory status: active (default), pending_review, rejected, quarantined, superseded, or archived */
+    /** Memory status: active (default), pending_review, rejected, quarantined, superseded, archived, or forgotten */
     status?: MemoryStatus;
     /** ID of memory that superseded this one */
     supersededBy?: string;
@@ -1427,6 +1935,35 @@ interface MemoryFrontmatter {
     supersededAt?: string;
     /** Timestamp when archived */
     archivedAt?: string;
+    /**
+     * Explicit fact validity start (issue #680). ISO 8601 timestamp.
+     *
+     * When present, marks the moment at which the fact begins being
+     * "true" / authoritative.  When absent at read time, callers fall
+     * back to `created` so legacy memories written before #680 still
+     * participate in `as_of` recall filtering without a migration.
+     */
+    valid_at?: string;
+    /**
+     * Explicit fact validity end (issue #680). ISO 8601 timestamp.
+     *
+     * Set automatically by the temporal-supersession pipeline when a
+     * newer fact supersedes this one — the value is the superseder's
+     * `valid_at` (or `created` if no `valid_at` was set).  May also be
+     * set manually for facts that are known to expire at a specific
+     * point in time.
+     */
+    invalid_at?: string;
+    /**
+     * Timestamp when the operator explicitly forgot this memory
+     * (issue #686 PR 4/6).  Set by `remnic forget <id>`.  Memories with
+     * `status === "forgotten"` are excluded from recall, browse, and
+     * entity attribution; the file remains on disk until the retention
+     * window passes.
+     */
+    forgottenAt?: string;
+    /** Optional human-readable reason captured by `remnic forget --reason`. */
+    forgottenReason?: string;
     /** Policy-driven lifecycle state used for retrieval eligibility/ranking. */
     lifecycleState?: LifecycleState;
     /** Verification provenance used by lifecycle policy. */
@@ -1492,12 +2029,35 @@ interface MemoryFrontmatter {
      */
     derived_from?: string[];
     /**
-     * Which consolidation operator produced this memory (issue #561).  See
-     * `ConsolidationOperator` in `semantic-consolidation.ts` for the
-     * operator algebra.  Absent on memories that were not produced by a
-     * consolidation pass.
+     * Which consolidation operator produced this memory (issue #561,
+     * extended in #687).  See `ConsolidationOperator` in
+     * `semantic-consolidation.ts` for the operator algebra.  Absent on
+     * memories that were not produced by a consolidation pass.
+     *
+     * `"pattern-reinforcement"` (issue #687 PR 2/4) tags memories that
+     * were promoted to canonical by the pattern-reinforcement
+     * maintenance job after observing the same content across
+     * multiple sessions.
+     */
+    derived_via?: "split" | "merge" | "update" | "pattern-reinforcement";
+    /**
+     * Number of source memories that reinforced this canonical memory
+     * (issue #687 PR 2/4).  Set by the pattern-reinforcement
+     * maintenance job when it clusters duplicate memories and promotes
+     * the most recent member to canonical.  Counts the cluster size at
+     * the time of the run; subsequent runs update this monotonically.
+     *
+     * Always a positive integer when present.  Absent on memories that
+     * have not been touched by pattern reinforcement.
+     */
+    reinforcement_count?: number;
+    /**
+     * ISO 8601 timestamp recording the most recent pattern-reinforcement
+     * run that touched this memory (issue #687 PR 2/4).  Updated each
+     * time the cluster size grows.  Absent when `reinforcement_count`
+     * is absent.
      */
-    derived_via?: "split" | "merge" | "update";
+    last_reinforced_at?: string;
 }
 /** Memory link relationship types */
 type MemoryLinkType = "follows" | "references" | "contradicts" | "supports" | "related";
@@ -1543,6 +2103,62 @@ interface MemoryFile {
     frontmatter: MemoryFrontmatter;
     content: string;
 }
+/**
+ * Public type representing the **Observation** stage in the
+ * Trace → Observation → Primitive pipeline (issue #685).
+ *
+ * - **Trace**: raw conversation turns captured in `buffer.ts`. Noisy,
+ *   verbose, ephemeral.
+ * - **Observation** (this type): post-extraction, importance-scored
+ *   fact candidate emitted by `extraction.ts` / `extraction-judge.ts`.
+ *   Already distilled — but not yet consolidated against the corpus.
+ * - **Primitive**: the durable `MemoryFile` written by `storage.ts`,
+ *   reinforced over time by `compounding/engine.ts`.
+ *
+ * `MemoryObservation` is the named handle on the intermediate stage
+ * the codebase has always produced but never publicly typed. It lets
+ * callers (telemetry, doctor surfaces, tests, downstream tooling)
+ * inspect the post-extraction shape without reaching into extraction
+ * internals.
+ *
+ * Naming note: this is intentionally NOT the same as the existing
+ * `state/observation-ledger/` directory, which is telemetry storage
+ * for the extraction pipeline (turn-count aggregates rebuilt by
+ * `maintenance/rebuild-observations.ts` and judge verdict events
+ * appended by `extraction-judge-telemetry.ts`). Lifecycle events on
+ * primitives — status flips, supersessions, archival, forget — live
+ * in `state/memory-lifecycle-ledger.jsonl`, written by
+ * `StorageManager`. A `MemoryObservation` describes the in-flight
+ * candidate that became (or didn't become) a primitive; the ledger
+ * directory is how the pipeline reports on itself. See
+ * `docs/trace-to-primitive.md` for the full pipeline walkthrough.
+ */
+interface MemoryObservation {
+    /** Stable id for this observation, distinct from any primitive id. */
+    id: string;
+    /** Source session id the trace came from. */
+    sessionId?: string;
+    /** ISO timestamp the observation was emitted. */
+    observedAt: string;
+    /** The extracted fact candidate (category, content, confidence, tags, etc.). */
+    fact: ExtractedFact;
+    /** Importance score in [0,1], from `importance.ts`. */
+    importance?: number;
+    /**
+     * Whether the observation passed the extraction judge
+     * (`extraction-judge.ts`). When `false`, the observation was
+     * captured for telemetry but not persisted as a primitive.
+     */
+    judgeAccepted?: boolean;
+    /** Optional reason the judge gave when rejecting. */
+    judgeRejectionReason?: string;
+    /**
+     * Id of the resulting `MemoryFile` primitive once consolidation runs.
+     * Absent until consolidation decides to ADD/MERGE/UPDATE the
+     * observation into the corpus.
+     */
+    resultingPrimitiveId?: string;
+}
 /** Ordered step for extracted procedure memories (issue #519). */
 interface ExtractedProcedureStep {
     order: number;
@@ -1562,6 +2178,13 @@ interface ExtractedFact {
     entityRef?: string;
     source?: ExtractionPassSource;
     promptedByQuestion?: string;
+    /**
+     * Whether this fact is project-scoped or globally applicable.
+     * When `extractionScopeClassificationEnabled` is true, the extraction LLM
+     * classifies each fact. Default is `"project"` when a coding context is
+     * active, `"global"` when no coding context is present.
+     */
+    scope?: MemoryScope;
     /** Structured key-value attributes extracted from the content (e.g., product attributes, dates, quantities). */
     structuredAttributes?: Record<string, string>;
     /** When category is `procedure`, ordered steps with intents (persisted under procedures/). */
@@ -1722,6 +2345,8 @@ interface QmdSearchExplain {
     rrf?: number;
     rerankScore?: number;
     blendedScore?: number;
+    /** Additive boost applied from `reinforcement_count` frontmatter (issue #687 PR 3/4). */
+    reinforcementBoost?: number;
 }
 interface MetaState {
     extractionCount: number;
@@ -2040,4 +2665,4 @@ interface HourlySummary {
     generatedAt: string;
 }
 
-export { type AccessTrackingEntry, type ActiveRecallChatType, type ActiveRecallModelFallbackPolicy, type ActiveRecallPromptStyle, type ActiveRecallQueryMode, type ActiveRecallThinking, type AgentAccessHttpConfig, type AgentDefaultsConfig, type AgentPersona, type AgentPersonaModelConfig, type BehaviorLoopAdjustment, type BehaviorLoopPolicyState, type BehaviorSignalDirection, type BehaviorSignalEvent, type BehaviorSignalType, type BootstrapOptions, type BootstrapResult, type BriefingActiveThread, type BriefingCalendarSourceError, type BriefingConfig, type BriefingFocus, type BriefingFollowup, type BriefingOpenCommitment, type BriefingRecentEntity, type BriefingResult, type BriefingSections, type BriefingWindow, type BufferEntryState, type BufferState, type BufferSurpriseEvent, type BufferTurn, type CalendarEvent, type CalendarSource, type CaptureMode, type Checkpoint, type CodexCompactionFlushMode, type CodexCompatConfig, type CodexConnectorConfig, type CodingContext, type CodingModeConfig, type CompressionGuidelineActivationState, type CompressionGuidelineOptimizerActionSummary, type CompressionGuidelineOptimizerEventCounts, type CompressionGuidelineOptimizerRuleUpdate, type CompressionGuidelineOptimizerSourceWindow, type CompressionGuidelineOptimizerState, type ConfidenceTier, type ConsolidationAction, type ConsolidationItem, type ConsolidationObservation, type ConsolidationResult, type ContinuityImprovementLoop, type ContinuityIncidentCloseInput, type ContinuityIncidentOpenInput, type ContinuityIncidentRecord, type ContinuityIncidentState, type ContinuityLoopCadence, type ContinuityLoopReviewInput, type ContinuityLoopStatus, type ContinuityLoopUpsertInput, type ContradictionScanConfig, type ConversationThread, type CronConversationRecallMode, type CronRecallMode, type DaySummaryResult, type DreamingConfig, type DreamingNarrativePromptStyle, type EngramTraceEvent, type EntityActivityEntry, type EntityFile, type EntityMention, type EntityRelationship, type EntitySchemaDefinition, type EntitySchemaSectionDefinition, type EntityStructuredSection, type EntityTimelineEntry, type ExtractedFact, type ExtractedProcedureStep, type ExtractedQuestion, type ExtractedReasoningTrace, type ExtractedReasoningTraceStep, type ExtractedRelationship, type ExtractionPassSource, type ExtractionResult, type FileHygieneConfig, type GatewayConfig, type HeartbeatConfig, type HeartbeatDetectionMode, type HourlySummary, type IdentityInjectionMode, type ImportanceLevel, type ImportanceScore, type LifecycleState, type LlmTraceCallback, type LlmTraceEvent, type MemoryActionEligibilityContext, type MemoryActionEligibilitySource, type MemoryActionEvent, type MemoryActionOutcome, type MemoryActionPolicyDecision, type MemoryActionPolicyResult, type MemoryActionStatus, type MemoryActionType, type MemoryCategory, type MemoryFile, type MemoryFrontmatter, type MemoryIntent, type MemoryLifecycleEvent, type MemoryLifecycleEventType, type MemoryLifecycleStateSummary, type MemoryLink, type MemoryLinkType, type MemoryOsPresetName, type MemoryProjectionCurrentState, type MemoryStatus, type MemorySummary, type MetaState, type ModelApi, type ModelDefinitionConfig, type ModelProviderAuthMode, type ModelProviderConfig, type NamespacePolicy, type NativeKnowledgeConfig, type NativeKnowledgeFolderRuleConfig, type NativeKnowledgeObsidianVaultConfig, type NativeKnowledgeOpenClawWorkspaceConfig, type PluginConfig, type PolicyClass, type PrincipalFromSessionKeyMode, type PrincipalRule, type ProceduralConfig, type QmdSearchExplain, type QmdSearchResult, type QuestionEntry, type ReasoningEffort, type RecallPipelineConfig, type RecallPlanMode, type RecallSectionConfig, type RecallTierExplain, type RecallTraceEvent, type RelevanceFeedback, type RetrievalTier, SPECULATIVE_TTL_DAYS, type ScoredEntity, type SemanticChunkingConfigShape, type SessionObserverBandConfig, type SignalLevel, type SignalScanResult, type SlotBehaviorConfig, type SlotMismatchMode, type TopicScore, type TranscriptEntry, type TriggerMode, type VerificationState, confidenceTier };
+export { type AccessTrackingEntry, type ActiveRecallChatType, type ActiveRecallModelFallbackPolicy, type ActiveRecallPromptStyle, type ActiveRecallQueryMode, type ActiveRecallThinking, type AgentAccessAuthToken, type AgentAccessHttpConfig, type AgentDefaultsConfig, type AgentPersona, type AgentPersonaModelConfig, type BehaviorLoopAdjustment, type BehaviorLoopPolicyState, type BehaviorSignalDirection, type BehaviorSignalEvent, type BehaviorSignalType, type BootstrapOptions, type BootstrapResult, type BriefingActiveThread, type BriefingCalendarSourceError, type BriefingConfig, type BriefingFocus, type BriefingFollowup, type BriefingOpenCommitment, type BriefingRecentEntity, type BriefingResult, type BriefingSections, type BriefingWindow, type BufferEntryState, type BufferState, type BufferSurpriseEvent, type BufferTurn, type CalendarEvent, type CalendarSource, type CaptureMode, type Checkpoint, type CodexCompactionFlushMode, type CodexCompatConfig, type CodexConnectorConfig, type CodingContext, type CodingModeConfig, type CompressionGuidelineActivationState, type CompressionGuidelineOptimizerActionSummary, type CompressionGuidelineOptimizerEventCounts, type CompressionGuidelineOptimizerRuleUpdate, type CompressionGuidelineOptimizerSourceWindow, type CompressionGuidelineOptimizerState, type ConfidenceTier, type ConsolidationAction, type ConsolidationItem, type ConsolidationObservation, type ConsolidationResult, type ContinuityImprovementLoop, type ContinuityIncidentCloseInput, type ContinuityIncidentOpenInput, type ContinuityIncidentRecord, type ContinuityIncidentState, type ContinuityLoopCadence, type ContinuityLoopReviewInput, type ContinuityLoopStatus, type ContinuityLoopUpsertInput, type ContradictionScanConfig, type ConversationThread, type CronConversationRecallMode, type CronRecallMode, DEFAULT_RECALL_DISCLOSURE, type DaySummaryResult, type DreamingConfig, type DreamingNarrativePromptStyle, type DreamsDeepSleepConfig, type DreamsLightSleepConfig, type DreamsPhase, type DreamsPhaseStatus, type DreamsPhasesConfig, type DreamsRemConfig, type DreamsRunResult, type DreamsStatusResult, type EngramTraceEvent, type EntityActivityEntry, type EntityFile, type EntityMention, type EntityRelationship, type EntitySchemaDefinition, type EntitySchemaSectionDefinition, type EntityStructuredSection, type EntityTimelineEntry, type ExtractedFact, type ExtractedProcedureStep, type ExtractedQuestion, type ExtractedReasoningTrace, type ExtractedReasoningTraceStep, type ExtractedRelationship, type ExtractionPassSource, type ExtractionResult, type FileHygieneConfig, type GatewayConfig, type GitHubLiveConnectorConfig, type GmailLiveConnectorConfig, type GoogleDriveLiveConnectorConfig, type HeartbeatConfig, type HeartbeatDetectionMode, type HourlySummary, type IdentityInjectionMode, type ImportanceLevel, type ImportanceScore, type LifecycleState, type LiveConnectorsConfig, type LlmTraceCallback, type LlmTraceEvent, type MemoryActionEligibilityContext, type MemoryActionEligibilitySource, type MemoryActionEvent, type MemoryActionOutcome, type MemoryActionPolicyDecision, type MemoryActionPolicyResult, type MemoryActionStatus, type MemoryActionType, type MemoryCategory, type MemoryFile, type MemoryFrontmatter, type MemoryIntent, type MemoryLifecycleEvent, type MemoryLifecycleEventType, type MemoryLifecycleStateSummary, type MemoryLink, type MemoryLinkType, type MemoryObservation, type MemoryOsPresetName, type MemoryProjectionCurrentState, type MemoryScope, type MemoryStatus, type MemorySummary, type MetaState, type ModelApi, type ModelDefinitionConfig, type ModelProviderAuthMode, type ModelProviderConfig, type NamespacePolicy, type NativeKnowledgeConfig, type NativeKnowledgeFolderRuleConfig, type NativeKnowledgeObsidianVaultConfig, type NativeKnowledgeOpenClawWorkspaceConfig, type NotionLiveConnectorConfig, type PluginConfig, type PolicyClass, type PrincipalFromSessionKeyMode, type PrincipalRule, type ProceduralConfig, type QmdSearchExplain, type QmdSearchResult, type QuestionEntry, RECALL_DISCLOSURE_LEVELS, type ReasoningEffort, type RecallDisclosure, type RecallPipelineConfig, type RecallPlanMode, type RecallSectionConfig, type RecallTierExplain, type RecallTraceEvent, type RelevanceFeedback, type RetrievalTier, SPECULATIVE_TTL_DAYS, type ScoredEntity, type SecretRef, type SemanticChunkingConfigShape, type SessionObserverBandConfig, type SignalLevel, type SignalScanResult, type SlotBehaviorConfig, type SlotMismatchMode, type TopicScore, type TranscriptEntry, type TriggerMode, type VerificationState, confidenceTier, isRecallDisclosure };