@clude/sdk 3.0.4 → 3.3.0

package/dist/sdk/memory-types.d.ts

@@ -0,0 +1,321 @@
+import type { MemoryLinkType } from './shared-constants';
+/** @internal Set the owner wallet address for tagging memories. */
+export declare function _setOwnerWallet(wallet: string): void;
+/** Get the configured owner wallet, if any. Checks async context first (hosted API), then module-level (SDK/bot). */
+export declare function getOwnerWallet(): string | null;
+/**
+ * Apply owner_wallet scoping to a Supabase query builder.
+ * When an owner wallet is set, filters to only that wallet's memories.
+ * When null, no filter is applied (backward-compatible).
+ */
+/** Sentinel value: scope to memories where owner_wallet IS NULL (bot's own). */
+export declare const SCOPE_BOT_OWN = "__BOT_OWN__";
+/**
+ * Owner-scope fail-closed flag (Memory 3.0 C0). Read live so benchmarks and
+ * staged rollouts can flip it without a rebuild. When ON, "no owner in scope"
+ * resolves to SCOPE_BOT_OWN (the bot's own memories) instead of null (no
+ * filter = every tenant's memories, the fail-open half of the PR #290 class).
+ */
+export declare function isOwnerScopeFailClosed(): boolean;
+/**
+ * Effective owner scope for READ paths: a tenant wallet, SCOPE_BOT_OWN, or null.
+ * Null (legacy fail-open) survives only while the flag is off. Migration 019
+ * teaches the recall RPCs the sentinel; against an older RPC the sentinel
+ * matches zero rows, so an early flip fails CLOSED, never cross-tenant.
+ *
+ * WRITE paths must keep using getOwnerWallet() (the sentinel is a filter,
+ * never a value to store — bot rows stay owner_wallet NULL).
+ */
+export declare function getOwnerScope(): string | null;
+export declare function scopeToOwner<T>(query: T): T;
+/**
+ * Owner post-guard (defense-in-depth, Memory 3.0 C0): strips rows that escaped
+ * RPC-level scoping via the entity / graph / fragment expansion paths. Pure so
+ * it is directly testable; recallMemories applies it after every phase merged.
+ */
+export declare function applyOwnerPostGuard<T extends {
+    owner_wallet?: string | null;
+}>(results: T[], scope: string | null): {
+    kept: T[];
+    stripped: number;
+};
+/**
+ * BENCH_MODE (Memory 3.0 C0): read-only recall. Benchmarks must observe the
+ * corpus, not mutate it — access boosts (access_count / last_accessed /
+ * decay_factor bumps) and Hebbian link reinforcement change retrieval state on
+ * every read, which is why a reused seeded wallet drifts (+2.6pp measured from
+ * data freshness alone). The harness preflight asserts this is set; prod never
+ * sets it.
+ */
+export declare function isBenchMode(): boolean;
+/**
+ * Should this recall mutate read-state? Callers pass RecallOptions; BENCH_MODE
+ * overrides everything. Pure, exported for tests.
+ */
+export declare function shouldTrackAccess(opts: {
+    trackAccess?: boolean;
+}): boolean;
+/**
+ * Fragment-lane RPC args (Memory 3.0 C0 / P0.3 fragment parity). The extended
+ * filters (min_decay, filter_types) exist only in the migration-043 signature
+ * of match_memory_fragments; PostgREST matches RPCs by named args, so sending
+ * them to the old 4-arg function finds no match and the lane dies. Flip
+ * MEMORY_FRAGMENT_FILTERS=true only AFTER 043 is applied. The reverse is safe:
+ * old-style 4-arg calls keep working against the new function via parameter
+ * defaults, so the flip is one-way and the flag can be retired later.
+ */
+export declare function buildFragmentRpcArgs(opts: {
+    embeddingJson: string;
+    matchThreshold: number;
+    matchCount: number;
+    minDecay: number;
+    memoryTypes?: string[] | null;
+}): Record<string, unknown>;
+/**
+ * Generate a collision-resistant hash ID for a memory.
+ * Format: clude-xxxxxxxx (8 hex chars = 4 bytes = 4 billion possibilities)
+ */
+export declare function generateHashId(): string;
+/**
+ * Validate a hash ID format.
+ */
+export declare function isValidHashId(id: string): boolean;
+export type MemoryType = 'episodic' | 'semantic' | 'procedural' | 'self_model' | 'introspective';
+export interface Memory {
+    id: number;
+    hash_id: string;
+    memory_type: MemoryType;
+    content: string;
+    summary: string;
+    tags: string[];
+    concepts: string[];
+    emotional_valence: number;
+    importance: number;
+    access_count: number;
+    source: string;
+    source_id: string | null;
+    related_user: string | null;
+    related_wallet: string | null;
+    metadata: Record<string, unknown>;
+    created_at: string;
+    last_accessed: string;
+    decay_factor: number;
+    evidence_ids: number[];
+    solana_signature: string | null;
+    compacted: boolean;
+    compacted_into: string | null;
+    encrypted: boolean;
+    encryption_pubkey: string | null;
+    owner_wallet?: string | null;
+    link_path?: Array<'vector' | 'bm25' | 'entity' | 'jepa'>;
+}
+/** Lightweight memory summary for progressive disclosure (no content field). */
+export interface MemorySummary {
+    id: number;
+    memory_type: MemoryType;
+    summary: string;
+    tags: string[];
+    concepts: string[];
+    importance: number;
+    decay_factor: number;
+    created_at: string;
+    source: string;
+}
+export interface StoreMemoryOptions {
+    type: MemoryType;
+    content: string;
+    summary: string;
+    tags?: string[];
+    concepts?: string[];
+    emotionalValence?: number;
+    importance?: number;
+    source: string;
+    sourceId?: string;
+    relatedUser?: string;
+    relatedWallet?: string;
+    metadata?: Record<string, unknown>;
+    evidenceIds?: number[];
+}
+export interface RecallOptions {
+    query?: string;
+    tags?: string[];
+    relatedUser?: string;
+    relatedWallet?: string;
+    memoryTypes?: MemoryType[];
+    limit?: number;
+    minImportance?: number;
+    minDecay?: number;
+    /** Skip access tracking (prevents decay reset). Use for internal processing like dream cycles. */
+    trackAccess?: boolean;
+    /** Pre-computed vector similarity scores from hybrid search (internal use). */
+    _vectorScores?: Map<number, number>;
+    /** Pre-computed BM25 rank scores from full-text search (internal use). */
+    _bm25Scores?: Map<number, number>;
+    /** Skip LLM-based query expansion for faster recall (saves ~500-800ms). */
+    skipExpansion?: boolean;
+}
+/**
+ * Auto-classify memories into structured concepts using keyword heuristics.
+ * Provides consistent cross-cutting knowledge labels without LLM cost.
+ * Concepts are additive to freeform tags, not a replacement.
+ */
+export declare function inferConcepts(summary: string, source: string, tags: string[]): string[];
+export declare function scoreImportanceOnWrite(opts: StoreMemoryOptions): number;
+/** Test/admin helper: clear the installed-packs cache (e.g. after install/uninstall). */
+export declare function invalidateInstalledPacksCache(ownerWallet?: string): void;
+export declare function storeMemory(opts: StoreMemoryOptions): Promise<number | null>;
+/** @internal test-only reset for the once-guard. */
+export declare function _resetOutboxDegradeLog(): void;
+/**
+ * Memory 3.0 C2: the enrichment pipeline the outbox worker runs for an 'enrich' job, in
+ * dependency order (autoLinkMemory reads the memory's own embedding, written by embedMemory).
+ * Sequential + awaited (unlike the fire-and-forget triad) so a whole-job retry re-runs all three;
+ * each step is idempotent (embed delete-before-insert, link unique-index upsert, extract
+ * upsert-RPC). The caller (outbox-worker) wraps this in withOwnerWallet(job owner) so the
+ * ambient owner scope is correct off the poller tick.
+ */
+export declare function runEnrichPipeline(memoryId: number, opts: StoreMemoryOptions): Promise<void>;
+/**
+ * storeMemory + outbox status, for callers that want the {hash_id, jobs_queued} shape (the design
+ * contract). storeMemory itself keeps its number|null signature (zero call-site churn); this thin
+ * wrapper reads the ground truth back: jobs_queued counts the memory's outbox rows (1 when the
+ * enrich job enqueued, 0 when the flag is off or the enqueue degraded to fire-and-forget).
+ */
+export declare function storeMemoryWithOutbox(opts: StoreMemoryOptions): Promise<{
+    id: number;
+    hash_id: string;
+    jobs_queued: number;
+} | null>;
+export declare function recallMemories(opts: RecallOptions): Promise<Memory[]>;
+/**
+ * Enhanced scoring function with optional vector similarity component.
+ *
+ * Unified formula (vector weight always in denominator when search was performed):
+ *   score = (w_recency * recency + w_relevance * keyword_rel
+ *            + w_importance * importance + w_vector * vector_sim) / sum(weights) * decay
+ *
+ * When vector search wasn't performed (graceful fallback):
+ *   score = (w_recency * recency + w_relevance * keyword_rel
+ *            + w_importance * importance) / sum(weights_no_vector) * decay
+ *
+ * Key: memories not found by vector search score lower (vectorSim=0 in numerator,
+ * but VECTOR weight still in denominator), naturally penalizing noise.
+ */
+export declare function scoreMemory(mem: Memory, opts: RecallOptions): number;
+/**
+ * Lightweight recall that returns only summaries (~50 tokens each).
+ * Use for dream cycle focal point generation, overview scans, and
+ * anywhere full content isn't needed. 10x more token-efficient than full recall.
+ *
+ * Call hydrateMemories() to fetch full content for selected IDs.
+ */
+export declare function recallMemorySummaries(opts: RecallOptions): Promise<MemorySummary[]>;
+/**
+ * Fetch full memory content for specific IDs (second stage of progressive disclosure).
+ * Use after recallMemorySummaries() to hydrate only the memories you actually need.
+ */
+export declare function hydrateMemories(ids: number[]): Promise<Memory[]>;
+export type MemoryLinkRow = {
+    source_id: number;
+    target_id: number;
+    link_type: MemoryLinkType;
+    strength: number;
+};
+/**
+ * Create a typed, weighted link between two memories.
+ * Idempotent — upserts on (source_id, target_id, link_type).
+ */
+export declare function createMemoryLink(sourceId: number, targetId: number, linkType: MemoryLinkType, strength?: number): Promise<void>;
+/**
+ * Batch-create multiple memory links in a single upsert.
+ * Filters out self-links and deduplicates by (source, target, type).
+ */
+export declare function createMemoryLinksBatch(links: MemoryLinkRow[]): Promise<void>;
+/**
+ * Apply type-specific memory decay.
+ * Episodic memories fade fastest (0.93/day), self-model slowest (0.99/day).
+ * This mirrors human cognition: events are forgotten but identity persists.
+ */
+export declare function decayMemories(): Promise<number>;
+export declare function deleteMemory(id: number): Promise<boolean>;
+export declare function updateMemory(id: number, patches: {
+    summary?: string;
+    content?: string;
+    tags?: string[];
+    importance?: number;
+    memory_type?: MemoryType;
+}): Promise<boolean>;
+export declare function listMemories(opts: {
+    page?: number;
+    page_size?: number;
+    memory_type?: MemoryType;
+    min_importance?: number;
+    order?: 'created_at' | 'importance' | 'last_accessed';
+}): Promise<{
+    memories: Memory[];
+    total: number;
+}>;
+export interface MemoryStats {
+    total: number;
+    byType: Record<MemoryType, number>;
+    avgImportance: number;
+    avgDecay: number;
+    oldestMemory: string | null;
+    newestMemory: string | null;
+    totalDreamSessions: number;
+    uniqueUsers: number;
+    topTags: {
+        tag: string;
+        count: number;
+    }[];
+    topConcepts: {
+        concept: string;
+        count: number;
+    }[];
+    embeddedCount: number;
+}
+export declare function getMemoryStats(): Promise<MemoryStats>;
+export declare function getRecentMemories(hours: number, types?: MemoryType[], limit?: number): Promise<Memory[]>;
+export declare function getSelfModel(): Promise<Memory[]>;
+export declare function storeDreamLog(sessionType: 'consolidation' | 'reflection' | 'emergence' | 'compaction' | 'contradiction_resolution', inputMemoryIds: number[], output: string, newMemoryIds: number[]): Promise<void>;
+export declare function formatMemoryContext(memories: Memory[]): string;
+export declare function calculateImportance(opts: {
+    tier?: string;
+    feature?: string;
+    mood?: string;
+    isFirstInteraction?: boolean;
+}): number;
+/**
+ * Score importance using LLM (Park et al. 2023).
+ * Falls back to rule-based calculateImportance() on failure.
+ */
+export declare function scoreImportanceWithLLM(description: string, fallbackOpts?: Parameters<typeof calculateImportance>[0]): Promise<number>;
+/**
+ * Returns the set of memory IDs already linked FROM the given memory
+ * (i.e. rows in memory_links where memory_a_id = memoryId).
+ */
+export declare function fetchExistingLinkTargets(memoryId: number): Promise<Set<number>>;
+/**
+ * Upserts a row in jepa_queried_memories marking this memory as queried now.
+ */
+export declare function markJepaQueried(memoryId: number): Promise<void>;
+/**
+ * Returns the set of memory IDs that have been JEPA-queried at or after sinceMs (epoch ms).
+ */
+export declare function fetchJepaQueriedSince(sinceMs: number): Promise<Set<number>>;
+/**
+ * Vector similarity search via the match_memories RPC.
+ * NOTE: query_embedding must be JSON-stringified per existing RPC convention.
+ * ownerWallet filtering is not forwarded to the RPC (no matching param in this
+ * codebase's match_memories signature); callers should filter client-side if needed.
+ */
+export declare function matchByEmbedding(opts: {
+    embedding: number[];
+    threshold: number;
+    limit: number;
+    ownerWallet?: string;
+}): Promise<Array<{
+    id: number;
+    similarity: number;
+}>>;
+export declare function moodToValence(mood: string): number;

