@remnic/core 1.0.2 → 1.1.0

package/dist/types.d.ts

@@ -1,7 +1,7 @@
 type ReasoningEffort = "none" | "low" | "medium" | "high";
 type TriggerMode = "smart" | "every_n" | "time_based";
 type SignalLevel = "none" | "low" | "medium" | "high";
-type MemoryCategory = "fact" | "preference" | "correction" | "entity" | "decision" | "relationship" | "principle" | "commitment" | "moment" | "skill" | "rule";
+type MemoryCategory = "fact" | "preference" | "correction" | "entity" | "decision" | "relationship" | "principle" | "commitment" | "moment" | "skill" | "rule" | "procedure";
 type ConsolidationAction = "ADD" | "MERGE" | "UPDATE" | "INVALIDATE" | "SKIP";
 type ConfidenceTier = "explicit" | "implied" | "inferred" | "speculative";
 type PrincipalFromSessionKeyMode = "map" | "prefix" | "regex";
@@ -12,6 +12,42 @@ type IdentityInjectionMode = "recovery_only" | "minimal" | "full";
 type CaptureMode = "implicit" | "explicit" | "hybrid";
 type MemoryOsPresetName = "conservative" | "balanced" | "research-max" | "local-llm-heavy";
 type ExtractionPassSource = "base" | "proactive";
