@mzhub/mem-ts 0.1.0

package/README.md

@@ -0,0 +1,335 @@
+<p align="center">
+  <img src="logo.png" alt="mem-ts" width="180" />
+</p>
+
+<h1 align="center">mem-ts</h1>
+
+<p align="center">
+  <strong>Persistent memory for AI agents — the digital brain</strong><br/>
+  <em>Built by MZ Hub</em>
+</p>
+
+<!-- TODO: Add GIF demo here showing memory in action -->
+<!-- <p align="center"><img src="demo.gif" width="600" /></p> -->
+
+---
+
+## The Problem
+
+AI agents forget.
+
+Not sometimes. Always.
+
+Every conversation starts from zero. Every user has to re-explain themselves. Every preference is lost the moment the session ends.
+
+```
+Monday   User: "I'm allergic to peanuts"
+         Bot:  "Noted!"
+
+Friday   User: "What snack should I get?"
+         Bot:  "Try our peanut butter cups!"
+```
+
+This is the default behavior of every LLM. They have no memory. Only context windows that reset.
+
+---
+
+## Why Current Memory Systems Fail
+
+The common solution is a vector database. Store everything as embeddings. Retrieve by similarity.
+
+This fails silently when facts change.
+
+```
+March    User: "I work at Google"
+         → Stored as embedding ✓
+
+June     User: "I just joined Microsoft"
+         → Also stored as embedding ✓
+
+July     User: "Where do I work?"
+         → Vector search returns BOTH
+         → LLM sees contradictory information
+         → Hallucinates or hedges
+```
+
+**The core issue:**
+
+| What vectors do    | What memory requires   |
+| ------------------ | ---------------------- |
+| Find similar text  | Track current truth    |
+| Retrieve matches   | Replace outdated facts |
+| Rank by similarity | Resolve contradictions |
+
+Vector databases answer: _"What text matches this query?"_
+
+They cannot answer: _"What is true about this user right now?"_
+
+[Read the full explanation →](./docs/why-vectors-fail.md)
+
+---
+
+## The Solution: Brain-Inspired Architecture
+
+mem-ts doesn't just store facts. It thinks like a brain.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        User Message                         │
+└──────────────────────────┬──────────────────────────────────┘
+                           │
+            ┌──────────────▼──────────────┐
+            │      🧠 FAST BRAIN          │
+            │      (Your LLM)             │
+            │                             │
+            │  • Reasoning                │
+            │  • Conversation             │
+            │  • Immediate responses      │
+            └──────────────┬──────────────┘
+                           │
+            ┌──────────────▼──────────────┐
+            │      Response to User       │ ◄── Returns immediately
+            └──────────────┬──────────────┘
+                           │
+                           │ (async, non-blocking)
+                           ▼
+            ┌─────────────────────────────┐
+            │      🔄 SLOW BRAIN          │
+            │      (mem-ts)               │
+            │                             │
+            │  • Extract facts            │
+            │  • Detect contradictions    │
+            │  • Synthesize patterns      │
+            │  • Consolidate memories     │
+            └─────────────────────────────┘
+```
+
+### Built-In Brain Components
+
+| Component                   | Biological Equivalent  | What It Does                                            |
+| --------------------------- | ---------------------- | ------------------------------------------------------- |
+| **Importance Scoring**      | Amygdala               | Safety-critical facts (allergies) are never forgotten   |
+| **Episodic Memory**         | Hippocampus            | Links facts to conversations ("when did I learn this?") |
+| **Hebbian Learning**        | Neural Plasticity      | Frequently accessed facts get stronger                  |
+| **Deep Sleep**              | Sleep Consolidation    | Synthesizes patterns across conversations               |
+| **Memory Stages**           | Short/Long-term Memory | Facts progress from temporary → permanent               |
+| **Contradiction Detection** | Prefrontal Cortex      | Flags conflicting information in real-time              |
+| **Knowledge Graph**         | Associative Cortex     | Links related facts together                            |
+| **Behavioral Prediction**   | Pattern Recognition    | Detects user habits and preferences                     |
+
+[Learn about the brain architecture →](./docs/brain-architecture.md)
+
+---
+
+## Quick Start
+
+### Install
+
+```bash
+npm install @mzhub/mem-ts
+```
+
+### Use
+
+```typescript
+import { MemoryOS, JSONFileAdapter } from "@mzhub/mem-ts";
+
+const memory = new MemoryOS({
+  llm: { provider: "openai", apiKey: process.env.OPENAI_API_KEY },
+  adapter: new JSONFileAdapter({ path: "./.mem-ts" }),
+});
+
+async function chat(userId, message) {
+  // 1. Ask: "What do I know about this user?"
+  const context = await memory.hydrate(userId, message);
+
+  // 2. Include it in your LLM call
+  const response = await yourLLM({
+    system: context.compiledPrompt,
+    user: message,
+  });
+
+  // 3. Learn from this conversation (non-blocking)
+  memory.digest(userId, message, response);
+
+  return response;
+}
+```
+
+That's it. The agent now remembers.
+
+---
+
+## Optional: Hierarchical Memory (HMM)
+
+For advanced use cases, enable the **Memory Pyramid** — compressing thousands of facts into wisdom.
+
+```typescript
+import { HierarchicalMemory } from "@mzhub/mem-ts";
+
+const hmm = new HierarchicalMemory(adapter, provider, { enabled: true });
+
+// Top-down retrieval: wisdom first, details only if needed
+const { coreBeliefs, patterns, facts } = await hmm.hydrateHierarchical(userId);
+
+// Compress facts into patterns ("User is health-conscious")
+await hmm.synthesizePatterns(userId);
+```
+
+**The Memory Pyramid:**
+
+```
+    Level 4: Core Beliefs (BIOS)
+    ────────────────────────────
+    • Allergies, identity, safety rules
+    • ALWAYS loaded, never forgotten
+
+    Level 3: Patterns (Wisdom)
+    ────────────────────────────
+    • "User is health-conscious"
+    • Synthesized from many facts
+    • 1 token instead of 50
+
+    Level 2: Facts (Knowledge)
+    ────────────────────────────
+    • "User ate salad on Tuesday"
+    • Standard discrete facts
+
+    Level 1: Raw Logs (Stream)
+    ────────────────────────────
+    • Ephemeral conversation buffer
+    • Auto-flushed after extraction
+```
+
+[Learn more about HMM →](./docs/hierarchical-memory.md)
+
+---
+
+## Before and After
+
+### Without mem-ts
+
+```
+User: "Recommend a restaurant"
+Bot:  "What kind of food do you like?"
+User: "I told you last week, I'm vegan"
+Bot:  "Sorry, I don't have memory of previous conversations"
+```
+
+- Token-heavy prompts (full history)
+- Repeated clarifications
+- Inconsistent behavior
+- User frustration
+
+### With mem-ts
+
+```
+User: "Recommend a restaurant"
+Bot:  "Here are some vegan spots near Berlin..."
+```
+
+- Preferences remembered
+- Facts updated when they change
+- Critical info never forgotten
+- Predictable behavior
+
+---
+
+## What Gets Stored
+
+mem-ts stores facts, not chat logs.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    User: john@example.com                   │
+├───────────────┬─────────────────────────────────────────────┤
+│ name          │ John                            (importance: 5) │
+│ diet          │ vegan                           (importance: 7) │
+│ location      │ Berlin                          (importance: 5) │
+│ allergies     │ peanuts                         (importance: 10)│
+│ PATTERN       │ health-conscious                (importance: 7) │
+├───────────────┴─────────────────────────────────────────────┤
+│ Memory Stage: long-term  │  Access Count: 47  │  Sentiment: + │
+└─────────────────────────────────────────────────────────────┘
+```
+
+When facts change, they are **replaced**, not appended.
+Critical facts (importance ≥ 9) are **always included** in context.
+
+---
+
+## Safety and Cost Considerations
+
+### Security
+
+| Risk                        | Mitigation                            |
+| --------------------------- | ------------------------------------- |
+| Prompt injection via memory | Content scanning, XML safety wrapping |
+| PII storage                 | Detection and optional redaction      |
+| Cross-user leakage          | Strict user ID isolation              |
+| Forgetting critical info    | Importance scoring (amygdala pattern) |
+
+### Cost Control
+
+| Risk                     | Mitigation                                |
+| ------------------------ | ----------------------------------------- |
+| Runaway extraction costs | Daily token/call budgets                  |
+| Token bloat from memory  | Hierarchical retrieval (patterns > facts) |
+| Stale data accumulation  | Memory consolidation + automatic decay    |
+
+```typescript
+// Built-in budget limits
+const budget = new BudgetManager({
+  maxTokensPerUserPerDay: 100000,
+  maxExtractionsPerUserPerDay: 100,
+});
+```
+
+---
+
+## Who This Is For
+
+**Good fit:**
+
+- AI agents with recurring users
+- Support bots that need context
+- Personal assistants
+- Workflow automation (n8n, Zapier)
+- Any system where users expect to be remembered
+
+**Not a fit:**
+
+- One-time chat interactions
+- Document search / RAG
+- Stateless demos
+- Replacing vector databases entirely
+
+mem-ts complements vectors. It does not replace them.
+
+---
+
+## Documentation
+
+- [Why Vector Databases Fail](./docs/why-vectors-fail.md)
+- [Brain Architecture](./docs/brain-architecture.md)
+- [Hierarchical Memory (HMM)](./docs/hierarchical-memory.md)
+- [Cost Guide](./docs/cost-guide.md)
+- [API Reference](./docs/api.md)
+- [Storage Adapters](./docs/adapters.md)
+- [Security](./docs/security.md)
+
+---
+
+## Philosophy
+
+- Memory should be explicit, not inferred from similarity
+- Facts should be overwriteable, not append-only
+- Critical information should never be forgotten
+- Agents should think like brains, not databases
+- Infrastructure should be boring and reliable
+
+---
+
+## License
+
+MIT — Built by **MZ Hub**

