memstack

# MemStack

> The open-source memory layer for AI agents — store, retrieve, summarize, and prune.

[![npm version](https://img.shields.io/npm/v/@memstack/core)](https://www.npmjs.com/package/@memstack/core)
[![skills.sh](https://skills.sh/b/isiomaC/memstack)](https://skills.sh/isiomaC/memstack)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-%40memstack%2Fmcp-blueviolet)](https://registry.modelcontextprotocol.io/?q=io.github.isiomaC%2Fmemstack)
[![memstack MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/isiomaC/memstack/badges/score.svg)](https://glama.ai/mcp/servers/isiomaC/memstack)
[![CI](https://github.com/isiomaC/memstack/actions/workflows/ci.yml/badge.svg)](https://github.com/isiomaC/memstack/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP Reference](https://img.shields.io/badge/MCP-LLM%20Reference-blue)](https://gitmcp.io/isiomaC/memstack)

```bash
# Use MemStack in your application
npm install @memstack/core

# Give your coding agent the MemStack skill
npx skills add isiomaC/memstack
```

`@memstack/core` is the runtime SDK; the Agent Skill teaches compatible coding agents how to integrate and operate MemStack correctly.

**The problem:** AI agents forget. Every interaction starts from zero. You either stuff everything into the context window (expensive, slow, degrades output quality) or the agent has no memory of past conversations.

**What MemStack does:** A persistent memory pipeline that lives between your agent and the LLM. It stores every interaction, retrieves only what's relevant, summarizes old memories to save tokens, and prunes stale ones automatically. One method call, no infrastructure required.

Think of it as the open-source alternative to [Mem0](https://mem0.ai/) — pluggable storage, bring your own LLM, zero vendor lock-in.

[![memstack MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/isiomaC/memstack/badges/card.svg)](https://glama.ai/mcp/servers/isiomaC/memstack)

---

## Table of Contents

- [Why MemStack](#why-memstack)
- [Quick Start](#quick-start)
- [Harness Memory (Claude Code & Codex)](#harness-memory-claude-code--codex)
  - [How it works](#how-it-works)
  - [Commands](#commands)
  - [What `connect` changes](#what-connect-changes)
  - [Projects](#projects)
  - [Storage](#storage)
  - [Troubleshooting](#troubleshooting)
- [The Memory Pipeline](#the-memory-pipeline)
  - [Store](#1-store)
  - [Retrieve](#2-retrieve)
  - [Compile Context](#3-compile-context)
  - [Summarize](#4-summarize)
  - [Prune](#5-prune)
- [Real-World Use Cases](#real-world-use-cases)
  - [Support Agent](#support-agent)
  - [RAG Pipeline](#rag-pipeline)
  - [Multi-User Chatbot](#multi-user-chatbot)
- [Memory Type Reference](#memory-type-reference)
- [Retrieval Strategies](#retrieval-strategies)
- [Embeddings](#embeddings)
- [Adapters](#adapters)
  - [LLM Adapters](#llm-adapters)
  - [Embedding Adapters](#embedding-adapters)
  - [Storage Adapters](#storage-adapters)
- [Full API Reference](#full-api-reference)
  - [MemStack Client](#memstack-client)
  - [Memory Subsystem](#memory-subsystem)
  - [Export / Import](#export-import)
  - [Health & Close](#health-close)
  - [Harness Memory API](#harness-memory-api)
- [Configuration](#configuration)
  - [Harness configuration file](#harness-configuration-file)
- [Advanced Usage](#advanced-usage)
  - [Custom Storage](#custom-storage)
  - [Custom LLM / Embedding](#custom-llm-embedding)
  - [Event Hooks](#event-hooks)
- [Development](#development)
  - [Setup & Tests](#setup-tests)
  - [Debugging](#debugging)
- [Publishing to npm](#publishing-to-npm)
- [Contributing](#contributing)
- [License](#license)

---

## Why MemStack

**LLMs have context windows, not memory.** The difference matters.

| Approach | Problem |
|----------|---------|
| **Stuff everything in context** | Cost is O(n²). 100 conversations = thousands of tokens = dollars per call. Quality degrades from "lost in the middle" effect. |
| **Use a vector DB directly** | You get similarity search. You don't get summarization, pruning, recency weighting, deduplication, or token budget management. You're building the pipeline yourself. |
| **Use Mem0** | Proprietary, cloud-only with their hosted API. You don't control where your data lives. |
| **Use MemStack** | Full pipeline. Pluggable everything. Your data, your infrastructure. Open source. |

**What MemStack handles that raw vector DBs don't:**

- **Summarization** — compress 100 old interactions into one paragraph, keep meaning, save tokens
- **Recency weighting** — recent memories matter more; MemStack sorts them higher
- **Importance scoring** — not all memories are equal; high-importance ones survive pruning
- **Deduplication** — identical or near-identical memories are collapsed in context assembly
- **Token budget** — `compileContext()` tells you how many tokens you're spending before the LLM call
- **Memory-type routing** — interactions, summaries, observations treated differently at retrieval time
- **Auto-pruning** — old, low-importance memories clean themselves up

---

## Quick Start

### Claude Code and Codex

Persistent memory across agent harnesses: what you tell Claude Code, Codex
recalls in the same project, and the reverse.

```bash
npm install -g @memstack/cli @memstack/mcp better-sqlite3@^11.10.0  # MemStack never installs storage drivers for you
memstack init                  # choose an LLM provider and a store
memstack connect claude-code
memstack connect codex
```

Then, in Claude Code: "Remember that this project uses Hono." In Codex, in the
same repository: "What framework does this project use?" Codex answers Hono.
See [Harness Memory](#harness-memory-claude-code--codex) for how it works.

### As a library

```bash
npm install @memstack/core
```

### OpenAI

```typescript
import { MemStack, OpenAILLMAdapter, OpenAIEmbeddingAdapter, InMemoryStorageAdapter } from "@memstack/core";

const llm = new OpenAILLMAdapter({ apiKey: process.env.OPENAI_API_KEY! });

const memstack = new MemStack({
  llm,
  embedding: new OpenAIEmbeddingAdapter({ apiKey: process.env.OPENAI_API_KEY! }),
  storage: new InMemoryStorageAdapter(),
});
```

### DeepSeek (no embeddings)

DeepSeek provides chat completions but has no embedding API. Use the OpenAI-compatible LLM adapter with `baseURL` and omit the embedding adapter — retrieval falls back to keyword + recency + importance ranking. You still get the full pipeline: store, summarize, prune, and compileContext.

```typescript
import { MemStack, OpenAILLMAdapter, InMemoryStorageAdapter } from "@memstack/core";

const llm = new OpenAILLMAdapter({
  apiKey: process.env.DEEPSEEK_API_KEY!,
  baseURL: "https://api.deepseek.com/v1",
  defaultModel: "deepseek-flash",
});

const memstack = new MemStack({
  llm,
  storage: new InMemoryStorageAdapter(),
  // No embedding adapter — retrieval uses keyword matching
});
```

### OpenRouter / Together AI / any OpenAI-compatible API

Same pattern — change `baseURL` and `defaultModel`:

```typescript
// OpenRouter
const llm = new OpenAILLMAdapter({
  apiKey: process.env.OPENROUTER_API_KEY!,
  baseURL: "https://openrouter.ai/api/v1",
  defaultModel: "openai/gpt-4o-mini",
});

// Together AI
const llm = new OpenAILLMAdapter({
  apiKey: process.env.TOGETHER_API_KEY!,
  baseURL: "https://api.together.xyz/v1",
  defaultModel: "meta-llama/Llama-3.3-70B-Instruct-Turbo",
});

// Gemini (OpenAI-compatible endpoint)
const llm = new OpenAILLMAdapter({
  apiKey: process.env.GEMINI_API_KEY!,
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai",
  defaultModel: "gemini-2.0-flash",
});
```

### Store and retrieve

```typescript
// 1. Store what happened
await memstack.memory.store({
  actorId: "support-bot-42",
  content: "User reports login failing with error 503 on Chrome 125.",
  tags: ["login", "bug", "chrome"],
  importance: 0.8,
});

// 2. Later, retrieve relevant context
const memories = await memstack.memory.retrieve({
  actorId: "support-bot-42",
  query: "login error",
  strategy: "hybrid",
});

// 3. Assemble an LLM-ready context
const ctx = await memstack.memory.compileContext({
  actorId: "support-bot-42",
  maxTokens: 2000,
});

const response = await llm.complete({
  system: `You are a support bot. Here is what you remember:\n${ctx.systemPrompt}`,
  user: "The user is back and still can't log in. What do you do?",
});

console.log(response.text);
// "Based on our history, the user has been experiencing 503 errors on Chrome 125..."

// 4. Every 100 interactions, summarization triggers automatically.
// Old interactions are compressed into a paragraph. Token costs stay flat.
```

---

## Harness Memory (Claude Code & Codex)

Coding agents forget everything between sessions, and they don't share what
they learn with each other. MemStack gives Claude Code and Codex one memory
per project: a decision made with one agent is known to the other, and to
every later session.

### How it works

- **Saving.** Each agent gets five MemStack tools (`memory_store`,
  `memory_retrieve`, `memory_get`, `memory_delete`, `memory_stats`) through
  the MCP harness profile. When you say "remember that…", or the agent learns
  a durable fact, decision, preference, or rule, it calls `memory_store`.
  MemStack asks your LLM for a few topic tags, so "uses Hono" can later be
  found by "which framework?". If tagging fails, the memory is still saved.
- **Recalling.** A session-start hook loads the project's most important
  memories into every new session, so the agent starts out knowing them.
  During a session the agent calls `memory_retrieve` with plain questions.
  Recall runs locally with keyword ranking (BM25 with stemming) and never
  calls the LLM, so it is fast and works offline.
- **Scope.** Memories belong to the current project. Preferences that apply
  everywhere can be saved as global (`scope: "global"`) and ar