aifastdb 2.7.2 → 2.8.1

package/dist/social-graph-v2.d.ts

@@ -12,7 +12,8 @@
  * - Batch operations for maximum throughput
  * - Real-time performance monitoring
  */
-import type { Entity, Relation, PersonInput, PersonFilter, FriendConfig, TagInput, TagFilter, RelationFilter, ItemInput, AttributeInput, ExportGraphOptions, ExportedGraph, PathOptions, PathResult, AllPathsResult, DegreeContacts, RelationshipStrength, SuggestionConfig, ConnectionSuggestion, NetworkStats, ItemMatchResult, SharedItemResult, SharedAttributeDetail, AttributeMatchConfig, AttributeMatchResult, CompatibilityResult, PaginatedResult, ExportGraphPaginatedOptions, PaginatedExportedGraph, EntityGroupAggregation } from './social-types';
+import type { Entity, Relation, PersonInput, PersonFilter, FriendConfig, TagInput, TagFilter, RelationFilter, ItemInput, AttributeInput, ExportGraphOptions, ExportedGraph, PathOptions, PathResult, AllPathsResult, DegreeContacts, RelationshipStrength, SuggestionConfig, ConnectionSuggestion, NetworkStats, ItemMatchResult, SharedItemResult, SharedAttributeDetail, AttributeMatchConfig, AttributeMatchResult, CompatibilityResult, PaginatedResult, ExportGraphPaginatedOptions, PaginatedExportedGraph, EntityGroupAggregation, BirthdayMatchResult, BirthdayStats } from './social-types';
+import type { Gender, FamilyPath, FamilyTree as FamilyTreeData, FamilyStats, SpouseInfo } from './family-types';
 /**
  * Configuration for vector similarity search (HNSW parameters).
  *
@@ -415,6 +416,366 @@ export declare class SocialGraphV2 {
      * Remove a person's birthday
      */
     removeBirthday(personId: string): boolean;
