┌─────────────────────────────────────────────────────────────┐
│                        Client API                           │
│  Memory.add() / .search() / .get() / .get_all() / .update()│
│  .delete() / .delete_all() / .history() / .reset()          │
├─────────────────────────────────────────────────────────────┤
│                   Memory Pipeline                           │
│  ┌──────────┐  ┌──────────────┐  ┌─────────────────────┐   │
│  │ Message   │→│ LLM Fact     │→│ Embed + Search       │   │
│  │ Parser    │  │ Extraction   │  │ Existing Memories    │   │
│  └──────────┘  └──────────────┘  └─────────┬───────────┘   │
│                                             │               │
│  ┌──────────────────────────────────────────▼───────────┐   │
│  │           LLM Memory Update Decision                 │   │
│  │  Compare new facts vs existing → ADD/UPDATE/DELETE   │   │
│  └──────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────┤
│                    Storage Layer                            │
│  ┌────────────┐  ┌────────────┐  ┌────────────────────┐    │
│  │ Vector DB  │  │ SQLite     │  │ Neo4j (optional)   │    │
│  │ (memories) │  │ (history)  │  │ (graph memory)     │    │
│  └────────────┘  └────────────┘  └────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

interface MemoryItem {
  id: string;              // UUID v4
  memory: string;          // The fact text, e.g. "User prefers Python over JavaScript"
  hash: string;            // MD5 hex digest of the memory text (for deduplication)
  metadata: Record<string, any>;  // Arbitrary key-value pairs
  score?: number;          // Similarity score (populated on search results only)
  created_at: string;      // ISO 8601 timestamp
  updated_at: string;      // ISO 8601 timestamp
}

interface MemoryEvent {
  event: "ADD" | "UPDATE" | "DELETE" | "NONE";
  id: string;                // Memory ID affected
  old_memory?: string;       // Previous text (for UPDATE/DELETE)
  new_memory?: string;       // New text (for ADD/UPDATE)
  metadata?: Record<string, any>;
}

type Message = {
  role: "system" | "user" | "assistant";
  content: string;
};

The `add()` method accepts either a single string or an array of `Message` objects. If a string is provided, it is wrapped as `[{ role: "user", content: str }]`.

interface MemoryScope {
  user_id?: string;    // Isolate memories per end-user
  agent_id?: string;   // Isolate memories per AI agent/persona
  run_id?: string;     // Isolate memories per conversation/session
}

class Memory {
  constructor(config?: MemoryConfig);
}

**Returns**: `{ results: MemoryEvent[] }` — list of all ADD/UPDATE/DELETE/NONE events.

**Returns**: `{ results: MemoryItem[] }` — sorted by descending similarity score.

**Returns**: `{ results: MemoryItem[] }` — all memories matching the scope filters.

interface HistoryRecord {
  id: string;           // History entry ID
  memory_id: string;    // The memory this event relates to
  event: "ADD" | "UPDATE" | "DELETE";
  old_value: string | null;
  new_value: string | null;
  timestamp: string;    // ISO 8601
  is_deleted: boolean;  // Whether memory was deleted in this event
}

function parseMessages(input: string | Message[]): string {
  if (typeof input === "string") return input;
  return input
    .map(m => `${m.role}: ${m.content}`)
    .join("\n");
}

You are an expert at extracting structured, atomic facts from conversations.
Your task is to identify and extract key pieces of information from the given
conversation that would be useful to remember for future interactions.

Extract facts that fall into these categories:
1. Personal preferences (likes, dislikes, habits)
2. Biographical information (name, occupation, location, relationships)
3. Goals and intentions
4. Technical preferences and skills
5. Important dates, events, or milestones
6. Opinions and viewpoints
7. Project details and requirements
8. Communication preferences

Rules:
- Each fact must be a single, self-contained statement
- Be specific and include context where necessary
- Avoid duplicating information across facts
- Only extract information that is clearly stated or strongly implied
- Do not make assumptions beyond what is provided
- Format each fact as a concise, declarative sentence
- Use third person (e.g., "User prefers..." not "You prefer...")

