@susu-eng/gralkor 26.0.0

package/dist/cli/lib/version.js

@@ -0,0 +1,51 @@
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Read CLI version from package.json (single source of truth). */
+export function getCLIVersion() {
+    try {
+        const __dirname = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(__dirname, "..", "..", "..", "package.json"), "utf-8"));
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * Tarball naming patterns:
+ *   susu-eng-gralkor-memory-{version}.tgz  (make pack output)
+ *   susu-eng-gralkor-{version}.tgz          (pnpm pack output)
+ */
+const TARBALL_PATTERNS = [
+    /susu-eng-gralkor-memory-(\d+\.\d+\.\d+)\.tgz$/,
+    /susu-eng-gralkor-(\d+\.\d+\.\d+)\.tgz$/,
+];
+/** Extract semver from a tarball filename or path. Returns null if no match. */
+export function extractVersionFromTarball(filenameOrPath) {
+    const basename = filenameOrPath.split("/").pop() ?? filenameOrPath;
+    for (const pattern of TARBALL_PATTERNS) {
+        const match = basename.match(pattern);
+        if (match)
+            return match[1];
+    }
+    return null;
+}
+/** Extract version from an npm package reference like `@susu-eng/gralkor@19.0.4`. */
+export function extractVersionFromNpmRef(ref) {
+    const match = ref.match(/@(\d+\.\d+\.\d+)$/);
+    return match ? match[1] : null;
+}
+/** Compare two semver strings. Returns -1 (a < b), 0 (equal), or 1 (a > b). */
+export function compareVersions(a, b) {
+    const pa = a.split(".").map(Number);
+    const pb = b.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        if (pa[i] < pb[i])
+            return -1;
+        if (pa[i] > pb[i])
+            return 1;
+    }
+    return 0;
+}
+//# sourceMappingURL=version.js.map