+    /**
+     * Find people with exact same birthday (same year-month-day)
+     *
+     * @param birthday - Birthday in YYYY-MM-DD format
+     * @returns Array of person entities with matching birthday
+     *
+     * @example
+     * ```typescript
+     * const matches = social.findSameBirthdayExact('1990-03-15');
+     * console.log(`${matches.length} people born on 1990-03-15`);
+     * ```
+     */
+    findSameBirthdayExact(birthday: string): Entity[];
+    /**
+     * Find people with same month-day birthday (different years allowed)
+     *
+     * @param birthday - Birthday in YYYY-MM-DD or MM-DD format
+     * @returns Array of person entities with matching month-day
+     *
+     * @example
+     * ```typescript
+     * const matches = social.findSameBirthdayDayMonth('03-15');
+     * console.log(`${matches.length} people born on March 15th`);
+     * ```
+     */
+    findSameBirthdayDayMonth(birthday: string): Entity[];
+    /**
+     * Find people with same exact birthday as a given person
+     *
+     * @param personId - The person ID to match against
+     * @returns Array of person entities (excludes the person themselves)
+     *
+     * @example
+     * ```typescript
+     * const twins = social.findSameBirthdayAsPersonExact(alice.id);
+     * console.log(`${twins.length} people share Alice's exact birthday`);
+     * ```
+     */
+    findSameBirthdayAsPersonExact(personId: string): Entity[];
+    /**
+     * Find people with same month-day birthday as a given person (different years allowed)
+     *
+     * @param personId - The person ID to match against
+     * @returns Array of person entities (excludes the person themselves)
+     *
+     * @example
+     * ```typescript
+     * const matches = social.findSameBirthdayAsPerson(alice.id);
+     * console.log(`${matches.length} people share Alice's birthday (any year)`);
+     * ```
+     */
+    findSameBirthdayAsPerson(personId: string): Entity[];
+    /**
+     * Recommend birthday matches for a person
+     *
+     * Returns matches sorted by priority: exact match (same year-month-day) > same month-day.
+     *
+     * @param personId - The person ID to find matches for
+     * @param limit - Maximum number of results (default: 10)
+     * @returns Array of birthday match results with match type
+     *
+     * @example
+     * ```typescript
+     * const matches = social.recommendBirthdayMatches(alice.id, 5);
+     * for (const m of matches) {
+     *   console.log(`${m.person.name}: ${m.birthday} (${m.matchType})`);
+     * }
+     * ```
+     */
+    recommendBirthdayMatches(personId: string, limit?: number): BirthdayMatchResult[];
+    /**
+     * Find people with birthdays in the next N days
+     *
+     * @param days - Number of days to look ahead
+     * @returns Array of birthday match results
+     *
+     * @example
+     * ```typescript
+     * const upcoming = social.findUpcomingBirthdays(7);
+     * console.log(`${upcoming.length} birthdays in the next week`);
+     * ```
+     */
+    findUpcomingBirthdays(days: number): BirthdayMatchResult[];
+    /**
+     * Find people with birthdays today
+     *
+     * @returns Array of person entities whose birthday is today
+     *
+     * @example
+     * ```typescript
+     * const todayBirthdays = social.findTodayBirthdays();
+     * for (const p of todayBirthdays) {
+     *   console.log(`🎂 Happy birthday, ${p.name}!`);
+     * }
+     * ```
+     */
+    findTodayBirthdays(): Entity[];
+    /**
+     * Find people with birthdays in a specific month
+     *
+     * @param month - Month number (1-12)
+     * @returns Array of person entities born in that month
+     *
+     * @example
+     * ```typescript
+     * const marchBirthdays = social.findBirthdaysInMonth(3);
+     * console.log(`${marchBirthdays.length} people have March birthdays`);
+     * ```
+     */
+    findBirthdaysInMonth(month: number): Entity[];
+    /**
+     * Get birthday statistics
+     *
+     * @returns Statistics object with total count, most common dates, and monthly distribution
+     *
+     * @example
+     * ```typescript
+     * const stats = social.getBirthdayStats();
+     * console.log(`Total with birthday: ${stats.totalWithBirthday}`);
+     * console.log('Most common dates:', stats.mostCommonDates);
+     * console.log('By month:', stats.byMonth);
+     * ```
+     */
+    getBirthdayStats(): BirthdayStats;
+    /**
+     * Check if two people have the same birthday
+     *
+     * @param personA - First person ID
+     * @param personB - Second person ID
+     * @param exact - If true, compare year+month+day; if false (default), compare month+day only
+     * @returns true if birthdays match
+     *
+     * @example
+     * ```typescript
+     * const sameDay = social.isSameBirthday(alice.id, bob.id);        // month+day only
+     * const sameExact = social.isSameBirthday(alice.id, bob.id, true); // exact date
+     * ```
+     */
+    isSameBirthday(personA: string, personB: string, exact?: boolean): boolean;
+    /**
+     * Rebuild birthday index from all person entities
+     *
+     * Useful after bulk imports or data recovery. Scans all persons
+     * and re-indexes their birthday properties.
+     *
+     * @example
+     * ```typescript
+     * // After bulk import of persons with birthday properties
+     * social.rebuildBirthdayIndex();
+     * ```
+     */
+    rebuildBirthdayIndex(): void;
+    /**
+     * Add parent-child relationship.
+     * Automatically determines father/mother based on parent's gender property.
+     * @param parentId - The parent's entity ID
+     * @param childId - The child's entity ID
+     * @returns The created relation, or null if failed
+     */
+    addParentChild(parentId: string, childId: string): Relation | null;
+    /**
+     * Add spouse relationship (bidirectional).
+     * @param personA - First person's ID
+     * @param personB - Second person's ID
+     */
+    addSpouse(personA: string, personB: string): Relation | null;
+    /**
+     * Add sibling relationship (bidirectional).
+     * @param personA - First person's ID
+     * @param personB - Second person's ID
+     * @param halfSibling - Whether this is a half-sibling relationship (default: false)
+     */
+    addSibling(personA: string, personB: string, halfSibling?: boolean): Relation | null;
+    /**
+     * Remove family relationship between two people.
+     * @returns True if any relationship was removed
+     */
+    removeFamilyRelation(personA: string, personB: string): boolean;
+    /**
+     * Add step-parent to step-child relationship (继父母-继子女).
+     */
+    addStepParentChild(stepParentId: string, stepChildId: string): Relation | null;
+    /**
+     * Add adoptive parent to adopted child relationship (养父母-养子女).
+     */
+    addAdoptiveParentChild(adoptiveParentId: string, adoptedChildId: string): Relation | null;
+    /**
+     * Add ex-spouse relationship (前配偶).
+     */
+    addExSpouse(personA: string, personB: string): Relation | null;
+    /** Get parents of a person */
+    getParents(personId: string): Entity[];
+    /** Get father of a person */
+    getFather(personId: string): Entity | null;
+    /** Get mother of a person */
+    getMother(personId: string): Entity | null;
+    /** Get children of a person */
+    getChildren(personId: string): Entity[];
+    /** Get sons of a person */
+    getSons(personId: string): Entity[];
+    /** Get daughters of a person */
+    getDaughters(personId: string): Entity[];
+    /** Get current spouse of a person */
+    getSpouse(personId: string): Entity | null;
+    /** Get all spouses including ex-spouses, with isEx flag */
+    getAllSpouses(personId: string): SpouseInfo[];
+    /** Get step-parents (继父母) */
+    getStepParents(personId: string): Entity[];
+    /** Get step-father (继父) */
+    getStepFather(personId: string): Entity | null;
+    /** Get step-mother (继母) */
+    getStepMother(personId: string): Entity | null;
+    /** Get step-children (继子女) */
+    getStepChildren(personId: string): Entity[];
+    /** Get adoptive parents (养父母) */
+    getAdoptiveParents(personId: string): Entity[];
+    /** Get adoptive father (养父) */
+    getAdoptiveFather(personId: string): Entity | null;
+    /** Get adoptive mother (养母) */
+    getAdoptiveMother(personId: string): Entity | null;
+    /** Get adopted children (养子女) */
+    getAdoptedChildren(personId: string): Entity[];
+    /**
+     * Get all parents with type (biological/step/adoptive).
+     * @returns Array of { person, type } objects
+     */
+    getAllParentsWithType(personId: string): Array<{
+        person: Entity;
+        type: 'biological' | 'step' | 'adoptive';
+    }>;
+    /**
+     * Get all children with type (biological/step/adopted).
+     * @returns Array of { person, type } objects
+     */
+    getAllChildrenWithType(personId: string): Array<{
+        person: Entity;
+        type: 'biological' | 'step' | 'adopted';
+    }>;
+    /** Get siblings */
+    getSiblings(personId: string): Entity[];
+    /** Get brothers */
+    getBrothers(personId: string): Entity[];
+    /** Get sisters */
+    getSisters(personId: string): Entity[];
+    /**
+     * Get all ancestors (traversing upward).
+     * @param maxGenerations - Maximum generations to traverse (default: 10)
+     */
+    getAncestors(personId: string, maxGenerations?: number): Entity[];
+    /**
+     * Get all descendants (traversing downward).
+     * @param maxGenerations - Maximum generations to traverse (default: 10)
+     */
+    getDescendants(personId: string, maxGenerations?: number): Entity[];
+    /** Get grandparents */
+    getGrandparents(personId: string): Entity[];
+    /** Get paternal grandfather (爷爷) */
+    getPaternalGrandfather(personId: string): Entity | null;
+    /** Get paternal grandmother (奶奶) */
+    getPaternalGrandmother(personId: string): Entity | null;
+    /** Get maternal grandfather (外公/姥爷) */
+    getMaternalGrandfather(personId: string): Entity | null;
+    /** Get maternal grandmother (外婆/姥姥) */
+    getMaternalGrandmother(personId: string): Entity | null;
+    /** Get grandchildren */
+    getGrandchildren(personId: string): Entity[];
+    /** Get uncles and aunts (叔伯姑姨舅) */
+    getUnclesAunts(personId: string): Entity[];
+    /** Get paternal uncles (叔叔/伯伯) */
+    getPaternalUncles(personId: string): Entity[];
+    /** Get paternal aunts (姑姑) */
+    getPaternalAunts(personId: string): Entity[];
+    /** Get maternal uncles (舅舅) */
+    getMaternalUncles(personId: string): Entity[];
+    /** Get maternal aunts (姨妈) */
+    getMaternalAunts(personId: string): Entity[];
+    /** Get nephews and nieces (侄子/侄女/外甥/外甥女) */
+    getNephewsNieces(personId: string): Entity[];
+    /** Get cousins (堂/表兄弟姐妹) */
+    getCousins(personId: string): Entity[];
+    /** Get paternal cousins (堂兄弟姐妹) */
+    getPaternalCousins(personId: string): Entity[];
+    /** Get maternal cousins (表兄弟姐妹) */
+    getMaternalCousins(personId: string): Entity[];
+    /** Get father-in-law (公公/岳父) */
+    getFatherInLaw(personId: string): Entity | null;
+    /** Get mother-in-law (婆婆/岳母) */
+    getMotherInLaw(personId: string): Entity | null;
+    /** Get siblings-in-law */
+    getSiblingsInLaw(personId: string): Entity[];
+    /** Get children-in-law (儿媳/女婿) */
+    getChildrenInLaw(personId: string): Entity[];
+    /**
+     * Calculate the family relationship between two people.
+     * Returns the full path including Chinese relationship title,
+     * generation difference, and blood distance.
+     * @param fromId - Starting person's ID
+     * @param toId - Ending person's ID
+     */
+    calculateFamilyRelationship(fromId: string, toId: string): FamilyPath | null;
+    /**
+     * Get the Chinese relationship title between two people.
+     * @example
+     * ```typescript
+     * const title = social.getRelationshipTitle(child.id, father.id);
+     * // Returns: "父亲"
+     * ```
+     */
+    getRelationshipTitle(fromId: string, toId: string): string | null;
+    /** Find the closest common ancestor of two people */
+    findCommonAncestor(personA: string, personB: string): Entity | null;
+    /**
+     * Calculate the blood distance between two people.
+     * Blood distance = number of parent-child links through common ancestor.
+     */
+    calculateBloodDistance(personA: string, personB: string): number | null;
+    /** Check if two people are direct blood relatives (ancestor/descendant) */
+    isDirectBloodRelative(personA: string, personB: string): boolean;
+    /**
+     * Build a family tree centered on a person.
+     * @param personId - Center person's ID
+     * @param generationsUp - Generations to traverse upward (default: 3)
+     * @param generationsDown - Generations to traverse downward (default: 3)
+     */
+    buildFamilyTree(personId: string, generationsUp?: number, generationsDown?: number): FamilyTreeData | null;
+    /**
+     * Get generation number of a person relative to a root.
+     * 0 = same as root, positive = younger, negative = older.
+     */
+    getGeneration(personId: string, rootId: string): number | null;
+    /** Get all people in the same generation (siblings, cousins, spouse) */
+    getSameGeneration(personId: string): Entity[];
+    /**
+     * Get paternal lineage (父系血统): father → grandfather → great-grandfather → ...
+     * @param maxGenerations - Maximum generations to trace (default: 10)
+     */
+    getPaternalLineage(personId: string, maxGenerations?: number): Entity[];
+    /**
+     * Get maternal lineage (母系血统): mother → grandmother → great-grandmother → ...
+     * @param maxGenerations - Maximum generations to trace (default: 10)
+     */
+    getMaternalLineage(personId: string, maxGenerations?: number): Entity[];
+    /** Get same surname relatives (同姓族人) */
+    getSameSurnameRelatives(personId: string): Entity[];
+    /**
+     * Get paternal clan members (父系宗族成员).
+     * Traditional Chinese "宗族" — all connected through paternal line.
+     * @param maxGenerations - Maximum generations to include (default: 5)
+     */
+    getPaternalClan(personId: string, maxGenerations?: number): Entity[];
+    /**
+     * Get family statistics for a tree rooted at the given person.
+     * @returns { total_members, total_generations, male_count, female_count, ... }
+     */
+    getFamilyStats(rootId: string): FamilyStats | null;
+    /**
+     * Set the gender of a person.
+     * @param gender - 'male', 'female', or 'unknown'
+     */
+    setPersonGender(personId: string, gender: Gender): boolean;
     /**
      * Delete any entity by ID (person, tag, attribute, item, etc.)
      *
@@ -1162,6 +1523,131 @@ export declare class SocialGraphV2 {
      * Check if an entity is in shadow (demoted) state.
      */
     isShadowEntity(entityId: string): boolean;