package/dist/BaseAdapter-BoRh1T7O.d.mts

@@ -0,0 +1,75 @@
+import { F as FactFilter, M as MemoryFact, C as ConversationExchange, S as Session } from './types-G9qmfSeZ.mjs';
+
+/**
+ * Abstract base class for storage adapters.
+ * All storage implementations must extend this class.
+ */
+declare abstract class BaseAdapter {
+    protected initialized: boolean;
+    /**
+     * Initialize the adapter (connect to database, create tables, etc.)
+     */
+    abstract initialize(): Promise<void>;
+    /**
+     * Close the adapter connection
+     */
+    abstract close(): Promise<void>;
+    /**
+     * Get facts for a user with optional filters
+     */
+    abstract getFacts(userId: string, filter?: FactFilter): Promise<MemoryFact[]>;
+    /**
+     * Get a specific fact by ID
+     */
+    abstract getFactById(userId: string, factId: string): Promise<MemoryFact | null>;
+    /**
+     * Insert or update a fact
+     */
+    abstract upsertFact(userId: string, fact: Omit<MemoryFact, "id" | "createdAt" | "updatedAt">): Promise<MemoryFact>;
+    /**
+     * Update an existing fact
+     */
+    abstract updateFact(userId: string, factId: string, updates: Partial<MemoryFact>): Promise<MemoryFact>;
+    /**
+     * Delete a fact (soft delete - sets invalidatedAt)
+     */
+    abstract deleteFact(userId: string, factId: string, reason?: string): Promise<void>;
+    /**
+     * Hard delete a fact (permanent)
+     */
+    abstract hardDeleteFact(userId: string, factId: string): Promise<void>;
+    /**
+     * Get conversation history for a user
+     */
+    abstract getConversationHistory(userId: string, limit?: number, sessionId?: string): Promise<ConversationExchange[]>;
+    /**
+     * Save a conversation exchange
+     */
+    abstract saveConversation(userId: string, exchange: Omit<ConversationExchange, "id">): Promise<ConversationExchange>;
+    /**
+     * Get all sessions for a user
+     */
+    abstract getSessions(userId: string, limit?: number): Promise<Session[]>;
+    /**
+     * Get a specific session
+     */
+    abstract getSession(userId: string, sessionId: string): Promise<Session | null>;
+    /**
+     * Create a new session
+     */
+    abstract createSession(userId: string): Promise<Session>;
+    /**
+     * End a session
+     */
+    abstract endSession(userId: string, sessionId: string, summary?: string): Promise<Session>;
+    /**
+     * Check if adapter is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Ensure adapter is initialized before operations
+     */
+    protected ensureInitialized(): Promise<void>;
+}
+
+export { BaseAdapter as B };