Return a JSON array of strings. If no meaningful facts can be extracted,
return an empty array.

Example output:
["User's name is Alice", "User works as a software engineer at Acme Corp",
 "User prefers Python for backend development"]

embedding = embedder.embed(fact_text)

existing = vectorStore.search(
  embedding = embedding,
  limit = 5,
  filters = buildScopeFilter(user_id, agent_id, run_id)
)

You are a memory management system. You will be given:
1. A new piece of information (the "new fact")
2. A list of existing memories that are potentially related

Your job is to decide what memory operations to perform. For each operation,
return a JSON object.

Possible operations:

1. ADD — The new fact contains genuinely new information not captured by any
   existing memory. Create a new memory.
   {"event": "ADD", "data": "the fact text to store"}

2. UPDATE — The new fact updates, corrects, refines, or supersedes an existing
   memory. Provide the existing memory ID and the new merged/updated text.
   {"event": "UPDATE", "id": "<existing_memory_id>", "old_memory": "<current text>",
    "data": "the updated fact text"}

3. DELETE — The new fact contradicts or invalidates an existing memory and
   the existing memory should be removed entirely.
   {"event": "DELETE", "id": "<existing_memory_id>", "old_memory": "<current text>"}

4. NONE — The new fact is already fully captured by existing memories and
   no action is needed.
   {"event": "NONE"}

Important rules:
- If the new fact contains information not present in ANY existing memory, use ADD
- If an existing memory says something similar but the new fact has updated info,
  use UPDATE (merge the information, keeping the more recent/accurate version)
- If the new fact directly contradicts an existing memory (e.g., "moved from NYC
  to SF" when existing says "lives in NYC"), UPDATE the existing memory
- If removing info is more appropriate than updating, use DELETE
- Only use NONE if the information is truly redundant
- You may return multiple operations if needed (e.g., UPDATE one memory AND ADD
  a new one)
- Always preserve important context and nuance when merging

Return a JSON array of operation objects.

New fact: {fact_text}

Existing memories:
{for each existing memory:}
  - ID: {memory.id}, Text: {memory.memory}
{end for}
{if no existing memories:}
  No existing memories found.
{end if}

4. Build metadata: `{ ...scope_fields, ...caller_metadata, hash: hash }`

5. Insert into vector store: `vectorStore.insert(id, embedding, { memory: fact_text, ...metadata })`

4. Update vector store record: `vectorStore.update(id, newEmbedding, { memory: updated_text, hash, updated_at })`

{
  "name": "extract_entities",
  "description": "Extract entities (people, organizations, concepts, locations, events) from the conversation",
  "parameters": {
    "type": "object",
    "properties": {
      "entities": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": { "type": "string", "description": "Entity name (normalized, title case)" },
            "type": { "type": "string", "enum": ["person", "organization", "concept", "location", "event", "technology", "product"] },
            "description": { "type": "string", "description": "Brief description of the entity" }
          },
          "required": ["name", "type"]
        }
      }
    }
  }
}

{
  "name": "extract_relations",
  "description": "Extract relationships between entities",
  "parameters": {
    "type": "object",
    "properties": {
      "relations": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "source": { "type": "string", "description": "Source entity name" },
            "relation": { "type": "string", "description": "Relationship type (e.g., works_at, located_in, uses, knows)" },
            "target": { "type": "string", "description": "Target entity name" }
          },
          "required": ["source", "relation", "target"]
        }
      }
    }
  }
}

MERGE (e:Entity {name: $name})
SET e.type = $type, e.description = $description, e.updated_at = $now

MATCH (s:Entity {name: $source})
MATCH (t:Entity {name: $target})
MERGE (s)-[r:RELATES_TO {type: $relation}]->(t)
SET r.updated_at = $now