+    /**
+     * Decompose text into a memory sub-graph using the rule-based decomposer.
+     *
+     * The decomposer splits text into atomic entities (facts, concepts, etc.)
+     * connected by typed relations (CONTAINS, RELATES, etc.), forming a
+     * knowledge sub-graph suitable for graph-based memory storage.
+     *
+     * @param text - The input text to decompose
+     * @param context - Optional context string (e.g., "phase-7 development")
+     * @param userId - User identifier
+     * @returns DecompositionResult with episode root, entities, and relations
+     *
+     * @example
+     * ```typescript
+     * const result = graph.memoryTreeDecompose(
+     *   "We decided to use Store Trait to unify heterogeneous storage backends.",
+     *   "architecture-discussion",
+     *   "user-1"
+     * );
+     * console.log(result.episode);      // Episode root entity
+     * console.log(result.entities);     // Atomic entities (facts, etc.)
+     * console.log(result.relations);    // Typed relations
+     * ```
+     */
+    memoryTreeDecompose(text: string, context?: string, userId?: string): DecompositionResult;
+    /**
+     * Parse an LLM-generated JSON decomposition into a DecompositionResult.
+     *
+     * Use this when an external LLM (e.g., GPT-4, Claude) produces the
+     * decomposition JSON instead of the built-in rule-based decomposer.
+     *
+     * @param jsonStr - The LLM's JSON output string
+     * @param userId - User identifier
+     * @param context - Optional context string
+     * @param sourceText - The original text that was decomposed
+     * @returns Parsed DecompositionResult
+     */
+    memoryTreeParseLlmDecomposition(jsonStr: string, userId: string, context?: string, sourceText?: string): DecompositionResult;
+    /**
+     * Store a decomposed memory tree sub-graph into the graph.
+     *
+     * Pipeline:
+     * 1. Store episode root entity
+     * 2. Store all atomic entities (facts, concepts, etc.)
+     * 3. Store all typed relations (CONTAINS, CAUSES, ENABLES, etc.)
+     * 4. Index vectors for entities that have embeddings
+     * 5. Run conflict detection against existing memories
+     *
+     * @param decomposition - DecompositionResult (from memoryTreeDecompose)
+     * @param embeddings - Array of { entityId, embedding } pairs for vector indexing
+     * @param config - Optional MemoryTreeConfig
+     * @returns MemoryTreeStoreResult with counts
+     *
+     * @example
+     * ```typescript
+     * const decomp = graph.memoryTreeDecompose(text, ctx, userId);
+     * // Generate embeddings for each entity (using your embedding model)
+     * const embeddings = decomp.entities.map(e => ({
+     *   entityId: e.id,
+     *   embedding: await embed(e.content),
+     * }));
+     * const result = graph.memoryTreeStore(decomp, embeddings);
+     * console.log(result.entitiesStored, result.relationsStored);
+     * ```
+     */
+    memoryTreeStore(decomposition: DecompositionResult, embeddings: MemoryTreeEmbeddingInput[], config?: MemoryTreeConfig): MemoryTreeStoreResult;
+    /**
+     * Search memories using the memory tree activation engine.
+     *
+     * Combines vector search with N-hop graph traversal for richer recall:
+     * 1. Vector Search: Find top-K entities most similar to the query
+     * 2. Subgraph Expansion: Extract 2-hop subgraph for each hit
+     * 3. Scoring: Combined score = α*vector + β*proximity + γ*weight
+     * 4. Dedup & Sort: Merge overlapping subgraphs, sort by score
+     *
+     * @param queryEmbedding - Vector representation of the query
+     * @param userId - Filter by user
+     * @param config - Optional MemoryTreeConfig
+     * @returns ActivationResult with scored activated memories
+     *
+     * @example
+     * ```typescript
+     * const queryEmb = await embed("What architecture decisions were made?");
+     * const result = graph.memoryTreeSearch(queryEmb, "user-1");
+     * for (const mem of result.memories) {
+     *   console.log(mem.content, mem.score.combined);
+     * }
+     * ```
+     */
+    memoryTreeSearch(queryEmbedding: number[], userId: string, config?: MemoryTreeConfig): ActivationResult;
+    /**
+     * Run Hebbian weight strengthening for co-activated memories.
+     *
+     * Should be called after a query retrieves multiple memories that are
+     * used together in the same response. This strengthens the relations
+     * between co-activated entities, implementing "neurons that fire together
+     * wire together".
+     *
+     * @param activatedIds - List of entity IDs that were co-activated
+     * @param config - Optional MemoryTreeConfig
+     * @returns Number of relation weights updated
+     */
+    memoryTreeStrengthen(activatedIds: string[], config?: MemoryTreeConfig): number;
+    /**
+     * Run a memory lifecycle scan (promote hot, demote cold).
+     *
+     * Should be called periodically (e.g., every N conversations).
+     * Uses DynamicNodeManager under the hood with memory-tree-aware config.
+     *
+     * @param config - Optional MemoryTreeConfig
+     * @returns MemoryScanReport with promoted/demoted/summaries counts
+     */
+    memoryTreeLifecycle(config?: MemoryTreeConfig): MemoryScanReport;
+    /**
+     * Detect and resolve conflicts between new entities and existing memories.
+     *
+     * This is a standalone API; conflict detection also runs automatically
+     * inside `memoryTreeStore()`.
+     *
+     * @param entities - Array of DecomposedEntity objects to check
+     * @param embeddings - Array of { entityId, embedding } pairs
+     * @param config - Optional MemoryTreeConfig
+     * @returns ConflictResult with detected conflicts and created relations
+     */
+    memoryTreeDetectConflicts(entities: DecomposedEntity[], embeddings: MemoryTreeEmbeddingInput[], config?: MemoryTreeConfig): ConflictResult;
 }
 /**
  * Graph mutation for batch operations
@@ -1356,6 +1842,232 @@ export interface WalCompactReport {
     /** Per-shard compaction results */
     shardResults: WalCompactShardResult[];
 }