package/dist/BaseAdapter-CQVX-gcA.d.ts

@@ -0,0 +1,75 @@
+import { F as FactFilter, M as MemoryFact, C as ConversationExchange, S as Session } from './types-G9qmfSeZ.js';
+
+/**
+ * Abstract base class for storage adapters.
+ * All storage implementations must extend this class.
+ */
+declare abstract class BaseAdapter {
+    protected initialized: boolean;
+    /**
+     * Initialize the adapter (connect to database, create tables, etc.)
+     */
+    abstract initialize(): Promise<void>;
+    /**
+     * Close the adapter connection
+     */
+    abstract close(): Promise<void>;
+    /**
+     * Get facts for a user with optional filters
+     */
+    abstract getFacts(userId: string, filter?: FactFilter): Promise<MemoryFact[]>;
+    /**
+     * Get a specific fact by ID
+     */
+    abstract getFactById(userId: string, factId: string): Promise<MemoryFact | null>;
+    /**
+     * Insert or update a fact
+     */
+    abstract upsertFact(userId: string, fact: Omit<MemoryFact, "id" | "createdAt" | "updatedAt">): Promise<MemoryFact>;
+    /**
+     * Update an existing fact
+     */
+    abstract updateFact(userId: string, factId: string, updates: Partial<MemoryFact>): Promise<MemoryFact>;
+    /**
+     * Delete a fact (soft delete - sets invalidatedAt)
+     */
+    abstract deleteFact(userId: string, factId: string, reason?: string): Promise<void>;
+    /**
+     * Hard delete a fact (permanent)
+     */
+    abstract hardDeleteFact(userId: string, factId: string): Promise<void>;
+    /**
+     * Get conversation history for a user
+     */
+    abstract getConversationHistory(userId: string, limit?: number, sessionId?: string): Promise<ConversationExchange[]>;
+    /**
+     * Save a conversation exchange
+     */
+    abstract saveConversation(userId: string, exchange: Omit<ConversationExchange, "id">): Promise<ConversationExchange>;
+    /**
+     * Get all sessions for a user
+     */
+    abstract getSessions(userId: string, limit?: number): Promise<Session[]>;
+    /**
+     * Get a specific session
+     */
+    abstract getSession(userId: string, sessionId: string): Promise<Session | null>;
+    /**
+     * Create a new session
+     */
+    abstract createSession(userId: string): Promise<Session>;
+    /**
+     * End a session
+     */
+    abstract endSession(userId: string, sessionId: string, summary?: string): Promise<Session>;
+    /**
+     * Check if adapter is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Ensure adapter is initialized before operations
+     */
+    protected ensureInitialized(): Promise<void>;
+}
+
+export { BaseAdapter as B };

