@bip-krishna/agentmind 0.1.0

package/examples/basic.ts

@@ -0,0 +1,25 @@
+import { Memory } from "../packages/core/src/memory.js";
+import { InMemoryStore } from "../packages/storage/src/memory-store.js";
+import { LocalEmbeddingProvider } from "../packages/embeddings/src/local.js";
+
+const store = new InMemoryStore();
+const memory = await Memory.create({
+  project: "research-mesh",
+  store,
+  embeddingProvider: new LocalEmbeddingProvider(),
+});
+
+await memory.remember({
+  type: "decision",
+  content: "We decided to use PostgreSQL with pgvector.",
+  importance: 0.9,
+});
+
+const context = await memory.context({
+  query: "What database did we decide to use?",
+  maxTokens: 6000,
+});
+
+console.log(context.text);
+// Relevant project memory (research-mesh):
+// - We decided to use PostgreSQL with pgvector.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@bip-krishna/agentmind",
+  "private": false,
+  "version": "0.1.0",
+  "description": "Persistent, project-scoped context layer for AI applications",
+  "type": "module",
+  "exports": {
+    ".": "./dist/packages/core/src/index.js",
+    "./storage": "./dist/packages/storage/src/index.js",
+    "./embeddings": "./dist/packages/embeddings/src/index.js",
+    "./integrations": "./dist/packages/integrations/src/index.js",
+    "./retrieval": "./dist/packages/retrieval/src/index.js"
+  },
+  "bin": {
+    "agentmind": "./dist/cli/src/index.js",
+    "context-memory": "./dist/cli/src/index.js"
+  },
+  "workspaces": [
+    "packages/*",
+    "apps/*",
+    "cli"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && npx tsc",
+    "test": "vitest run",
+    "test:mvp": "node test-mvp.mjs",
+    "dashboard": "node ./dist/apps/dashboard/src/server.js",
+    "cli": "node ./dist/cli/src/index.js"
+  },
+  "keywords": [
+    "memory",
+    "vector",
+    "ai",
+    "context",
+    "rag",
+    "pgvector"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/pg": "^8.23.1",
+    "typescript": "^5.5.0",
+    "vitest": "^1.6.0",
+    "zod": "^3.23.0"
+  },
+  "dependencies": {
+    "pg": "^8.23.0"
+  }
+}

package/packages/core/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@agentmind/core",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "zod": "^3.23.0"
+  }
+}

package/packages/core/src/consolidation.ts

@@ -0,0 +1,104 @@
+import { randomUUID } from "node:crypto";
+import type { MemoryStore } from "./memory-store.js";
+import type { Memory } from "./types.js";
+import type { EmbeddingProvider } from "../../embeddings/src/provider.js";
+import { cosineSimilarity } from "../../embeddings/src/provider.js";
+
+/**
+ * Memory consolidation: 1000 memories -> 150 useful memories.
+ * Keeps originals as archived, creates summary memories.
+ * Uses embedding similarity to cluster, then heuristic summary.
+ */
+
+export interface ConsolidationResult {
+  summary: Memory;
+  sourceIds: string[];
+}
+
+export class Consolidator {
+  constructor(private store: MemoryStore, private embed?: EmbeddingProvider) {}
+
+  /**
+   * Consolidate a project. Groups memories with cosine > threshold (0.82) and creates summaries.
+   * Returns summaries created.
+   */
+  async consolidate(projectId: string, opts?: { threshold?: number; minClusterSize?: number }): Promise<ConsolidationResult[]> {
+    const threshold = opts?.threshold ?? 0.82;
+    const minClusterSize = opts?.minClusterSize ?? 3;
+    const memories = (await this.store.listMemories(projectId)).filter((m) => !m.archived && m.status === "active");
+    if (memories.length < minClusterSize) return [];
+
+    // Build embedding map
+    const vectors = new Map<string, number[]>();
+    for (const m of memories) {
+      const emb = await this.store.getEmbedding(m.id);
+      if (emb) vectors.set(m.id, emb.vector);
+      else if (this.embed) {
+        const v = await this.embed.embed(m.content);
+        vectors.set(m.id, v);
+      }
+    }
+
+    // Greedy clustering
+    const clusters: string[][] = [];
+    const visited = new Set<string>();
+    for (const m of memories) {
+      if (visited.has(m.id)) continue;
+      const cluster = [m.id];
+      visited.add(m.id);
+      const vecA = vectors.get(m.id);
+      if (!vecA) continue;
+      for (const other of memories) {
+        if (visited.has(other.id)) continue;
+        const vecB = vectors.get(other.id);
+        if (!vecB) continue;
+        if (cosineSimilarity(vecA, vecB) > threshold) {
+          cluster.push(other.id);
+          visited.add(other.id);
+        }
+      }
+      if (cluster.length >= minClusterSize) clusters.push(cluster);
+    }
+
+    const results: ConsolidationResult[] = [];
+    for (const cluster of clusters) {
+      const sourceMems = cluster.map((id) => memories.find((m) => m.id === id)!).filter(Boolean);
+      const summaryContent = this.summarizeCluster(sourceMems);
+      const now = new Date();
+      const summary: Memory = {
+        id: randomUUID(),
+        projectId,
+        type: "summary",
+        content: summaryContent,
+        importance: Math.max(...sourceMems.map((m) => m.importance)),
+        confidence: 0.85,
+        status: "active",
+        createdAt: now,
+        updatedAt: now,
+        accessCount: 0,
+        metadata: { consolidatedFrom: cluster, count: cluster.length },
+        archived: false,
+      };
+      await this.store.createMemory(summary);
+      if (this.embed) {
+        const vec = await this.embed.embed(summaryContent);
+        await this.store.upsertEmbedding(summary.id, vec, this.embed.model);
+      }
+      // Archive sources but keep traceable
+      for (const id of cluster) {
+        await this.store.updateMemory(id, { archived: true, status: "archived", updatedAt: now });
+      }
+      results.push({ summary, sourceIds: cluster });
+    }
+    return results;
+  }
+
+  private summarizeCluster(mems: Memory[]): string {
+    // Simple heuristic: most important + common prefix extraction
+    const byImp = [...mems].sort((a, b) => b.importance - a.importance);
+    const top = byImp[0].content;
+    const count = mems.length;
+    const types = [...new Set(mems.map((m) => m.type))].join(", ");
+    return `Consolidated ${count} memories (${types}): ${top} (and ${count - 1} related memories about similar topic)`;
+  }
+}

