@mono-agent/memory 0.4.1

package/dist/store/schema.js

@@ -0,0 +1,61 @@
+import { MEMORY_STATUSES, MEMORY_TYPES } from "./types.js";
+/** Ordered DDL applied once at open. `${dim}` is substituted with the configured dimension. */
+export function migrations(dim) {
+    return [
+        `CREATE TABLE IF NOT EXISTS memories (
+      id TEXT PRIMARY KEY,
+      seq INTEGER NOT NULL UNIQUE,
+      type TEXT NOT NULL CHECK(type IN (${sqlStringList(MEMORY_TYPES)})),
+      status TEXT NOT NULL CHECK(status IN (${sqlStringList(MEMORY_STATUSES)})),
+      text TEXT NOT NULL,
+      salience REAL NOT NULL DEFAULT 0.5,
+      is_insight INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL,
+      last_accessed_at TEXT,
+      access_count INTEGER NOT NULL DEFAULT 0,
+      valid_from TEXT,
+      valid_to TEXT,
+      superseded_by TEXT,
+      superseded_at TEXT,
+      due_at TEXT,
+      collection TEXT,
+      source_session TEXT,
+      source_file TEXT,
+      source_line INTEGER,
+      embedding_model TEXT,
+      dim INTEGER,
+      tags TEXT NOT NULL DEFAULT '[]'
+    )`,
+        `CREATE TABLE IF NOT EXISTS edges (
+      src TEXT NOT NULL,
+      dst TEXT NOT NULL,
+      kind TEXT NOT NULL CHECK(kind IN ('thread','about','supports','supersedes')),
+      weight REAL NOT NULL DEFAULT 1.0,
+      created_at TEXT NOT NULL,
+      PRIMARY KEY(src, dst, kind)
+    )`,
+        `CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(id UNINDEXED, text)`,
+        `CREATE VIRTUAL TABLE IF NOT EXISTS memories_vec USING vec0(embedding float[${dim}] distance_metric=cosine)`,
+        `CREATE INDEX IF NOT EXISTS idx_memories_status ON memories(status)`,
+        `CREATE INDEX IF NOT EXISTS idx_memories_due ON memories(due_at)`,
+        `CREATE TABLE IF NOT EXISTS entities (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      type TEXT,
+      summary TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT
+    )`,
+        `CREATE TABLE IF NOT EXISTS entity_relations (
+      src TEXT NOT NULL,
+      dst TEXT NOT NULL,
+      relation TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      PRIMARY KEY(src, dst, relation)
+    )`,
+    ];
+}
+function sqlStringList(values) {
+    return values.map((value) => `'${value.replaceAll("'", "''")}'`).join(",");
+}
+//# sourceMappingURL=schema.js.map

package/dist/store/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/store/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE3D,+FAA+F;AAC/F,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,OAAO;QACL;;;0CAGsC,aAAa,CAAC,YAAY,CAAC;8CACvB,aAAa,CAAC,eAAe,CAAC;;;;;;;;;;;;;;;;;;;MAmBtE;QACF;;;;;;;MAOE;QACF,gFAAgF;QAChF,8EAA8E,GAAG,2BAA2B;QAC5G,oEAAoE;QACpE,iEAAiE;QACjE;;;;;;;MAOE;QACF;;;;;;MAME;KACH,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,MAAyB;IAC9C,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC7E,CAAC"}

package/dist/store/types.d.ts

