synapse-kit-memory 0.0.0-stage → 0.2.2

package/dist/causal-benchmark.d.ts

@@ -0,0 +1,29 @@
+import { type CausalMemoryDatabase } from './causal-store';
+export interface OverloadBenchmarkConfig {
+    readonly ruleScale: number;
+    readonly relationScale: number;
+    readonly concurrency: number;
+    readonly totalRequests: number;
+    readonly fileInputScale: number;
+    readonly crudIterations: number;
+}
+export interface ScenarioMetrics {
+    readonly name: string;
+    readonly passed: boolean;
+    readonly details: Record<string, string | number>;
+}
+export interface OverloadBenchmarkReport {
+    readonly timestamp: string;
+    readonly config: OverloadBenchmarkConfig;
+    readonly allPassed: boolean;
+    readonly totalDurationMs: number;
+    readonly scenarios: readonly ScenarioMetrics[];
+}
+/**
+ * 대규모 합성 인과율 데이터베이스 생성기 (10,000 Rules + 20,000 Relations + 5-Hop & Circular Chains)
+ */
+export declare function generateSyntheticDatabase(ruleCount: number, relationCount: number): CausalMemoryDatabase;
+/**
+ * 차세대 인과율 메모리(Causal Memory 2.1) 4대 차원 과부하 벤치마크 실행기
+ */
+export declare function executeOverloadBenchmark(customConfig?: Partial<OverloadBenchmarkConfig>, silent?: boolean): Promise<OverloadBenchmarkReport>;

package/dist/causal-config.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 인과율 메모리(Causal Memory) 전역 설정 및 환경 변수 모듈
+ * 하드코딩을 배제하고 환경 변수와 OS 표준 경로를 통해 설정값을 관리합니다.
+ */
+export declare const CAUSAL_MEMORY_CONFIG: {
+    /** 데이터베이스 스키마 버전 */
+    readonly SCHEMA_VERSION: string;
+    /** 전역 인과율 메모리 데이터베이스 기본 경로 */
+    readonly GLOBAL_DB_PATH: string;
+    /** 구형 메모리 백업 경로 */
+    readonly LEGACY_BACKUP_PATH: string;
+    /** 패키지 내장 폴백 데이터베이스 경로 */
+    readonly LOCAL_DB_PATH: string;
+    /** 독립 로컬 데몬 서버 기본 호스트 */
+    readonly DEFAULT_HOST: string;
+    /** 독립 로컬 데몬 서버 기본 포트 */
+    readonly DEFAULT_PORT: number;
+    /** MCP 서버 프로토콜 버전 */
+    readonly MCP_PROTOCOL_VERSION: string;
+    /** MCP 서버 식별 이름 */
+    readonly MCP_SERVER_NAME: "synapse-causal-memory";
+    /** 공명 쿼리 시 컨텍스트 최대 노출 줄 수 (토큰 절감 임계치) */
+    readonly MAX_CONTEXT_PREVIEW_LINES: number;
+};

package/dist/causal-migrator.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 구형 지식 그래프(memory_backup)를 차세대 인과율 메모리(Causal Memory 2.1)로 무손실 변환합니다.
+ * 엔티티뿐만 아니라 모든 인과 간선(Relations)을 100% 보존하며, 도메인 오분류를 방지합니다.
+ */
+export declare function migrateLegacyMemoryGraph(sourceBackupPath?: string, targetGlobalPath?: string, targetLocalPath?: string): {
+    readonly ok: boolean;
+    readonly totalRules: number;
+    readonly totalRelations: number;
+    readonly alwaysActiveCount: number;
+    readonly domains: readonly string[];
+};

package/dist/causal-query.d.ts

@@ -0,0 +1,21 @@
+import { type CausalResonanceResult } from './causal-store';
+/**
+ * Git 작업 트리의 변경 파일 목록 자동 추출
+ */
+export declare function detectModifiedFiles(cwd?: string): Promise<string[]>;
+/**
+ * 인과율 공명 쿼리 실행기
+ */
+export declare function runCausalQuery(rawOptions: {
+    files?: string[];
+    keywords?: string[];
+    command?: string;
+    domain?: string;
+    autoGit?: boolean;
+    cwd?: string;
+    propagateRelations?: boolean;
+}, storeCustomPath?: string): Promise<CausalResonanceResult>;
+/**
+ * AI 에이전트 주입용 초경량 마크다운/텍스트 포맷터
+ */
+export declare function formatResonanceForAgent(result: CausalResonanceResult, compact?: boolean): string;

package/dist/causal-server.d.ts

