Claude Memory

Persistent memory for Claude Code Channels via Telegram, powered by Supabase and MCP.

Claude Memory is a lightweight MCP server built to give Claude Code Channels on Telegram a practical long-term memory layer. It stores facts, conversation logs, and session summaries in Supabase so Claude can recall useful context across sessions instead of starting from scratch every time.

It was created for the real-world workflow of staying connected to Claude through Telegram, where convenience is high but continuity can easily get lost.

Why this exists

Claude Code Channels on Telegram make it incredibly convenient to stay connected to Claude from anywhere, but useful context can disappear between sessions unless you provide a memory layer.

This project solves that problem by adding persistent memory through Supabase. It allows Claude to remember important facts, recall previous conversations, and carry forward relevant context over time.

The goal is not to build a giant, overengineered framework. The goal is to create a simple, practical memory system that is easy to run, easy to understand, and genuinely useful in everyday Claude Code workflows via Telegram.

While it was built specifically for Claude Code Channels on Telegram, the same overall pattern may also be useful for other trusted MCP-based Claude workflows.

What it stores

• Facts for long-lived memory
• Messages for conversation history
• Summaries for session-level context compression

Core tools

• remember — save an important fact
• recall — search previous facts, messages, and summaries
• forget — deactivate a fact
• start_session — begin a new conversation session
• end_session — close a session
• load_context — load useful recent context
• log_message — store conversation messages

Quick example

• “Remember that I prefer TypeScript” → saves a fact
• “What did we discuss yesterday?” → recalls prior context
• “Forget that TypeScript preference” → deactivates the saved fact
• Start a new session → Claude can load relevant context automatically

Prerequisites

• Bun runtime (install: curl -fsSL https://bun.sh/install | bash)
• A free Supabase account
• Claude Code (CLI) or Claude Desktop

Setup (5 minutes)

Step 1: Create a Supabase Project

1. Go to supabase.com and create a free account
2. Click New Project, give it a name (e.g. claude-memory), set a password, and pick a region
3. Wait for the project to finish provisioning (~30 seconds)

Step 2: Create the Database Tables

1. In your Supabase dashboard, go to SQL Editor (left sidebar)
2. Click New Query
3. Paste the entire contents of schema.sql into the editor
4. Click Run — you should see "Success. No rows returned" for each statement

This creates three tables: messages, summaries, and facts.

Step 3: Get Your Credentials

1. In Supabase, go to Settings > API (left sidebar)
2. Copy these two values:
   • Project URL (looks like https://abc123.supabase.co)
   • service_role key (under "Project API keys" — use the service_role key, NOT the anon key)

Step 4: Clone and Configure

git clone https://github.com/jordanl61/claude-memory.git
cd claude-memory

# Create your .env file
cp .env.example .env

Edit .env and paste in your credentials:

SUPABASE_URL=https://your-project-id.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here

Step 5: Install and Build

bun install
bun run build

Step 6: Register the MCP Server

For Claude Code (CLI)

Add this to your .claude.json file (in your home directory or project root):

{
  "mcpServers": {
    "memory": {
      "command": "bun",
      "args": ["run", "/full/path/to/claude-memory/dist/server.js"],
      "env": {
        "SUPABASE_URL": "https://your-project-id.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key-here"
      }
    }
  }
}

Important: Replace /full/path/to/claude-memory/ with the actual absolute path where you cloned the repo.

For Claude Desktop

Add the same config to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "memory": {
      "command": "bun",
      "args": ["run", "/full/path/to/claude-memory/dist/server.js"],
      "env": {
        "SUPABASE_URL": "https://your-project-id.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key-here"
      }
    }
  }
}

Step 7: Restart Claude

Restart Claude Code or Claude Desktop. The memory tools should now be available.

To verify: Ask Claude "Do you have memory tools available?" — it should list the remember, recall, forget tools.

Usage

Once installed, just talk to Claude naturally:

