@remnic/core 1.0.3 → 1.1.0

package/dist/access-service-HmO1Trrx.d.ts

@@ -0,0 +1,732 @@
+import { DaySummaryResult, RecallPlanMode, MemoryFile, MemoryLifecycleEvent, EntityFile, MemoryStatus, PluginConfig } from './types.js';
+import { ExplicitCaptureInput } from './explicit-capture.js';
+import { r as readMemoryGovernanceRunArtifact } from './memory-projection-store-DeSXPh1j.js';
+import { LastRecallSnapshot } from './recall-state.js';
+import { O as Orchestrator, I as IntentDebugSnapshot, G as GraphRecallSnapshot } from './orchestrator-DRYA6_lW.js';
+import { StorageManager } from './storage.js';
+import { TrustZoneStoreStatus, TrustZoneName, TrustZoneRecordKind, TrustZoneSourceClass, TrustZoneProvenanceScore, TrustZonePromotionResult, TrustZoneDemoSeedResult } from './trust-zones.js';
+import { LocalLlmClient } from './local-llm.js';
+import { FallbackLlmClient } from './fallback-llm.js';
+
+/**
+ * @remnic/core — Write-time semantic dedup guard
+ *
+ * Complements the exact content-hash check in the orchestrator's write path
+ * by detecting near-duplicate candidate facts via embedding cosine similarity.
+ *
+ * The module intentionally has no dependency on the EmbeddingFallback or QMD
+ * classes directly — callers pass in a `lookup` function that returns the
+ * top-K nearest neighbors with their cosine scores. This keeps the decision
+ * logic pure and trivially testable with synthetic fixtures, and lets the
+ * orchestrator reuse whichever backend it already has wired up.
+ *
+ * Related issue: joshuaswarren/remnic#373
+ */
+/** A single nearest-neighbor hit from the embedding backend. */
+interface SemanticDedupHit {
+    /** Memory id of the existing neighbor. */
+    id: string;
+    /** Cosine similarity score in [0, 1]. */
+    score: number;
+    /** Optional source path, purely informational. */
+    path?: string;
+}
+/**
+ * Lookup function passed by the caller. Must return an array of hits sorted
+ * descending by score. Implementations should return an empty array (never
+ * throw) when the embedding backend is unavailable — the decision function
+ * treats that as "no near duplicate" (fail-open).
+ */
+type SemanticDedupLookup = (content: string, limit: number) => Promise<SemanticDedupHit[]>;
+interface SemanticDedupOptions {
+    /** Master switch. When false, `decideSemanticDedup` always returns `keep`. */
+    enabled: boolean;
+    /** Cosine similarity threshold (0-1). ≥ threshold ⇒ treat as duplicate. */
+    threshold: number;
+    /** How many nearest neighbors to compare against. */
+    candidates: number;
+}
+type SemanticDedupDecision = {
+    action: "keep";
+    reason: "disabled" | "backend_unavailable" | "no_candidates" | "no_near_duplicate";
+    topScore?: number;
+    topId?: string;
+} | {
+    action: "skip";
+    reason: "near_duplicate";
+    topScore: number;
+    topId: string;
+    topPath?: string;
+};
+/**
+ * Pure decision function: given a lookup callback and options, decide whether
+ * the candidate content should be written or skipped as a near-duplicate.
+ *
+ * Contract:
+ *   - When `options.enabled` is false → always keep, reason="disabled".
+ *   - When the lookup throws (provider down / network error) → keep,
+ *     reason="backend_unavailable". Fail-open: a lookup failure must not block
+ *     writes.
+ *   - When the lookup succeeds but returns 0 hits (empty index or no
+ *     neighbors above the score floor) → keep, reason="no_candidates".
+ *     This is distinct from backend_unavailable so telemetry dashboards can
+ *     correctly distinguish "provider is down" from "index is empty".
+ *   - When the top hit's score ≥ threshold → skip with reason="near_duplicate".
+ *   - Otherwise → keep with reason="no_near_duplicate".
+ */
+declare function decideSemanticDedup(content: string, lookup: SemanticDedupLookup, options: SemanticDedupOptions): Promise<SemanticDedupDecision>;
+
+declare class EngramAccessInputError extends Error {
+}
+declare const ENGRAM_ACCESS_WRITE_SCHEMA_VERSION = 1;
+interface EngramAccessHealthResponse {
+    ok: true;
+    memoryDir: string;
+    namespacesEnabled: boolean;
+    defaultNamespace: string;
+    searchBackend: string;
+    qmdEnabled: boolean;
+    nativeKnowledgeEnabled: boolean;
+    projectionAvailable: boolean;
+}
+interface EngramAccessRecallRequest {
+    query: string;
+    sessionKey?: string;
+    namespace?: string;
+    topK?: number;
+    mode?: RecallPlanMode | "auto";
+    includeDebug?: boolean;
+}
+interface EngramAccessRecallResponse {
+    query: string;
+    sessionKey?: string;
+    namespace: string;
+    context: string;
+    count: number;
+    memoryIds: string[];
+    results: EngramAccessMemorySummary[];
+    recordedAt?: string;
+    traceId?: string;
+    plannerMode?: RecallPlanMode;
+    fallbackUsed: boolean;
+    sourcesUsed: string[];
+    budgetsApplied?: LastRecallSnapshot["budgetsApplied"];
+    latencyMs?: number;
+    debug?: {
+        snapshot?: LastRecallSnapshot;
+        intent?: IntentDebugSnapshot | null;
+        graph?: GraphRecallSnapshot | null;
+    };
+}
+interface EngramAccessRecallExplainRequest {
+    sessionKey?: string;
+    namespace?: string;
+}
+interface EngramAccessRecallExplainResponse {
+    found: boolean;
+    snapshot?: LastRecallSnapshot;
+    intent?: IntentDebugSnapshot | null;
+    graph?: GraphRecallSnapshot | null;
+}
+interface EngramAccessDaySummaryRequest {
+    memories?: string;
+    sessionKey?: string;
+    namespace?: string;
+}
+/** Inputs accepted by the `remnic_briefing` MCP tool. */
+interface EngramAccessBriefingRequest {
+    since?: string;
+    focus?: string;
+    namespace?: string;
+    format?: "markdown" | "json";
+    maxFollowups?: number;
+    /** Caller principal for namespace access checks. Transport-bound — never from untrusted payloads. */
+    principal?: string;
+}
+/** Response for `remnic_briefing`. */
+interface EngramAccessBriefingResponse {
+    format: "markdown" | "json";
+    window: {
+        from: string;
+        to: string;
+    };
+    namespace: string;
+    markdown: string;
+    json: Record<string, unknown>;
+    followupsUnavailableReason?: string;
+}
+interface EngramAccessMemoryRecord {
+    id: string;
+    path: string;
+    category: string;
+    status?: string;
+    created?: string;
+    updated?: string;
+    content: string;
+    frontmatter: MemoryFile["frontmatter"];
+}
+interface EngramAccessMemorySummary {
+    id: string;
+    path: string;
+    category: string;
+    status: string;
+    created?: string;
+    updated?: string;
+    tags: string[];
+    entityRef?: string;
+    preview: string;
+}
+interface EngramAccessMemoryBrowseRequest {
+    query?: string;
+    status?: string;
+    category?: string;
+    namespace?: string;
+    sort?: "updated_desc" | "updated_asc" | "created_desc" | "created_asc";
+    limit?: number;
+    offset?: number;
+}
+interface EngramAccessMemoryBrowseResponse {
+    namespace: string;
+    sort: "updated_desc" | "updated_asc" | "created_desc" | "created_asc";
+    total: number;
+    count: number;
+    limit: number;
+    offset: number;
+    memories: EngramAccessMemorySummary[];
+}
+interface EngramAccessMemoryResponse {
+    found: boolean;
+    namespace: string;
+    memory?: EngramAccessMemoryRecord;
+}
+interface EngramAccessTimelineResponse {
+    found: boolean;
+    namespace: string;
+    count: number;
+    timeline: MemoryLifecycleEvent[];
+}
+interface EngramAccessEntitySummary {
+    name: string;
+    type: string;
+    updated: string;
+    summary?: string;
+    aliases: string[];
+}
+interface EngramAccessEntityListResponse {
+    namespace: string;
+    total: number;
+    count: number;
+    limit: number;
+    offset: number;
+    entities: EngramAccessEntitySummary[];
+}
+interface EngramAccessEntityResponse {
+    found: boolean;
+    namespace: string;
+    entity?: EntityFile;
+}
+interface EngramAccessReviewQueueResponse {
+    found: boolean;
+    namespace?: string;
+    runId?: string;
+    summary?: Awaited<ReturnType<typeof readMemoryGovernanceRunArtifact>>["summary"];
+    metrics?: Awaited<ReturnType<typeof readMemoryGovernanceRunArtifact>>["metrics"];
+    qualityScore?: Awaited<ReturnType<typeof readMemoryGovernanceRunArtifact>>["qualityScore"];
+    reviewQueue?: Awaited<ReturnType<typeof readMemoryGovernanceRunArtifact>>["reviewQueue"];
+    appliedActions?: Awaited<ReturnType<typeof readMemoryGovernanceRunArtifact>>["appliedActions"];
+    transitionReport?: Awaited<ReturnType<typeof readMemoryGovernanceRunArtifact>>["transitionReport"];
+    report?: string;
+}
+interface EngramAccessMaintenanceResponse {
+    namespace: string;
+    health: EngramAccessHealthResponse;
+    latestGovernanceRun: EngramAccessReviewQueueResponse;
+}
+interface EngramAccessTrustZoneStatusResponse {
+    namespace: string;
+    status: TrustZoneStoreStatus;
+}
+interface EngramAccessTrustZoneRecordSummary {
+    recordId: string;
+    filePath: string;
+    zone: TrustZoneName;
+    recordedAt: string;
+    kind: TrustZoneRecordKind;
+    summary: string;
+    sourceClass: TrustZoneSourceClass;
+    sessionKey?: string;
+    sourceId?: string;
+    evidenceHashPresent: boolean;
+    anchored: boolean;
+    entityRefs: string[];
+    tags: string[];
+    metadata?: Record<string, string>;
+    trustScore?: TrustZoneProvenanceScore;
+    nextPromotionTarget?: TrustZoneName;
+    nextPromotionAllowed: boolean;
+    nextPromotionReasons: string[];
+    corroborationCount?: number;
+    corroborationSourceClasses?: TrustZoneSourceClass[];
+}
+interface EngramAccessTrustZoneBrowseRequest {
+    query?: string;
+    zone?: TrustZoneName;
+    kind?: TrustZoneRecordKind;
+    sourceClass?: TrustZoneSourceClass;
+    namespace?: string;
+    limit?: number;
+    offset?: number;
+}
+interface EngramAccessTrustZoneBrowseResponse {
+    namespace: string;
+    total: number;
+    count: number;
+    limit: number;
+    offset: number;
+    records: EngramAccessTrustZoneRecordSummary[];
+}
+interface EngramAccessTrustZonePromoteRequest {
+    recordId: string;
+    targetZone: TrustZoneName;
+    promotionReason: string;
+    recordedAt?: string;
+    summary?: string;
+    dryRun?: boolean;
+    namespace?: string;
+    authenticatedPrincipal?: string;
+}
+interface EngramAccessTrustZonePromoteResponse extends TrustZonePromotionResult {
+    namespace: string;
+    dryRun: boolean;
+}
+interface EngramAccessTrustZoneDemoSeedRequest {
+    scenario?: string;
+    recordedAt?: string;
+    dryRun?: boolean;
+    namespace?: string;
+    authenticatedPrincipal?: string;
+}
+interface EngramAccessTrustZoneDemoSeedResponse extends TrustZoneDemoSeedResult {
+    namespace: string;
+}
+interface EngramAccessQualityResponse {
+    namespace: string;
+    totalMemories: number;
+    statusCounts: Record<string, number>;
+    categoryCounts: Record<string, number>;
+    confidenceTierCounts: Record<string, number>;
+    ageBucketCounts: Record<string, number>;
+    archivePressure: {
+        pendingReview: number;
+        quarantined: number;
+        archived: number;
+        staleActive: number;
+        lowConfidenceActive: number;
+    };
+    latestGovernanceRun: {
+        found: boolean;
+        runId?: string;
+        qualityScore?: EngramAccessReviewQueueResponse["qualityScore"];
+        reviewQueueCount: number;
+    };
+}
+interface EngramAccessReviewDispositionRequest {
+    memoryId: string;
+    status: MemoryStatus | "archived";
+    reasonCode: string;
+    namespace?: string;
+    /**
+     * Trusted transport-bound principal. This must never come from untrusted client payloads.
+     * When present, write authorization is evaluated against this principal instead of sessionKey.
+     */
+    authenticatedPrincipal?: string;
+}
+interface EngramAccessReviewDispositionResponse {
+    ok: boolean;
+    namespace: string;
+    memoryId: string;
+    status: MemoryStatus | "archived";
+    previousStatus: MemoryStatus;
+    currentPath?: string;
+}
+interface EngramAccessWriteEnvelope {
+    schemaVersion?: number;
+    idempotencyKey?: string;
+    dryRun?: boolean;
+    sessionKey?: string;
+    /**
+     * Trusted transport-bound principal. This must never come from untrusted client payloads.
+     * When present, write authorization is evaluated against this principal instead of sessionKey.
+     */
+    authenticatedPrincipal?: string;
+}
+interface EngramAccessMemoryStoreRequest extends EngramAccessWriteEnvelope, ExplicitCaptureInput {
+}
+interface EngramAccessSuggestionSubmitRequest extends EngramAccessWriteEnvelope, ExplicitCaptureInput {
+}
+interface EngramAccessWriteResponse {
+    schemaVersion: 1;
+    operation: "memory_store" | "suggestion_submit";
+    namespace: string;
+    dryRun: boolean;
+    accepted: boolean;
+    queued: boolean;
+    status: "validated" | "stored" | "duplicate" | "queued_for_review";
+    memoryId?: string;
+    duplicateOf?: string;
+    idempotencyKey?: string;
+    idempotencyReplay?: boolean;
+}
+interface EngramAccessObserveRequest {
+    sessionKey: string;
+    messages: Array<{
+        role: "user" | "assistant";
+        content: string;
+    }>;
+    namespace?: string;
+    authenticatedPrincipal?: string;
+    skipExtraction?: boolean;
+}
+interface EngramAccessObserveResponse {
+    accepted: number;
+    sessionKey: string;
+    namespace: string;
+    lcmArchived: boolean;
+    extractionQueued: boolean;
+}
+interface EngramAccessLcmSearchRequest {
+    query: string;
+    sessionKey?: string;
+    namespace?: string;
+    limit?: number;
+    authenticatedPrincipal?: string;
+}
+interface EngramAccessLcmSearchResponse {
+    query: string;
+    namespace: string;
+    results: Array<{
+        sessionId: string;
+        content: string;
+        turnIndex?: number;
+    }>;
+    count: number;
+    lcmEnabled: boolean;
+}
+interface EngramAccessLcmStatusResponse {
+    enabled: boolean;
+    archiveAvailable: boolean;
+    stats?: {
+        totalTurns?: number;
+    };
+}
+type EngramAccessIdempotencyStatus = "miss" | "replay" | "conflict";
+declare class EngramAccessService {
+    private readonly orchestrator;
+    private readonly idempotency;
+    private readonly idempotencyLocks;
+    constructor(orchestrator: Orchestrator);
+    get briefingEnabled(): boolean;
+    private resolveNamespace;
+    private normalizeRecallMode;
+    private resolveRecallNamespace;
+    private resolveWritePrincipal;
+    private resolveWritableNamespace;
+    private resolveReadableNamespace;
+    private buildRecallDebug;
+    private serializeRecallResults;
+    private handleIdempotentWrite;
+    private peekIdempotentWrite;
+    private withIdempotencyLock;
+    health(namespace?: string): Promise<EngramAccessHealthResponse>;
+    daySummary(request: EngramAccessDaySummaryRequest): Promise<DaySummaryResult | null>;
+    /**
+     * Build a daily context briefing. Gracefully degrades when the OpenAI key
+     * or Responses API is unavailable — never throws for LLM-related problems.
+     */
+    briefing(request: EngramAccessBriefingRequest): Promise<EngramAccessBriefingResponse>;
+    recall(request: EngramAccessRecallRequest): Promise<EngramAccessRecallResponse>;
+    recallExplain(request?: EngramAccessRecallExplainRequest): Promise<EngramAccessRecallExplainResponse>;
+    memoryStore(request: EngramAccessMemoryStoreRequest): Promise<EngramAccessWriteResponse>;
+    peekMemoryStoreIdempotency(request: EngramAccessMemoryStoreRequest): Promise<EngramAccessIdempotencyStatus>;
+    suggestionSubmit(request: EngramAccessSuggestionSubmitRequest): Promise<EngramAccessWriteResponse>;
+    peekSuggestionSubmitIdempotency(request: EngramAccessSuggestionSubmitRequest): Promise<EngramAccessIdempotencyStatus>;
+    private validateWriteCandidate;
+    memoryGet(memoryId: string, namespace?: string, principal?: string): Promise<EngramAccessMemoryResponse>;
+    memoryBrowse(request?: EngramAccessMemoryBrowseRequest): Promise<EngramAccessMemoryBrowseResponse>;
+    memoryTimeline(memoryId: string, namespace?: string, limit?: number, principal?: string): Promise<EngramAccessTimelineResponse>;
+    entityList(options?: {
+        namespace?: string;
+        query?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<EngramAccessEntityListResponse>;
+    entityGet(name: string, namespace?: string): Promise<EngramAccessEntityResponse>;
+    reviewQueue(runId?: string, namespace?: string, principal?: string): Promise<EngramAccessReviewQueueResponse>;
+    maintenance(namespace?: string, principal?: string): Promise<EngramAccessMaintenanceResponse>;
+    quality(namespace?: string, principal?: string): Promise<EngramAccessQualityResponse>;
+    governanceRun(request: {
+        namespace?: string;
+        mode?: "shadow" | "apply";
+        recentDays?: number;
+        maxMemories?: number;
+        batchSize?: number;
+        authenticatedPrincipal?: string;
+    }, principal?: string): Promise<{
+        namespace: string;
+        runId: string;
+        traceId: string;
+        mode: "shadow" | "apply";
+        reviewQueueCount: number;
+        proposedActionCount: number;
+        appliedActionCount: number;
+        summaryPath: string;
+        reportPath: string;
+    }>;
+    procedureMiningRun(request: {
+        namespace?: string;
+        authenticatedPrincipal?: string;
+    }, principal?: string): Promise<{
+        namespace: string;
+        clustersProcessed: number;
+        proceduresWritten: number;
+        skippedReason?: string;
+    }>;
+    trustZoneStatus(namespace?: string, principal?: string): Promise<EngramAccessTrustZoneStatusResponse>;
+    trustZoneBrowse(request: EngramAccessTrustZoneBrowseRequest, principal?: string): Promise<EngramAccessTrustZoneBrowseResponse>;
+    trustZonePromote(request: EngramAccessTrustZonePromoteRequest): Promise<EngramAccessTrustZonePromoteResponse>;
+    trustZoneDemoSeed(request: EngramAccessTrustZoneDemoSeedRequest): Promise<EngramAccessTrustZoneDemoSeedResponse>;
+    reviewDisposition(request: EngramAccessReviewDispositionRequest): Promise<EngramAccessReviewDispositionResponse>;
+    private serializeMemory;
+    private serializeMemorySummary;
+    observe(request: EngramAccessObserveRequest): Promise<EngramAccessObserveResponse>;
+    lcmSearch(request: EngramAccessLcmSearchRequest): Promise<EngramAccessLcmSearchResponse>;
+    continuityAuditGenerate(request: {
+        period?: "weekly" | "monthly";
+        key?: string;
+    }): Promise<{
+        enabled: boolean;
+        reason?: string;
+        period?: string;
+        key?: string;
+        reportPath?: string;
+    }>;
+    continuityIncidentOpen(request: {
+        symptom: string;
+        namespace?: string;
+        principal?: string;
+        triggerWindow?: string;
+        suspectedCause?: string;
+    }): Promise<unknown>;
+    continuityIncidentClose(request: {
+        id: string;
+        namespace?: string;
+        principal?: string;
+        fixApplied: string;
+        verificationResult: string;
+        preventiveRule?: string;
+    }): Promise<unknown>;
+    continuityIncidentList(request: {
+        state?: "open" | "closed" | "all";
+        namespace?: string;
+        principal?: string;
+        limit?: number;
+    }): Promise<unknown>;
+    continuityLoopAddOrUpdate(request: {
+        id: string;
+        cadence: "daily" | "weekly" | "monthly" | "quarterly";
+        purpose: string;
+        status: "active" | "paused" | "retired";
+        killCondition: string;
+        namespace?: string;
+        principal?: string;
+        lastReviewed?: string;
+        notes?: string;
+    }): Promise<unknown>;
+    continuityLoopReview(request: {
+        id: string;
+        namespace?: string;
+        principal?: string;
+        status?: "active" | "paused" | "retired";
+        notes?: string;
+        reviewedAt?: string;
+    }): Promise<unknown>;
+    identityAnchorGet(request: {
+        namespace?: string;
+        principal?: string;
+    }): Promise<unknown>;
+    identityAnchorUpdate(request: {
+        namespace?: string;
+        principal?: string;
+        identityTraits?: string;
+        communicationPreferences?: string;
+        operatingPrinciples?: string;
+        continuityNotes?: string;
+    }): Promise<unknown>;
+    memoryIdentity(request: {
+        namespace?: string;
+        principal?: string;
+    }): Promise<unknown>;
+    workTask(request: {
+        action: "create" | "get" | "list" | "update" | "transition" | "delete";
+        id?: string;
+        title?: string;
+        description?: string;
+        status?: string;
+        priority?: string;
+        owner?: string;
+        assignee?: string;
+        projectId?: string;
+        tags?: string[];
+        dueAt?: string;
+    }): Promise<unknown>;
+    workProject(request: {
+        action: "create" | "get" | "list" | "update" | "delete" | "link_task";
+        id?: string;
+        name?: string;
+        description?: string;
+        status?: string;
+        owner?: string;
+        tags?: string[];
+        taskId?: string;
+        projectId?: string;
+    }): Promise<unknown>;
+    workBoard(request: {
+        action: "export_markdown" | "export_snapshot" | "import_snapshot";
+        projectId?: string;
+        snapshotJson?: string;
+        linkToMemory?: boolean;
+    }): Promise<unknown>;
+    sharedContextWriteOutput(request: {
+        agentId: string;
+        title: string;
+        content: string;
+    }): Promise<unknown>;
+    sharedFeedbackRecord(request: {
+        agent: string;
+        decision: "approved" | "approved_with_feedback" | "rejected";
+        reason: string;
+        date?: string;
+        learning?: string;
+        outcome?: string;
+        severity?: "low" | "medium" | "high";
+        confidence?: number;
+        workflow?: string;
+        tags?: string[];
+        evidenceWindowStart?: string;
+        evidenceWindowEnd?: string;
+        refs?: string[];
+    }): Promise<unknown>;
+    sharedPrioritiesAppend(request: {
+        agentId: string;
+        text: string;
+    }): Promise<unknown>;
+    sharedContextCrossSignalsRun(request: {
+        date?: string;
+    }): Promise<unknown>;
+    sharedContextCurateDaily(request: {
+        date?: string;
+    }): Promise<unknown>;
+    compoundingWeeklySynthesize(request: {
+        weekId?: string;
+    }): Promise<unknown>;
+    compoundingPromoteCandidate(request: {
+        weekId: string;
+        candidateId: string;
+        dryRun?: boolean;
+    }): Promise<unknown>;
+    compressionGuidelinesOptimize(request: {
+        dryRun?: boolean;
+        eventLimit?: number;
+    }): Promise<unknown>;
+    compressionGuidelinesActivate(request: {
+        expectedContentHash?: string;
+        expectedGuidelineVersion?: number;
+    }): Promise<unknown>;
+    /** Conservative identity anchor section merge (matches tools.ts mergeIdentityAnchor logic). */
+    private mergeIdentityAnchorSections;
+    memorySearch(request: {
+        query: string;
+        namespace?: string;
+        maxResults?: number;
+        collection?: string;
+        principal?: string;
+    }): Promise<{
+        query: string;
+        results: Array<{
+            path: string;
+            score: number;
+            snippet: string;
+        }>;
+        count: number;
+    }>;
+    memoryProfile(namespace?: string, principal?: string): Promise<Record<string, unknown>>;
+    memoryEntitiesList(namespace?: string, principal?: string): Promise<{
+        entities: string[];
+        count: number;
+    }>;
+    memoryQuestions(namespace?: string, principal?: string): Promise<{
+        questions: Array<{
+            id: string;
+            question: string;
+            resolved: boolean;
+        }>;
+        count: number;
+    }>;
+    lastRecallSnapshot(sessionKey?: string): Promise<unknown>;
+    intentDebug(namespace?: string): Promise<unknown>;
+    qmdDebug(namespace?: string): Promise<unknown>;
+    graphExplainLastRecall(namespace?: string): Promise<unknown>;
+    memoryFeedback(request: {
+        memoryId: string;
+        vote: "up" | "down";
+        note?: string;
+    }): Promise<{
+        recorded: boolean;
+        enabled?: boolean;
+        reason?: string;
+    }>;
+    memoryPromote(request: {
+        memoryId: string;
+        namespace?: string;
+        principal?: string;
+        sessionKey?: string;
+    }): Promise<unknown>;
+    contextCheckpoint(request: {
+        sessionKey: string;
+        context: string;
+        namespace?: string;
+        principal?: string;
+    }): Promise<{
+        saved: boolean;
+    }>;
+    lcmStatus(): Promise<EngramAccessLcmStatusResponse>;
+    /**
+     * Record citation usage from an observed oai-mem-citation block.
+     * For each citation entry, extract the memory ID from the path and
+     * increment its access tracking via the orchestrator. Returns the
+     * count of submitted IDs and the count of IDs that matched real memories.
+     */
+    recordCitationUsage(request: {
+        sessionId?: string;
+        namespace?: string;
+        authenticatedPrincipal?: string;
+        entries: Array<{
+            path: string;
+            lineStart: number;
+            lineEnd: number;
+            note: string;
+        }>;
+        rolloutIds: string[];
+    }): Promise<{
+        submitted: number;
+        matched: number;
+    }>;
+    get memoryDir(): string;
+    get storageRef(): StorageManager;
+    get configRef(): PluginConfig;
+    get localLlmRef(): LocalLlmClient | null;
+    get fallbackLlmRef(): FallbackLlmClient | null;
+    get embeddingLookupRef(): SemanticDedupLookup | undefined;
+}
+
+export { type EngramAccessRecallExplainRequest as A, type EngramAccessRecallExplainResponse as B, type EngramAccessRecallRequest as C, type EngramAccessRecallResponse as D, EngramAccessService as E, type EngramAccessReviewDispositionRequest as F, type EngramAccessReviewDispositionResponse as G, type EngramAccessReviewQueueResponse as H, type EngramAccessSuggestionSubmitRequest as I, type EngramAccessTimelineResponse as J, type EngramAccessTrustZoneBrowseRequest as K, type EngramAccessTrustZoneBrowseResponse as L, type EngramAccessTrustZoneDemoSeedRequest as M, type EngramAccessTrustZoneDemoSeedResponse as N, type EngramAccessTrustZonePromoteRequest as O, type EngramAccessTrustZonePromoteResponse as P, type EngramAccessTrustZoneRecordSummary as Q, type EngramAccessTrustZoneStatusResponse as R, type SemanticDedupDecision as S, type EngramAccessWriteEnvelope as T, type EngramAccessWriteResponse as U, EngramAccessInputError as a, type SemanticDedupHit as b, type SemanticDedupLookup as c, type SemanticDedupOptions as d, decideSemanticDedup as e, ENGRAM_ACCESS_WRITE_SCHEMA_VERSION as f, type EngramAccessBriefingRequest as g, type EngramAccessBriefingResponse as h, type EngramAccessDaySummaryRequest as i, type EngramAccessEntityListResponse as j, type EngramAccessEntityResponse as k, type EngramAccessEntitySummary as l, type EngramAccessHealthResponse as m, type EngramAccessLcmSearchRequest as n, type EngramAccessLcmSearchResponse as o, type EngramAccessLcmStatusResponse as p, type EngramAccessMaintenanceResponse as q, type EngramAccessMemoryBrowseRequest as r, type EngramAccessMemoryBrowseResponse as s, type EngramAccessMemoryRecord as t, type EngramAccessMemoryResponse as u, type EngramAccessMemoryStoreRequest as v, type EngramAccessMemorySummary as w, type EngramAccessObserveRequest as x, type EngramAccessObserveResponse as y, type EngramAccessQualityResponse as z };