@cleocode/contracts 2026.4.95 → 2026.4.97

package/dist/operations/memory.d.ts

@@ -0,0 +1,814 @@
+/**
+ * Memory Domain Operations (31 operations)
+ *
+ * Query operations: 21
+ * Mutate operations: 10
+ *
+ * memory is the cognitive memory subsystem backed by `brain.db` (SQLite + FTS5
+ * + vector + graph). It surfaces observations, decisions, patterns, learnings,
+ * a PageIndex graph, RRF hybrid search, causal reasoning, and quality/health
+ * telemetry. CLI identifiers start with `memory.*` and are routed through the
+ * `memory` domain handler.
+ *
+ * Distinct from BRAIN (super-domain) — a NEW `operations/brain.ts` will be
+ * authored in T962 Wave B for the unified cross-substrate graph operations
+ * (wraps memory + nexus + tasks + conduit + signaldock).
+ *
+ * SYNC: Canonical implementations at packages/core/src/memory/*.
+ * Wire-format types live here; they are the contract for CLI + HTTP dispatch.
+ *
+ * @task T910 — Orchestration Coherence v4 (contract surface completion)
+ * @task T965 — operations/brain.ts → operations/memory.ts rename
+ * @see packages/cleo/src/dispatch/domains/memory.ts
+ * @see packages/contracts/src/brain.ts
+ */
+import type { BrainCognitiveType, BrainMemoryTier, BrainSourceConfidence } from '../brain.js';
+import type { LAFSPage } from '../lafs.js';
+/**
+ * Cognitive type of a memory entry.
+ *
+ * @remarks
+ * Mirrors the CLI-facing taxonomy accepted by `memory.observe`. Distinct from
+ * `BrainCognitiveType` from `../brain.js` which carries the 3-axis
+ * semantic/episodic/procedural cognitive model used internally.
+ */
+export type MemoryEntryType = 'observation' | 'decision' | 'pattern' | 'learning' | 'reference';
+/** Memory observation subtype categories (from `brain_observations.type`). */
+export type MemoryObservationKind = 'discovery' | 'change' | 'feature' | 'bugfix' | 'decision' | 'refactor';
+/** Origin tag distinguishing where an observation was captured. */
+export type MemoryObservationSourceType = 'manual' | 'session-debrief' | 'observer' | 'reflector' | 'transcript';
+/** Pattern taxonomy (from `brain_patterns.type`). */
+export type MemoryPatternType = 'workflow' | 'blocker' | 'success' | 'failure' | 'optimization';
+/** Severity/impact level for a stored pattern. */
+export type MemoryPatternImpact = 'low' | 'medium' | 'high';
+/** Compact hit returned from `memory.find` / `memory.search.hybrid` layer-0 search. */
+export interface MemoryCompactHit {
+    /** Memory entry identifier (e.g. `O-abc123`, `D-def456`). */
+    id: string;
+    /** Table this hit was drawn from. */
+    type: 'decision' | 'pattern' | 'learning' | 'observation';
+    /** Normalized display title for the entry. */
+    title: string;
+    /** ISO 8601 timestamp of entry creation. */
+    date: string;
+    /** Relevance score (table-specific; higher = better). */
+    relevance?: number;
+    /** Reciprocal Rank Fusion score (only when RRF path engaged). */
+    rrfScore?: number;
+    /** BM25 normalized score from FTS path (0..1). */
+    bm25Score?: number;
+}
+/** Full memory entry body returned by `memory.fetch` (layer-2 retrieval). */
+export interface MemoryFetchedEntry {
+    /** Memory entry identifier. */
+    id: string;
+    /** Table the entry was drawn from. */
+    type: string;
+    /** Raw entry payload — columns vary by table. */
+    data: unknown;
+}
+/** Timeline neighbor tuple returned by `memory.timeline`. */
+export interface MemoryTimelineNeighbor {
+    /** Memory entry identifier. */
+    id: string;
+    /** Entry table type. */
+    type: string;
+    /** ISO 8601 timestamp. */
+    date: string;
+}
+/** Anchor entry (shape is table-dependent). */
+export type MemoryAnchor = Record<string, unknown>;
+/** PageIndex graph node (projection of `brain_page_nodes`). */
+export interface MemoryGraphNode {
+    /** Node identifier. */
+    id: string;
+    /** Node type classification (e.g. `symbol`, `file`, `concept`). */
+    nodeType: string;
+    /** Human-readable label. */
+    label: string;
+    /** Quality score [0..1] used by PageIndex ranking. */
+    qualityScore: number;
+    /** SHA-256 hash of the referenced content (if applicable). */
+    contentHash: string | null;
+    /** ISO 8601 timestamp of last activity touching this node. */
+    lastActivityAt: string;
+    /** Optional JSON-encoded metadata string. */
+    metadataJson: string | null;
+    /** ISO 8601 timestamp of creation. */
+    createdAt: string;
+    /** ISO 8601 timestamp of last update (nullable). */
+    updatedAt: string | null;
+}
+/** PageIndex graph edge (projection of `brain_page_edges`). */
+export interface MemoryGraphEdge {
+    /** Source node id. */
+    fromId: string;
+    /** Target node id. */
+    toId: string;
+    /** Edge type classification. */
+    edgeType: string;
+    /** Edge weight/confidence [0..1]. */
+    weight: number;
+    /** Optional JSON-encoded metadata string. */
+    metadataJson: string | null;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+}
+/** Decision node returned by reasoning queries. */
+export interface MemoryDecisionNode {
+    /** Decision entry identifier (`D-...`). */
+    id: string;
+    /** The decision statement. */
+    title: string;
+    /** Rationale for the decision. */
+    rationale: string;
+}
+/**
+ * Parameters for `memory.find`.
+ *
+ * @remarks
+ * Preconditions: `query` must be non-empty. Returns compact hits suitable for
+ * follow-up `memory.fetch` batching (3-layer retrieval: find → filter → fetch).
+ */
+export interface MemoryFindParams {
+    /** Full-text query string (required). */
+    query: string;
+    /** Max results to return. */
+    limit?: number;
+    /** Tables to search (defaults to all four). */
+    tables?: Array<'decisions' | 'patterns' | 'learnings' | 'observations'>;
+    /** ISO 8601 lower bound on entry date. */
+    dateStart?: string;
+    /** ISO 8601 upper bound on entry date. */
+    dateEnd?: string;
+    /** Filter to observations produced by a specific agent (T418 mental models). */
+    agent?: string;
+    /** When true (default), apply Reciprocal Rank Fusion across FTS + vector sources. */
+    useRRF?: boolean;
+}
+/** Result of `memory.find`. */
+export interface MemoryFindResult {
+    /** Ranked matches. */
+    results: MemoryCompactHit[];
+    /** Total match count (may exceed `results.length` when limit applied). */
+    total: number;
+    /** Estimated token weight of the payload. */
+    tokensEstimated: number;
+}
+/** Parameters for `memory.timeline`. */
+export interface MemoryTimelineParams {
+    /** Anchor entry id (required). */
+    anchor: string;
+    /** Number of entries to retrieve before the anchor. */
+    depthBefore?: number;
+    /** Number of entries to retrieve after the anchor. */
+    depthAfter?: number;
+}
+/** Result of `memory.timeline`. */
+export interface MemoryTimelineResult {
+    /** The anchor entry (or null if not found). */
+    anchor: MemoryAnchor | null;
+    /** Entries preceding the anchor (chronological). */
+    before: MemoryTimelineNeighbor[];
+    /** Entries following the anchor (chronological). */
+    after: MemoryTimelineNeighbor[];
+}
+/** Parameters for `memory.fetch`. */
+export interface MemoryFetchParams {
+    /** One or more memory entry IDs to retrieve. Must be non-empty. */
+    ids: string[];
+}
+/** Result of `memory.fetch`. */
+export interface MemoryFetchResult {
+    /** Full entry bodies. */
+    results: MemoryFetchedEntry[];
+    /** IDs that could not be located. */
+    notFound: string[];
+    /** Estimated token weight of the payload. */
+    tokensEstimated: number;
+}
+/** Parameters for `memory.decision.find`. */
+export interface MemoryDecisionFindParams {
+    /** Optional free-text filter. */
+    query?: string;
+    /** Filter decisions linked to a specific task. */
+    taskId?: string;
+    /** Max results. */
+    limit?: number;
+}
+/** A single decision entry returned by the API. */
+export interface MemoryDecisionEntry {
+    /** Decision id (`D-...`). */
+    id: string;
+    /** Decision statement. */
+    decision: string;
+    /** Rationale body. */
+    rationale: string;
+    /** Alternatives considered at decision time. */
+    alternatives?: string[];
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** Epic context, if captured. */
+    contextEpicId?: string;
+    /** Task context, if captured. */
+    contextTaskId?: string;
+    /** Phase context, if captured. */
+    contextPhase?: string;
+    /** Source confidence (T549). */
+    sourceConfidence?: BrainSourceConfidence;
+}
+/** Result of `memory.decision.find`. */
+export type MemoryDecisionFindResult = MemoryDecisionEntry[];
+/** Parameters for `memory.pattern.find`. */
+export interface MemoryPatternFindParams {
+    /** Filter by pattern type. */
+    type?: MemoryPatternType;
+    /** Filter by pattern impact. */
+    impact?: MemoryPatternImpact;
+    /** Optional free-text query. */
+    query?: string;
+    /** Minimum reinforcement frequency. */
+    minFrequency?: number;
+    /** Max results. */
+    limit?: number;
+}
+/** A single pattern entry returned by the API. */
+export interface MemoryPatternEntry {
+    /** Pattern id (`P-...`). */
+    id: string;
+    /** Pattern classification. */
+    type: MemoryPatternType;
+    /** Pattern description. */
+    pattern: string;
+    /** Surrounding context. */
+    context: string;
+    /** Impact level. */
+    impact: MemoryPatternImpact;
+    /** Anti-pattern counter-example (if applicable). */
+    antiPattern?: string;
+    /** Mitigation guidance (if applicable). */
+    mitigation?: string;
+    /** Concrete examples. */
+    examples?: string[];
+    /** Empirical success rate [0..1]. */
+    successRate?: number;
+    /** How often this pattern has been observed. */
+    frequency: number;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+}
+/** Result of `memory.pattern.find`. */
+export interface MemoryPatternFindResult {
+    /** Matching pattern entries. */
+    patterns: MemoryPatternEntry[];
+    /** Count of matches. */
+    total: number;
+}
+/** Parameters for `memory.learning.find`. */
+export interface MemoryLearningFindParams {
+    /** Optional free-text query. */
+    query?: string;
+    /** Minimum confidence threshold [0..1]. */
+    minConfidence?: number;
+    /** Restrict to learnings marked actionable. */
+    actionableOnly?: boolean;
+    /** Filter by applicable task/entry type. */
+    applicableType?: string;
+    /** Max results. */
+    limit?: number;
+}
+/** A single learning entry returned by the API. */
+export interface MemoryLearningEntry {
+    /** Learning id (`L-...`). */
+    id: string;
+    /** Insight statement. */
+    insight: string;
+    /** Source reference for the insight. */
+    source: string;
+    /** Confidence score [0..1]. */
+    confidence: number;
+    /** Whether the learning is actionable. */
+    actionable: boolean;
+    /** How to apply the insight. */
+    application?: string;
+    /** Types this insight applies to. */
+    applicableTypes?: string[];
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+}
+/** Result of `memory.learning.find`. */
+export type MemoryLearningFindResult = MemoryLearningEntry[];
+/** Parameters for `memory.graph.show`. */
+export interface MemoryGraphShowParams {
+    /** Node identifier. */
+    nodeId: string;
+}
+/** Result of `memory.graph.show`. */
+export interface MemoryGraphShowResult {
+    /** The node, if found. */
+    node: MemoryGraphNode | null;
+    /** In-edges (node is target). */
+    inEdges: MemoryGraphEdge[];
+    /** Out-edges (node is source). */
+    outEdges: MemoryGraphEdge[];
+}
+/** Parameters for `memory.graph.neighbors`. */
+export interface MemoryGraphNeighborsParams {
+    /** Node identifier. */
+    nodeId: string;
+    /** Optional filter to a single edge type. */
+    edgeType?: string;
+}
+/** Result of `memory.graph.neighbors`. */
+export interface MemoryGraphNeighbor {
+    /** The neighbor node. */
+    node: MemoryGraphNode;
+    /** Edge type connecting the query node to this neighbor. */
+    edgeType: string;
+    /** Relative to the queried node: `out` = outbound, `in` = inbound. */
+    direction: 'out' | 'in';
+    /** Edge weight/confidence. */
+    weight: number;
+}
+/** Result payload for `memory.graph.neighbors`. */
+export type MemoryGraphNeighborsResult = MemoryGraphNeighbor[];
+/** Parameters for `memory.graph.trace` (BFS traversal). */
+export interface MemoryGraphTraceParams {
+    /** Seed node identifier. */
+    nodeId: string;
+    /** Max traversal depth. */
+    maxDepth?: number;
+}
+/** A node visited during BFS traversal. */
+export interface MemoryGraphTraceNode extends MemoryGraphNode {
+    /** Distance from the seed (0 = seed itself). */
+    depth: number;
+}
+/** Result of `memory.graph.trace`. */
+export type MemoryGraphTraceResult = MemoryGraphTraceNode[];
+/** Parameters for `memory.graph.related` (1-hop typed neighbors). */
+export interface MemoryGraphRelatedParams {
+    /** Node identifier. */
+    nodeId: string;
+    /** Optional filter to a single edge type. */
+    edgeType?: string;
+}
+/** Result of `memory.graph.related`. */
+export type MemoryGraphRelatedResult = MemoryGraphNeighbor[];
+/** Parameters for `memory.graph.context` (360-degree view). */
+export interface MemoryGraphContextParams {
+    /** Node identifier. */
+    nodeId: string;
+}
+/** Result of `memory.graph.context`. */
+export interface MemoryGraphContextResult {
+    /** The node itself. */
+    node: MemoryGraphNode;
+    /** In-edges (this node is target). */
+    inEdges: MemoryGraphEdge[];
+    /** Out-edges (this node is source). */
+    outEdges: MemoryGraphEdge[];
+    /** Deduplicated neighbour list with direction + edge metadata. */
+    neighbors: MemoryGraphNeighbor[];
+}
+/** Parameters for `memory.graph.stats` — none. */
+export type MemoryGraphStatsParams = Record<string, never>;
+/** Result of `memory.graph.stats`. */
+export interface MemoryGraphStatsResult {
+    /** Per-type node counts. */
+    nodesByType: Array<{
+        nodeType: string;
+        count: number;
+    }>;
+    /** Per-type edge counts. */
+    edgesByType: Array<{
+        edgeType: string;
+        count: number;
+    }>;
+    /** Total node count. */
+    totalNodes: number;
+    /** Total edge count. */
+    totalEdges: number;
+}
+/** Parameters for `memory.reason.why` (causal trace). */
+export interface MemoryReasonWhyParams {
+    /** Task identifier whose blocker chain should be traced. */
+    taskId: string;
+}
+/** A single blocker in a causal trace. */
+export interface MemoryBlockerNode {
+    /** Blocking task identifier. */
+    taskId: string;
+    /** Task status at time of trace. */
+    status: string;
+    /** Free-text reason (if captured). */
+    reason?: string;
+    /** Decisions linked to this blocker. */
+    decisions: MemoryDecisionNode[];
+}
+/** Result of `memory.reason.why`. */
+export interface MemoryReasonWhyResult {
+    /** Root task ID that triggered the trace. */
+    taskId: string;
+    /** Walk of unresolved blockers (depth-ordered). */
+    blockers: MemoryBlockerNode[];
+    /** Leaf blocker IDs flagged as root causes. */
+    rootCauses: string[];
+    /** Maximum traversal depth reached. */
+    depth: number;
+}
+/** Parameters for `memory.reason.similar`. */
+export interface MemoryReasonSimilarParams {
+    /** Source entry id to compare against. */
+    entryId: string;
+    /** Maximum results to return. */
+    limit?: number;
+}
+/** A similar entry with a distance score. */
+export interface MemorySimilarEntry {
+    /** Matched entry id. */
+    id: string;
+    /** Cosine / vector distance (lower = more similar). */
+    distance: number;
+    /** Entry type/table. */
+    type: string;
+    /** Display title. */
+    title: string;
+    /** Truncated text preview. */
+    text: string;
+}
+/** Result of `memory.reason.similar`. */
+export type MemoryReasonSimilarResult = MemorySimilarEntry[];
+/** Parameters for `memory.search.hybrid`. */
+export interface MemorySearchHybridParams {
+    /** Query string (required). */
+    query: string;
+    /** RRF weight for FTS results [0..1]. */
+    ftsWeight?: number;
+    /** RRF weight for vector results [0..1]. */
+    vecWeight?: number;
+    /** RRF weight for graph-expansion results [0..1]. */
+    graphWeight?: number;
+    /** Max results to return. */
+    limit?: number;
+}
+/** A fused result from hybrid search. */
+export interface MemoryHybridHit {
+    /** Memory entry id. */
+    id: string;
+    /** Fused RRF score. */
+    score: number;
+    /** Entry type/table. */
+    type: string;
+    /** Display title. */
+    title: string;
+    /** Truncated text preview. */
+    text: string;
+    /** Retrieval sources that contributed. */
+    sources: Array<'fts' | 'vec' | 'graph'>;
+    /** Rank from FTS source (0-based; undefined if absent). */
+    ftsRank?: number;
+    /** Rank from vector source (0-based; undefined if absent). */
+    vecRank?: number;
+}
+/** Result of `memory.search.hybrid`. */
+export type MemorySearchHybridResult = MemoryHybridHit[];
+/** Parameters for `memory.quality` — none. */
+export type MemoryQualityParams = Record<string, never>;
+/** Result of `memory.quality`. */
+export interface MemoryQualityResult {
+    /** Per-tier entry counts. */
+    tierDistribution: Record<BrainMemoryTier, number>;
+    /** Per-cognitive-type counts. */
+    cognitiveDistribution: Record<BrainCognitiveType, number>;
+    /** Fraction of entries classified as noise [0..1]. */
+    noiseRatio: number;
+    /** Retrieval hit-rate stats for the last sampling window. */
+    retrievalStats: {
+        /** Count of retrieval requests. */
+        totalQueries: number;
+        /** Fraction returning at least one hit [0..1]. */
+        hitRate: number;
+    };
+    /** ISO 8601 timestamp when the report was computed. */
+    generatedAt: string;
+}
+/** Parameters for `memory.code.links` — none. */
+export type MemoryCodeLinksParams = Record<string, never>;
+/** A single code_reference edge. */
+export interface MemoryCodeLink {
+    /** Memory entry id. */
+    memoryId: string;
+    /** Nexus code symbol identifier. */
+    codeSymbol: string;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+}
+/** Result of `memory.code.links`. */
+export type MemoryCodeLinksResult = MemoryCodeLink[];
+/** Parameters for `memory.code.memories-for-code`. */
+export interface MemoryCodeMemoriesForCodeParams {
+    /** Code symbol identifier. */
+    symbol: string;
+}
+/** Result of `memory.code.memories-for-code`. */
+export interface MemoryCodeMemoriesForCodeResult {
+    /** Code symbol that was queried. */
+    symbol: string;
+    /** Memory entries referencing this symbol. */
+    memories: Array<{
+        id: string;
+        type: string;
+        title: string;
+    }>;
+}
+/** Parameters for `memory.code.for-memory`. */
+export interface MemoryCodeForMemoryParams {
+    /** Memory entry id. */
+    memoryId: string;
+}
+/** Result of `memory.code.for-memory`. */
+export interface MemoryCodeForMemoryResult {
+    /** Memory entry id that was queried. */
+    memoryId: string;
+    /** Code symbols referenced by this memory. */
+    codeSymbols: string[];
+}
+/** Parameters for `memory.llm-status` — none. */
+export type MemoryLlmStatusParams = Record<string, never>;
+/** Result of `memory.llm-status`. */
+export interface MemoryLlmStatusResult {
+    /** Where the Anthropic API key was resolved from (env, config, keychain, etc.). */
+    resolvedSource: string;
+    /** True when LLM-assisted extraction is wired and key is present. */
+    extractionEnabled: boolean;
+    /** ISO 8601 timestamp of the most recent extraction run; null if none. */
+    lastExtractionRun: string | null;
+    /** Suggested CLI command to trigger a test extraction. */
+    testCommand: string;
+}
+/** Parameters for `memory.pending-verify`. */
+export interface MemoryPendingVerifyParams {
+    /** Minimum citation count to surface an entry (default 5). */
+    minCitations?: number;
+    /** Max entries to return (default 50). */
+    limit?: number;
+}
+/** A single pending-verify row. */
+export interface MemoryPendingEntry {
+    /** Entry id (prefix varies by table). */
+    id: string;
+    /** Normalized display title. */
+    title: string | null;
+    /** Source confidence (nullable when never scored). */
+    sourceConfidence: string | null;
+    /** Times this entry has been cited by retrieval/reasoning. */
+    citationCount: number;
+    /** Memory tier (nullable when never assigned). */
+    memoryTier: string | null;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** Source table name (e.g. `observations`, `decisions`). */
+    table: string;
+}
+/** Result of `memory.pending-verify`. */
+export interface MemoryPendingVerifyResult {
+    /** Count of entries returned. */
+    count: number;
+    /** Minimum citation threshold applied. */
+    minCitations: number;
+    /** Pending entries ordered by citation count desc. */
+    items: MemoryPendingEntry[];
+    /** Human-readable next-step hint. */
+    hint: string;
+}
+/** Parameters for `memory.observe`. */
+export interface MemoryObserveParams {
+    /** Observation text body (required). */
+    text: string;
+    /** Short display title. */
+    title?: string;
+    /** Observation kind (default inferred from content). */
+    type?: MemoryObservationKind;
+    /** Project context override. */
+    project?: string;
+    /** Originating session id. */
+    sourceSessionId?: string;
+    /** Observation source classification. */
+    sourceType?: MemoryObservationSourceType;
+    /** Agent that captured this observation (T417 mental models). */
+    agent?: string;
+    /** Source confidence override (T549). */
+    sourceConfidence?: BrainSourceConfidence;
+    /** Attachment SHA-256 refs to link to this observation (T799). */
+    attachmentRefs?: string[];
+    /** Cross-reference to other memory or external IDs (T794). */
+    crossRef?: string[];
+}
+/** Result of `memory.observe`. */
+export interface MemoryObserveResult {
+    /** Newly-created observation id (`O-...`). */
+    id: string;
+    /** Entry table this was written to. */
+    type: string;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+}
+/** Parameters for `memory.decision.store`. */
+export interface MemoryDecisionStoreParams {
+    /** Decision statement (required). */
+    decision: string;
+    /** Rationale for the decision (required). */
+    rationale: string;
+    /** Alternatives considered at decision time. */
+    alternatives?: string[];
+    /** Task ID providing decision context. */
+    taskId?: string;
+    /** Session ID providing decision context. */
+    sessionId?: string;
+    /** Epic context. */
+    contextEpicId?: string;
+    /** Phase context. */
+    contextPhase?: string;
+}
+/** Result of `memory.decision.store`. */
+export interface MemoryDecisionStoreResult {
+    /** New decision id (`D-...` or sequential `D001`). */
+    id: string;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+}
+/** Parameters for `memory.pattern.store`. */
+export interface MemoryPatternStoreParams {
+    /** Pattern description (required). */
+    pattern: string;
+    /** Surrounding context (required). */
+    context: string;
+    /** Pattern classification (default `workflow`). */
+    type?: MemoryPatternType;
+    /** Pattern impact level. */
+    impact?: MemoryPatternImpact;
+    /** Counter-example anti-pattern. */
+    antiPattern?: string;
+    /** Mitigation guidance. */
+    mitigation?: string;
+    /** Concrete examples. */
+    examples?: string[];
+    /** Empirical success rate [0..1]. */
+    successRate?: number;
+    /** Origin tag (e.g. `auto`, `agent`). Routes source confidence. */
+    source?: string;
+}
+/** Result of `memory.pattern.store`. */
+export interface MemoryPatternStoreResult {
+    /** New pattern id (`P-...`). */
+    id: string;
+    /** True when this store call incremented frequency on a duplicate match. */
+    deduplicated: boolean;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+}
+/** Parameters for `memory.learning.store`. */
+export interface MemoryLearningStoreParams {
+    /** Insight statement (required). */
+    insight: string;
+    /** Source reference for the insight (required). */
+    source: string;
+    /** Confidence [0..1] (default 0.5). */
+    confidence?: number;
+    /** Marks the learning as actionable. */
+    actionable?: boolean;
+    /** How to apply the insight. */
+    application?: string;
+    /** Types/domains this learning applies to. */
+    applicableTypes?: string[];
+}
+/** Result of `memory.learning.store`. */
+export interface MemoryLearningStoreResult {
+    /** New learning id (`L-...`). */
+    id: string;
+    /** True when this store call updated an existing duplicate. */
+    deduplicated: boolean;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+}
+/** Parameters for `memory.link`. */
+export interface MemoryLinkParams {
+    /** Task id to link. */
+    taskId: string;
+    /** Memory entry id to link. */
+    entryId: string;
+}
+/** Result of `memory.link`. */
+export interface MemoryLinkResult {
+    /** Task id that was linked. */
+    taskId: string;
+    /** Entry id that was linked. */
+    entryId: string;
+    /** True when the edge was newly created (false if already present). */
+    linked: boolean;
+}
+/**
+ * Parameters for `memory.graph.add`.
+ *
+ * @remarks
+ * Either a node-insert shape (`nodeId` + `nodeType` + `label`) or an
+ * edge-insert shape (`fromId` + `toId` + `edgeType`). Caller MUST supply
+ * exactly one of those two variants.
+ */
+export interface MemoryGraphAddParams {
+    /** Node id (node-insert mode). */
+    nodeId?: string;
+    /** Node type classification (node-insert mode). */
+    nodeType?: string;
+    /** Display label (node-insert mode). */
+    label?: string;
+    /** JSON-encoded metadata string. */
+    metadataJson?: string;
+    /** Source node id (edge-insert mode). */
+    fromId?: string;
+    /** Target node id (edge-insert mode). */
+    toId?: string;
+    /** Edge type (edge-insert mode). */
+    edgeType?: string;
+    /** Edge weight [0..1] (edge-insert mode). */
+    weight?: number;
+}
+/** Result of `memory.graph.add`. */
+export interface MemoryGraphAddResult {
+    /** Variant applied. */
+    mode: 'node' | 'edge';
+    /** Id of the node or `fromId:toId:edgeType` edge key. */
+    id: string;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+}
+/** Parameters for `memory.graph.remove`. */
+export interface MemoryGraphRemoveParams {
+    /** Node id (node-remove mode). */
+    nodeId?: string;
+    /** Source node id (edge-remove mode). */
+    fromId?: string;
+    /** Target node id (edge-remove mode). */
+    toId?: string;
+    /** Edge type (edge-remove mode). */
+    edgeType?: string;
+}
+/** Result of `memory.graph.remove`. */
+export interface MemoryGraphRemoveResult {
+    /** Variant applied. */
+    mode: 'node' | 'edge';
+    /** Number of rows deleted. */
+    removed: number;
+}
+/** Parameters for `memory.code.link`. */
+export interface MemoryCodeLinkParams {
+    /** Memory entry id. */
+    memoryId: string;
+    /** Nexus code symbol identifier. */
+    codeSymbol: string;
+}
+/** Result of `memory.code.link`. */
+export interface MemoryCodeLinkResult {
+    /** True when the edge was newly created (false when it already existed). */
+    linked: boolean;
+}
+/** Parameters for `memory.code.auto-link` — none. */
+export type MemoryCodeAutoLinkParams = Record<string, never>;
+/** Result of `memory.code.auto-link`. */
+export interface MemoryCodeAutoLinkResult {
+    /** Count of memory entries scanned. */
+    scanned: number;
+    /** Count of new edges created by the scan. */
+    linked: number;
+    /** Count of edges skipped because they already existed. */
+    skipped: number;
+}
+/** Parameters for `memory.verify`. */
+export interface MemoryVerifyParams {
+    /** Memory entry id to promote to verified=1. */
+    id: string;
+    /** Caller identity (`cleo-prime` or `owner`). Omit for terminal invocation. */
+    agent?: string;
+}
+/** Result of `memory.verify`. */
+export interface MemoryVerifyResult {
+    /** Entry id that was verified. */
+    id: string;
+    /** Table the entry lives in. */
+    table: string;
+    /** True when verified=0 → 1 transition occurred. False when already verified. */
+    promoted: boolean;
+    /** ISO 8601 timestamp of the verify attempt. */
+    verifiedAt: string;
+}
+/** Generic paginated envelope reused by future list variants. */
+export interface MemoryPagedResult<T> {
+    /** Items for this page. */
+    items: T[];
+    /** Total count across all pages. */
+    total: number;
+    /** Pagination descriptor. */
+    page: LAFSPage;
+}
+//# sourceMappingURL=memory.d.ts.map