• "Remember that I prefer dark mode" — Claude calls remember
• "What did we talk about yesterday?" — Claude calls recall
• "Forget that thing about dark mode" — Claude calls forget

Claude will also automatically load context from past sessions when starting a new conversation (if you or Claude calls start_session).

Optional: Auto-Sync Hooks (Claude Code Only)

The scripts/ directory contains hook scripts that automatically log every message and generate session summaries without you having to do anything. These only work with Claude Code (not Desktop), since they rely on Claude Code's hook system.

See the scripts in scripts/ if you want to set these up — they require additional configuration in your Claude Code settings.json.

Architecture

You <-> Claude <-> MCP Server <-> Supabase
                       |
                  memory tools
              (remember, recall, etc.)

• MCP Server (server.ts) — Exposes memory tools via the Model Context Protocol
• Database (db.ts) — Handles all Supabase queries
• Schema (schema.sql) — Three tables: messages, summaries, facts

Files

File	Purpose
server.ts	MCP server entry point — defines all tools
db.ts	Supabase database helpers
schema.sql	Database table definitions
package.json	Dependencies and build scripts
scripts/sync-to-supabase.ts	Auto-sync hook (logs messages after each turn)
scripts/session-summary.ts	Session end summary hook
scripts/save-fact.ts	Utility to save facts directly
scripts/memory-health-check.sh	Health check script

Security Notes

This project is intended to run in a trusted local or server-side MCP environment for Claude Code Channels via Telegram.

• Use the service_role key only in environments you control
• Never expose the service_role key in browser-based apps or client-side code
• Never commit your .env file or API keys to GitHub
• Rotate your key immediately if you believe it has been exposed
• Consider creating a dedicated Supabase project just for this memory server

Row Level Security (RLS) is enabled in the Supabase setup, but the service_role key still has elevated privileges and should always be treated as highly sensitive.

Trust Model

Claude Memory is designed for a trusted MCP runtime using Supabase server credentials.

This project uses Supabase as the persistent memory layer and is intended to run locally or in a server environment you control. Row Level Security (RLS) is enabled, but the MCP server uses the Supabase service_role key for trusted server-side access.

That means:

• database access happens through the MCP server, not directly from a client app
• the service_role key must remain private
• this project is optimized for trusted Claude workflows rather than public-facing client deployments

If you want to adapt this project for a broader multi-user or less-trusted environment, you may want to extend it further with:

• per-user ownership and tenancy design
• stricter authenticated access patterns
• tighter secret handling and deployment controls
• additional audit and usage safeguards

Disclaimer

This project is provided in good faith as a practical tool for trusted Claude Code Channels via Telegram workflows.

It is provided as is, without warranty of any kind. You are responsible for reviewing the code, securing your environment, protecting your secrets, and deciding whether it is appropriate for your use case.

Please do not expose privileged Supabase credentials in untrusted or client-side environments. See the LICENSE file for the full license terms.

Roadmap

• [x] Persistent fact storage
• [x] Conversation logging
• [x] Session summaries
• [x] Claude Code Channels via Telegram workflow
• [x] Supabase-backed persistent storage
• [x] RLS-enabled database setup
• [ ] Better search and recall quality
• [ ] Optional semantic search / embeddings
• [ ] Multi-user namespacing
• [ ] Hardened deployment guidance for broader use cases
• [ ] Backup / export utilities
• [ ] Additional examples, screenshots, and setup docs

Troubleshooting

"Missing SUPABASE_URL or SUPABASE_SERVICE_ROLE_KEY" Your .env file is missing or the env vars aren't being passed. Make sure the env block in your MCP config has the correct values.

Memory tools don't show up Restart Claude Code/Desktop after adding the MCP config. Check that the path to dist/server.js is correct and absolute.

"logMessage error" / database errors Make sure you ran schema.sql in the Supabase SQL Editor. Check that you're using the service_role key (not the anon key).

Created by Lawrence Jordan

License

MIT