package/dist/sdk/sdk-mode.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/shared-constants.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Centralized constants — magic numbers, well-known addresses, and configuration defaults.
+ */
+export declare const MEMO_PROGRAM_ID = "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr";
+export declare const JUPITER_PRICE_URL = "https://api.jup.ag/price/v2";
+export declare const SOLSCAN_TX_BASE_URL = "https://solscan.io/tx";
+export declare const TWEET_MAX_LENGTH = 4000;
+export declare const TWEET_SAFE_LENGTH = 3900;
+export declare const BOT_X_HANDLE: string;
+export declare const MEMORY_DECAY_RATE = 0.95;
+export declare const MEMORY_MIN_DECAY = 0.05;
+export declare const MEMORY_MAX_CONTENT_LENGTH = 5000;
+export declare const MEMORY_MAX_SUMMARY_LENGTH = 500;
+export declare const DECAY_RATES: Record<string, number>;
+export declare const RECENCY_DECAY_BASE = 0.995;
+export declare const RETRIEVAL_WEIGHT_RECENCY: number;
+export declare const RETRIEVAL_WEIGHT_RELEVANCE: number;
+export declare const RETRIEVAL_WEIGHT_IMPORTANCE: number;
+export declare const RETRIEVAL_WEIGHT_VECTOR: number;
+export declare const RETRIEVAL_WEIGHT_BM25: number;
+export declare const KNOWLEDGE_TYPE_BOOST: Record<string, number>;
+export declare const VECTOR_MATCH_THRESHOLD = 0.15;
+export declare const MEMORY_CONCEPTS: readonly ["market_event", "holder_behavior", "self_insight", "social_interaction", "community_pattern", "token_economics", "sentiment_shift", "recurring_user", "whale_activity", "price_action", "engagement_pattern", "identity_evolution"];
+export type MemoryConcept = typeof MEMORY_CONCEPTS[number];
+export declare const BOND_TYPE_WEIGHTS: Record<MemoryLinkType, number>;
+export declare const RETRIEVAL_WEIGHT_GRAPH = 1.5;
+export declare const RETRIEVAL_WEIGHT_COOCCURRENCE = 0.4;
+export declare const LINK_SIMILARITY_THRESHOLD = 0.6;
+export declare const MAX_AUTO_LINKS = 5;
+export declare const LINK_CO_RETRIEVAL_BOOST = 0.05;
+export declare const INTERNAL_MEMORY_SOURCES: Set<string>;
+export declare const EXTERNAL_MEMORY_SOURCES: Set<string>;
+export declare const INTERNAL_REINFORCEMENT_GATE = 0.3;
+export declare const INTERNAL_IMPORTANCE_BOOST = 0.005;
+export type MemoryLinkType = 'supports' | 'contradicts' | 'elaborates' | 'causes' | 'follows' | 'relates' | 'resolves' | 'supersedes' | 'happens_before' | 'happens_after' | 'concurrent_with';
+export declare const EMBEDDING_DIMENSIONS = 1024;
+export declare const EMBEDDING_FRAGMENT_MAX_LENGTH = 2000;
+export declare const REFLECTION_IMPORTANCE_THRESHOLD = 2;
+export declare const REFLECTION_MIN_INTERVAL_MS: number;
+export declare const PRICE_SNAPSHOT_RETENTION_HOURS = 48;
+export declare const WHALE_SELL_COOLDOWN_MS: number;
+export declare const PUMP_DUMP_THRESHOLD_PERCENT = 10;
+export declare const SIDEWAYS_THRESHOLD_PERCENT = 2;
+export declare const BASE_CHAIN_ID = 8453;
+export declare const BASESCAN_TX_BASE_URL = "https://basescan.org/tx";
+export declare const BASESCAN_API_BASE_URL = "https://api.basescan.org/api";
+export declare const DEXSCREENER_PRICE_URL = "https://api.dexscreener.com/latest/dex/tokens";
+export declare const BASE_WETH_ADDRESS = "0x4200000000000000000000000000000000000006";
+export declare const ERC20_BALANCE_ABI: string[];
+export declare const MEMO_MAX_LENGTH = 100;
+export declare const MAJOR_TOKENS: Set<string>;
+export declare const KNOWN_MEMECOINS: Set<string>;
+export declare function isNoteworthyToken(symbol: string): boolean;

