@jungjaehoon/mama-core 2.4.0 → 4.0.0

package/dist/storage/database.js

@@ -0,0 +1,158 @@
+"use strict";
+/**
+ * Database lifetime.
+ *
+ * `openDatabase` returns a handle to one database. It does not register itself
+ * anywhere, so two calls give two independent databases and a caller always
+ * knows which one it holds. `db-manager.ts` keeps a single handle for the
+ * callers that still reach for a module-level connection; nothing here depends
+ * on that handle existing.
+ *
+ * @module storage/database
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIGRATIONS_DIR = void 0;
+exports.isTestMode = isTestMode;
+exports.declareProductionDatabasePath = declareProductionDatabasePath;
+exports.clearProductionDatabasePaths = clearProductionDatabasePaths;
+exports.assertTestProcessIsNotUsingRealDb = assertTestProcessIsNotUsingRealDb;
+exports.resolveAdapterDbPath = resolveAdapterDbPath;
+exports.openDatabase = openDatabase;
+const node_path_1 = __importDefault(require("node:path"));
+const index_js_1 = require("../db-adapter/index.js");
+const db_manager_js_1 = require("../db-manager.js");
+const debug_logger_js_1 = require("../debug-logger.js");
+const progress_indicator_js_1 = require("../progress-indicator.js");
+/** Migrations ship beside the compiled output, two levels up from `dist/storage`. */
+exports.MIGRATIONS_DIR = node_path_1.default.join(__dirname, '..', '..', 'db', 'migrations');
+function isTestMode() {
+    return Boolean(process.env.MAMA_TEST_MODE || process.env.VITEST || process.env.NODE_ENV === 'test');
+}
+/**
+ * A path a consumer states must already be resolved.
+ *
+ * The core used to expand `~` and `${HOME}` itself, which made it the thing that
+ * decides what home means. Two consumers with different homes then got the same
+ * answer from a library neither of them configured. Expansion belongs to whoever owns
+ * the home directory; this only refuses to guess.
+ */
+function requireResolvedPath(value, source) {
+    if (value === '~' || value.startsWith('~/') || value.includes('${HOME}')) {
+        throw new Error(`[db-boundary] ${source} is not a resolved path (${value}). ` +
+            'Expand it where the home directory is known and state the result.');
+    }
+    return node_path_1.default.resolve(value);
+}
+/**
+ * Databases a product has declared as its live one.
+ *
+ * The core used to hold one such path itself, `~/.claude/mama-memory.db`, which meant
+ * a shared library knew where one product kept its data in order to protect it. Each
+ * product declares its own now, and the guard below refuses all of them.
+ */
+const productionDatabasePaths = new Set();
+/**
+ * Declare where this product's live database is, as a resolved absolute path.
+ * Call once, before opening anything.
+ */
+function declareProductionDatabasePath(value) {
+    productionDatabasePaths.add(requireResolvedPath(value, 'the declared production database path'));
+}
+/** Test seam: forget what was declared. */
+function clearProductionDatabasePaths() {
+    productionDatabasePaths.clear();
+}
+/**
+ * Refuse, in a test process, to open a database nobody named or one a product
+ * declared as live.
+ *
+ * This used to compare against one hard-coded path, `~/.claude/mama-memory.db`, which
+ * meant the core held a product's data location in order to protect it. The rule is
+ * the same and says no product's name: a test that did not state where it wanted to
+ * write is about to write somewhere it did not choose, and that failure surfaces far
+ * from its cause.
+ */
+function assertTestProcessIsNotUsingRealDb(effectivePath, effectivePathSource = 'adapter') {
+    if (!isTestMode()) {
+        return;
+    }
+    const configuredPaths = [
+        { name: 'MAMA_DB_PATH', value: process.env.MAMA_DB_PATH },
+        { name: 'MAMA_DATABASE_PATH', value: process.env.MAMA_DATABASE_PATH },
+    ];
+    if (effectivePath) {
+        configuredPaths.push({ name: effectivePathSource, value: effectivePath });
+    }
+    const named = configuredPaths.find((configuredPath) => Boolean(configuredPath.value));
+    if (!named) {
+        throw new Error('[db-boundary] Refusing to open an unnamed database from a test process. ' +
+            'Set MAMA_DB_PATH to a temporary path first.');
+    }
+    for (const configuredPath of configuredPaths) {
+        if (!configuredPath.value) {
+            continue;
+        }
+        const resolvedPath = requireResolvedPath(configuredPath.value, configuredPath.name);
+        if (productionDatabasePaths.has(resolvedPath)) {
+            throw new Error(`[db-boundary] Refusing to open the live database ${resolvedPath} ` +
+                `from a test process (${configuredPath.name}=${configuredPath.value}). ` +
+                'Set MAMA_DB_PATH to a temporary path first.');
+        }
+    }
+}
+function resolveAdapterDbPath(adapter) {
+    if (typeof adapter.getDbPath === 'function') {
+        return adapter.getDbPath();
+    }
+    return adapter.dbPath;
+}
+/**
+ * Open one database: connect, migrate, and verify the embedding scheme.
+ *
+ * Throws if any step fails. Nothing partially opened is returned, so a caller
+ * that receives a handle holds a migrated database it can use.
+ */
+async function openDatabase(options = {}) {
+    assertTestProcessIsNotUsingRealDb(options.path, 'openDatabase({ path })');
+    (0, progress_indicator_js_1.logSearching)('Initializing database...');
+    const adapter = (0, index_js_1.createAdapter)(options.path ? { dbPath: options.path } : {});
+    assertTestProcessIsNotUsingRealDb(resolveAdapterDbPath(adapter), 'adapter.getDbPath()');
+    let connection;
+    try {
+        connection = await adapter.connect();
+        await adapter.runMigrations([
+            { name: 'core', dir: options.migrationsDir ?? exports.MIGRATIONS_DIR },
+            ...(options.migrations ?? []),
+        ]);
+        // New tables and rows exist only after migrations run.
+        if (typeof adapter.reloadVectorCache === 'function') {
+            adapter.reloadVectorCache();
+        }
+        // Fail loud on legacy vectors meeting current code.
+        (0, db_manager_js_1.assertEmbeddingSchemeCurrent)(adapter);
+    }
+    catch (error) {
+        try {
+            adapter.disconnect();
+        }
+        catch {
+            // The open already failed; a disconnect error would only mask it.
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to initialize database: ${message}`);
+    }
+    (0, debug_logger_js_1.info)(`[storage/database] Database opened (${adapter.constructor.name})`);
+    (0, progress_indicator_js_1.logComplete)('Database ready');
+    return {
+        adapter,
+        connection,
+        dbPath: resolveAdapterDbPath(adapter) ?? `${adapter.constructor.name} (path unavailable)`,
+        close: async () => {
+            await adapter.disconnect();
+        },
+    };
+}
+//# sourceMappingURL=database.js.map

package/package.json

@@ -1,53 +1,39 @@
 {
   "name": "@jungjaehoon/mama-core",
-  "version": "2.4.0",
+  "version": "4.0.0",
   "description": "MAMA Core - Shared modules for Memory-Augmented MCP Assistant",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": "./dist/index.js",
-    "./embeddings": "./dist/embeddings.js",
-    "./embedding-cache": "./dist/embedding-cache.js",
-    "./embedding-client": "./dist/embedding-client.js",
-    "./embedding-server": "./dist/embedding-server/index.js",
+    "./embeddings": "./dist/embedding/embedder.js",
     "./memory/types": "./dist/memory/types.js",
-    "./memory-store": "./dist/memory-store.js",
     "./db-manager": "./dist/db-manager.js",
-    "./db-adapter": "./dist/db-adapter/index.js",
     "./mama-api": "./dist/mama-api.js",
-    "./config-loader": "./dist/config-loader.js",
     "./relevance-scorer": "./dist/relevance-scorer.js",
-    "./decision-tracker": "./dist/decision-tracker.js",
     "./debug-logger": "./dist/debug-logger.js",
     "./decision-formatter": "./dist/decision-formatter.js",
-    "./ollama-client": "./dist/ollama-client.js",
     "./errors": "./dist/errors.js",
-    "./time-formatter": "./dist/time-formatter.js",
-    "./outcome-tracker": "./dist/outcome-tracker.js",
-    "./query-intent": "./dist/query-intent.js",
-    "./test-utils": "./dist/test-utils.js",
-    "./entities/store": "./dist/entities/store.js",
-    "./entities/candidate-generator": "./dist/entities/candidate-generator.js",
     "./canonicalize": "./dist/canonicalize.js",
-    "./cases/types": "./dist/cases/types.js",
-    "./cases/store": "./dist/cases/store.js",
-    "./cases/search-rollup": "./dist/cases/search-rollup.js",
-    "./cases/timeline-range": "./dist/cases/timeline-range.js",
-    "./cases/wiki-page-index": "./dist/cases/wiki-page-index.js",
-    "./connectors": "./dist/connectors/event-index.js",
-    "./connectors/event-index": "./dist/connectors/event-index.js",
-    "./connectors/raw-query": "./dist/connectors/raw-query.js",
-    "./connectors/types": "./dist/connectors/types.js",
-    "./agent-situation": "./dist/agent-situation/index.js",
-    "./agent-graph": "./dist/agent-graph/index.js",
-    "./context-compile": "./dist/context-compile/index.js",
+    "./connectors": "./dist/knowledge/event-index.js",
+    "./connectors/event-index": "./dist/knowledge/event-index.js",
+    "./connectors/raw-query": "./dist/knowledge/raw-query.js",
     "./provenance/source-ref": "./dist/provenance/source-ref.js",
-    "./edges/types": "./dist/edges/types.js",
-    "./edges/store": "./dist/edges/store.js",
-    "./edges/ref-validation": "./dist/edges/ref-validation.js"
+    "./registry/store": "./dist/registry/store.js",
+    "./operations/owner-action-effects": "./dist/operations/owner-action-effects.js",
+    "./knowledge": "./dist/knowledge/index.js",
+    "./action-contracts": "./dist/action-contracts.js",
+    "./api/catalog": "./dist/api/catalog.js",
+    "./api/dispatch": "./dist/api/dispatch.js",
+    "./client/client": "./dist/client/client.js",
+    "./client/ipc": "./dist/client/ipc.js",
+    "./runtime/*": {
+      "types": "./dist/runtime/*.d.ts",
+      "default": "./dist/runtime/*.js"
+    }
   },
   "scripts": {
-    "build": "tsc",
+    "build": "node scripts/clean-dist.mjs && tsc",
     "build:watch": "tsc --watch",
     "test": "vitest run",
     "test:watch": "vitest watch",
@@ -83,12 +69,12 @@
   "dependencies": {
     "@huggingface/transformers": "^3.8.1",
     "better-sqlite3": "^12.8.0",
-    "ws": "^8.19.0"
+    "js-tiktoken": "^1.0.21",
+    "minimatch": "^10.1.1"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.0.0",
-    "@types/ws": "^8.18.1",
     "typescript": "^5.9.3",
     "vitest": "^1.0.0"
   },

package/dist/agent-graph/alias-write.d.ts

@@ -1,3 +0,0 @@
-import type { AgentGraphAdapter, AttachEntityAliasWithEdgeInput, AttachEntityAliasWithEdgeResult } from './types.js';
-export declare function attachEntityAliasWithEdge(adapter: AgentGraphAdapter, input: AttachEntityAliasWithEdgeInput): AttachEntityAliasWithEdgeResult;
-//# sourceMappingURL=alias-write.d.ts.map

package/dist/agent-graph/alias-write.js

@@ -1,234 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.attachEntityAliasWithEdge = attachEntityAliasWithEdge;
-const node_crypto_1 = require("node:crypto");
-const canonicalize_js_1 = require("../canonicalize.js");
-const ref_validation_js_1 = require("../edges/ref-validation.js");
-const store_js_1 = require("../edges/store.js");
-const types_js_1 = require("../edges/types.js");
-const normalization_js_1 = require("../entities/normalization.js");
-const store_js_2 = require("../entities/store.js");
-const errors_js_1 = require("./errors.js");
-const TWIN_REF_KIND_SET = new Set(types_js_1.TWIN_REF_KINDS);
-function stableAliasId(input, normalizedLabel) {
-    const replayKey = replayIdempotencyKey(input);
-    if (replayKey) {
-        const hash = (0, node_crypto_1.createHash)('sha256')
-            .update(`${input.entity_id}\0${normalizedLabel}\0${replayKey}`, 'utf8')
-            .digest('hex')
-            .slice(0, 32);
-        return `alias_${hash}`;
-    }
-    return `alias_${(0, node_crypto_1.randomUUID)().replace(/-/g, '')}`;
-}
-function replayIdempotencyKey(input) {
-    return input.edge_idempotency_key ?? input.request_idempotency_key;
-}
-function loadAlias(adapter, aliasId) {
-    const row = adapter.prepare('SELECT * FROM entity_aliases WHERE id = ?').get(aliasId);
-    if (!row) {
-        throw new Error(`Entity alias was not written: ${aliasId}`);
-    }
-    return {
-        id: String(row.id),
-        entity_id: String(row.entity_id),
-        label: String(row.label),
-        normalized_label: String(row.normalized_label),
-        lang: typeof row.lang === 'string' ? row.lang : null,
-        script: typeof row.script === 'string' ? row.script : null,
-        label_type: row.label_type,
-        source_type: String(row.source_type),
-        source_ref: typeof row.source_ref === 'string' ? row.source_ref : null,
-        confidence: typeof row.confidence === 'number' ? row.confidence : null,
-        status: row.status,
-        created_at: Number(row.created_at),
-    };
-}
-function normalizeConfidence(value) {
-    if (value === undefined || value === null) {
-        return 1;
-    }
-    if (typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1) {
-        return value;
-    }
-    throw new errors_js_1.AgentGraphValidationError(`confidence must be between 0 and 1: ${String(value)}`);
-}
-function selectExistingAliasEdge(adapter, modelRunId, edgeIdempotencyKey) {
-    if (!edgeIdempotencyKey) {
-        return null;
-    }
-    const row = adapter
-        .prepare(`
-        SELECT *
-        FROM twin_edges
-        WHERE model_run_id = ?
-          AND edge_idempotency_key = ?
-        LIMIT 1
-      `)
-        .get(modelRunId, edgeIdempotencyKey);
-    return row ? (0, store_js_1.mapTwinEdgeRow)(row) : null;
-}
-function normalizeSourceRefs(sourceRefs) {
-    if (!sourceRefs || sourceRefs.length === 0) {
-        return [];
-    }
-    const refs = [];
-    const seen = new Set();
-    for (const ref of sourceRefs) {
-        if (!ref ||
-            typeof ref !== 'object' ||
-            typeof ref.kind !== 'string' ||
-            typeof ref.id !== 'string' ||
-            ref.id.trim().length === 0 ||
-            !TWIN_REF_KIND_SET.has(ref.kind)) {
-            throw new errors_js_1.AgentGraphValidationError('source_refs must be TwinRef objects with kind and id.');
-        }
-        const normalized = { kind: ref.kind, id: ref.id.trim() };
-        const key = `${normalized.kind}:${normalized.id}`;
-        if (!seen.has(key)) {
-            seen.add(key);
-            refs.push(normalized);
-        }
-    }
-    return refs.sort((left, right) => `${left.kind}:${left.id}`.localeCompare(`${right.kind}:${right.id}`));
-}
-function expectedRelationAttrs(alias, sourceRefs) {
-    const attrs = {
-        alias_id: alias.id,
-        label: alias.label,
-        normalized_label: alias.normalized_label,
-        lang: alias.lang,
-        script: alias.script,
-        label_type: alias.label_type,
-    };
-    if (sourceRefs.length > 0) {
-        attrs.source_refs = sourceRefs.map((ref) => ({ kind: ref.kind, id: ref.id }));
-    }
-    return attrs;
-}
-function assertAliasReplayMatches(alias, input, normalized, confidence) {
-    const expectedScript = input.script ?? normalized.script;
-    const expectedLabelType = input.label_type ?? 'alt';
-    const expectedSourceRef = input.source_ref ?? null;
-    const matches = alias.entity_id === input.entity_id &&
-        alias.label === input.label &&
-        alias.normalized_label === normalized.normalized &&
-        alias.lang === (input.lang ?? null) &&
-        alias.script === expectedScript &&
-        alias.label_type === expectedLabelType &&
-        alias.source_type === input.source_type &&
-        alias.source_ref === expectedSourceRef &&
-        alias.confidence === confidence &&
-        alias.status === 'active';
-    if (!matches) {
-        throw new errors_js_1.AgentGraphValidationError(`Conflicting entity alias replay for request idempotency key: ${replayIdempotencyKey(input)}`);
-    }
-}
-function assertAliasEdgeReplayMatches(edge, input, alias, confidence, edgeIdempotencyKey, sourceRefs) {
-    const matches = edge.edge_type === 'alias_of' &&
-        edge.subject_ref.kind === 'entity' &&
-        edge.subject_ref.id === input.entity_id &&
-        edge.object_ref.kind === 'entity' &&
-        edge.object_ref.id === input.entity_id &&
-        edge.relation_attrs_json === (0, canonicalize_js_1.canonicalizeJSON)(expectedRelationAttrs(alias, sourceRefs)) &&
-        edge.confidence === confidence &&
-        edge.source === 'agent' &&
-        edge.agent_id === input.agent_id &&
-        edge.model_run_id === input.model_run_id &&
-        edge.envelope_hash === input.envelope_hash &&
-        edge.request_idempotency_key === (input.request_idempotency_key ?? null) &&
-        edge.edge_idempotency_key === (edgeIdempotencyKey ?? null);
-    if (!matches) {
-        throw new errors_js_1.AgentGraphValidationError(`Conflicting alias edge replay for request idempotency key: ${replayIdempotencyKey(input)}`);
-    }
-}
-function insertAliasEdge(adapter, input, alias, confidence, sourceRefs) {
-    const edgeIdempotencyKey = replayIdempotencyKey(input);
-    const existing = selectExistingAliasEdge(adapter, input.model_run_id, edgeIdempotencyKey);
-    const edgeId = `edge_${(0, node_crypto_1.randomUUID)().replace(/-/g, '')}`;
-    const relationAttrs = expectedRelationAttrs(alias, sourceRefs);
-    const relationAttrsJson = (0, canonicalize_js_1.canonicalizeJSON)(relationAttrs);
-    if (existing) {
-        assertAliasEdgeReplayMatches(existing, input, alias, confidence, edgeIdempotencyKey, sourceRefs);
-        return existing;
-    }
-    const contentHash = (0, node_crypto_1.createHash)('sha256')
-        .update((0, canonicalize_js_1.canonicalizeJSON)({
-        edge_type: 'alias_of',
-        subject_ref: { kind: 'entity', id: input.entity_id },
-        object_ref: { kind: 'entity', id: input.entity_id },
-        relation_attrs_json: relationAttrsJson,
-        confidence,
-        source: 'agent',
-        agent_id: input.agent_id,
-        model_run_id: input.model_run_id,
-        envelope_hash: input.envelope_hash,
-    }), 'utf8')
-        .digest();
-    adapter
-        .prepare(`
-        INSERT INTO twin_edges (
-          edge_id, edge_type, subject_kind, subject_id, object_kind, object_id,
-          relation_attrs_json, confidence, source, agent_id, model_run_id, envelope_hash,
-          request_idempotency_key, edge_idempotency_key, content_hash, created_at
-        )
-        VALUES (?, 'alias_of', 'entity', ?, 'entity', ?, ?, ?, 'agent', ?, ?, ?, ?, ?, ?, ?)
-      `)
-        .run(edgeId, input.entity_id, input.entity_id, relationAttrsJson, confidence, input.agent_id, input.model_run_id, input.envelope_hash, input.request_idempotency_key ?? null, edgeIdempotencyKey ?? null, contentHash, Date.now());
-    const row = adapter.prepare('SELECT * FROM twin_edges WHERE edge_id = ?').get(edgeId);
-    if (!row) {
-        throw new Error(`Entity alias edge was not written: ${edgeId}`);
-    }
-    return (0, store_js_1.mapTwinEdgeRow)(row);
-}
-function attachEntityAliasWithEdge(adapter, input) {
-    const entity = (0, store_js_2.getEntityNode)(input.entity_id, adapter);
-    if (!entity || entity.status !== 'active') {
-        throw new errors_js_1.AgentGraphValidationError(`Active entity not found: ${input.entity_id}`);
-    }
-    const visibility = {
-        scopes: input.scopes,
-        connectors: input.connectors,
-        projectRefs: input.project_refs,
-        tenantId: input.tenant_id,
-        // source_refs are caller-supplied, so this is the surface where naming a raw id from
-        // an ungranted channel would bind it to an entity the caller can read back.
-        ...(input.channels ? { channels: input.channels } : {}),
-    };
-    const sourceRefs = normalizeSourceRefs(input.source_refs);
-    if (sourceRefs.length === 0) {
-        throw new errors_js_1.AgentGraphValidationError('source_refs must include at least one visible source.');
-    }
-    try {
-        (0, ref_validation_js_1.assertTwinRefsVisible)(adapter, [{ kind: 'entity', id: input.entity_id }, ...sourceRefs], visibility);
-    }
-    catch (error) {
-        throw new errors_js_1.AgentGraphValidationError(error instanceof Error ? error.message : String(error));
-    }
-    let normalized;
-    try {
-        normalized = (0, normalization_js_1.normalizeEntityLabel)(input.label);
-    }
-    catch (error) {
-        throw new errors_js_1.AgentGraphValidationError(error instanceof Error ? error.message : String(error));
-    }
-    const confidence = normalizeConfidence(input.confidence);
-    const aliasId = stableAliasId(input, normalized.normalized);
-    const createdAt = Date.now();
-    return adapter.transaction(() => {
-        adapter
-            .prepare(`
-          INSERT OR IGNORE INTO entity_aliases (
-            id, entity_id, label, normalized_label, lang, script, label_type,
-            source_type, source_ref, confidence, status, created_at
-          )
-          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', ?)
-        `)
-            .run(aliasId, input.entity_id, input.label, normalized.normalized, input.lang ?? null, input.script ?? normalized.script, input.label_type ?? 'alt', input.source_type, input.source_ref ?? null, confidence, createdAt);
-        const alias = loadAlias(adapter, aliasId);
-        assertAliasReplayMatches(alias, input, normalized, confidence);
-        const edge = insertAliasEdge(adapter, input, alias, confidence, sourceRefs);
-        return { alias, edge };
-    });
-}
-//# sourceMappingURL=alias-write.js.map

package/dist/agent-graph/entity-resolve.d.ts

@@ -1,3 +0,0 @@
-import type { AgentGraphAdapter, ResolveEntityInput, ResolveEntityResult } from './types.js';
-export declare function resolveEntity(adapter: AgentGraphAdapter, input: ResolveEntityInput): ResolveEntityResult;
-//# sourceMappingURL=entity-resolve.d.ts.map