@@ -0,0 +1,102 @@
+import type { EmbeddingProvider } from "../search/index.js";
+export type MemoryType = "task" | "event" | "note";
+export declare const MEMORY_TYPES: readonly ["task", "event", "note"];
+export type MemoryStatus = "open" | "done" | "scheduled" | "migrated" | "dropped" | "invalidated";
+export declare const MEMORY_STATUSES: readonly ["open", "done", "scheduled", "migrated", "dropped", "invalidated"];
+export interface MemorySource {
+    readonly session?: string;
+    readonly file?: string;
+    readonly line?: number;
+}
+export interface MemoryRecord {
+    readonly id: string;
+    readonly type: MemoryType;
+    readonly status: MemoryStatus;
+    readonly text: string;
+    readonly salience: number;
+    readonly isInsight: boolean;
+    readonly createdAt: string;
+    readonly lastAccessedAt?: string;
+    readonly accessCount: number;
+    readonly validFrom?: string;
+    readonly validTo?: string;
+    readonly supersededBy?: string;
+    readonly supersededAt?: string;
+    readonly dueAt?: string;
+    readonly tags: readonly string[];
+    readonly collection?: string;
+    readonly source: MemorySource;
+    readonly embeddingModel?: string;
+    readonly dim?: number;
+}
+export type MemoryEdgeKind = "thread" | "about" | "supports" | "supersedes";
+export interface RecallHit {
+    readonly record: MemoryRecord;
+    readonly score: number;
+}
+export interface SimilarHit {
+    readonly record: MemoryRecord;
+    readonly distance: number;
+}
+export interface EntityRecord {
+    readonly id: string;
+    readonly name: string;
+    readonly type?: string;
+    readonly summary?: string;
+    readonly createdAt: string;
+    readonly updatedAt?: string;
+}
+export interface EntityRelationRecord {
+    readonly src: string;
+    readonly dst: string;
+    readonly relation: string;
+    readonly createdAt: string;
+}
+export interface RecallWeights {
+    readonly rrf: number;
+    readonly recency: number;
+    readonly salience: number;
+    readonly insight: number;
+}
+export interface RecallOptions {
+    readonly topK?: number;
+    readonly candidates?: number;
+    readonly expandHops?: number;
+    readonly includeInvalid?: boolean;
+    readonly trackAccess?: boolean;
+    readonly now?: Date;
+}
+export interface MemoryStoreStatsOptions {
+    readonly topEntitiesLimit?: number;
+}
+export type MemoryCountByStatus = Readonly<Record<MemoryStatus, number>>;
+export type MemoryCountByType = Readonly<Record<MemoryType, number>>;
+export interface MemoryStoreStats {
+    readonly totalMemories: number;
+    readonly liveMemories: number;
+    readonly countsByStatus: MemoryCountByStatus;
+    readonly countsByType: MemoryCountByType;
+    readonly latestCreatedMemory?: MemoryRecord;
+    readonly latestAccessedMemory?: MemoryRecord;
+    readonly topEntities: readonly EntityRecord[];
+}
+export interface MemoryDbOptions {
+    readonly path: string;
+    readonly embeddings?: EmbeddingProvider;
+    readonly dim?: number;
+    readonly k?: number;
+    readonly weights?: Partial<RecallWeights>;
+    readonly decayGamma?: number;
+    readonly clock?: () => Date;
+}
+/** Default vector dimension used for the `memories_vec` table DDL when no `dim` is provided. */
+export declare const DEFAULT_VEC_DIM = 768;
+/**
+ * Re-score weights. `rrf` scales the (small, ~1/k) fused rank score; the others
+ * are added on top. These are independent scalars, NOT a distribution that sums to 1.
+ */
+export declare const DEFAULT_WEIGHTS: RecallWeights;
+export declare const DEFAULT_RRF_K = 60;
+/** Exponential recency decay per day: score *= gamma^daysSinceLastAccess. 0.995 ≈ 16% weight after one year. */
+export declare const DEFAULT_DECAY_GAMMA = 0.995;
+//# sourceMappingURL=types.d.ts.map

package/dist/store/types.d.ts.map

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

package/dist/store/types.js

@@ -0,0 +1,25 @@
+export const MEMORY_TYPES = ["task", "event", "note"];
+export const MEMORY_STATUSES = [
+    "open",
+    "done",
+    "scheduled",
+    "migrated",
+    "dropped",
+    "invalidated",
+];
+/** Default vector dimension used for the `memories_vec` table DDL when no `dim` is provided. */
+export const DEFAULT_VEC_DIM = 768;
+/**
+ * Re-score weights. `rrf` scales the (small, ~1/k) fused rank score; the others
+ * are added on top. These are independent scalars, NOT a distribution that sums to 1.
+ */
+export const DEFAULT_WEIGHTS = {
+    rrf: 1.0,
+    recency: 0.3,
+    salience: 0.3,
+    insight: 0.2,
+};
+export const DEFAULT_RRF_K = 60;
+/** Exponential recency decay per day: score *= gamma^daysSinceLastAccess. 0.995 ≈ 16% weight after one year. */
+export const DEFAULT_DECAY_GAMMA = 0.995;
+//# sourceMappingURL=types.js.map

