mackin 0.1.0

package/dist/embeddings.d.ts

@@ -0,0 +1,3 @@
+export declare function embed(text: string, apiKey?: string): Promise<number[]>;
+export declare function hashEmbed(text: string): number[];
+export declare function cosineSimilarity(a: number[], b: number[]): number;

package/dist/embeddings.js

@@ -0,0 +1,93 @@
+import Anthropic from "@anthropic-ai/sdk";
+const clients = new Map();
+function getClient(apiKey) {
+    const key = apiKey || process.env.ANTHROPIC_API_KEY;
+    if (!key)
+        return null;
+    let client = clients.get(key);
+    if (!client) {
+        client = new Anthropic({ apiKey: key });
+        clients.set(key, client);
+    }
+    return client;
+}
+const EMBED_DIMS = 64;
+export async function embed(text, apiKey) {
+    const anthropic = getClient(apiKey);
+    if (anthropic) {
+        try {
+            const response = await anthropic.messages.create({
+                model: "claude-haiku-4-5-20251001",
+                max_tokens: 512,
+                messages: [
+                    {
+                        role: "user",
+                        content: `Generate a semantic embedding for the following text. Respond with ONLY a valid JSON array of exactly ${EMBED_DIMS} floating point numbers between -1 and 1. No explanation, no markdown, just the array.\n\nText: "${text.slice(0, 1000)}"`,
+                    },
+                ],
+            });
+            const content = response.content[0];
+            if (content.type === "text") {
+                const cleaned = content.text.trim().replace(/^```json?\s*/, "").replace(/\s*```$/, "");
+                const parsed = JSON.parse(cleaned);
+                if (Array.isArray(parsed) && parsed.length === EMBED_DIMS && parsed.every((v) => typeof v === "number" && isFinite(v))) {
+                    const magnitude = Math.sqrt(parsed.reduce((sum, v) => sum + v * v, 0));
+                    if (magnitude > 0) {
+                        return parsed.map((v) => v / magnitude);
+                    }
+                }
+            }
+        }
+        catch {
+            // API unavailable or malformed response — fall back to hash-based embedding
+        }
+    }
+    return hashEmbed(text);
+}
+export function hashEmbed(text) {
+    const dims = 64;
+    const embedding = new Array(dims).fill(0);
+    const normalized = text.toLowerCase().replace(/[^\w\s]/g, " ");
+    const words = normalized.split(/\s+/).filter(Boolean);
+    for (let i = 0; i < words.length; i++) {
+        const word = words[i];
+        let hash = 0;
+        for (let j = 0; j < word.length; j++) {
+            hash = ((hash << 5) - hash + word.charCodeAt(j)) | 0;
+        }
+        const idx1 = Math.abs(hash) % dims;
+        const idx2 = Math.abs((hash * 31 + i) | 0) % dims;
+        const idx3 = Math.abs((hash * 17 + word.length) | 0) % dims;
+        embedding[idx1] += 1.0;
+        embedding[idx2] += 0.5;
+        embedding[idx3] += 0.25;
+        // bigram context
+        if (i > 0) {
+            const bigramHash = ((hash << 3) + words[i - 1].length) | 0;
+            const idx4 = Math.abs(bigramHash) % dims;
+            embedding[idx4] += 0.3;
+        }
+    }
+    // Normalize to unit vector
+    const magnitude = Math.sqrt(embedding.reduce((sum, v) => sum + v * v, 0));
+    if (magnitude > 0) {
+        for (let i = 0; i < dims; i++) {
+            embedding[i] /= magnitude;
+        }
+    }
+    return embedding;
+}
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    let dot = 0;
+    let magA = 0;
+    let magB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        magA += a[i] * a[i];
+        magB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(magA) * Math.sqrt(magB);
+    return denom === 0 ? 0 : dot / denom;
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import type { MackinStoreOptions, WriteInput, ReadQuery, ConflictsQuery, ConflictPair, ReasoningEntry, Session } from "./types.js";
+export declare class MackinStore {
+    private storage;
+    private retrieval;
+    private sessionId;
+    private apiKey?;
+    constructor(options: MackinStoreOptions);
+    write(input: WriteInput): Promise<ReasoningEntry>;
+    read(query: ReadQuery): Promise<ReasoningEntry[]>;
+    conflicts(query?: ConflictsQuery): Promise<ConflictPair[]>;
+    trace(): Promise<ReasoningEntry[]>;
+    getSession(): Session | null;
+    close(): void;
+}
+export { Storage } from "./storage.js";
+export { Retrieval } from "./retrieval.js";
+export { embed, cosineSimilarity, hashEmbed } from "./embeddings.js";
+export type { MackinStoreOptions, WriteInput, ReadQuery, ReadFilter, ConflictsQuery, ConflictPair, ReasoningEntry, Session, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,40 @@
+import { Storage } from "./storage.js";
+import { Retrieval } from "./retrieval.js";
+import { embed } from "./embeddings.js";
+export class MackinStore {
+    storage;
+    retrieval;
+    sessionId;
+    apiKey;
+    constructor(options) {
+        const dbPath = options.dbPath || "./mackin.db";
+        this.sessionId = options.sessionId;
+        this.apiKey = options.anthropicApiKey || process.env.ANTHROPIC_API_KEY;
+        this.storage = new Storage(dbPath);
+        this.retrieval = new Retrieval(this.storage, this.apiKey);
+        this.storage.ensureSession(this.sessionId);
+    }
+    async write(input) {
+        const text = `${input.decision} ${input.reasoning}`;
+        const embedding = await embed(text, this.apiKey);
+        return this.storage.writeEntry(this.sessionId, input.agent, input.decision, input.reasoning, input.alternatives_considered, input.confidence ?? 0.5, input.flags, input.tags, embedding);
+    }
+    async read(query) {
+        return this.retrieval.read(this.sessionId, query);
+    }
+    async conflicts(query) {
+        return this.retrieval.conflicts(this.sessionId, query?.topic);
+    }
+    async trace() {
+        return this.storage.getEntriesBySession(this.sessionId);
+    }
+    getSession() {
+        return this.storage.getSession(this.sessionId);
+    }
+    close() {
+        this.storage.close();
+    }
+}
+export { Storage } from "./storage.js";
+export { Retrieval } from "./retrieval.js";
+export { embed, cosineSimilarity, hashEmbed } from "./embeddings.js";

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,161 @@
+import { test, describe, beforeEach, afterEach } from "node:test";
+import assert from "node:assert";
+import * as fs from "fs";
+import { MackinStore } from "./index.js";
+const TEST_DB = "./test-mackin.db";
+function cleanup() {
+    if (fs.existsSync(TEST_DB)) {
+        fs.unlinkSync(TEST_DB);
+    }
+}
+describe("MackinStore", () => {
+    let store;
+    beforeEach(() => {
+        cleanup();
+        store = new MackinStore({ sessionId: "test-session", dbPath: TEST_DB });
+    });
+    afterEach(() => {
+        store.close();
+        cleanup();
+    });
+    test("write and read a reasoning entry", async () => {
+        const entry = await store.write({
+            agent: "researcher",
+            decision: "use source A",
+            reasoning: "it is more recent and authoritative",
+            confidence: 0.9,
+            tags: ["source-selection"],
+        });
+        assert.strictEqual(entry.agentId, "researcher");
+        assert.strictEqual(entry.decision, "use source A");
+        assert.strictEqual(entry.confidence, 0.9);
+        assert.ok(entry.id);
+        assert.ok(entry.embedding);
+        assert.ok(entry.embedding.length > 0);
+    });
+    test("read with structured filter by tags", async () => {
+        await store.write({
+            agent: "a1",
+            decision: "decision 1",
+            reasoning: "reason 1",
+            tags: ["finance", "data"],
+            confidence: 0.8,
+        });
+        await store.write({
+            agent: "a2",
+            decision: "decision 2",
+            reasoning: "reason 2",
+            tags: ["tech"],
+            confidence: 0.7,
+        });
+        await store.write({
+            agent: "a3",
+            decision: "decision 3",
+            reasoning: "reason 3",
+            tags: ["finance"],
+            confidence: 0.6,
+        });
+        const results = await store.read({
+            agent: "reader",
+            filter: { tags: ["finance"] },
+        });
+        assert.strictEqual(results.length, 2);
+        assert.ok(results.every((r) => r.tags?.includes("finance")));
+    });
+    test("read with confidence_min filter", async () => {
+        await store.write({
+            agent: "a1",
+            decision: "high confidence",
+            reasoning: "very sure",
+            confidence: 0.95,
+            tags: ["test"],
+        });
+        await store.write({
+            agent: "a2",
+            decision: "low confidence",
+            reasoning: "not sure",
+            confidence: 0.3,
+            tags: ["test"],
+        });
+        const results = await store.read({
+            agent: "reader",
+            filter: { tags: ["test"], confidence_min: 0.8 },
+        });
+        assert.strictEqual(results.length, 1);
+        assert.strictEqual(results[0].decision, "high confidence");
+    });
+    test("semantic search returns relevant results", async () => {
+        await store.write({
+            agent: "a1",
+            decision: "use PostgreSQL for storage",
+            reasoning: "relational data with complex joins",
+            tags: ["database"],
+        });
+        await store.write({
+            agent: "a2",
+            decision: "deploy to AWS us-east-1",
+            reasoning: "lowest latency for east coast users",
+            tags: ["infrastructure"],
+        });
+        const results = await store.read({
+            agent: "reader",
+            semantic_query: "database choice for storage",
+            limit: 1,
+        });
+        assert.strictEqual(results.length, 1);
+        assert.strictEqual(results[0].decision, "use PostgreSQL for storage");
+    });
+    test("conflict detection finds contradictions", async () => {
+        await store.write({
+            agent: "agent-a",
+            decision: "the market size is $47 billion",
+            reasoning: "based on IEA report",
+            confidence: 0.9,
+            tags: ["market-size"],
+        });
+        await store.write({
+            agent: "agent-b",
+            decision: "the market size is $52 billion",
+            reasoning: "based on bottom-up analysis",
+            confidence: 0.75,
+            tags: ["market-size"],
+        });
+        const conflicts = await store.conflicts({ topic: "market size" });
+        assert.ok(conflicts.length >= 1);
+        const c = conflicts[0];
+        assert.ok(c.entry_a.agentId !== c.entry_b.agentId);
+        assert.ok(c.reason.length > 0);
+    });
+    test("trace returns entries in chronological order", async () => {
+        await store.write({ agent: "a1", decision: "first", reasoning: "r1" });
+        await store.write({ agent: "a2", decision: "second", reasoning: "r2" });
+        await store.write({ agent: "a3", decision: "third", reasoning: "r3" });
+        const trace = await store.trace();
+        assert.strictEqual(trace.length, 3);
+        assert.strictEqual(trace[0].decision, "first");
+        assert.strictEqual(trace[1].decision, "second");
+        assert.strictEqual(trace[2].decision, "third");
+    });
+    test("works without API key (hash embeddings)", async () => {
+        const entry = await store.write({
+            agent: "test",
+            decision: "test decision",
+            reasoning: "test reasoning",
+        });
+        assert.ok(entry.embedding);
+        assert.strictEqual(entry.embedding.length, 64);
+        const magnitude = Math.sqrt(entry.embedding.reduce((sum, v) => sum + v * v, 0));
+        assert.ok(Math.abs(magnitude - 1.0) < 0.01, "embedding should be unit normalized");
+    });
+    test("alternatives and flags are stored correctly", async () => {
+        const entry = await store.write({
+            agent: "test",
+            decision: "chose option A",
+            reasoning: "better fit",
+            alternatives_considered: ["option B", "option C"],
+            flags: ["needs_review", "uncertain"],
+        });
+        assert.deepStrictEqual(entry.alternativesConsidered, ["option B", "option C"]);
+        assert.deepStrictEqual(entry.flags, ["needs_review", "uncertain"]);
+    });
+});

package/dist/retrieval.d.ts

@@ -0,0 +1,15 @@
+import { Storage } from "./storage.js";
+import type { ReasoningEntry, ReadQuery, ConflictPair } from "./types.js";
+export declare class Retrieval {
+    private storage;
+    private apiKey?;
+    constructor(storage: Storage, apiKey?: string | undefined);
+    read(sessionId: string, query: ReadQuery): Promise<ReasoningEntry[]>;
+    private structuredFilter;
+    private semanticSearch;
+    private mergeResults;
+    conflicts(sessionId: string, topic?: string, maxResults?: number): Promise<ConflictPair[]>;
+    private detectConflict;
+    private hasTagOverlap;
+    private stringSimilarity;
+}

package/dist/retrieval.js

@@ -0,0 +1,191 @@
+import { embed, cosineSimilarity } from "./embeddings.js";
+const SEMANTIC_FALLBACK_THRESHOLD = 3;
+const CONFLICT_SIMILARITY_HIGH = 0.95;
+const CONFLICT_DECISION_SIMILARITY_LOW = 0.5;
+const CONFLICT_CONFIDENCE_DELTA = 0.3;
+export class Retrieval {
+    storage;
+    apiKey;
+    constructor(storage, apiKey) {
+        this.storage = storage;
+        this.apiKey = apiKey;
+    }
+    async read(sessionId, query) {
+        const limit = query.limit || 10;
+        if (query.filter) {
+            const results = this.structuredFilter(sessionId, query.filter, limit);
+            if (results.length >= SEMANTIC_FALLBACK_THRESHOLD) {
+                return results.slice(0, limit);
+            }
+            if (query.semantic_query) {
+                const semanticResults = await this.semanticSearch(sessionId, query.semantic_query, limit);
+                const merged = this.mergeResults(results, semanticResults, limit);
+                return merged;
+            }
+            return results;
+        }
+        if (query.semantic_query) {
+            return this.semanticSearch(sessionId, query.semantic_query, limit);
+        }
+        return this.storage.getEntriesBySession(sessionId).slice(0, limit);
+    }
+    structuredFilter(sessionId, filter, limit) {
+        return this.storage.queryEntries(sessionId, {
+            tags: filter.tags,
+            confidenceMin: filter.confidence_min,
+            agentId: filter.agent_id,
+            createdAfter: filter.created_after,
+            createdBefore: filter.created_before,
+            limit,
+        });
+    }
+    async semanticSearch(sessionId, query, limit) {
+        const queryEmbedding = await embed(query, this.apiKey);
+        const allEntries = this.storage.getEntriesBySession(sessionId);
+        const scored = allEntries
+            .filter((entry) => entry.embedding && entry.embedding.length > 0)
+            .map((entry) => ({
+            entry,
+            score: cosineSimilarity(queryEmbedding, entry.embedding),
+        }))
+            .sort((a, b) => b.score - a.score);
+        return scored.slice(0, limit).map((s) => s.entry);
+    }
+    mergeResults(structured, semantic, limit) {
+        const seen = new Set(structured.map((e) => e.id));
+        const merged = [...structured];
+        for (const entry of semantic) {
+            if (!seen.has(entry.id)) {
+                merged.push(entry);
+                seen.add(entry.id);
+            }
+        }
+        return merged.slice(0, limit);
+    }
+    async conflicts(sessionId, topic, maxResults = 50) {
+        let entries = this.storage.getEntriesBySession(sessionId);
+        if (topic) {
+            const topicEmbedding = await embed(topic, this.apiKey);
+            const scored = entries
+                .filter((entry) => entry.embedding)
+                .map((entry) => ({
+                entry,
+                score: cosineSimilarity(topicEmbedding, entry.embedding),
+            }))
+                .sort((a, b) => b.score - a.score);
+            if (scored.length > 0) {
+                const maxScore = scored[0].score;
+                const threshold = maxScore * 0.6;
+                entries = scored
+                    .filter((s) => s.score >= threshold)
+                    .map((s) => s.entry);
+            }
+        }
+        // Build tag index to avoid full O(n^2) when possible
+        const tagIndex = new Map();
+        for (const entry of entries) {
+            if (entry.tags) {
+                for (const tag of entry.tags) {
+                    let group = tagIndex.get(tag);
+                    if (!group) {
+                        group = [];
+                        tagIndex.set(tag, group);
+                    }
+                    group.push(entry);
+                }
+            }
+        }
+        const conflicts = [];
+        const seen = new Set();
+        // Check tag-grouped pairs first (covers path 1 and path 3)
+        for (const group of tagIndex.values()) {
+            for (let i = 0; i < group.length && conflicts.length < maxResults; i++) {
+                for (let j = i + 1; j < group.length && conflicts.length < maxResults; j++) {
+                    const pairKey = group[i].id < group[j].id
+                        ? `${group[i].id}:${group[j].id}`
+                        : `${group[j].id}:${group[i].id}`;
+                    if (seen.has(pairKey))
+                        continue;
+                    seen.add(pairKey);
+                    const conflict = this.detectConflict(group[i], group[j]);
+                    if (conflict)
+                        conflicts.push(conflict);
+                }
+            }
+        }
+        // Check embedding-based conflicts (path 2) for entries with embeddings
+        if (conflicts.length < maxResults) {
+            const withEmbeddings = entries.filter((e) => e.embedding && e.embedding.length > 0);
+            for (let i = 0; i < withEmbeddings.length && conflicts.length < maxResults; i++) {
+                for (let j = i + 1; j < withEmbeddings.length && conflicts.length < maxResults; j++) {
+                    const pairKey = withEmbeddings[i].id < withEmbeddings[j].id
+                        ? `${withEmbeddings[i].id}:${withEmbeddings[j].id}`
+                        : `${withEmbeddings[j].id}:${withEmbeddings[i].id}`;
+                    if (seen.has(pairKey))
+                        continue;
+                    seen.add(pairKey);
+                    const conflict = this.detectConflict(withEmbeddings[i], withEmbeddings[j]);
+                    if (conflict)
+                        conflicts.push(conflict);
+                }
+            }
+        }
+        return conflicts;
+    }
+    detectConflict(a, b) {
+        const tagsOverlap = this.hasTagOverlap(a.tags, b.tags);
+        const confidenceDelta = Math.abs(a.confidence - b.confidence);
+        const decisionSim = this.stringSimilarity(a.decision, b.decision);
+        // Path 1: Same topic, different decisions, significant confidence gap
+        if (tagsOverlap && confidenceDelta > CONFLICT_CONFIDENCE_DELTA) {
+            if (decisionSim < CONFLICT_DECISION_SIMILARITY_LOW) {
+                return {
+                    entry_a: a,
+                    entry_b: b,
+                    reason: `Same topic area (overlapping tags) but different decisions with confidence delta of ${confidenceDelta.toFixed(2)}`,
+                };
+            }
+        }
+        // Path 2: High embedding similarity but different decisions
+        if (a.embedding && b.embedding) {
+            const embeddingSim = cosineSimilarity(a.embedding, b.embedding);
+            if (embeddingSim > CONFLICT_SIMILARITY_HIGH) {
+                if (decisionSim < CONFLICT_DECISION_SIMILARITY_LOW) {
+                    return {
+                        entry_a: a,
+                        entry_b: b,
+                        reason: `High semantic similarity (${embeddingSim.toFixed(2)}) but different decisions (similarity: ${decisionSim.toFixed(2)})`,
+                    };
+                }
+            }
+        }
+        // Path 3: Same topic, very similar phrasing but different specific values
+        // (e.g. "$47B" vs "$52B" — high word overlap but not identical)
+        if (tagsOverlap && a.agentId !== b.agentId && decisionSim > 0.7 && decisionSim < 1.0) {
+            if (a.decision !== b.decision) {
+                return {
+                    entry_a: a,
+                    entry_b: b,
+                    reason: `Same topic, different agents, nearly identical framing but different conclusions (similarity: ${decisionSim.toFixed(2)})`,
+                };
+            }
+        }
+        return null;
+    }
+    hasTagOverlap(tagsA, tagsB) {
+        if (!tagsA || !tagsB)
+            return false;
+        return tagsA.some((t) => tagsB.includes(t));
+    }
+    stringSimilarity(a, b) {
+        const wordsA = new Set(a.toLowerCase().split(/\s+/));
+        const wordsB = new Set(b.toLowerCase().split(/\s+/));
+        let intersection = 0;
+        for (const word of wordsA) {
+            if (wordsB.has(word))
+                intersection++;
+        }
+        const union = new Set([...wordsA, ...wordsB]).size;
+        return union === 0 ? 0 : intersection / union;
+    }
+}

package/dist/storage.d.ts

@@ -0,0 +1,23 @@
+import type { ReasoningEntry, Session } from "./types.js";
+export declare class Storage {
+    private db;
+    constructor(dbPath: string);
+    private initialize;
+    createSession(id?: string, name?: string, metadata?: Record<string, unknown>): Session;
+    getSession(id: string): Session | null;
+    deleteSession(id: string): void;
+    ensureSession(id: string): void;
+    writeEntry(sessionId: string, agentId: string, decision: string, reasoning: string, alternativesConsidered?: string[], confidence?: number, flags?: string[], tags?: string[], embedding?: number[]): ReasoningEntry;
+    getEntry(id: string): ReasoningEntry | null;
+    getEntriesBySession(sessionId: string): ReasoningEntry[];
+    queryEntries(sessionId: string, opts: {
+        tags?: string[];
+        confidenceMin?: number;
+        agentId?: string;
+        createdAfter?: string;
+        createdBefore?: string;
+        limit?: number;
+    }): ReasoningEntry[];
+    private rowToEntry;
+    close(): void;
+}

package/dist/storage.js

@@ -0,0 +1,147 @@
+import Database from "better-sqlite3";
+import { v4 as uuidv4 } from "uuid";
+export class Storage {
+    db;
+    constructor(dbPath) {
+        this.db = new Database(dbPath);
+        this.db.pragma("journal_mode = WAL");
+        this.db.pragma("foreign_keys = ON");
+        this.initialize();
+    }
+    initialize() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS sessions (
+        id TEXT PRIMARY KEY,
+        name TEXT,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        metadata TEXT
+      );
+
+      CREATE TABLE IF NOT EXISTS reasoning_entries (
+        id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL,
+        agent_id TEXT NOT NULL,
+        decision TEXT NOT NULL,
+        reasoning TEXT NOT NULL,
+        alternatives_considered TEXT,
+        confidence REAL DEFAULT 0.5,
+        flags TEXT,
+        tags TEXT,
+        embedding TEXT,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (session_id) REFERENCES sessions(id)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_session ON reasoning_entries(session_id);
+      CREATE INDEX IF NOT EXISTS idx_agent ON reasoning_entries(agent_id);
+      CREATE INDEX IF NOT EXISTS idx_confidence ON reasoning_entries(confidence);
+    `);
+    }
+    createSession(id, name, metadata) {
+        const sessionId = id || uuidv4();
+        const stmt = this.db.prepare("INSERT INTO sessions (id, name, metadata) VALUES (?, ?, ?)");
+        stmt.run(sessionId, name || null, metadata ? JSON.stringify(metadata) : null);
+        return this.getSession(sessionId);
+    }
+    getSession(id) {
+        const row = this.db.prepare("SELECT * FROM sessions WHERE id = ?").get(id);
+        if (!row)
+            return null;
+        return {
+            id: row.id,
+            name: row.name,
+            createdAt: row.created_at,
+            metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
+        };
+    }
+    deleteSession(id) {
+        this.db.prepare("DELETE FROM reasoning_entries WHERE session_id = ?").run(id);
+        this.db.prepare("DELETE FROM sessions WHERE id = ?").run(id);
+    }
+    ensureSession(id) {
+        const exists = this.db.prepare("SELECT 1 FROM sessions WHERE id = ?").get(id);
+        if (!exists) {
+            this.createSession(id);
+        }
+    }
+    writeEntry(sessionId, agentId, decision, reasoning, alternativesConsidered, confidence = 0.5, flags, tags, embedding) {
+        const id = uuidv4();
+        this.ensureSession(sessionId);
+        const stmt = this.db.prepare(`
+      INSERT INTO reasoning_entries
+        (id, session_id, agent_id, decision, reasoning, alternatives_considered, confidence, flags, tags, embedding)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        stmt.run(id, sessionId, agentId, decision, reasoning, alternativesConsidered ? JSON.stringify(alternativesConsidered) : null, confidence, flags ? JSON.stringify(flags) : null, tags ? JSON.stringify(tags) : null, embedding ? JSON.stringify(embedding) : null);
+        return this.getEntry(id);
+    }
+    getEntry(id) {
+        const row = this.db.prepare("SELECT * FROM reasoning_entries WHERE id = ?").get(id);
+        if (!row)
+            return null;
+        return this.rowToEntry(row);
+    }
+    getEntriesBySession(sessionId) {
+        const rows = this.db
+            .prepare("SELECT * FROM reasoning_entries WHERE session_id = ? ORDER BY created_at ASC")
+            .all(sessionId);
+        return rows.map(this.rowToEntry);
+    }
+    queryEntries(sessionId, opts) {
+        let sql = "SELECT * FROM reasoning_entries WHERE session_id = ?";
+        const params = [sessionId];
+        if (opts.confidenceMin !== undefined) {
+            sql += " AND confidence >= ?";
+            params.push(opts.confidenceMin);
+        }
+        if (opts.agentId) {
+            sql += " AND agent_id = ?";
+            params.push(opts.agentId);
+        }
+        if (opts.createdAfter) {
+            sql += " AND created_at > ?";
+            params.push(opts.createdAfter);
+        }
+        if (opts.createdBefore) {
+            sql += " AND created_at < ?";
+            params.push(opts.createdBefore);
+        }
+        sql += " ORDER BY created_at DESC";
+        // Don't apply SQL LIMIT when tags filter is active (tags are filtered in-memory)
+        if (opts.limit && !(opts.tags && opts.tags.length > 0)) {
+            sql += " LIMIT ?";
+            params.push(opts.limit);
+        }
+        let rows = this.db.prepare(sql).all(...params);
+        if (opts.tags && opts.tags.length > 0) {
+            rows = rows.filter((row) => {
+                const entryTags = row.tags ? JSON.parse(row.tags) : [];
+                return opts.tags.some((t) => entryTags.includes(t));
+            });
+        }
+        if (opts.limit && opts.tags && opts.tags.length > 0) {
+            rows = rows.slice(0, opts.limit);
+        }
+        return rows.map(this.rowToEntry);
+    }
+    rowToEntry(row) {
+        return {
+            id: row.id,
+            sessionId: row.session_id,
+            agentId: row.agent_id,
+            decision: row.decision,
+            reasoning: row.reasoning,
+            alternativesConsidered: row.alternatives_considered
+                ? JSON.parse(row.alternatives_considered)
+                : undefined,
+            confidence: row.confidence,
+            flags: row.flags ? JSON.parse(row.flags) : undefined,
+            tags: row.tags ? JSON.parse(row.tags) : undefined,
+            embedding: row.embedding ? JSON.parse(row.embedding) : undefined,
+            createdAt: row.created_at,
+        };
+    }
+    close() {
+        this.db.close();
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,54 @@
+export interface MackinStoreOptions {
+    sessionId: string;
+    dbPath?: string;
+    anthropicApiKey?: string;
+}
+export interface ReasoningEntry {
+    id: string;
+    sessionId: string;
+    agentId: string;
+    decision: string;
+    reasoning: string;
+    alternativesConsidered?: string[];
+    confidence: number;
+    flags?: string[];
+    tags?: string[];
+    embedding?: number[];
+    createdAt: string;
+}
+export interface WriteInput {
+    agent: string;
+    decision: string;
+    reasoning: string;
+    alternatives_considered?: string[];
+    confidence?: number;
+    flags?: string[];
+    tags?: string[];
+}
+export interface ReadFilter {
+    tags?: string[];
+    confidence_min?: number;
+    agent_id?: string;
+    created_after?: string;
+    created_before?: string;
+}
+export interface ReadQuery {
+    agent: string;
+    filter?: ReadFilter;
+    semantic_query?: string;
+    limit?: number;
+}
+export interface ConflictsQuery {
+    topic?: string;
+}
+export interface ConflictPair {
+    entry_a: ReasoningEntry;
+    entry_b: ReasoningEntry;
+    reason: string;
+}
+export interface Session {
+    id: string;
+    name?: string;
+    createdAt: string;
+    metadata?: Record<string, unknown>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "mackin",
+  "version": "0.1.0",
+  "description": "Shared reasoning memory for parallel multi-agent systems",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node --import tsx --test src/**/*.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "multi-agent",
+    "memory",
+    "reasoning",
+    "llm",
+    "rag",
+    "embeddings",
+    "sqlite"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HarrisSagiris/mackin.git",
+    "directory": "sdk/typescript"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "better-sqlite3": "^11.0.0",
+    "uuid": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/node": "^22.0.0",
+    "@types/uuid": "^10.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/sdk": ">=0.30.0"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/sdk": {
+      "optional": true
+    }
+  }
+}