CREATE TABLE IF NOT EXISTS memory_history (
    id TEXT PRIMARY KEY,           -- UUID v4
    memory_id TEXT NOT NULL,       -- References the memory
    event TEXT NOT NULL,           -- 'ADD', 'UPDATE', 'DELETE'
    old_value TEXT,                -- Previous memory text (null for ADD)
    new_value TEXT,                -- New memory text (null for DELETE)
    timestamp TEXT NOT NULL,       -- ISO 8601
    is_deleted INTEGER DEFAULT 0,  -- 1 if this was a DELETE event

    -- Scope fields for queryability
    user_id TEXT,
    agent_id TEXT,
    run_id TEXT
);

CREATE INDEX IF NOT EXISTS idx_history_memory_id ON memory_history(memory_id);
CREATE INDEX IF NOT EXISTS idx_history_timestamp ON memory_history(timestamp);

function logHistory(memoryId, event, oldValue, newValue, scope, isDeleted = false):
    insert into memory_history values (
        uuid4(), memoryId, event, oldValue, newValue,
        new Date().toISOString(), isDeleted ? 1 : 0,
        scope.user_id, scope.agent_id, scope.run_id
    )

function getHistory(memoryId):
    SELECT * FROM memory_history
    WHERE memory_id = ?
    ORDER BY timestamp ASC

interface VectorStoreBase {
  // Collection management
  createCollection(name: string, dimension: number): Promise<void>;
  deleteCollection(name: string): Promise<void>;
  listCollections(): Promise<string[]>;
  getCollectionInfo(name: string): Promise<{ name: string; count: number; dimension: number }>;

  // CRUD operations
  insert(
    collectionName: string,
    id: string,
    vector: number[],
    payload: Record<string, any>
  ): Promise<void>;

  search(
    collectionName: string,
    queryVector: number[],
    limit: number,
    filters?: FilterExpression
  ): Promise<Array<{ id: string; score: number; payload: Record<string, any> }>>;

  get(collectionName: string, id: string): Promise<{ id: string; payload: Record<string, any> } | null>;

  update(
    collectionName: string,
    id: string,
    vector?: number[],
    payload?: Record<string, any>
  ): Promise<void>;

  delete(collectionName: string, id: string): Promise<void>;

  list(
    collectionName: string,
    filters?: FilterExpression,
    limit?: number
  ): Promise<Array<{ id: string; payload: Record<string, any> }>>;

  reset(): Promise<void>;
}

class InMemoryVectorStore implements VectorStoreBase {
  private collections: Map<string, Map<string, { vector: number[]; payload: Record<string, any> }>>;

  search(collectionName, queryVector, limit, filters?):
    // For each record in collection:
    //   1. If filters provided, check metadata matches
    //   2. Compute cosine similarity: dot(a,b) / (norm(a) * norm(b))
    //   3. Collect (id, score, payload)
    // Sort by score descending, return top `limit`
}

function cosineSimilarity(a: number[], b: number[]): number {
  let dot = 0, normA = 0, normB = 0;
  for (let i = 0; i < a.length; i++) {
    dot += a[i] * b[i];
    normA += a[i] * a[i];
    normB += b[i] * b[i];
  }
  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
}

class QdrantVectorStore implements VectorStoreBase {
  constructor(config: { host: string; port: number; apiKey?: string; onDisk?: boolean });

  // Uses Qdrant REST API:
  // PUT /collections/{name} — createCollection
  // PUT /collections/{name}/points — insert (upsert)
  // POST /collections/{name}/points/search — search
  // GET /collections/{name}/points/{id} — get
  // POST /collections/{name}/points/delete — delete

  // Filter translation: Convert FilterExpression to Qdrant filter format
  // { must: [{ key: "user_id", match: { value: "alice" } }] }
}

class PgVectorStore implements VectorStoreBase {
  constructor(config: { connectionString: string; schema?: string });

  createCollection(name, dimension):
    // CREATE TABLE {name} (
    //   id TEXT PRIMARY KEY,
    //   vector vector({dimension}),
    //   payload JSONB,
    //   created_at TIMESTAMP DEFAULT NOW()
    // );
    // CREATE INDEX ON {name} USING ivfflat (vector vector_cosine_ops);