package/dist/cli/lib/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../../src/cli/lib/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,mEAAmE;AACnE,MAAM,UAAU,aAAa;IAC3B,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QACjG,OAAO,GAAG,CAAC,OAAO,IAAI,SAAS,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,gBAAgB,GAAG;IACvB,+CAA+C;IAC/C,wCAAwC;CACzC,CAAC;AAEF,gFAAgF;AAChF,MAAM,UAAU,yBAAyB,CAAC,cAAsB;IAC9D,MAAM,QAAQ,GAAG,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,cAAc,CAAC;IACnE,KAAK,MAAM,OAAO,IAAI,gBAAgB,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACtC,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,wBAAwB,CAAC,GAAW;IAClD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;IAC7C,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACjC,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,eAAe,CAAC,CAAS,EAAE,CAAS;IAClD,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC,CAAC;QAC7B,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,72 @@
+export interface Episode {
+    uuid: string;
+    name: string;
+    content: string;
+    source_description: string;
+    group_id: string;
+    created_at: string;
+}
+export interface Fact {
+    uuid: string;
+    name: string;
+    fact: string;
+    group_id: string;
+    valid_at: string | null;
+    invalid_at: string | null;
+    expired_at: string | null;
+    created_at: string;
+}
+/** A filtered content block for episode ingestion. */
+export interface EpisodeBlock {
+    type: "text" | "thinking" | "tool_use" | "tool_result";
+    text: string;
+}
+/** A filtered message for episode ingestion. */
+export interface EpisodeMessage {
+    role: "user" | "assistant";
+    content: EpisodeBlock[];
+}
+export interface AddEpisodeParams {
+    name: string;
+    episode_body: string;
+    source_description: string;
+    group_id: string;
+    source?: "message" | "text" | "json";
+}
+export interface IngestMessagesParams {
+    name: string;
+    source_description: string;
+    group_id: string;
+    messages: EpisodeMessage[];
+}
+export interface SearchResults {
+    facts: Fact[];
+}
+export interface HealthResponse {
+    status: string;
+    graph?: {
+        connected: boolean;
+        node_count?: number;
+        edge_count?: number;
+        error?: string;
+    };
+    data_dir?: string;
+}
+export interface GraphitiClientOptions {
+    baseUrl: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+}
+export declare class GraphitiClient {
+    private baseUrl;
+    private timeoutMs;
+    private maxRetries;
+    constructor(options: GraphitiClientOptions);
+    private request;
+    health(): Promise<HealthResponse>;
+    addEpisode(params: AddEpisodeParams): Promise<Episode>;
+    ingestMessages(params: IngestMessagesParams): Promise<Episode>;
+    search(query: string, groupIds: string[], limit?: number): Promise<SearchResults>;
+    clearGraph(groupId: string): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,UAAU,GAAG,aAAa,CAAC;IACvD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,cAAc,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE;QACN,SAAS,EAAE,OAAO,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,EAAE,qBAAqB;YAM5B,OAAO;IAwDf,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC;IAIjC,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IAQtD,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ9D,MAAM,CACV,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAAE,EAClB,KAAK,SAAK,GACT,OAAO,CAAC,aAAa,CAAC;IAQnB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAIjD"}

package/dist/client.js

@@ -0,0 +1,85 @@
+export class GraphitiClient {
+    baseUrl;
+    timeoutMs;
+    maxRetries;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+        this.maxRetries = options.maxRetries ?? 2;
+    }
+    async request(method, path, body) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+            let clientError;
+            try {
+                const res = await fetch(`${this.baseUrl}${path}`, {
+                    method,
+                    headers: body ? { "Content-Type": "application/json" } : undefined,
+                    body: body ? JSON.stringify(body) : undefined,
+                    signal: controller.signal,
+                });
+                if (!res.ok) {
+                    const text = await res.text().catch(() => "").then((t) => t.slice(0, 500));
+                    const err = new Error(`Graphiti ${method} ${path} returned ${res.status}: ${text}`);
+                    // Don't retry client errors (4xx) — only server errors are transient
+                    if (res.status >= 400 && res.status < 500) {
+                        clientError = err;
+                        throw err;
+                    }
+                    lastError = err;
+                    if (attempt < this.maxRetries) {
+                        await new Promise((r) => setTimeout(r, 500 * (attempt + 1)));
+                    }
+                    continue;
+                }
+                const contentType = res.headers.get("content-type") ?? "";
+                if (contentType.includes("application/json")) {
+                    return (await res.json());
+                }
+                return (await res.text());
+            }
+            catch (err) {
+                if (clientError)
+                    throw clientError;
+                lastError = err instanceof Error ? err : new Error(String(err));
+                if (attempt < this.maxRetries) {
+                    await new Promise((r) => setTimeout(r, 500 * (attempt + 1)));
+                }
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        throw lastError;
+    }
+    async health() {
+        return this.request("GET", "/health");
+    }
+    async addEpisode(params) {
+        return this.request("POST", "/episodes", {
+            ...params,
+            idempotency_key: crypto.randomUUID(),
+            reference_time: new Date().toISOString(),
+        });
+    }
+    async ingestMessages(params) {
+        return this.request("POST", "/ingest-messages", {
+            ...params,
+            idempotency_key: crypto.randomUUID(),
+            reference_time: new Date().toISOString(),
+        });
+    }
+    async search(query, groupIds, limit = 10) {
+        return this.request("POST", "/search", {
+            query,
+            group_ids: groupIds,
+            num_results: limit,
+        });
+    }
+    async clearGraph(groupId) {
+        await this.request("POST", "/clear", { group_id: groupId });
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,69 @@
+export interface ModelConfig {
+    provider: string;
+    model: string;
+}
+export type OntologyAttributeValue = string | string[] | {
+    type: "string" | "int" | "float" | "bool" | "datetime";
+    description: string;
+} | {
+    enum: string[];
+    description: string;
+};
+export interface OntologyTypeDef {
+    description: string;
+    attributes?: Record<string, OntologyAttributeValue>;
+}
+export interface OntologyConfig {
+    entities?: Record<string, OntologyTypeDef>;
+    edges?: Record<string, OntologyTypeDef>;
+    edgeMap?: Record<string, string[]>;
+    excludedEntityTypes?: string[];
+}
+export declare function validateOntologyConfig(ontology?: OntologyConfig): void;
+export declare const PROVIDER_ENV_KEYS: Record<string, string>;
+export interface ConfigCheckResult {
+    ok: boolean;
+    checks: Array<{
+        label: string;
+        status: "pass" | "fail" | "warn";
+        message: string;
+    }>;
+}
+export declare function validateConfig(config: GralkorConfig): Promise<ConfigCheckResult>;
+export declare const GRAPHITI_URL = "http://127.0.0.1:8001";
+export declare const GRAPHITI_PORT = 8001;
+export declare const DEFAULT_LLM_PROVIDER = "gemini";
+export declare const DEFAULT_LLM_MODEL = "gemini-3.1-flash-lite-preview";
+export declare const DEFAULT_EMBEDDER_PROVIDER = "gemini";
+export declare const DEFAULT_EMBEDDER_MODEL = "gemini-embedding-2-preview";
+export interface GralkorConfig {
+    autoCapture: {
+        enabled: boolean;
+    };
+    autoRecall: {
+        enabled: boolean;
+        maxResults: number;
+    };
+    idleTimeoutMs: number;
+    llm?: ModelConfig;
+    embedder?: ModelConfig;
+    ontology?: OntologyConfig;
+    dataDir?: string;
+    test?: boolean;
+}
+export declare const defaultConfig: GralkorConfig;
+export declare function resolveConfig(raw?: Partial<GralkorConfig>): GralkorConfig;
+export declare function resolveProviders(config: GralkorConfig): {
+    llmProvider: string;
+    llmModel: string;
+    embedderProvider: string;
+    embedderModel: string;
+};
+export interface ReadyGate {
+    isReady(): boolean;
+    resolve(): void;
+}
+export declare function createReadyGate(): ReadyGate;
+/** Reset ready state. Only used in tests. */
+export declare function resetReadyGate(): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,sBAAsB,GAC9B,MAAM,GACN,MAAM,EAAE,GACR;IAAE,IAAI,EAAE,QAAQ,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC/E;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5C,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACnC,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC;AAaD,wBAAgB,sBAAsB,CAAC,QAAQ,CAAC,EAAE,cAAc,GAAG,IAAI,CAoDtE;AAED,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAKpD,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrF;AAED,wBAAsB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAwCtF;AAED,eAAO,MAAM,YAAY,0BAA0B,CAAC;AACpD,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAC7C,eAAO,MAAM,iBAAiB,kCAAkC,CAAC;AACjE,eAAO,MAAM,yBAAyB,WAAW,CAAC;AAClD,eAAO,MAAM,sBAAsB,+BAA+B,CAAC;AAEnE,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAClC,UAAU,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,eAAO,MAAM,aAAa,EAAE,aAI3B,CAAC;AAEF,wBAAgB,aAAa,CAAC,GAAG,GAAE,OAAO,CAAC,aAAa,CAAM,GAAG,aAAa,CAiB7E;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa;;;;;EAOrD;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,IAAI,OAAO,CAAC;IACnB,OAAO,IAAI,IAAI,CAAC;CACjB;AAeD,wBAAgB,eAAe,IAAI,SAAS,CAK3C;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,IAAI,IAAI,CAErC"}

package/dist/config.js

@@ -0,0 +1,163 @@
+const RESERVED_ENTITY_NAMES = new Set(["Entity", "Episodic", "Community", "Saga"]);
+const PROTECTED_ENTITY_ATTRS = new Set([
+    "uuid", "name", "group_id", "labels", "created_at", "summary", "attributes", "name_embedding",
+]);
+const PROTECTED_EDGE_ATTRS = new Set([
+    "uuid", "group_id", "source_node_uuid", "target_node_uuid", "created_at",
+    "name", "fact", "fact_embedding", "episodes", "expired_at", "valid_at", "invalid_at", "attributes",
+]);
+export function validateOntologyConfig(ontology) {
+    if (!ontology)
+        return;
+    const entityNames = new Set(Object.keys(ontology.entities ?? {}));
+    const edgeNames = new Set(Object.keys(ontology.edges ?? {}));
+    for (const name of entityNames) {
+        if (RESERVED_ENTITY_NAMES.has(name)) {
+            throw new Error(`Reserved entity name: '${name}' is used internally by Graphiti`);
+        }
+    }
+    for (const [name, def] of Object.entries(ontology.entities ?? {})) {
+        for (const attr of Object.keys(def.attributes ?? {})) {
+            if (PROTECTED_ENTITY_ATTRS.has(attr)) {
+                throw new Error(`Protected attribute '${attr}' on entity '${name}'`);
+            }
+        }
+    }
+    for (const [name, def] of Object.entries(ontology.edges ?? {})) {
+        for (const attr of Object.keys(def.attributes ?? {})) {
+            if (PROTECTED_EDGE_ATTRS.has(attr)) {
+                throw new Error(`Protected attribute '${attr}' on edge '${name}'`);
+            }
+        }
+    }
+    for (const [key, edgeTypes] of Object.entries(ontology.edgeMap ?? {})) {
+        const parts = key.split(",");
+        if (parts.length !== 2) {
+            throw new Error(`Invalid edgeMap key '${key}': expected 'EntityA,EntityB'`);
+        }
+        for (const part of parts) {
+            if (!entityNames.has(part)) {
+                throw new Error(`edgeMap references undeclared entity '${part}'`);
+            }
+        }
+        for (const edge of edgeTypes) {
+            if (!edgeNames.has(edge)) {
+                throw new Error(`edgeMap references undeclared edge '${edge}'`);
+            }
+        }
+    }
+    if (ontology.excludedEntityTypes) {
+        for (const name of ontology.excludedEntityTypes) {
+            if (entityNames.has(name)) {
+                throw new Error(`excludedEntityTypes contains declared entity '${name}' — contradictory`);
+            }
+        }
+    }
+}
+export const PROVIDER_ENV_KEYS = {
+    openai: "OPENAI_API_KEY",
+    anthropic: "ANTHROPIC_API_KEY",
+    gemini: "GOOGLE_API_KEY",
+    groq: "GROQ_API_KEY",
+};
+export async function validateConfig(config) {
+    const checks = [];
+    // LLM provider check
+    const llmProvider = config.llm?.provider ?? DEFAULT_LLM_PROVIDER;
+    const llmEnvKey = PROVIDER_ENV_KEYS[llmProvider];
+    if (!llmEnvKey) {
+        checks.push({ label: "LLM provider", status: "warn", message: `Unknown provider '${llmProvider}' — cannot verify API key` });
+    }
+    else if (process.env[llmEnvKey]) {
+        checks.push({ label: "LLM provider", status: "pass", message: `${llmProvider} (${llmEnvKey} set)` });
+    }
+    else {
+        checks.push({ label: "LLM provider", status: "fail", message: `${llmProvider} requires ${llmEnvKey}` });
+    }
+    // Embedder provider check
+    const embedderProvider = config.embedder?.provider ?? DEFAULT_EMBEDDER_PROVIDER;
+    const embedderEnvKey = PROVIDER_ENV_KEYS[embedderProvider];
+    if (!embedderEnvKey) {
+        checks.push({ label: "Embedder provider", status: "warn", message: `Unknown provider '${embedderProvider}' — cannot verify API key` });
+    }
+    else if (process.env[embedderEnvKey]) {
+        checks.push({ label: "Embedder provider", status: "pass", message: `${embedderProvider} (${embedderEnvKey} set)` });
+    }
+    else {
+        checks.push({ label: "Embedder provider", status: "fail", message: `${embedderProvider} requires ${embedderEnvKey}` });
+    }
+    // uv check
+    try {
+        const { execFile } = await import("node:child_process");
+        const { promisify } = await import("node:util");
+        const execFileAsync = promisify(execFile);
+        await execFileAsync("uv", ["--version"]);
+        checks.push({ label: "uv", status: "pass", message: "found on PATH" });
+    }
+    catch {
+        checks.push({ label: "uv", status: "fail", message: "not found on PATH — install: curl -LsSf https://astral.sh/uv/install.sh | sh" });
+    }
+    return {
+        ok: checks.every(c => c.status !== "fail"),
+        checks,
+    };
+}
+export const GRAPHITI_URL = "http://127.0.0.1:8001";
+export const GRAPHITI_PORT = 8001;
+export const DEFAULT_LLM_PROVIDER = "gemini";
+export const DEFAULT_LLM_MODEL = "gemini-3.1-flash-lite-preview";
+export const DEFAULT_EMBEDDER_PROVIDER = "gemini";
+export const DEFAULT_EMBEDDER_MODEL = "gemini-embedding-2-preview";
+export const defaultConfig = {
+    autoCapture: { enabled: true },
+    idleTimeoutMs: 5 * 60 * 1000,
+    autoRecall: { enabled: true, maxResults: 10 },
+};
+export function resolveConfig(raw = {}) {
+    return {
+        autoCapture: {
+            enabled: raw.autoCapture?.enabled ?? defaultConfig.autoCapture.enabled,
+        },
+        idleTimeoutMs: raw.idleTimeoutMs ?? defaultConfig.idleTimeoutMs,
+        autoRecall: {
+            enabled: raw.autoRecall?.enabled ?? defaultConfig.autoRecall.enabled,
+            maxResults: raw.autoRecall?.maxResults ?? defaultConfig.autoRecall.maxResults,
+        },
+        llm: raw.llm,
+        embedder: raw.embedder,
+        ontology: raw.ontology,
+        dataDir: raw.dataDir,
+        test: raw.test ?? false,
+    };
+}
+export function resolveProviders(config) {
+    return {
+        llmProvider: config.llm?.provider ?? DEFAULT_LLM_PROVIDER,
+        llmModel: config.llm?.model ?? DEFAULT_LLM_MODEL,
+        embedderProvider: config.embedder?.provider ?? DEFAULT_EMBEDDER_PROVIDER,
+        embedderModel: config.embedder?.model ?? DEFAULT_EMBEDDER_MODEL,
+    };
+}
+/**
+ * Module-level ready gate — shared across all plugin instances within the
+ * same process. This is critical because OpenClaw reloads the plugin 4+
+ * times per event, each creating a new instance. If the gate were per-
+ * instance, only the instance whose service `start()` ran would have a
+ * resolved gate; hooks/tools from newer instances would see `false` and
+ * silently skip graph calls even though the server is running fine.
+ *
+ * By making it module-level, the first `start()` resolves it and all
+ * subsequent reloads inherit the resolved state.
+ */
+let moduleReady = false;
+export function createReadyGate() {
+    return {
+        isReady: () => moduleReady,
+        resolve: () => { moduleReady = true; },
+    };
+}
+/** Reset ready state. Only used in tests. */
+export function resetReadyGate() {
+    moduleReady = false;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/hooks.d.ts

@@ -0,0 +1,131 @@
+import type { GraphitiClient, EpisodeMessage } from "./client.js";
+import type { GralkorConfig } from "./config.js";
+import { type ReadyGate } from "./config.js";
+/**
+ * A content block inside a message entry.
+ */
+interface ContentBlock {
+    type: string;
+    text?: string;
+    [key: string]: unknown;
+}
+/**
+ * A message entry in the OpenClaw messages array.
+ */
+interface MessageEntry {
+    role: string;
+    content: string | ContentBlock[];
+}
+/** before_prompt_build event — prompt and messages always present. */
+export interface PromptBuildEvent {
+    prompt: string;
+    messages: MessageEntry[];
+}
+/** agent_end event — messages always present. */
+export interface AgentEndEvent {
+    messages: MessageEntry[];
+    success?: boolean;
+    error?: unknown;
+    durationMs?: number;
+}
+/**
+ * Hook agent context — the second argument passed to agent hook handlers.
+ * Contains per-agent identity and session info.
+ */
+export interface HookAgentContext {
+    agentId?: string;
+    sessionKey?: string;
+    sessionId?: string;
+    workspaceDir?: string;
+    messageProvider?: string;
+}
+/**
+ * Hook session context — passed to session hooks (session_start, session_end).
+ * Has required sessionId unlike HookAgentContext.
+ */
+export interface HookSessionContext {
+    agentId?: string;
+    sessionId: string;
+    sessionKey?: string;
+}
+/**
+ * Extract the user's actual message from event.prompt.
+ *
+ * The prompt may be wrapped in metadata:
+ *   "Sender (untrusted metadata):\n```json\n{...}\n```\n\nActual message"
+ *
+ * System prompts (e.g. "A new session was started via /new") are not user messages.
+ */
+export declare function extractUserMessageFromPrompt(event: PromptBuildEvent): string;
+/**
+ * Extract the last user message text from the messages array.
+ * Used as fallback when the prompt contains only metadata wrapper.
+ */
+export declare function extractLastUserMessageFromMessages(messages: MessageEntry[]): string;
+/**
+ * Extract and filter messages for episode ingestion.
+ *
+ * Filters the raw OpenClaw message array down to user and assistant messages
+ * with only text/output_text/thinking blocks. Cleans user messages of system
+ * noise (session-start instructions, metadata wrappers, gralkor-memory XML).
+ * Serializes toolCall/toolUse/functionCall blocks as tool_use blocks.
+ * Converts toolResult messages to assistant messages with truncated tool_result blocks.
+ *
+ * The server handles transcript formatting and thinking distillation.
+ */
+export declare function extractMessagesFromCtx(event: AgentEndEvent): EpisodeMessage[];
+/**
+ * Count actual results in a native search response.
+ * Native memory_search returns JSON with metadata even when results are empty:
+ *   { "results": [], "provider": "...", ... }
+ * For non-JSON strings, returns 1 if non-empty (opaque content).
+ */
+export declare function countNativeResults(nativeResult: string | null): number;
+export type NativeSearchFn = (query: string) => Promise<string>;
+export interface RecallOpts {
+    setGroupId?: (id: string) => void;
+    getNativeSearch?: () => NativeSearchFn | null;
+    serverReady?: ReadyGate;
+}
+export declare function createBeforePromptBuildHandler(client: GraphitiClient, config: GralkorConfig, opts?: RecallOpts): (event: PromptBuildEvent, ctx?: HookAgentContext) => Promise<{
+    prependContext?: string;
+} | void>;
+/**
+ * Session buffer entry — holds the latest message snapshot for a session,
+ * flushed as a single episode on session boundary events.
+ */
+export interface SessionBuffer {
+    messages: MessageEntry[];
+    agentId?: string;
+    sessionKey?: string;
+}
+/**
+ * Keyed debouncer: stores a value per key and flushes it after idle timeout.
+ * Each `set()` resets the timer. `flush()` forces immediate delivery.
+ * At most one flush per key — whichever fires first (idle or explicit) wins.
+ */
+export declare class DebouncedFlush<T> {
+    private delayMs;
+    private onFlush;
+    private entries;
+    private timers;
+    constructor(delayMs: number, onFlush: (key: string, value: T) => Promise<void>);
+    set(key: string, value: T): void;
+    flush(key: string): Promise<void>;
+    flushAll(): Promise<void>;
+    has(key: string): boolean;
+    get pendingCount(): number;
+    get timerCount(): number;
+    dispose(): void;
+}
+/**
+ * Flush a session buffer → episode. Retries up to 3 times with exponential backoff.
+ */
+export declare function flushSessionBuffer(key: string, buffer: SessionBuffer, client: GraphitiClient, { retryDelayMs, test }?: {
+    retryDelayMs?: number;
+    test?: boolean;
+}): Promise<void>;
+export declare function createAgentEndHandler(config: GralkorConfig, debouncer: DebouncedFlush<SessionBuffer>): (event: AgentEndEvent, ctx?: HookAgentContext) => Promise<void>;
+export declare function createSessionEndHandler(debouncer: DebouncedFlush<SessionBuffer>): (_event: unknown, ctx: HookSessionContext) => Promise<void>;
+export {};
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"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"}