package/packages/core/src/events.ts

@@ -0,0 +1,25 @@
+import { EventEmitter } from "node:events";
+import type { Memory, RetrievalEvent } from "./types.js";
+
+export type MemoryEventMap = {
+  "memory.created": (memory: Memory) => void;
+  "memory.updated": (memory: Memory) => void;
+  "memory.deleted": (id: string) => void;
+  "memory.retrieved": (memories: Memory[], query: string) => void;
+  "memory.archived": (memory: Memory) => void;
+  "memory.superseded": (old: Memory, next: Memory) => void;
+  "retrieval.completed": (event: RetrievalEvent) => void;
+  "consolidation.completed": (summary: Memory, sources: string[]) => void;
+};
+
+export class MemoryEvents extends EventEmitter {
+  emit<K extends keyof MemoryEventMap>(event: K, ...args: Parameters<MemoryEventMap[K]>): boolean {
+    return super.emit(event, ...args);
+  }
+  on<K extends keyof MemoryEventMap>(event: K, listener: MemoryEventMap[K]): this {
+    return super.on(event, listener);
+  }
+  off<K extends keyof MemoryEventMap>(event: K, listener: MemoryEventMap[K]): this {
+    return super.off(event, listener);
+  }
+}

package/packages/core/src/extraction.ts