  search(collectionName, queryVector, limit, filters?):
    // SELECT id, payload, 1 - (vector <=> $1::vector) as score
    // FROM {collection}
    // WHERE {filter_clauses}
    // ORDER BY vector <=> $1::vector
    // LIMIT $2

  // Filter translation: Convert FilterExpression to SQL WHERE clauses
  // { field: "user_id", op: "eq", value: "alice" }
  //   → payload->>'user_id' = 'alice'
}

class ChromaVectorStore implements VectorStoreBase {
  constructor(config: { host: string; port: number; path?: string });

  // Uses ChromaDB client:
  // client.createCollection(name) / getCollection(name)
  // collection.add(ids, embeddings, metadatas, documents)
  // collection.query(queryEmbeddings, nResults, where)
  // collection.update(ids, embeddings, metadatas, documents)
  // collection.delete(ids)

  // Filter translation: Convert FilterExpression to ChromaDB where format
  // { "$and": [{ "user_id": { "$eq": "alice" } }] }
}

type FilterOperator = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" |
                       "in" | "nin" | "contains" | "icontains";

type FilterCondition = {
  field: string;
  operator: FilterOperator;
  value: any;
};

type FilterExpression =
  | FilterCondition
  | { AND: FilterExpression[] }
  | { OR: FilterExpression[] }
  | { NOT: FilterExpression };

| eq | Equals | `{ field: "user_id", operator: "eq", value: "alice" }` |

| ne | Not equals | `{ field: "status", operator: "ne", value: "archived" }` |

| gt | Greater than | `{ field: "score", operator: "gt", value: 0.8 }` |

| gte | Greater or equal | `{ field: "created_at", operator: "gte", value: "2024-01-01" }` |

| lt | Less than | `{ field: "priority", operator: "lt", value: 5 }` |

| lte | Less or equal | `{ field: "age", operator: "lte", value: 30 }` |

| in | Value in set | `{ field: "tag", operator: "in", value: ["work", "personal"] }` |

| nin | Value not in set | `{ field: "tag", operator: "nin", value: ["spam"] }` |

| contains | String contains (case-sensitive) | `{ field: "memory", operator: "contains", value: "Python" }` |

| icontains | String contains (case-insensitive) | `{ field: "memory", operator: "icontains", value: "python" }` |

// Example: Find memories for user "alice" that mention either "Python" or "JavaScript"
const filter: FilterExpression = {
  AND: [
    { field: "user_id", operator: "eq", value: "alice" },
    { OR: [
      { field: "memory", operator: "icontains", value: "Python" },
      { field: "memory", operator: "icontains", value: "JavaScript" }
    ]}
  ]
};

- **Qdrant**: `{ must: [{ key: "field", match: { value: "x" } }] }`

- **ChromaDB**: `{ "$and": [{ "field": { "$eq": "x" } }] }`

- **Pinecone**: `{ "field": { "$eq": "x" } }`

interface MemoryConfig {
  // Vector store backend configuration
  vector_store?: {
    provider: "memory" | "qdrant" | "chroma" | "pgvector" | "pinecone" |
              "weaviate" | "milvus" | "faiss" | "elasticsearch" | "redis";
    config: Record<string, any>;  // Provider-specific connection config
    collection_name?: string;     // Default: "memories"
  };

  // LLM configuration (for fact extraction and update decisions)
  llm?: {
    provider: "openai" | "anthropic" | "google" | "ollama" | "azure_openai";
    config: {
      model: string;
      api_key?: string;        // Falls back to env var (OPENAI_API_KEY, etc.)
      temperature?: number;    // Default: 0
      max_tokens?: number;     // Default: 2000
      base_url?: string;       // For custom endpoints
    };
  };

  // Embedding model configuration
  embedder?: {
    provider: "openai" | "ollama" | "huggingface" | "azure_openai" | "google";
    config: {
      model: string;           // e.g., "text-embedding-3-small"
      api_key?: string;
      dimensions?: number;     // Output dimension (default: 1536 for OpenAI)
    };
  };