+/**
+ * Configuration for the memory tree system.
+ */
+export interface MemoryTreeConfig {
+    /** Alpha weight for vector score in activation scoring (default: 0.5) */
+    activationAlpha?: number;
+    /** Beta weight for graph proximity in activation scoring (default: 0.3) */
+    activationBeta?: number;
+    /** Gamma weight for relation weight in activation scoring (default: 0.2) */
+    activationGamma?: number;
+    /** Max hops for subgraph extraction during activation (default: 2) */
+    activationMaxHops?: number;
+    /** Max nodes per subgraph during activation (default: 50) */
+    activationMaxNodes?: number;
+    /** Top-K vector search results to expand (default: 10) */
+    activationTopK?: number;
+    /** Minimum vector similarity for conflict detection (default: 0.8) */
+    conflictMinSimilarity?: number;
+    /** Whether to enable automatic Hebbian weight strengthening (default: true) */
+    hebbianEnabled?: boolean;
+    /** Hebbian weight increment per co-activation (default: 0.05) */
+    hebbianIncrement?: number;
+    /** Maximum relation weight cap (default: 1.0) */
+    hebbianMaxWeight?: number;
+    /** DynamicNode promote threshold (hit count) (default: 5) */
+    promoteHitThreshold?: number;
+    /** DynamicNode demote idle timeout in seconds (default: 604800 = 7 days) */
+    demoteIdleTimeoutSecs?: number;
+    /** Entity types that should never be demoted */
+    preserveEntityTypes?: string[];
+}
+/**
+ * A decomposed entity extracted from text.
+ */
+export interface DecomposedEntity {
+    /** Unique entity ID */
+    id: string;
+    /** Entity type (e.g., "episode", "fact", "concept", "decision", "actor") */
+    entity_type: string;
+    /** Content text */
+    content: string;
+    /** Optional entity name */
+    name?: string;
+    /** Confidence score (0.0 ~ 1.0) */
+    confidence: number;
+    /** Additional properties */
+    properties: Record<string, unknown>;
+}
+/**
+ * A decomposed relation extracted from text.
+ */
+export interface DecomposedRelation {
+    /** Unique relation ID */
+    id: string;
+    /** Source entity ID */
+    source: string;
+    /** Target entity ID */
+    target: string;
+    /** Relation type (e.g., "CONTAINS", "CAUSES", "ENABLES", "RELATES") */
+    relation_type: string;
+    /** Relation weight (0.0 ~ 1.0) */
+    weight: number;
+    /** Additional metadata */
+    metadata: Record<string, unknown>;
+}
+/**
+ * Result of text decomposition into a memory sub-graph.
+ */
+export interface DecompositionResult {
+    /** Episode root entity */
+    episode: DecomposedEntity;
+    /** Atomic entities extracted from text */
+    entities: DecomposedEntity[];
+    /** Typed relations between entities */
+    relations: DecomposedRelation[];
+    /** Original source text */
+    source_text: string;
+}
+/**
+ * Embedding input for memory tree operations.
+ */
+export interface MemoryTreeEmbeddingInput {
+    /** Entity ID this embedding belongs to */
+    entityId: string;
+    /** The embedding vector (float array) */
+    embedding: number[];
+}
+/**
+ * Result of storing a memory tree sub-graph.
+ */
+export interface MemoryTreeStoreResult {
+    /** ID of the episode root entity */
+    episode_id: string;
+    /** Number of entities stored */
+    entities_stored: number;
+    /** Number of relations stored */
+    relations_stored: number;
+    /** Number of vectors indexed */
+    vectors_indexed: number;
+    /** Number of conflicts detected */
+    conflicts_detected: number;
+    /** Number of SUPERSEDES/CONFLICTS relations created */
+    relations_created_by_conflict: number;
+}
+/**
+ * Score breakdown for an activated memory.
+ */
+export interface ActivationScore {
+    /** Vector similarity score component */
+    vector_score: number;
+    /** Graph proximity score component */
+    proximity_score: number;
+    /** Relation weight score component */
+    weight_score: number;
+    /** Combined weighted score */
+    combined: number;
+}
+/**
+ * A relation in the activated subgraph.
+ */
+export interface ActivatedRelation {
+    /** Relation ID */
+    relation_id: string;
+    /** Source entity ID */
+    source: string;
+    /** Target entity ID */
+    target: string;
+    /** Relation type */
+    relation_type: string;
+    /** Relation weight */
+    weight: number;
+}
+/**
+ * An activated memory entity from the memory tree search.
+ */
+export interface ActivatedMemory {
+    /** Entity ID */
+    entity_id: string;
+    /** Entity type */
+    entity_type: string;
+    /** Entity content */
+    content: string;
+    /** Activation score breakdown */
+    score: ActivationScore;
+    /** Hop distance from the nearest vector anchor */
+    hop_distance: number;
+    /** Relations connecting this entity to other activated entities */
+    connected_relations: ActivatedRelation[];
+}
+/**
+ * Result of a memory activation (search) query.
+ */
+export interface ActivationResult {
+    /** Activated memories, sorted by combined score (descending) */
+    memories: ActivatedMemory[];
+    /** Total entities explored during activation */
+    entities_explored: number;
+    /** Total subgraphs extracted */
+    subgraphs_extracted: number;
+    /** Vector search anchor IDs (the top-K vector hits) */
+    anchor_ids: string[];
+}
+/**
+ * Report from a memory lifecycle scan.
+ */
+export interface MemoryScanReport {
+    /** Number of entities promoted (strengthened) */
+    promoted: number;
+    /** Number of entities demoted (forgotten) */
+    demoted: number;
+    /** Number of summaries created for demoted entities */
+    summaries_created: number;
+    /** Number of Hebbian weight updates applied */
+    hebbian_updates: number;
+    /** Total entities scanned */
+    entities_scanned: number;
+}
+/**
+ * A detected memory conflict.
+ */
+export interface MemoryConflict {
+    /** New entity ID */
+    new_entity_id: string;
+    /** Existing entity ID */
+    existing_entity_id: string;
+    /** Similarity score between the two */
+    similarity: number;
+    /** Conflict type: "supersedes" | "contradicts" | "supplements" */
+    conflict_type: string;
+    /** Relation created (if any) */
+    relation_created?: string;
+}
+/**
+ * Result of conflict detection.
+ */
+export interface ConflictResult {
+    /** Detected conflicts */
+    conflicts: MemoryConflict[];
+    /** Number of entities checked */
+    entities_checked: number;
+    /** Number of relations created */
+    relations_created: number;
+}
+/**
+ * Memory Tree entity type constants.
+ */
+export declare const MemoryEntityTypes: {
+    readonly EPISODE: "episode";
+    readonly FACT: "fact";
+    readonly CONCEPT: "concept";
+    readonly DECISION: "decision";
+    readonly ACTOR: "actor";
+    readonly PREFERENCE: "preference";
+};
+/**
+ * Memory Tree relation type constants.
+ */
+export declare const MemoryRelationTypes: {
+    readonly CONTAINS: "CONTAINS";
+    readonly CAUSES: "CAUSES";
+    readonly ENABLES: "ENABLES";
+    readonly RELATES: "RELATES";
+    readonly SUPERSEDES: "SUPERSEDES";
+    readonly CONFLICTS: "CONFLICTS";
+    readonly SUPPLEMENTS: "SUPPLEMENTS";
+};
 /**
  * Create a SocialGraphV2 instance with default configuration
  */