package/dist/store/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/store/types.ts"],"names":[],"mappings":"AAIA,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAA0C,CAAC;AAU/F,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,MAAM;IACN,MAAM;IACN,WAAW;IACX,UAAU;IACV,SAAS;IACT,aAAa;CAC6B,CAAC;AAqG7C,gGAAgG;AAChG,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAC;AAEnC;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAkB;IAC5C,GAAG,EAAE,GAAG;IACR,OAAO,EAAE,GAAG;IACZ,QAAQ,EAAE,GAAG;IACb,OAAO,EAAE,GAAG;CACb,CAAC;AACF,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAC;AAChC,gHAAgH;AAChH,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC"}

package/dist/store/vec.d.ts

@@ -0,0 +1,12 @@
+import type { Database } from "better-sqlite3";
+/** Load the sqlite-vec extension into an open better-sqlite3 connection. */
+export declare function loadVec(db: Database): void;
+/**
+ * Encode a numeric vector as a little-endian float32 BLOB for vec0.
+ *
+ * sqlite-vec interprets float32 vectors as little-endian, so we write the bytes explicitly with
+ * `writeFloatLE` rather than relying on `Float32Array`'s platform-native byte order — that keeps the
+ * BLOB correct on a (rare) big-endian runtime.
+ */
+export declare function toBlob(vector: readonly number[]): Buffer;
+//# sourceMappingURL=vec.d.ts.map

package/dist/store/vec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vec.d.ts","sourceRoot":"","sources":["../../src/store/vec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAG/C,4EAA4E;AAC5E,wBAAgB,OAAO,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAE1C;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAMxD"}

package/dist/store/vec.js

@@ -0,0 +1,20 @@
+import * as sqliteVec from "sqlite-vec";
+/** Load the sqlite-vec extension into an open better-sqlite3 connection. */
+export function loadVec(db) {
+    sqliteVec.load(db);
+}
+/**
+ * Encode a numeric vector as a little-endian float32 BLOB for vec0.
+ *
+ * sqlite-vec interprets float32 vectors as little-endian, so we write the bytes explicitly with
+ * `writeFloatLE` rather than relying on `Float32Array`'s platform-native byte order — that keeps the
+ * BLOB correct on a (rare) big-endian runtime.
+ */
+export function toBlob(vector) {
+    const buf = Buffer.allocUnsafe(vector.length * 4);
+    for (let i = 0; i < vector.length; i += 1) {
+        buf.writeFloatLE(vector[i] ?? 0, i * 4);
+    }
+    return buf;
+}
+//# sourceMappingURL=vec.js.map

package/dist/store/vec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vec.js","sourceRoot":"","sources":["../../src/store/vec.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,SAAS,MAAM,YAAY,CAAC;AAExC,4EAA4E;AAC5E,MAAM,UAAU,OAAO,CAAC,EAAY;IAClC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACrB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CAAC,MAAyB;IAC9C,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAClD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1C,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@mono-agent/memory",
+  "version": "0.4.1",
+  "description": "Local memory package with SQLite store, embedding search, and Bullet-Journal engine subpaths.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "private": false,
+  "exports": {
+    "./store": {
+      "types": "./dist/store/index.d.ts",
+      "import": "./dist/store/index.js"
+    },
+    "./search": {
+      "types": "./dist/search/index.d.ts",
+      "import": "./dist/search/index.js"
+    },
+    "./bujo": {
+      "types": "./dist/bujo/index.d.ts",
+      "import": "./dist/bujo/index.js"
+    }
+  },
+  "bin": {
+    "memory-bujo": "./dist/bujo/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@mono-agent/agent-contracts": "0.4.1",
+    "better-sqlite3": "^11.8.1",
+    "sqlite-vec": "^0.1.7-alpha.2"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}