  // Graph memory (optional)
  graph_store?: {
    provider: "neo4j";
    config: {
      url: string;             // bolt://localhost:7687
      username: string;
      password: string;
    };
  };

  // History store
  history?: {
    db_path?: string;          // SQLite path, default: ~/.memory/history.db
  };

  // Custom prompts (override defaults)
  custom_prompts?: {
    fact_extraction?: string;  // Override FACT_EXTRACTION_PROMPT
    update_decision?: string;  // Override UPDATE_MEMORY_PROMPT
  };

  // Versioning
  version?: "v1.0" | "v1.1";  // API version, affects behavior
}

interface EmbedderBase {
  embed(text: string): Promise<number[]>;
  embedBatch(texts: string[]): Promise<number[][]>;
  getDimension(): number;
}

class OpenAIEmbedder implements EmbedderBase {
  constructor(config: { model: string; apiKey: string; dimensions?: number });

  async embed(text: string): Promise<number[]> {
    // POST https://api.openai.com/v1/embeddings
    // { model: this.model, input: text, dimensions: this.dimensions }
    // Return response.data[0].embedding
  }

  async embedBatch(texts: string[]): Promise<number[][]> {
    // Same endpoint accepts array input
    // Return response.data.map(d => d.embedding)
  }
}

class OllamaEmbedder implements EmbedderBase {
  constructor(config: { model: string; baseUrl?: string });

  async embed(text: string): Promise<number[]> {
    // POST http://localhost:11434/api/embeddings
    // { model: this.model, prompt: text }
    // Return response.embedding
  }
}

interface LLMBase {
  generate(
    systemPrompt: string,
    userMessage: string,
    options?: { temperature?: number; maxTokens?: number; responseFormat?: "json" | "text"; tools?: ToolDef[] }
  ): Promise<string>;

  generateWithToolCalls(
    systemPrompt: string,
    userMessage: string,
    tools: ToolDef[],
    options?: { temperature?: number }
  ): Promise<{ content?: string; toolCalls?: Array<{ name: string; arguments: Record<string, any> }> }>;
}

- **OpenAI**: `POST /v1/chat/completions` with `response_format: { type: "json_object" }` when JSON mode requested

class AsyncMemory {
  constructor(config?: MemoryConfig);

  async add(messages, ...scope): Promise<{ results: MemoryEvent[] }>;
  async search(query, ...scope): Promise<{ results: MemoryItem[] }>;
  async get(memoryId): Promise<MemoryItem | null>;
  async getAll(...scope): Promise<{ results: MemoryItem[] }>;
  async update(memoryId, newText): Promise<void>;
  async delete(memoryId): Promise<void>;
  async deleteAll(...scope): Promise<void>;
  async history(memoryId): Promise<HistoryRecord[]>;
  async reset(): Promise<void>;
}

POST   /v1/memories/          — Add memories (body: { messages, user_id?, agent_id?, run_id?, metadata? })
GET    /v1/memories/search/   — Search (query: q, user_id, limit)
GET    /v1/memories/:id/      — Get single memory
GET    /v1/memories/           — Get all memories (query: user_id, agent_id, run_id, limit)
PUT    /v1/memories/:id/      — Update memory (body: { text })
DELETE /v1/memories/:id/      — Delete memory
DELETE /v1/memories/           — Delete all (query: user_id, agent_id, run_id)
GET    /v1/memories/:id/history/ — Get history
POST   /v1/reset/             — Reset all

POST   /v1/entities/          — Get graph entities for scope
GET    /v1/entities/:name/relations/ — Get entity relationships

const memory = new Memory();

// Add memories from a conversation
const result = await memory.add(
  [
    { role: "user", content: "Hi, I'm Alice. I work at Acme Corp as a data scientist." },
    { role: "assistant", content: "Nice to meet you, Alice! What kind of data science work do you do?" },
    { role: "user", content: "Mostly NLP and recommendation systems. I prefer PyTorch over TensorFlow." }
  ],
  { user_id: "alice" }
);

