@memstack/mcp

@memstack/mcp

MCP server for MemStack — persistent AI agent memory via the Model Context Protocol.

Installation

npm install -g @memstack/mcp

Quick Start

Add to your MCP client config (~/.claude/mcp.json or .cursor/mcp.json):

{
  "mcpServers": {
    "memstack": {
      "command": "npx",
      "args": ["-y", "@memstack/mcp"],
      "env": {
        "MEMSTACK_STORAGE": "memory",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Configuration

All configuration is via environment variables. No config files needed.

Storage backends

Variable	Values	Default
MEMSTACK_STORAGE	memory, disk, markdown, postgres, sqlite, redis	memory

In-memory (default — testing only, data lost on restart):

MEMSTACK_STORAGE=memory

Disk (JSON file per actor):

MEMSTACK_STORAGE=disk
MEMSTACK_DIR=/Users/me/.memstack

Markdown (zero infra, human-readable):

MEMSTACK_STORAGE=markdown
MEMSTACK_DIR=/Users/me/.memstack

Postgres (production):

MEMSTACK_STORAGE=postgres
DATABASE_URL=postgresql://user:pass@localhost/memstack

Redis:

MEMSTACK_STORAGE=redis
REDIS_URL=redis://localhost:6379

SQLite:

MEMSTACK_STORAGE=sqlite
SQLITE_PATH=./memory.db

LLM providers

Variable	Purpose
OPENAI_API_KEY	OpenAI LLM (default)
ANTHROPIC_API_KEY	Anthropic (summarization)
MEMSTACK_OPENAI_BASE_URL	Custom API endpoint (DeepSeek, etc.)
MEMSTACK_LLM_MODEL	Model override
MEMSTACK_EMBED_ON_STORE	Auto-embed on store (default: true)
MEMSTACK_ACTOR	Default actor ID

At least one of OPENAI_API_KEY or ANTHROPIC_API_KEY must be set. Anthropic preferred if both are set.

Embeddings (semantic search)

Variable	Purpose
OPENAI_API_KEY	OpenAI embeddings

Without embedding config, retrieval falls back to keyword + importance search.

Tools

The MCP server exposes these tools to the agent:

Tool	Description
memory_process	Store with auto-enrichment (importance, tags)
memory_store	Store a memory
memory_retrieve	Retrieve memories by query, strategy, time range
memory_compile_context	Assemble token-budgeted LLM-ready context
memory_summarize	Compress old interactions via LLM
memory_prune	Remove stale/low-importance memories
memory_purge_actor	Delete all memories for an actor
memory_merge	Merge multiple memories into one
memory_stats	Memory diagnostics (counts, types, importance)
memory_delete	Delete a single memory
memory_health	Check storage/LLM/embedding connectivity
memory_dry_run_prune	Preview what would be pruned

Resources

URI	Description
memory://{actorId}/context	Compiled LLM context as markdown
memory://{actorId}/stats	Actor memory stats as JSON

Prompts

Prompt	Description
memory_context	Auto-injected memory context for current actor

Actor persistence

By default, all memories belong to the "default" actor. Set MEMSTACK_ACTOR to identify the agent:

MEMSTACK_ACTOR=my-agent

This keeps memory isolated per agent. The agent can also override the actor with actorId in any tool call.

Publishing

cd packages/mcp
pnpm build && pnpm check && pnpm test
npm publish --access public

After publishing, users install with:

npm install -g @memstack/mcp

License

MIT