@@ -0,0 +1,81 @@
+import type { MemoryType } from "./types.js";
+
+export interface ExtractedMemory {
+  type: MemoryType;
+  content: string;
+  importance: number; // 0-1
+  confidence: number; // 0-1
+}
+
+export interface ExtractorOptions {
+  minimumImportance?: number;
+}
+
+export interface ExtractorProvider {
+  extract(conversation: string, opts?: ExtractorOptions): Promise<ExtractedMemory[]>;
+}
+
+/** Prompt template for LLM extraction */
+export const EXTRACTION_PROMPT = `Extract only information that is likely to remain useful in future interactions.
+
+Do not store:
+- greetings
+- temporary conversation
+- obvious information
+- filler
+- transient thoughts
+- sensitive information unless explicitly configured
+
+Return JSON array of {type, content, importance, confidence} where type is one of: fact, preference, decision, event, knowledge, procedure, task, summary.
+Importance 0-1, confidence 0-1. Content must be a concise standalone statement.
+
+Conversation:
+{{conversation}}
+`;
+
+/**
+ * Deterministic regex-based extractor for offline / tests.
+ * Real provider would call OpenAI / Anthropic with structured output.
+ */
+export class HeuristicExtractor implements ExtractorProvider {
+  async extract(conversation: string): Promise<ExtractedMemory[]> {
+    const results: ExtractedMemory[] = [];
+    const sentences = conversation.split(/[.!?]+/).map((s) => s.trim()).filter(Boolean);
+    const keywords = ["decided", "will use", "using", "prefer", "need", "should", "must", "database", "postgres", "mongodb", "api", "always", "never"];
+    for (const s of sentences) {
+      const lower = s.toLowerCase();
+      if (keywords.some((k) => lower.includes(k)) && s.length > 20 && s.length < 300) {
+        const type: MemoryType = lower.includes("decided") || lower.includes("will use") ? "decision" : lower.includes("prefer") ? "preference" : "fact";
+        results.push({
+          type,
+          content: s + ".",
+          importance: lower.includes("decided") ? 0.9 : 0.6,
+          confidence: 0.8,
+        });
+      }
+    }
+    return results;
+  }
+}
+
+/**
+ * LLM-backed extractor (generic). Provide a chat completion function.
+ */
+export class LLMExtractor implements ExtractorProvider {
+  constructor(
+    private callLLM: (prompt: string) => Promise<string>,
+    private minImportance = 0.65
+  ) {}
+
+  async extract(conversation: string, opts?: ExtractorOptions): Promise<ExtractedMemory[]> {
+    const prompt = EXTRACTION_PROMPT.replace("{{conversation}}", conversation);
+    const raw = await this.callLLM(prompt);
+    try {
+      const parsed = JSON.parse(raw) as ExtractedMemory[];
+      const threshold = opts?.minimumImportance ?? this.minImportance;
+      return parsed.filter((m) => m.importance >= threshold);
+    } catch {
+      return [];
+    }
+  }
+}

package/packages/core/src/index.ts

@@ -0,0 +1,22 @@
+export type {
+  Project,
+  Source,
+  SourceType,
+  MemoryType,
+  MemoryStatus,
+  RetrievalEvent,
+  SearchQuery,
+  CandidateMemory,
+  SearchResult,
+  ContextOptions,
+  ContextResult,
+  CreateMemoryInput,
+} from "./types.js";
+export type { Memory as MemoryData } from "./types.js";
+export { MemoryTypeSchema, MemoryStatusSchema, CreateMemoryInputSchema } from "./types.js";
+export type { MemoryStore } from "./memory-store.js";
+export { MemoryEngine, Memory } from "./memory.js";
+export * from "./extraction.js";
+export * from "./policy.js";
+export * from "./events.js";
+export * from "./consolidation.js";

package/packages/core/src/memory-store.ts

@@ -0,0 +1,50 @@
+import type {
+  Memory,
+  Project,
+  Source,
+  SearchQuery,
+  SearchResult,
+  RetrievalEvent,
+} from "./types.js";
+
+/**
+ * Core abstraction — Memory Store.
+ * LocalStore (SQLite) and PostgresStore both implement this.
+ * Dashboard / CLI / core engine depend only on this interface.
+ */
+export interface MemoryStore {
+  // Projects
+  createProject(project: Project): Promise<Project>;
+  getProject(id: string): Promise<Project | null>;
+  getProjectByName(name: string): Promise<Project | null>;
+  listProjects(): Promise<Project[]>;
+  deleteProject(projectId: string): Promise<void>;
+
+  // Sources
+  createSource(source: Source): Promise<Source>;
+  getSource(id: string): Promise<Source | null>;
+
+  // Memories
+  createMemory(memory: Memory): Promise<void>;
+  getMemory(id: string): Promise<Memory | null>;
+  updateMemory(id: string, update: Partial<Memory>): Promise<void>;
+  deleteMemory(id: string): Promise<void>;
+  archiveMemory(id: string): Promise<void>;
+  listMemories(projectId: string): Promise<Memory[]>;
+  search(query: SearchQuery): Promise<SearchResult[]>; // keyword fallback default
+
+  // Embeddings — stored alongside but decoupled
+  upsertEmbedding(memoryId: string, vector: number[], model: string): Promise<void>;
+  getEmbedding(memoryId: string): Promise<{ vector: number[]; model: string } | null>;
+  deleteEmbedding?(memoryId: string): Promise<void>;
+
+  // Optional native vector search (pgvector)
+  vectorSearch?(projectId: string, queryVector: number[], limit: number): Promise<Array<{ memory: Memory; distance: number }>>;
+
+  // Retrieval logs
+  logRetrieval(event: RetrievalEvent): Promise<void>;
+  listRetrievals(projectId: string, limit?: number): Promise<RetrievalEvent[]>;
+
+  // Admin
+  close?(): Promise<void>;
+}