MAMA - Memory-Augmented MCP Assistant

Version 1.0.0 | Monorepo migration complete

MAMA tracks how your decisions evolve. Instead of just remembering what you chose, it remembers why you chose it, what you tried before, and what didn't work.

What is MAMA?

An always-on companion for Claude Code and Claude Desktop that remembers decision evolution. When you make architectural choices, try different approaches, or learn from failures, MAMA stores this context and surfaces it when relevant.

The killer feature: Session continuity. End your day with /mama-checkpoint, resume tomorrow with /mama-resume - and pick up exactly where you left off with full context.

---

Installation

Claude Code

Quick Start (2 steps):

# Step 1: Add MAMA marketplace (one-time setup)
/plugin marketplace add jungjaehoon-lifegamez/claude-plugins

# Step 2: Install MAMA plugin
/plugin install mama

Note: Claude Code uses decentralized marketplaces. You need to add the MAMA marketplace once, then you can install and update the plugin anytime.

First use of /mama-save downloads the MCP server automatically (~50MB for embedding model).

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mama": {
      "command": "npx",
      "args": ["-y", "@jungjaehoon/mama-server"]
    }
  }
}

Other MCP Clients

MAMA works with any MCP-compatible client. Below are verified configurations:

Codex

Add to ~/.codex/config.toml:

[mcp_servers.mama]
  command = "npx"
  args = ["-y", "@jungjaehoon/mama-server"]
  disabled = false
  disabled_tools = []

Antigravity IDE (Gemini)

Add to ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "mama": {
      "command": "npx",
      "args": ["-y", "@jungjaehoon/mama-server"],
      "disabled": false,
      "disabledTools": []
    }
  }
}

Note: All MCP clients share the same database at ~/.claude/mama-memory.db, so decisions are available across all your IDEs.

Prerequisites

• Node.js >= 18.0.0 (20+ recommended)
• 500MB free disk space for embedding model cache
• SQLite support (included on most systems)

---

💡 Session Continuity - Never Lose Your Context

End your coding session. Pick up exactly where you left off.

# End of day - save your session state
/mama-checkpoint

# Next morning - resume with full context
/mama-resume

What you get:

🔄 Resuming Session (from yesterday, 6:30 PM)

📝 Session Summary:
Refactoring authentication module. Switched from session-based to JWT.
Token refresh working, but need to add expiration validation.

📂 Relevant Files:
- src/auth/jwt-handler.ts
- src/middleware/auth.ts
- tests/auth.test.ts

👉 Next Steps:
1. Add token expiration validation
2. Update tests for new JWT flow
3. Document API changes in README

Ready to continue where you left off!

This is MAMA's killer feature - you never lose context between sessions.

---

Quick Start

After installation:

# Save a decision
/mama-save topic="auth_strategy" decision="JWT with refresh tokens" reasoning="Need stateless auth for API scaling"

# Search for related decisions
/mama-suggest "How should I handle authentication?"

# View decision history
/mama-recall auth_strategy

# List all decisions
/mama-list

Available Commands

Command	Purpose
/mama-save	Save decision with reasoning and confidence
/mama-recall <topic>	View full evolution history for a topic
/mama-suggest <query>	Semantic search across all decisions
/mama-list	Browse recent decisions chronologically
/mama-checkpoint <summary>	Save current session state for later resumption
/mama-resume	Load last checkpoint and restore context
/mama-configure	View/modify settings and tier status

---

How It Works

MAMA uses a two-package architecture:

MCP Server (@jungjaehoon/mama-server)

Published as an independent npm package. Handles SQLite database and vector embeddings. Shared across Claude Code, Claude Desktop, and any MCP client.

Claude Code Plugin (mama)

Lightweight markdown-based plugin. Provides /mama-* commands and hooks. References the MCP server via .mcp.json.

This separation means one database works across all your Claude environments, and the MCP server updates independently from the plugin.

---

Key Features

Session Continuity (💡 Killer Feature) Save your session state before closing Claude. Resume next time with full context: what you were working on, relevant files, and exact next steps. Never lose your flow between sessions.

Decision Evolution Tracking See how your thinking changed over time, from initial attempts to final solutions.

Semantic Search Natural language queries find relevant decisions even if exact keywords don't match.

Automatic Context Relevant past decisions surface automatically when you're working on similar problems.

Local-First All data stored on your device. No network calls, no external dependencies.

Multilingual Support Queries work across different languages using multilingual embeddings.

Tier Transparency System always shows what's working. Degraded mode still functions, just without vector search.

---

Project Structure

This is a monorepo containing two packages:

MAMA/
├── packages/
│   ├── mcp-server/          # @jungjaehoon/mama-server (npm)
│   │   ├── src/             # Server implementation
│   │   └── tests/           # Server tests
│   │
│   └── claude-code-plugin/  # mama (marketplace)
│       ├── commands/        # Slash commands
│       ├── hooks/           # Auto-context injection
│       ├── skills/          # Background skills
│       └── tests/           # Plugin tests
│
└── docs/                    # Documentation

---

Development

Setup

git clone https://github.com/jungjaehoon-lifegamez/MAMA.git
cd MAMA
pnpm install
pnpm test

Running Tests

# All tests
pnpm test

# MCP server only
cd packages/mcp-server && pnpm test

# Plugin only
cd packages/claude-code-plugin && pnpm test

Local Testing

Link the plugin for local development:

cd packages/claude-code-plugin
ln -s $(pwd) ~/.claude/plugins/repos/mama

Test the MCP server standalone:

cd packages/mcp-server
npm start  # Runs in stdio mode

---

Documentation

User Guides

• Getting Started - 10-minute quickstart
• Installation - Complete setup guide
• Commands Reference - All available commands
• Troubleshooting - Common issues

Developer Docs

• Developer Playbook - Architecture overview
• Contributing Guide - How to contribute
• Testing Guide - Test suite documentation

Full Documentation Index

---

Testing

134 tests, 100% pass rate:

• 62 unit tests (core logic)
• 39 integration tests (hooks, workflows)
• 33 regression tests (bug prevention)

pnpm test               # Run all tests
pnpm test -- --coverage # With coverage report

---

Contributing

Contributions welcome. See Contributing Guide for code standards, pull request process, and testing requirements.

---

License

MIT - see LICENSE for details

---

Acknowledgments

MAMA was inspired by the excellent work of mem0 (Apache 2.0). While MAMA is a distinct implementation focused on local-first SQLite/MCP architecture for Claude, we appreciate their pioneering work in LLM memory management.

---

Links

• GitHub Repository
• Issues
• npm Package
• Documentation

---

Author: SpineLift Team Last Updated: 2025-11-22