synapse-kit 0.0.0-stage → 0.3.1

package/dist/memory/causal-store.d.ts

@@ -0,0 +1,280 @@
+/**
+ * 인과율 트리거 규격
+ */
+export interface CausalTrigger {
+    readonly files?: readonly string[];
+    readonly keywords?: readonly string[];
+    readonly commands?: readonly string[];
+    readonly alwaysActive?: boolean;
+}
+/**
+ * 인과율 간선(Relation) 규격
+ */
+export interface CausalRelation {
+    readonly from: string;
+    readonly to: string;
+    readonly relationType: string;
+    readonly relation?: string;
+}
+/**
+ * 인과율 규칙(Node) 규격
+ */
+export interface CausalRule {
+    readonly id: string;
+    readonly domain: string;
+    readonly title: string;
+    readonly entityType?: string;
+    readonly triggers: CausalTrigger;
+    readonly invariants: readonly string[];
+    readonly actions: readonly string[];
+    readonly context: readonly string[];
+    readonly lastVerified?: string;
+    readonly name?: string;
+    readonly confidence?: number;
+    readonly weight?: number;
+    readonly updatedAt?: string;
+    readonly description?: string;
+    readonly pattern?: string;
+}
+/**
+ * 인과율 메모리 데이터베이스 규격
+ */
+export interface CausalMemoryDatabase {
+    readonly version: string;
+    readonly updatedAt: string;
+    readonly totalRules: number;
+    readonly totalRelations: number;
+    readonly rules: readonly CausalRule[];
+    readonly relations: readonly CausalRelation[];
+}
+/**
+ * 공명 쿼리 입력 규격
+ */
+export interface CausalQueryOptions {
+    readonly files?: readonly string[];
+    readonly keywords?: readonly string[];
+    readonly command?: string;
+    readonly domain?: string;
+    readonly propagateRelations?: boolean;
+    readonly maxHops?: number;
+}
+/**
+ * 공명 쿼리 결과 규격
+ */
+export interface CausalResonanceResult {
+    readonly queryDurationMs: number;
+    readonly matchedCount: number;
+    readonly totalDatabaseRules: number;
+    readonly resonanceRules: readonly CausalRule[];
+    readonly activeRelations: readonly CausalRelation[];
+    readonly tokenDietSavingsRatio: string;
+}
+/**
+ * 구형 memory MCP 호환 엔티티 규격
+ */
+export interface LegacyEntityInput {
+    readonly name: string;
+    readonly entityType: string;
+    readonly observations: readonly string[];
+}
+/**
+ * 인과율 메모리 저장소 및 O(1) 역인덱스 공명 엔진 클래스 (SRP 및 OCP 준수)
+ */
+export declare class CausalMemoryStore {
+    private readonly dbPath;
+    private database;
+    private lastMtimeMs;
+    private alwaysActiveRules;
+    private domainIndex;
+    private commandIndex;
+    private exactKeywordIndex;
+    private exactFileIndex;
+    private prefixFileRules;
+    private compiledSearchRules;
+    private titleToRuleMap;
+    private idToRuleMap;
+    private relationAdjacency;
+    constructor(customPath?: string, initialDatabase?: CausalMemoryDatabase);
+    /**
+     * 디스크 파일 변경(mtimeMs)이 감지된 경우에만 스마트 리로드 수행 (Zero-Copy Cache)
+     */
+    reloadIfNeeded(): boolean;
+    /**
+     * 강제 디스크 리로드
+     */
+    reload(): void;
+    /**
+     * 인메모리 데이터베이스 직접 주입 (벤치마크 및 인메모리 시뮬레이션용)
+     */
+    loadFromMemory(db: CausalMemoryDatabase): void;
+    /**
+     * O(1) 역인덱스(Inverted Index) 및 인접 리스트 그래프(Adjacency List) 재구축
+     */
+    private rebuildIndices;
+    /**
+     * 동일 제목(title) 규칙 중복 시 도메인 우선순위 점수 산출
+     */
+    private static getRuleDomainPriority;
+    /**
+     * 규칙 배열에서 동일 제목(title) 중복 제거 및 정규화
+     */
+    private static deduplicateRulesByTitle;
+    /**
+     * 데이터베이스 로드
+     */
+    private loadDatabase;
+    /**
+     * 데이터베이스 디스크 동기화
+     */
+    private saveDatabase;
+    getAllRules(): readonly CausalRule[];
+    getAllRelations(): readonly CausalRelation[];
+    getStatus(): {
+        version: string;
+        updatedAt: string;
+        totalRules: number;
+        totalRelations: number;
+        dbPath: string;
+        domains: string[];
+        domainCounts: Record<string, number>;
+    };
+    /**
+     * 부분 문자열 폴백 검색을 위한 지연 컴파일러 (Lazy Compilation)
+     */
+    private getCompiledSearchRules;
+    /**
+     * 초고속 O(1) 역인덱스 및 다중 홉(Multi-Hop) 그래프 전파 공명 쿼리 엔진
+     */
+    queryResonance(options: CausalQueryOptions): CausalResonanceResult;
+    /**
+     * 신규 규칙 등록 또는 기존 규칙 갱신
+     */
+    assertRule(rule: CausalRule, persistToDisk?: boolean): void;
+    /**
+     * 구형 memory MCP 호환: read_graph 대체 (초경량 인과 공명 요약 반환)
+     */
+    readSmartGraph(files?: readonly string[]): {
+        causalMemoryEngine: string;
+        tokenDietSavings: string;
+        queryDurationMs: number;
+        activeEntitiesCount: number;
+        totalIndexedRules: number;
+        totalIndexedRelations: number;
+        availableDomains: Record<string, number>;
+        hint: string;
+        entities: {
+            name: string;
+            entityType: string;
+            domain: string;
+            invariants: readonly string[];
+            actions: readonly string[];
+            observations: string[];
+        }[];
+        relations: readonly CausalRelation[];
+    };
+    /**
+     * 구형 memory MCP 호환: search_nodes
+     */
+    searchNodes(query: string): {
+        causalMemoryEngine: string;
+        tokenDietSavings: string;
+        queryDurationMs: number;
+        activeEntitiesCount: number;
+        totalIndexedRules: number;
+        totalIndexedRelations: number;
+        availableDomains: Record<string, number>;
+        hint: string;
+        entities: {
+            name: string;
+            entityType: string;
+            domain: string;
+            invariants: readonly string[];
+            actions: readonly string[];
+            observations: string[];
+        }[];
+        relations: readonly CausalRelation[];
+    } | {
+        entities: {
+            name: string;
+            entityType: string;
+            observations: string[];
+        }[];
+        relations: CausalRelation[];
+    };
+    /**
+     * 구형 memory MCP 호환: open_nodes
+     */
+    openNodes(names: readonly string[]): {
+        entities: {
+            name: string;
+            entityType: string;
+            observations: string[];
+        }[];
+        relations: CausalRelation[];
+    };
+    /**
+     * 구형 memory MCP 호환: create_entities
+     */
+    createEntities(entities: readonly LegacyEntityInput[], persistToDisk?: boolean): LegacyEntityInput[];
+    /**
+     * 구형 memory MCP 호환: add_observations
+     */
+    addObservations(observations: readonly {
+        readonly entityName: string;
+        readonly contents: readonly string[];
+    }[], persistToDisk?: boolean): {
+        entityName: string;
+        addedObservations: string[];
+    }[];
+    /**
+     * 구형 memory MCP 호환: create_relations
+     */
+    createRelations(relations: readonly CausalRelation[], persistToDisk?: boolean): CausalRelation[];
+    /**
+     * 단일 인과 규칙 삭제 (연결된 고아 인과 간선 동시 정리)
+     */
+    deleteRule(ruleId: string, persistToDisk?: boolean): boolean;
+    /**
+     * 구형 memory MCP 호환: delete_entities
+     */
+    deleteEntities(entityNames: readonly string[], persistToDisk?: boolean): void;
+    /**
+     * 구형 memory MCP 호환: delete_observations
+     */
+    deleteObservations(deletions: readonly {
+        readonly entityName: string;
+        readonly observations: readonly string[];
+    }[], persistToDisk?: boolean): void;
+    /**
+     * 구형 memory MCP 호환: delete_relations
+     */
+    deleteRelations(relations: readonly CausalRelation[], persistToDisk?: boolean): void;
+    /**
+     * 엔티티 입력으로부터 도메인 및 인과율 규칙 자동 추론
+     */
+    static inferRuleFromEntity(ent: LegacyEntityInput, today: string): CausalRule;
+    /**
+     * 메모리 무결성 감사 (Audit)
+     */
+    audit(): {
+        ok: boolean;
+        totalRules: number;
+        totalRelations: number;
+        alwaysActiveCount: number;
+        issues: string[];
+    };
+    /**
+     * 원시 데이터베이스 객체 반환 (백업 및 피어 동기화용)
+     */
+    getRawDatabase(): CausalMemoryDatabase;
+    /**
+     * 원격 피어 데이터베이스와 로컬 데이터베이스 양방향 무손실 병합 (Sync)
+     */
+    mergeDatabase(incomingRules: readonly CausalRule[], incomingRelations?: readonly CausalRelation[]): {
+        addedRules: number;
+        updatedRules: number;
+        addedRelations: number;
+        totalRules: number;
+        totalRelations: number;
+    };
+}