package/dist/BaseProvider-CEoiLGj5.d.ts

@@ -0,0 +1,34 @@
+import { a as CompletionOptions, b as CompletionResult } from './types-G9qmfSeZ.js';
+
+/**
+ * Abstract base class for LLM providers.
+ * All provider implementations must extend this class.
+ */
+declare abstract class BaseProvider {
+    protected apiKey: string;
+    protected model: string;
+    protected baseUrl?: string;
+    constructor(config: {
+        apiKey: string;
+        model?: string;
+        baseUrl?: string;
+    });
+    /**
+     * Get the default model for this provider
+     */
+    abstract getDefaultModel(): string;
+    /**
+     * Get the provider name
+     */
+    abstract getName(): string;
+    /**
+     * Generate a completion from the LLM
+     */
+    abstract complete(options: CompletionOptions): Promise<CompletionResult>;
+    /**
+     * Check if the provider SDK is available
+     */
+    static isAvailable(): boolean;
+}
+
+export { BaseProvider as B };

package/dist/BaseProvider-edMh_R9t.d.mts

@@ -0,0 +1,34 @@
+import { a as CompletionOptions, b as CompletionResult } from './types-G9qmfSeZ.mjs';
+
+/**
+ * Abstract base class for LLM providers.
+ * All provider implementations must extend this class.
+ */
+declare abstract class BaseProvider {
+    protected apiKey: string;
+    protected model: string;
+    protected baseUrl?: string;
+    constructor(config: {
+        apiKey: string;
+        model?: string;
+        baseUrl?: string;
+    });
+    /**
+     * Get the default model for this provider
+     */
+    abstract getDefaultModel(): string;
+    /**
+     * Get the provider name
+     */
+    abstract getName(): string;
+    /**
+     * Generate a completion from the LLM
+     */
+    abstract complete(options: CompletionOptions): Promise<CompletionResult>;
+    /**
+     * Check if the provider SDK is available
+     */
+    static isAvailable(): boolean;
+}
+
+export { BaseProvider as B };