+type SlotMismatchMode = "error" | "warn" | "silent";
+type CodexCompactionFlushMode = "signal" | "heuristic" | "auto";
+type DreamingNarrativePromptStyle = "reflective" | "diary" | "analytical";
+type HeartbeatDetectionMode = "runtime-signal" | "heuristic" | "auto";
+type ActiveRecallQueryMode = "message" | "recent" | "full";
+type ActiveRecallPromptStyle = "balanced" | "strict" | "contextual" | "recall-heavy" | "precision-heavy" | "preference-only";
+type ActiveRecallThinking = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "adaptive";
+type ActiveRecallChatType = "direct" | "group" | "channel";
+type ActiveRecallModelFallbackPolicy = "default-remote" | "resolved-only";
+/**
+ * Retrieval tier ladder (issue #518).  Identifies which tier served a recall
+ * result.  Ordered top-to-bottom by cost, but routing is not strictly
+ * sequential — callers may jump straight to a lower tier when eligibility
+ * does not hold.
+ */
+type RetrievalTier = "exact-cache" | "fuzzy-cache" | "direct-answer" | "hybrid" | "rerank-graph" | "agentic";
+/**
+ * Per-recall annotation describing which retrieval tier served a result,
+ * why that tier was chosen, and what was filtered along the way.  Added as
+ * part of issue #518 (direct-answer tier + `query --explain`).
+ *
+ * Not to be confused with the existing `recallExplain` operation
+ * (graph-path explanation) — that is a user-invoked RPC; this is a
+ * per-result annotation that can be attached to any recall response.
+ */
+interface RecallTierExplain {
+    tier: RetrievalTier;
+    tierReason: string;
+    filteredBy: string[];
+    candidatesConsidered: number;
+    latencyMs: number;
+    sourceAnchors?: Array<{
+        path: string;
+        lineRange?: [number, number];
+    }>;
+}
 interface RecallSectionConfig {
     id: string;
     enabled?: boolean;
@@ -103,9 +139,82 @@ interface AgentAccessHttpConfig {
     principal?: string;
     maxBodyBytes: number;
 }
+interface DreamingConfig {
+    enabled: boolean;
+    journalPath: string;
+    maxEntries: number;
+    injectRecentCount: number;
+    minIntervalMinutes: number;
+    narrativeModel: string | null;
+    narrativePromptStyle: DreamingNarrativePromptStyle;
+    watchFile: boolean;
+}
+/** Procedural memory (issue #519): mining + recall gates. All sub-features default off. */
+interface ProceduralConfig {
+    enabled: boolean;
+    /** Minimum cluster size before emitting a candidate; `0` disables mining (`minOccurrences_zero`). */
+    minOccurrences: number;
+    /** Minimum success rate from trajectory outcomes in [0, 1]. */
+    successFloor: number;
+    /** When auto-promotion is enabled, promote pending_review → active after this many occurrences. */
+    autoPromoteOccurrences: number;
+    autoPromoteEnabled: boolean;
+    lookbackDays: number;
+    /** When true, installer may register the nightly procedural mining cron (default off). */
+    proceduralMiningCronAutoRegister: boolean;
+    /** Max procedure memories to inject on task-initiation recall (1–10). */
+    recallMaxProcedures: number;
+}
+/** Configuration for the nightly contradiction-scan cron (issue #520). */
+interface ContradictionScanConfig {
+    /** Master switch for the contradiction scan cron. Default true. */
+    enabled: boolean;
+    /** Embedding cosine similarity floor for candidate pair generation. Default 0.82. */
+    similarityFloor: number;
+    /** Minimum topic-token Jaccard overlap for unstructured pairs. Default 0.4. */
+    topicOverlapFloor: number;
+    /** Cap on candidate pairs evaluated per cron run. Default 500. */
+    maxPairsPerRun: number;
+    /** Cooldown in days before re-evaluating a pair judged independent/both-valid. Default 14. */
+    cooldownDays: number;
+    /** When true, pairs judged "duplicates" are auto-flagged for dedup (still need user approval). Default false. */
+    autoMergeDuplicates: boolean;
+}
+interface HeartbeatConfig {
+    enabled: boolean;
+    journalPath: string;
+    maxPreviousRuns: number;
+    watchFile: boolean;
+    detectionMode: HeartbeatDetectionMode;
+    gateExtractionDuringHeartbeat: boolean;
+}
+interface SlotBehaviorConfig {
+    requireExclusiveMemorySlot: boolean;
+    onSlotMismatch: SlotMismatchMode;
+}
+interface CodexCompatConfig {
+    enabled: boolean;
+    threadIdBufferKeying: boolean;
+    compactionFlushMode: CodexCompactionFlushMode;
+    fingerprintDedup: boolean;
+}
 declare function confidenceTier(score: number): ConfidenceTier;
 /** Default TTL in days for speculative memories (auto-expire if unconfirmed) */
 declare const SPECULATIVE_TTL_DAYS = 30;
+/**
+ * Shape for semantic chunking config overrides stored in PluginConfig.
+ * Mirrors SemanticChunkingConfig from semantic-chunking.ts without creating
+ * a circular import (types.ts is imported by everything).
+ */
+interface SemanticChunkingConfigShape {
+    targetTokens: number;
+    minTokens: number;
+    maxTokens: number;
+    smoothingWindowSize: number;
+    boundaryThresholdStdDevs: number;
+    embeddingBatchSize: number;
+    fallbackToRecursive: boolean;
+}
 interface PluginConfig {
     openaiApiKey: string | undefined;
     openaiBaseUrl: string | undefined;
@@ -181,10 +290,54 @@ interface PluginConfig {
     chunkingTargetTokens: number;
     chunkingMinTokens: number;
     chunkingOverlapSentences: number;
+    /** Enable semantic chunking with embedding-based topic boundary detection. Default: false. */
+    semanticChunkingEnabled: boolean;
+    /** Optional overrides for the semantic chunking algorithm. */
+    semanticChunkingConfig: Partial<SemanticChunkingConfigShape>;
     contradictionDetectionEnabled: boolean;
     contradictionSimilarityThreshold: number;
     contradictionMinConfidence: number;
     contradictionAutoResolve: boolean;
+    /** Nightly contradiction-scan cron config (issue #520). */
+    contradictionScan: ContradictionScanConfig;
+    /**
+     * When enabled, writes that carry `structuredAttributes` mark any older
+     * fact with the same `entityRef + attribute_name` supersession key and a
+     * conflicting value as `status: "superseded"`.
+     */
+    temporalSupersessionEnabled: boolean;
+    /**
+     * When enabled, superseded memories are still returned by recall (useful
+     * for audit/history queries).  Default: false — superseded memories are
+     * filtered out.
+     */
+    temporalSupersessionIncludeInRecall: boolean;
+    /**
+     * When true, recall checks whether a single validated memory in a
+     * high-trust taxonomy bucket can answer the query before invoking QMD.
+     * Default false — enable explicitly after bench validation.
+     */
+    recallDirectAnswerEnabled: boolean;
+    /**
+     * Minimum token-overlap ratio (query tokens ∩ memory tokens / query tokens)
+     * required for direct-answer eligibility.  Set to 0 to disable the gate.
+     */
+    recallDirectAnswerTokenOverlapFloor: number;
+    /**
+     * Minimum calibrated importance score required for direct-answer
+     * eligibility.  Set to 0 to disable the gate.
+     */
+    recallDirectAnswerImportanceFloor: number;
+    /**
+     * Ambiguity margin: if the second-best candidate scores within this
+     * ratio of the top candidate, direct-answer defers to the hybrid tier.
+     */
+    recallDirectAnswerAmbiguityMargin: number;
+    /**
+     * Taxonomy category IDs eligible for direct-answer routing.  Memories
+     * whose resolved taxonomy category is not in this list never qualify.
+     */
+    recallDirectAnswerEligibleTaxonomyBuckets: string[];
     memoryLinkingEnabled: boolean;
     threadingEnabled: boolean;
     threadingGapMinutes: number;
@@ -205,6 +358,53 @@ interface PluginConfig {
     checkpointEnabled: boolean;
     checkpointTurns: number;
     compactionResetEnabled: boolean;
+    beforeResetTimeoutMs: number;
+    flushOnResetEnabled: boolean;
+    commandsListEnabled: boolean;
+    openclawToolsEnabled: boolean;
+    openclawToolSnippetMaxChars: number;
+    sessionTogglesEnabled: boolean;
+    verboseRecallVisibility: boolean;
+    recallTranscriptsEnabled: boolean;
+    recallTranscriptRetentionDays: number;
+    respectBundledActiveMemoryToggle: boolean;
+    activeRecallEnabled: boolean;
+    activeRecallAgents: string[] | null;
+    activeRecallAllowedChatTypes: ActiveRecallChatType[];
+    activeRecallQueryMode: ActiveRecallQueryMode;
+    activeRecallPromptStyle: ActiveRecallPromptStyle;
+    activeRecallPromptOverride: string | null;
+    activeRecallPromptAppend: string | null;
+    activeRecallMaxSummaryChars: number;
+    activeRecallRecentUserTurns: number;
+    activeRecallRecentAssistantTurns: number;
+    activeRecallRecentUserChars: number;
+    activeRecallRecentAssistantChars: number;
+    activeRecallThinking: ActiveRecallThinking;
+    activeRecallTimeoutMs: number;
+    activeRecallCacheTtlMs: number;
+    activeRecallModel: string | null;
+    activeRecallModelFallbackPolicy: ActiveRecallModelFallbackPolicy;
+    activeRecallPersistTranscripts: boolean;
+    activeRecallTranscriptDir: string;
+    activeRecallEntityGraphDepth: number;
+    activeRecallIncludeCausalTrajectories: boolean;
+    activeRecallIncludeDaySummary: boolean;
+    activeRecallAttachRecallExplain: boolean;
+    activeRecallAllowChainedActiveMemory: boolean;
+    dreaming: DreamingConfig;
+    procedural: ProceduralConfig;
+    heartbeat: HeartbeatConfig;
+    slotBehavior: SlotBehaviorConfig;
+    codexCompat: CodexCompatConfig;
+    /** 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. */
+    extractionJudgeModel: string;
+    /** Maximum number of candidate facts per judge LLM batch call. */
+    extractionJudgeBatchSize: number;
+    /** Shadow mode: log judge verdicts but do not filter facts. Default false. */
+    extractionJudgeShadow: boolean;
     hourlySummariesEnabled: boolean;
     daySummaryEnabled: boolean;
     /** If true, Engram may attempt to auto-register an hourly summary cron job (default off). */
@@ -336,6 +536,29 @@ interface PluginConfig {
     extractionMaxEntitiesPerRun: number;
     extractionMaxQuestionsPerRun: number;
     extractionMaxProfileUpdatesPerRun: number;
+    /**
+     * Minimum importance level required to persist an extracted fact. Facts
+     * whose locally-scored level falls below this threshold are dropped before
+     * write and counted toward the `importance_gated` metric. Defaults to
+     * "low" so trivial content (greetings, single-word replies, filler) is
+     * silently dropped while everything else still passes.
+     */
+    extractionMinImportanceLevel: ImportanceLevel;
+    /**
+     * Inline source attribution (issue #369).
+     * When enabled, extracted facts carry a compact provenance tag (agent,
+     * session, timestamp) inlined into the fact text — not just in YAML
+     * frontmatter — so the citation survives prompt injection, copy/paste,
+     * and LLM quoting. Off by default to preserve backwards compatibility
+     * with existing downstream consumers that expect raw fact text.
+     */
+    inlineSourceAttributionEnabled: boolean;
+    /**
+     * Template used when injecting inline citations. Supported placeholders:
+     * `{agent}`, `{session}`, `{sessionId}`, `{ts}`, `{date}`. Defaults to
+     * `[Source: agent={agent}, session={sessionId}, ts={ts}]`.
+     */
+    inlineSourceAttributionFormat: string;
     consolidationRequireNonZeroExtraction: boolean;
     consolidationMinIntervalMs: number;
     qmdMaintenanceEnabled: boolean;
@@ -352,6 +575,21 @@ interface PluginConfig {
     localLlmFastModel: string;
     localLlmFastUrl: string;
     localLlmFastTimeoutMs: number;
+    /**
+     * Suppress chain-of-thought / thinking mode on the main local LLM
+     * (issue #548).  When true, Remnic injects
+     * `chat_template_kwargs: { enable_thinking: false }` on every
+     * request so thinking-capable models (Qwen 3.5, Gemma 4, DeepSeek,
+     * etc.) skip reasoning tokens that structured-output tasks like
+     * extraction and consolidation cannot benefit from.  Default: true
+     * — the dominant localLlm use case is JSON-shaped extraction where
+     * thinking is pure latency tax and a common cause of 60s timeouts.
+     * Set to false to restore thinking for narrative tasks.
+     *
+     * The fast-tier client (`fastLlm`) always disables thinking; that
+     * contract is baked into "fast tier" and is unaffected by this flag.
+     */
+    localLlmDisableThinking: boolean;
     gatewayConfig?: GatewayConfig;
     modelSource: "plugin" | "gateway";
     gatewayAgentId: string;
@@ -440,11 +678,18 @@ interface PluginConfig {
     entityRetrievalMaxSupportingFacts: number;
     entityRetrievalMaxRelatedEntities: number;
     entityRetrievalRecentTurns: number;
+    entitySchemas?: Record<string, EntitySchemaDefinition>;
     recallBudgetChars: number;
     recallOuterTimeoutMs: number;
     recallCoreDeadlineMs: number;
     recallEnrichmentDeadlineMs: number;
     recallPipeline: RecallSectionConfig[];
+    /** Apply Maximal Marginal Relevance to the final recall selection per-section. */
+    recallMmrEnabled: boolean;
+    /** MMR λ parameter. 1.0 = pure relevance, 0.0 = pure diversity. Default 0.7. */
+    recallMmrLambda: number;
+    /** MMR is applied over the top N candidates per section. Default 40. */
+    recallMmrTopN: number;
     qmdRecallCacheTtlMs: number;
     qmdRecallCacheStaleTtlMs: number;
     qmdRecallCacheMaxEntries: number;
@@ -453,8 +698,22 @@ interface PluginConfig {
     entityActivityLogMaxEntries: number;
     entityAliasesEnabled: boolean;
     entitySummaryEnabled: boolean;
+    entitySynthesisMaxTokens: number;
     /** Enable content-hash deduplication to prevent storing semantically identical facts. */
     factDeduplicationEnabled: boolean;
+    /**
+     * Issue #373 — Write-time semantic similarity guard. When enabled (default),
+     * the orchestrator embeds each candidate fact and queries the existing
+     * embedding index for its top-K nearest neighbors. If the best cosine
+     * similarity is at or above `semanticDedupThreshold`, the fact is dropped
+     * as a near-duplicate. Fails open (keeps the fact) if the embedding backend
+     * is unavailable.
+     */
+    semanticDedupEnabled: boolean;
+    /** Cosine similarity threshold in [0, 1] above which a candidate fact is skipped. */
+    semanticDedupThreshold: number;
+    /** Number of nearest-neighbor candidates to consider during semantic dedup. */
+    semanticDedupCandidates: number;
     /** Enable automatic archival of old, low-importance, rarely-accessed facts. */
     factArchivalEnabled: boolean;
     /** Minimum age in days before a fact is eligible for archival. */
@@ -627,6 +886,187 @@ interface PluginConfig {
     };
     /** Max results fetched per agent before merge. */
     parallelMaxResultsPerAgent: number;
+    /** Briefing configuration knobs — see BriefingConfig for field docs. */
+    briefing: BriefingConfig;
+    codex: CodexConnectorConfig;
+    /** Enable the MECE taxonomy knowledge directory. Default false. */
+    taxonomyEnabled: boolean;
+    /** Auto-regenerate RESOLVER.md when taxonomy changes. Default true. */
+    taxonomyAutoGenResolver: boolean;
+    /** Materialize Remnic memories into Codex's expected ~/.codex/memories/ layout. Default true. */
+    codexMaterializeMemories: boolean;
+    /** Namespace to materialize; "auto" derives from the connector context. Default "auto". */
+    codexMaterializeNamespace: string;
+    /** Max whitespace-tokenized size of memory_summary.md. Default 4500. */
+    codexMaterializeMaxSummaryTokens: number;
+    /** Max age in days for rollout_summaries/*.md before pruning. Default 30. */
+    codexMaterializeRolloutRetentionDays: number;
+    /** Run materialization after semantic/causal consolidation completes. Default true. */
+    codexMaterializeOnConsolidation: boolean;
+    /** Run materialization at Codex session-end hook. Default true. */
+    codexMaterializeOnSessionEnd: boolean;
+    /** Enable Codex marketplace integration. Default true. */
+    codexMarketplaceEnabled: boolean;
+    /** Enable page-level versioning with sidecar snapshots. Default false. */
+    versioningEnabled: boolean;
+    /** Maximum number of version snapshots to keep per page. Default 50. Set to 0 to disable pruning. */
+    versioningMaxPerPage: number;
+    /** Name of the sidecar directory inside memoryDir. Default ".versions". */
+    versioningSidecarDir: string;
+    /** Enable binary file lifecycle management (mirror, redirect, clean). Default: false. */
+    binaryLifecycleEnabled: boolean;
+    /** Grace period in days before a mirrored binary is eligible for local cleanup. Default: 7. */
+    binaryLifecycleGracePeriodDays: number;
+    /** Storage backend type: "filesystem" copies to a local dir, "none" is no-op. Default: "none". */
+    binaryLifecycleBackendType: "filesystem" | "s3" | "none";
+    /** Base path for the filesystem backend. Required when backendType is "filesystem". */
+    binaryLifecycleBackendPath: string;
+    /** Enable oai-mem-citation blocks in recall responses. Default false. */
+    citationsEnabled: boolean;
+    /** Auto-enable citations when the Codex adapter is detected. Default true. */
+    citationsAutoDetect: boolean;
+    /** Enable the external enrichment pipeline. Default false. */
+    enrichmentEnabled: boolean;
+    /** Automatically enrich new entities on creation. Default false. */
+    enrichmentAutoOnCreate: boolean;
+    /** Max candidates accepted per entity per enrichment run. Default 20. */
+    enrichmentMaxCandidatesPerEntity: number;
+    /** Whether third-party memory extensions are discovered and injected into consolidation. Default true. */
+    memoryExtensionsEnabled: boolean;
+    /**
+     * Root directory for memory extensions. Empty string means derive from
+     * memoryDir: go up to the Remnic home dir and append memory_extensions.
+     */
+    memoryExtensionsRoot: string;
+}
+/** Runtime configuration for the daily context briefing feature. */
+interface BriefingConfig {
+    /** Whether `remnic briefing` CLI and MCP tool are enabled. */
+    enabled: boolean;
+    /** Default lookback window token (e.g. "yesterday", "3d", "1w", "24h"). */
+    defaultWindow: string;
+    /** Default output format for the CLI. */
+    defaultFormat: "markdown" | "json";
+    /** Maximum number of LLM-generated suggested follow-ups. */
+    maxFollowups: number;
+    /** Optional path to an ICS or JSON calendar file. null disables the section. */
+    calendarSource: string | null;
+    /** If true, CLI writes a dated briefing file by default. */
+    saveByDefault: boolean;
+    /** Override directory for saved briefings. null → $REMNIC_HOME/briefings/. */
+    saveDir: string | null;
+    /** Whether to call the Responses API for follow-up suggestions. */
+    llmFollowups: boolean;
+}
+/** Parsed representation of a briefing lookback window. */
+type BriefingWindow = "yesterday" | "today" | string;
+/** Filter the briefing to a single entity / project / topic. */
+interface BriefingFocus {
+    type: "person" | "project" | "topic";
+    value: string;
+}
+/** Calendar event surfaced by a CalendarSource implementation. */
+interface CalendarEvent {
+    /** Stable identifier for dedupe / linking. */
+    id: string;
+    /** Event title (short). */
+    title: string;
+    /** ISO 8601 start timestamp. */
+    start: string;
+    /** Optional ISO 8601 end timestamp. */
+    end?: string;
+    /** Optional freeform location. */
+    location?: string;
+    /** Optional short notes. */
+    notes?: string;
+}
+/** Abstraction over any calendar backend. Concrete implementations: `FileCalendarSource`. */
+interface CalendarSource {
+    /** Return events that fall on the given UTC date (YYYY-MM-DD). */
+    eventsForDate(dateIso: string): Promise<CalendarEvent[]>;
+}
+/** A single "active thread" surfaced in a briefing. */
+interface BriefingActiveThread {
+    id: string;
+    title: string;
+    updatedAt: string;
+    reason: string;
+}
+/** A single "recent entity" entry. */
+interface BriefingRecentEntity {
+    name: string;
+    type: string;
+    updatedAt: string;
+    score: number;
+    summary?: string;
+}
+/** A single unresolved commitment or open question. */
+interface BriefingOpenCommitment {
+    id: string;
+    kind: "question" | "commitment" | "pending_memory";
+    text: string;
+    source?: string;
+    createdAt?: string;
+}
+/** An LLM-generated short follow-up suggestion. */
+interface BriefingFollowup {
+    text: string;
+    rationale?: string;
+}
+/** Structured sections of a briefing result. */
+interface BriefingSections {
+    activeThreads: BriefingActiveThread[];
+    recentEntities: BriefingRecentEntity[];
+    openCommitments: BriefingOpenCommitment[];
+    suggestedFollowups: BriefingFollowup[];
+    /** Only populated when a calendar source is configured and returns events. */
+    todayCalendar?: CalendarEvent[];
+}
+/** A calendar source failure recorded when a CalendarSource throws during briefing generation. */
+interface BriefingCalendarSourceError {
+    /** Human-readable description of the source (e.g. file path or source name). */
+    source: string;
+    /** Stringified error message from the failed source. */
+    error: string;
+}
+/** Result returned by `buildBriefing`. */
+interface BriefingResult {
+    markdown: string;
+    json: Record<string, unknown>;
+    sections: BriefingSections;
+    /** Reason why suggested follow-ups were omitted (e.g. missing API key, LLM error). */
+    followupsUnavailableReason?: string;
+    /** Effective lookback window (ISO date range) used for this briefing. */
+    window: {
+        from: string;
+        to: string;
+    };
+    /**
+     * Calendar sources that failed during this briefing run.
+     * Only present (non-empty) when at least one source threw.
+     * Allows callers to distinguish "no events today" from "source unavailable".
+     */
+    calendarSourceErrors?: BriefingCalendarSourceError[];
+}
+/**
+ * Settings for the Codex CLI connector. These are consumed by
+ * `remnic connectors install codex-cli` to decide where the phase-2 memory
+ * extension is dropped and whether to install it at all.
+ */
+interface CodexConnectorConfig {
+    /**
+     * Whether to install the Remnic memory extension into
+     * `<codex_home>/memories_extensions/remnic/` when the `codex-cli`
+     * connector is installed. Default `true`. Set to `false` for users who
+     * self-manage the Codex memory extensions folder.
+     */
+    installExtension: boolean;
+    /**
+     * Optional override for the Codex home directory. When `null`, the
+     * connector reads `$CODEX_HOME` and falls back to `~/.codex`. Setting
+     * this is useful for integration tests and non-default installs.
+     */
+    codexHome: string | null;
 }
 interface BootstrapOptions {
     dryRun?: boolean;
@@ -662,11 +1102,21 @@ interface BufferTurn {
     content: string;
     timestamp: string;
     sessionKey?: string;
+    logicalSessionKey?: string;
+    providerThreadId?: string | null;
+    turnFingerprint?: string;
+    persistProcessedFingerprint?: boolean;
+}
+interface BufferEntryState {
+    turns: BufferTurn[];
+    lastExtractionAt: string | null;
+    extractionCount: number;
 }
 interface BufferState {
     turns: BufferTurn[];
     lastExtractionAt: string | null;
     extractionCount: number;
+    entries?: Record<string, BufferEntryState>;
 }
 interface BehaviorLoopAdjustment {
     parameter: string;
@@ -774,9 +1224,20 @@ interface MemoryFrontmatter {
     sourceMemoryId?: string;
     sourceTurnId?: string;
     /** episode = time-specific event; note = stable belief/preference/decision */
-    memoryKind?: "episode" | "note";
+    memoryKind?: "episode" | "note" | "box" | "dream" | "procedural";
     /** Structured key-value attributes extracted from the content (e.g., product attributes, dates, quantities). */
     structuredAttributes?: Record<string, string>;
+    /**
+     * SHA-256 (via ContentHashIndex.computeHash) of the raw content that was
+     * used as the dedup key at write time. Persists through archive and
+     * consolidation so the hash can be removed from the index even if the stored
+     * content has been transformed (e.g. an inline citation was appended).
+     *
+     * When present, archive/consolidation paths use this directly instead of
+     * calling stripCitation(memory.content), which only handles the default
+     * [Source: ...] format and silently fails for custom citation templates.
+     */
+    contentHash?: string;
 }
 /** Memory link relationship types */
 type MemoryLinkType = "follows" | "references" | "contradicts" | "supports" | "related";
@@ -822,6 +1283,17 @@ interface MemoryFile {
     frontmatter: MemoryFrontmatter;
     content: string;
 }
+/** Ordered step for extracted procedure memories (issue #519). */
+interface ExtractedProcedureStep {
+    order: number;
+    intent: string;
+    toolCall?: {
+        kind: string;
+        signature: string;
+    };
+    expectedOutcome?: string;
+    optional?: boolean;
+}
 interface ExtractedFact {
     category: MemoryCategory;
     content: string;
@@ -832,11 +1304,15 @@ interface ExtractedFact {
     promptedByQuestion?: string;
     /** 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/). */
+    procedureSteps?: ExtractedProcedureStep[];
 }
 interface MemoryIntent {
     goal: string;
     actionType: string;
     entityTypes: string[];
+    /** True when the prompt reads like starting a concrete task (ship/deploy/tests/PR, etc.). */
+    taskInitiation?: boolean;
 }
 interface ExtractedQuestion {
     question: string;
@@ -864,6 +1340,7 @@ interface EntityMention {
     name: string;
     type: "person" | "project" | "tool" | "company" | "place" | "other";
     facts: string[];
+    structuredSections?: EntityStructuredSection[];
     source?: ExtractionPassSource;
     promptedByQuestion?: string;
 }
@@ -875,15 +1352,51 @@ interface EntityActivityEntry {
     date: string;
     note: string;
 }
+interface EntityTimelineEntry {
+    timestamp: string;
+    text: string;
+    source?: string;
+    sessionKey?: string;
+    principal?: string;
+}
+interface EntityStructuredSection {
+    key: string;
+    title: string;
+    facts: string[];
+}
+interface EntitySchemaSectionDefinition {
+    key: string;
+    title: string;
+    description: string;
+    aliases?: string[];
+}
+interface EntitySchemaDefinition {
+    sections: EntitySchemaSectionDefinition[];
+}
 interface EntityFile {
     name: string;
     type: string;
+    created?: string;
     updated: string;
+    extraFrontmatterLines?: string[];
+    preSectionLines?: string[];
     facts: string[];
     summary?: string;
+    synthesis?: string;
+    synthesisUpdatedAt?: string;
+    synthesisTimelineCount?: number;
+    synthesisStructuredFactCount?: number;
+    synthesisStructuredFactDigest?: string;
+    synthesisVersion?: number;
+    timeline: EntityTimelineEntry[];
+    structuredSections?: EntityStructuredSection[];
     relationships: EntityRelationship[];
     activity: EntityActivityEntry[];
     aliases: string[];
+    extraSections?: Array<{
+        title: string;
+        lines: string[];
+    }>;
 }
 interface ScoredEntity {
     name: string;
@@ -912,6 +1425,15 @@ interface ConsolidationResult {
     profileUpdates: string[];
     entityUpdates: EntityMention[];
 }
+interface ConsolidationObservation {
+    runAt: string;
+    recentMemories: MemoryFile[];
+    existingMemories: MemoryFile[];
+    profile: string;
+    result: ConsolidationResult;
+    merged: number;
+    invalidated: number;
+}
 interface QmdSearchResult {
     docid: string;
     path: string;
@@ -933,6 +1455,10 @@ interface MetaState {
     lastConsolidationAt: string | null;
     totalMemories: number;
     totalEntities: number;
+    processedExtractionFingerprints?: Array<{
+        fingerprint: string;
+        observedAt: string;
+    }>;
 }
 type MemoryActionType = "store_episode" | "store_note" | "update_note" | "create_artifact" | "summarize_node" | "discard" | "link_graph";
 type MemoryActionOutcome = "applied" | "skipped" | "failed";
@@ -1240,4 +1766,4 @@ interface HourlySummary {
     generatedAt: string;
 }
 
-export { type AccessTrackingEntry, type AgentAccessHttpConfig, type AgentDefaultsConfig, type AgentPersona, type AgentPersonaModelConfig, type BehaviorLoopAdjustment, type BehaviorLoopPolicyState, type BehaviorSignalDirection, type BehaviorSignalEvent, type BehaviorSignalType, type BootstrapOptions, type BootstrapResult, type BufferState, type BufferTurn, type CaptureMode, type Checkpoint, type CompressionGuidelineActivationState, type CompressionGuidelineOptimizerActionSummary, type CompressionGuidelineOptimizerEventCounts, type CompressionGuidelineOptimizerRuleUpdate, type CompressionGuidelineOptimizerSourceWindow, type CompressionGuidelineOptimizerState, type ConfidenceTier, type ConsolidationAction, type ConsolidationItem, type ConsolidationResult, type ContinuityImprovementLoop, type ContinuityIncidentCloseInput, type ContinuityIncidentOpenInput, type ContinuityIncidentRecord, type ContinuityIncidentState, type ContinuityLoopCadence, type ContinuityLoopReviewInput, type ContinuityLoopStatus, type ContinuityLoopUpsertInput, type ConversationThread, type CronConversationRecallMode, type CronRecallMode, type DaySummaryResult, type EngramTraceEvent, type EntityActivityEntry, type EntityFile, type EntityMention, type EntityRelationship, type ExtractedFact, type ExtractedQuestion, type ExtractedRelationship, type ExtractionPassSource, type ExtractionResult, type FileHygieneConfig, type GatewayConfig, 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 QmdSearchExplain, type QmdSearchResult, type QuestionEntry, type ReasoningEffort, type RecallPipelineConfig, type RecallPlanMode, type RecallSectionConfig, type RecallTraceEvent, type RelevanceFeedback, SPECULATIVE_TTL_DAYS, type ScoredEntity, type SessionObserverBandConfig, type SignalLevel, type SignalScanResult, type TopicScore, type TranscriptEntry, type TriggerMode, type VerificationState, confidenceTier };
+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 BufferTurn, type CalendarEvent, type CalendarSource, type CaptureMode, type Checkpoint, type CodexCompactionFlushMode, type CodexCompatConfig, type CodexConnectorConfig, 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 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 };