package/dist/memory/causal-synthesizer.d.ts

@@ -0,0 +1,96 @@
+import { ContextCheckpointStore, type ContextCheckpoint } from './causal-context';
+import { CausalMemoryStore } from './causal-store';
+/**
+ * Git 변경 사항 상세 통계 규격
+ */
+export interface GitChangeStats {
+    readonly insertions: number;
+    readonly deletions: number;
+    readonly filesChanged: number;
+}
+/**
+ * Git 변경 코드에서 추출된 주요 심볼 메타데이터 규격
+ */
+export interface ExtractedCodeSymbols {
+    readonly functions: readonly string[];
+    readonly classes: readonly string[];
+    readonly interfaces: readonly string[];
+    readonly types: readonly string[];
+}
+/**
+ * 작업 트리의 변경 사항 요약 규격
+ */
+export interface GitChangeSummary {
+    readonly cwd: string;
+    readonly branch?: string;
+    readonly commit?: string;
+    readonly modifiedFiles: readonly string[];
+    readonly addedFiles: readonly string[];
+    readonly deletedFiles: readonly string[];
+    readonly untrackedFiles: readonly string[];
+    readonly allActiveFiles: readonly string[];
+    readonly stats: GitChangeStats;
+    readonly extractedSymbols: ExtractedCodeSymbols;
+    readonly detectedDomains: readonly string[];
+}
+/**
+ * 역합성된 의도 및 진행 상태 규격
+ */
+export interface SynthesizedIntent {
+    readonly title: string;
+    readonly goal: string;
+    readonly completedSteps: readonly string[];
+    readonly pendingTasks: readonly string[];
+    readonly keyDecisions: readonly string[];
+    readonly activeInvariants: readonly string[];
+    readonly suggestedKeywords: readonly string[];
+}
+/**
+ * 자동 체크포인트 생성 옵션
+ */
+export interface AutoCheckpointOptions {
+    readonly title?: string;
+    readonly goal?: string;
+    readonly extraCompletedSteps?: readonly string[];
+    readonly extraPendingTasks?: readonly string[];
+    readonly extraKeyDecisions?: readonly string[];
+    readonly extraInvariants?: readonly string[];
+    readonly customMeta?: Record<string, unknown>;
+    readonly autoResonance?: boolean;
+}
+/**
+ * Git 커밋 및 diff 기반으로 작업자의 의도와 상태를 역합성하는 인과율 엔진 클래스 (SRP 준수)
+ */
+export declare class CausalSynthesizerEngine {
+    private readonly contextStore;
+    private readonly memoryStore;
+    constructor(contextStore?: ContextCheckpointStore, memoryStore?: CausalMemoryStore);
+    /**
+     * 지정된 작업 디렉터리의 Git 상태와 diff를 분석하여 변경 내역 요약 생성
+     */
+    inspectGitChanges(cwd?: string): Promise<GitChangeSummary>;
+    /**
+     * Git 통계 파싱 (git diff --stat)
+     */
+    private parseGitStats;
+    /**
+     * git diff로부터 변경된 함수, 클래스, 타입 심볼을 추출
+     */
+    private extractSymbolsFromDiff;
+    /**
+     * 파일 경로 기반 도메인 분류
+     */
+    private detectDomainsFromFiles;
+    /**
+     * Git 미설치 또는 Git 저장소가 아닌 경우의 폴백 파일시스템 스캔
+     */
+    private fallbackFilesystemScan;
+    /**
+     * 변경 사항 분석 결과를 기반으로 작업 의도 및 컨텍스트를 자동 역합성(Reverse Synthesis)
+     */
+    synthesizeIntent(summary: GitChangeSummary, customTitle?: string): SynthesizedIntent;
+    /**
+     * 원클릭 자동 체크포인트 생성 (Git diff 분석 ➔ 역합성 ➔ 스냅샷 저장)
+     */
+    autoCheckpoint(cwd?: string, options?: AutoCheckpointOptions): Promise<ContextCheckpoint>;
+}