@@ -0,0 +1,299 @@
+import { CausalMemoryStore } from './causal-store';
+export interface ServerOptions {
+    readonly port?: number;
+    readonly host?: string;
+    readonly dbPath?: string;
+}
+export interface JsonRpcRequest {
+    readonly jsonrpc?: string;
+    readonly id?: string | number | null;
+    readonly method: string;
+    readonly params?: Record<string, any>;
+}
+/**
+ * MCP 표준 도구 스키마 목록 (신규 인과율 도구 3종 + 구형 memory 호환 도구 9종 = 총 12종)
+ */
+export declare const CAUSAL_MCP_TOOLS: readonly [{
+    readonly name: "query_causal_memory";
+    readonly description: "작업 컨텍스트(수정된 파일, 키워드, 명령어, 도메인)에 매칭되는 인과율 지식과 불변 규칙만 0ms 초경량으로 공명 쿼리합니다.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly files: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "감지할 대상 파일 경로 목록 (생략 시 Git 변경 파일 자동 감지)";
+            };
+            readonly keywords: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "검색할 도메인/작업 키워드 목록";
+            };
+            readonly command: {
+                readonly type: "string";
+                readonly description: "연동 명령어 (예: check, build, release, sign)";
+            };
+            readonly domain: {
+                readonly type: "string";
+                readonly description: "특정 도메인 필터";
+            };
+            readonly compact: {
+                readonly type: "boolean";
+                readonly description: "초소형 JSON 포맷 반환 여부";
+            };
+        };
+    };
+}, {
+    readonly name: "assert_causal_rule";
+    readonly description: "신규 인과율 규칙(원인 트리거 ➔ 불변 계약 ➔ 실행 지침)을 메모리에 등록하거나 갱신합니다.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["id", "domain", "title", "triggers"];
+        readonly properties: {
+            readonly id: {
+                readonly type: "string";
+            };
+            readonly domain: {
+                readonly type: "string";
+            };
+            readonly title: {
+                readonly type: "string";
+            };
+            readonly triggers: {
+                readonly type: "object";
+            };
+            readonly invariants: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly actions: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly context: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+        };
+    };
+}, {
+    readonly name: "audit_causal_memory";
+    readonly description: "인과율 메모리 데이터베이스의 무결성, 도메인 분포, 토큰 절감 상태를 감사(Audit)합니다.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+    };
+}, {
+    readonly name: "read_graph";
+    readonly description: "Read the active causal resonance knowledge graph (automatically filters out unrelated noise for 90%+ token savings)";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+    };
+}, {
+    readonly name: "search_nodes";
+    readonly description: "Search for causal rules and nodes in the knowledge graph based on a query and traverse causal relations";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["query"];
+        readonly properties: {
+            readonly query: {
+                readonly type: "string";
+                readonly description: "The search query to match against rule titles, domains, triggers, and invariants";
+            };
+        };
+    };
+}, {
+    readonly name: "open_nodes";
+    readonly description: "Open specific causal rule nodes in the knowledge graph by their names or IDs";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["names"];
+        readonly properties: {
+            readonly names: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "An array of entity names or rule IDs to retrieve";
+            };
+        };
+    };
+}, {
+    readonly name: "create_entities";
+    readonly description: "Create multiple new entities (automatically converted into structured Causal Rules)";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["entities"];
+        readonly properties: {
+            readonly entities: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly required: readonly ["name", "entityType", "observations"];
+                    readonly properties: {
+                        readonly name: {
+                            readonly type: "string";
+                        };
+                        readonly entityType: {
+                            readonly type: "string";
+                        };
+                        readonly observations: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+}, {
+    readonly name: "create_relations";
+    readonly description: "Create multiple new causal relations between nodes in the knowledge graph";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["relations"];
+        readonly properties: {
+            readonly relations: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly required: readonly ["from", "to", "relationType"];
+                    readonly properties: {
+                        readonly from: {
+                            readonly type: "string";
+                        };
+                        readonly to: {
+                            readonly type: "string";
+                        };
+                        readonly relationType: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+            };
+        };
+    };
+}, {
+    readonly name: "add_observations";
+    readonly description: "Add new invariants, actions, or context observations to existing causal rules";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["observations"];
+        readonly properties: {
+            readonly observations: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly required: readonly ["entityName", "contents"];
+                    readonly properties: {
+                        readonly entityName: {
+                            readonly type: "string";
+                        };
+                        readonly contents: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+}, {
+    readonly name: "delete_entities";
+    readonly description: "Delete multiple entities/rules and their associated causal relations";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["entityNames"];
+        readonly properties: {
+            readonly entityNames: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+        };
+    };
+}, {
+    readonly name: "delete_observations";
+    readonly description: "Delete specific observations from entities/rules in the causal memory";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["deletions"];
+        readonly properties: {
+            readonly deletions: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly required: readonly ["entityName", "observations"];
+                    readonly properties: {
+                        readonly entityName: {
+                            readonly type: "string";
+                        };
+                        readonly observations: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+}, {
+    readonly name: "delete_relations";
+    readonly description: "Delete multiple causal relations from the knowledge graph";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["relations"];
+        readonly properties: {
+            readonly relations: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly required: readonly ["from", "to", "relationType"];
+                    readonly properties: {
+                        readonly from: {
+                            readonly type: "string";
+                        };
+                        readonly to: {
+                            readonly type: "string";
+                        };
+                        readonly relationType: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+            };
+        };
+    };
+}];
+/**
+ * MCP JSON-RPC 2.0 요청 통합 처리기 (HTTP 데몬 및 Stdio 서버 공용)
+ */
+export declare function handleMcpJsonRpcRequest(rpc: JsonRpcRequest, store: CausalMemoryStore, dbPath?: string): Promise<Record<string, any> | null>;
+/**
+ * 인과율 메모리 독립 로컬 서버 (Causal Memory HTTP & MCP Daemon)
+ */
+export declare function startCausalServer(options?: ServerOptions): Bun.Server<undefined>;
+/**
+ * MCP 표준 입출력(stdio) 서버 모드
+ * Antigravity / Claude Code 등의 MCP 호스트가 프로세스를 직접 스폰하여 통신할 때 동작합니다.
+ * 로컬 데몬(4242 포트)이 실행 중이면 데몬으로 프록시하고, 꺼져 있으면 인메모리 스토어로 즉시 응답합니다.
+ */
+export declare function startCausalMcpStdioServer(dbPath?: string): Promise<void>;

package/dist/causal-store.d.ts

@@ -0,0 +1,247 @@
+/**
+ * 인과율 트리거 규격
+ */
+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;
+}
+/**
+ * 인과율 규칙(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;
+}
+/**
+ * 인과율 메모리 데이터베이스 규격
+ */
+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;
+    /**
+     * 데이터베이스 로드
+     */
+    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[];
+    /**
+     * 구형 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[];
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,12 @@
+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>;