@dahch/muninn 0.0.0-stage → 0.1.0

package/dist/service/memory-service.d.ts

@@ -0,0 +1,203 @@
+import Database from "better-sqlite3";
+import { type Project, type Observation, type Entity, type ObservationCategory, type EntityType, type ObservationEntity, type DependencyRelationType, type EntityDependency } from "../db/client.js";
+export { type Project, type Observation, type Entity, type ObservationCategory, type EntityType, type ObservationEntity, type DependencyRelationType, type EntityDependency, };
+export declare const VALID_CATEGORIES: ReadonlyArray<ObservationCategory>;
+export declare const VALID_ENTITY_TYPES: ReadonlyArray<EntityType>;
+export interface SymbolInput {
+    name?: string | null;
+    filePath?: string | null;
+    file_path?: string | null;
+    identifier?: string | null;
+    type?: EntityType | null;
+    entity_type?: EntityType | null;
+    id?: string | null;
+}
+export interface ObservationWithEntities extends Observation {
+    entities: Entity[];
+}
+export interface SaveObservationInput {
+    category: ObservationCategory | string;
+    title: string;
+    content: string;
+    topicKey?: string | null;
+    topic_key?: string | null;
+    projectId?: string;
+    project_id?: string;
+    symbols?: Array<SymbolInput | string> | null;
+}
+export interface SearchOptions {
+    query: string;
+    category?: ObservationCategory | string | null;
+    projectId?: string | null;
+    project_id?: string | null;
+    allProjects?: boolean | null;
+    limit?: number | null;
+}
+export interface SearchResult extends ObservationWithEntities {
+    rank: number;
+}
+export interface ContextOptions {
+    limit?: number | null;
+    category?: ObservationCategory | string | null;
+    topicKey?: string | null;
+    topic_key?: string | null;
+    projectId?: string | null;
+    project_id?: string | null;
+    allProjects?: boolean | null;
+}
+export interface SyncToDiskOptions {
+    projectId?: string;
+    allProjects?: boolean;
+}
+export interface LinkSymbolInput {
+    observationId?: string;
+    observation_id?: string;
+    symbol: SymbolInput | string;
+    projectId?: string;
+}
+export interface MemoryStats {
+    projects: number;
+    observations: number;
+    entities: number;
+    links: number;
+}
+export interface MemoryServiceOptions {
+    db?: Database.Database;
+    dbPath?: string;
+    projectRoot?: string;
+}
+export interface SymbolInspectionDependency {
+    entity: Entity;
+    relationType: DependencyRelationType;
+}
+export interface SymbolInspection {
+    entity: Entity;
+    dependencies: {
+        outgoing: SymbolInspectionDependency[];
+        incoming: SymbolInspectionDependency[];
+    };
+    observations: Observation[];
+}
+export interface IMemoryService {
+    readonly currentProject: Project;
+    readonly db: Database.Database;
+    saveObservation(input: SaveObservationInput): ObservationWithEntities;
+    search(options: SearchOptions): SearchResult[];
+    getContext(options?: ContextOptions): ObservationWithEntities[];
+    linkSymbol(inputOrObsId: LinkSymbolInput | string, symbol?: SymbolInput | string): {
+        observation: Observation;
+        entity: Entity;
+    };
+    inspectSymbol(symbol: string, projectId?: string): SymbolInspection | null;
+    getStats(projectId?: string): MemoryStats;
+    syncToDisk(targetPath?: string, options?: {
+        projectId?: string;
+        allProjects?: boolean;
+    }): {
+        path: string;
+        count: number;
+    };
+    importFromDisk(sourcePath?: string): {
+        imported: number;
+        skipped: number;
+    };
+    close?(force?: boolean): void;
+}
+/**
+ * Normalizes input symbols into canonical identifier, filePath, and entityType.
+ */
+export declare function normalizeSymbol(symbol: SymbolInput | string): {
+    identifier: string;
+    filePath: string;
+    entityType: EntityType;
+};
+/**
+ * Safely format query terms for SQLite FTS5 syntax.
+ * Escapes special characters, wraps terms in quotes, and safely supports prefix queries.
+ * Returns an empty string if no valid search terms remain.
+ */
+export declare function sanitizeFtsQuery(query: string): string;
+export declare class MemoryService implements IMemoryService {
+    private readonly _db;
+    private readonly _currentProject;
+    private readonly isDbOwned;
+    constructor(options?: MemoryServiceOptions);
+    get db(): Database.Database;
+    get currentProject(): Project;
+    /**
+     * Screen the durable JSONL export path exactly like the database path
+     * (SEC-006): a `.huginn/memories.jsonl` a cloned repository ships as a symlink
+     * must be neither written through nor read from — either direction would move
+     * project content outside the project (or pull foreign content in, where the
+     * MCP memory tools would serve it to the agent).
+     */
+    private assertMemoryPath;
+    /**
+     * Closes the database connection if managed internally by the service.
+     */
+    close(force?: boolean): void;
+    /**
+     * Saves an observation and transactionally links any provided symbols.
+     */
+    saveObservation(input: SaveObservationInput): ObservationWithEntities;
+    /**
+     * Retrieves linked entities for observation IDs in chunks of at most 500
+     * to prevent exceeding SQLite parameter bounds.
+     */
+    private _fetchEntitiesForObservations;
+    /**
+     * Searches observations using FTS5 BM25 relevance ranking.
+     * Query terms are safely sanitized, rank ordering is ASC (lower BM25 = higher relevance),
+     * and linked entities are attached to each result.
+     */
+    search(options: SearchOptions): SearchResult[];
+    /**
+     * Retrieves recent observations ordered by updated_at DESC, created_at DESC.
+     */
+    getContext(options?: ContextOptions): ObservationWithEntities[];
+    /**
+     * Transactionally links an entity to an observation.
+     */
+    linkSymbol(inputOrObsId: LinkSymbolInput | string, symbolArg?: SymbolInput | string): {
+        observation: Observation;
+        entity: Entity;
+    };
+    /**
+     * Escapes LIKE pattern special characters (%, _, \)
+     */
+    private _escapeLikePattern;
+    /**
+     * Inspects a symbol in Muninn memory, returning its entity metadata,
+     * incoming and outgoing dependencies, and linked observations.
+     */
+    inspectSymbol(symbol: string, projectId?: string): SymbolInspection | null;
+    /**
+     * Retrieves aggregate counts of projects, observations, entities, and links.
+     */
+    getStats(projectId?: string): MemoryStats;
+    /**
+     * Exports all observations with linked entities to a JSON Lines (.jsonl) file.
+     */
+    syncToDisk(targetPath?: string, options?: {
+        projectId?: string;
+        allProjects?: boolean;
+    }): {
+        path: string;
+        count: number;
+    };
+    syncToDisk(options?: {
+        projectId?: string;
+        allProjects?: boolean;
+    }): {
+        path: string;
+        count: number;
+    };
+    /**
+     * Reads a JSON Lines (.jsonl) file and idempotently imports records into the database.
+     */
+    importFromDisk(sourcePath?: string): {
+        imported: number;
+        skipped: number;
+    };
+}
+//# sourceMappingURL=memory-service.d.ts.map

package/dist/service/memory-service.d.ts.map

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