package/dist/memory/causal-timeseries.d.ts

@@ -0,0 +1,92 @@
+import { ContextCheckpointStore, type ContextCheckpoint } from './causal-context';
+/**
+ * 시계열 이벤트 레코드 규격
+ */
+export interface TimelineEvent {
+    readonly id: string;
+    readonly timestamp: string;
+    readonly timestampMs: number;
+    readonly type: 'checkpoint' | 'rule_added' | 'rule_updated' | 'branch_merged' | 'trap_recorded';
+    readonly sessionId: string;
+    readonly title: string;
+    readonly summary: string;
+    readonly tags: readonly string[];
+    readonly checkpointId?: string;
+}
+/**
+ * 두 체크포인트 간의 시계열 차분(Diff) 결과 규격
+ */
+export interface CheckpointDiffResult {
+    readonly fromId?: string;
+    readonly toId?: string;
+    readonly fromCheckpointId: string;
+    readonly toCheckpointId: string;
+    readonly fromTimestamp: string;
+    readonly toTimestamp: string;
+    readonly timeDeltaHours: number;
+    readonly newlyCompletedSteps?: readonly string[];
+    readonly resolvedPendingTasks?: readonly string[];
+    readonly addedModifiedFiles?: readonly string[];
+    readonly addedPendingTasks: readonly string[];
+    readonly resolvedTasks: readonly string[];
+    readonly newCompletedSteps: readonly string[];
+    readonly newDecisions: readonly string[];
+    readonly modifiedFilesDelta: {
+        readonly added: readonly string[];
+        readonly removed: readonly string[];
+        readonly retained: readonly string[];
+    };
+    readonly activeInvariantsDelta: {
+        readonly added: readonly string[];
+        readonly removed: readonly string[];
+    };
+}
+/**
+ * 시계열 감쇠 가중치 계산기 및 타임라인 분석기 클래스 (SRP 준수)
+ */
+export declare class CausalTimeSeriesEngine {
+    private readonly contextStore;
+    constructor(contextStore?: ContextCheckpointStore, _memoryStore?: unknown);
+    /**
+     * 시계열 감쇠 지수 가중치 산출 (시간 경과 감쇠 + 빈도 가산)
+     * Score = BaseScore * exp(-lambda * deltaHours) + alpha * ln(1 + hitCount)
+     */
+    static calculateTemporalDecayScore(options: {
+        baseScore?: number;
+        lastActiveMs: number;
+        nowMs?: number;
+        halfLifeHours?: number;
+        hitCount?: number;
+    }): number;
+    /**
+     * 공명 인과 규칙들에 시계열 시간 감쇠 가중치 계산 반영
+     */
+    computeDecayedResonance<T extends {
+        updatedAt?: string;
+        confidence?: number;
+        weight?: number;
+    }>(rules: readonly T[]): Array<T & {
+        decayScore: number;
+    }>;
+    /**
+     * 특정 세션 또는 전체 작업의 시계열 타임라인 궤적 생성
+     */
+    generateTimeline(options?: number | {
+        sessionId?: string;
+        sinceMs?: number;
+        limit?: number;
+    }): TimelineEvent[];
+    /**
+     * 두 체크포인트 간의 차분(Diff) 계산
+     */
+    diffCheckpoints(fromId: string, toId: string): CheckpointDiffResult;
+    /**
+     * 특정 시점으로 컨텍스트 되감기(Rewind)
+     * 지정한 체크포인트를 최신 체크포인트로 재발행(Clone)하여 안전하게 되돌림
+     */
+    rewindToCheckpoint(targetIdOrTag: string): Promise<ContextCheckpoint>;
+    /**
+     * 시계열 차분 결과 마크다운 렌더러
+     */
+    static formatDiffReport(diff: CheckpointDiffResult): string;
+}

package/dist/memory/cli.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env bun
+export interface MemoryCliOptions {
+    lang?: string;
+    compact?: boolean;
+    agent?: boolean;
+    agentMode?: boolean;
+    force?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * synapse memory CLI 명령어 핸들러
+ */
+export declare function handleMemoryCommand(args: readonly string[], options?: MemoryCliOptions): Promise<number>;