package/dist/sdk/types.d.ts

@@ -0,0 +1,47 @@
+import type { MemoryType, Memory, MemorySummary, StoreMemoryOptions, RecallOptions, MemoryStats } from './memory-types';
+import type { MemoryLinkType, MemoryConcept } from './shared-constants';
+export interface CortexConfig {
+    /** Supabase connection. Required for self-hosted mode. Mutually exclusive with `hosted`. */
+    supabase?: {
+        url: string;
+        serviceKey: string;
+    };
+    /** Hosted mode — memories stored on CLUDE infrastructure. Mutually exclusive with `supabase`. */
+    hosted?: {
+        /** API key from `npx @clude/sdk register` or POST /api/cortex/register. */
+        apiKey: string;
+        /** API base URL. Defaults to 'https://clude.io'. */
+        baseUrl?: string;
+    };
+    /** Anthropic API config. Required for dream cycles and LLM importance scoring. Self-hosted only. */
+    anthropic?: {
+        apiKey: string;
+        model?: string;
+    };
+    /** Embedding provider config. Optional — falls back to keyword-only retrieval. Self-hosted only. */
+    embedding?: {
+        provider: 'voyage' | 'openai';
+        apiKey: string;
+        model?: string;
+        dimensions?: number;
+    };
+    /** Owner wallet address (Solana public key). Tags all memories with ownership. */
+    ownerWallet?: string;
+    /** Solana on-chain commit config. Optional — memories won't be committed on-chain. Self-hosted only. */
+    solana?: {
+        rpcUrl?: string;
+        botWalletPrivateKey?: string;
+        /** Program ID for the on-chain memory registry (Anchor program). Optional — falls back to memo writes. */
+        memoryRegistryProgramId?: string;
+    };
+    /** Client-side encryption config. Optional — memories stored plaintext if not provided. Self-hosted only. */
+    encryption?: {
+        /** User's 64-byte Ed25519 secret key (Solana keypair). Used to derive encryption key via HKDF. */
+        solanaSecretKey: Uint8Array;
+    };
+}
+export interface DreamOptions {
+    /** Custom handler for emergence output (replaces posting to X). */
+    onEmergence?: (text: string) => Promise<void>;
+}
+export type { MemoryType, Memory, MemorySummary, StoreMemoryOptions, RecallOptions, MemoryStats, MemoryLinkType, MemoryConcept, };