console.log(result.results);
// [
//   { event: "ADD", id: "abc-123", new_memory: "User's name is Alice" },
//   { event: "ADD", id: "def-456", new_memory: "User works at Acme Corp as a data scientist" },
//   { event: "ADD", id: "ghi-789", new_memory: "User specializes in NLP and recommendation systems" },
//   { event: "ADD", id: "jkl-012", new_memory: "User prefers PyTorch over TensorFlow" }
// ]

// Search memories
const searchResults = await memory.search("What does Alice do?", { user_id: "alice" });
// Returns sorted by relevance: work info, specialization, etc.

// Later conversation updates a memory
await memory.add(
  [
    { role: "user", content: "I just switched jobs. I'm now at BigTech Inc." }
  ],
  { user_id: "alice" }
);
// Result: { event: "UPDATE", id: "def-456",
//           old_memory: "User works at Acme Corp as a data scientist",
//           new_memory: "User works at BigTech Inc as a data scientist" }

// Check history
const history = await memory.history("def-456");
// Shows ADD (original) then UPDATE (job change)

// Agent-specific memories
await memory.add(messages, { user_id: "alice", agent_id: "code-helper" });

// Session-scoped (ephemeral, per conversation)
await memory.add(messages, { user_id: "alice", run_id: "session-20240315" });

// Search across a specific agent's memories for a user
const results = await memory.search("Python frameworks", {
  user_id: "alice",
  agent_id: "code-helper"
});

const memory = new Memory({
  vector_store: {
    provider: "qdrant",
    config: { host: "localhost", port: 6333 }
  },
  llm: {
    provider: "anthropic",
    config: { model: "claude-sonnet-4-20250514", api_key: process.env.ANTHROPIC_API_KEY }
  },
  embedder: {
    provider: "openai",
    config: { model: "text-embedding-3-small", dimensions: 1536 }
  },
  graph_store: {
    provider: "neo4j",
    config: { url: "bolt://localhost:7687", username: "neo4j", password: "password" }
  }
});

// Search with metadata filters
const results = await memory.search("project deadlines", {
  user_id: "alice",
  filters: {
    AND: [
      { field: "category", operator: "eq", value: "work" },
      { field: "created_at", operator: "gte", value: "2024-01-01" }
    ]
  }
});

class MemoryError extends Error {
  constructor(message: string, public code: string);
}

// Specific errors
class ScopeError extends MemoryError {}       // Missing user_id/agent_id/run_id
class VectorStoreError extends MemoryError {}  // Backend connection/query failures
class LLMError extends MemoryError {}          // LLM API failures
class EmbeddingError extends MemoryError {}    // Embedding API failures
class NotFoundError extends MemoryError {}     // Memory ID not found

function withRetry(fn, maxRetries = 3, baseDelay = 1000):
  for attempt in 0..maxRetries:
    try:
      return await fn()
    catch error:
      if attempt == maxRetries: throw error
      if error is rate_limit: delay = baseDelay * 2^attempt
      else: throw error  // Don't retry non-transient errors
      await sleep(delay)

1. **Add single fact** — `add("My name is Bob", { user_id: "bob" })` → returns one ADD event with memory text "User's name is Bob"

2. **Add conversation** — `add([{role:"user",content:"..."},{role:"assistant",content:"..."}])` → extracts multiple facts, returns multiple ADD events

3. **Add with empty input** — `add("hello", { user_id: "x" })` → may return empty results if no extractable facts

5. **Search with limit** — `search(query, { limit: 3 })` → returns at most 3 results

8. **Get all for scope** — After adding 3 memories for user "alice", `get_all({ user_id: "alice" })` → returns all 3

12. **Delete all for scope** — `delete_all({ user_id: "alice" })` → `get_all({ user_id: "alice" })` returns empty

20. **Multi-scope filter** — Memories added with `{ user_id: "alice", agent_id: "helper" }` require BOTH fields to match in queries

27. **Equals filter** — `search(query, { filters: { field: "tag", operator: "eq", value: "work" } })` → only returns memories with tag "work"