package/package.json

@@ -1,20 +1,24 @@
 {
   "name": "@clude/sdk",
-  "version": "3.0.4",
+  "version": "3.3.0",
   "mcpName": "io.github.sebbsssss/clude",
   "description": "Persistent memory SDK for AI agents — Stanford Generative Agents architecture on Supabase + pgvector",
   "main": "dist/sdk/index.js",
   "exports": {
     ".": {
+      "types": "./dist/sdk/index.d.ts",
       "require": "./dist/sdk/index.js"
     },
     "./schema": "./supabase-schema.sql",
     "./local": {
+      "types": "./dist/mcp/local-store.d.ts",
       "require": "./dist/mcp/local-store.js"
     },
     "./mcp": {
+      "types": "./dist/mcp/server.d.ts",
       "require": "./dist/mcp/server.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "bin": {
     "clude": "dist/cli/index.js"
@@ -72,33 +76,19 @@
   },
   "packageManager": "pnpm@10.18.1",
   "dependencies": {
-    "@ai-sdk/anthropic": "^3.0.64",
-    "@ai-sdk/google": "^3.0.55",
-    "@ai-sdk/openai": "^3.0.49",
-    "@ai-sdk/xai": "^3.0.75",
     "@anthropic-ai/sdk": "^0.39.0",
     "@huggingface/transformers": "^4.1.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "@openrouter/ai-sdk-provider": "^2.3.3",
-    "@privy-io/node": "^0.12.0",
     "@solana/web3.js": "^1.98.4",
     "@supabase/supabase-js": "^2.95.3",
-    "ai": "^6.0.142",
     "better-sqlite3": "^12.9.0",
     "bs58": "^6.0.0",
     "dotenv": "^16.4.0",
-    "express": "^4.21.0",
-    "express-rate-limit": "^8.2.1",
-    "jose": "^6.1.3",
-    "multer": "^2.1.1",
     "murmurhash3js": "^3.0.1",
     "node-cron": "^3.0.3",
     "pino": "^9.0.0",
     "sqlite-vec": "^0.1.9",
     "tweetnacl": "^1.0.3",
-    "twitter-api-v2": "^1.29.0",
-    "unpdf": "^1.4.0",
-    "vercel-minimax-ai-provider": "^0.0.2",
     "zod": "^4.3.6"
   },
   "devDependencies": {
@@ -111,5 +101,6 @@
   },
   "optionalDependencies": {
     "utf-8-validate": "^5.0.10"
-  }
+  },
+  "types": "./dist/sdk/index.d.ts"
 }