@withone/mem 0.1.0

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@withone/mem",
+  "version": "0.1.0",
+  "description": "Memory for AI agents. Simple, fast, works anywhere.",
+  "keywords": [
+    "ai",
+    "memory",
+    "agents",
+    "supabase",
+    "knowledge",
+    "graph",
+    "mem",
+    "claude-code",
+    "llm",
+    "vector-search"
+  ],
+  "author": "Moe Katib",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/withoneai/mem"
+  },
+  "homepage": "https://mem.now",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "mem": "./bin/mem"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.0.0",
+    "@supabase/supabase-js": "^2.49.1",
+    "commander": "^12.1.0",
+    "openai": "^4.77.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/context/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: mem-context
+description: Get startup context from Mem memory
+triggers:
+  - "get context"
+  - "load memory"
+  - "what's important"
+  - "session context"
+  - "/context"
+---
+
+# Context Skill
+
+Get the most relevant memories for session startup.
+
+## Quick Command
+
+```bash
+# Default: top 20 most relevant
+mem context
+
+# Limit results
+mem context -n 10
+
+# Filter by types
+mem context -t decision,preference
+```
+
+## How Relevance Works
+
+Context uses a **relevance score** combining:
+- **Weight (40%)**: Explicit importance (1-10, set with `weight` command)
+- **Access frequency (30%)**: How often the memory is accessed/returned
+- **Recency (30%)**: How recently it was accessed (decays over ~30 days)
+
+This means:
+- High-weight items always surface (preferences, critical decisions)
+- Frequently useful items rise naturally
+- Old, unused items fade away
+
+## When to Use
+
+### Session Startup
+
+Run at the start of each conversation to load important context:
+
+```bash
+mem context
+```
+
+This returns preferences, active decisions, recent context.
+
+### Before Major Work
+
+Before starting significant tasks:
+
+```bash
+mem context -t decision,preference
+```
+
+Gets relevant decisions and preferences that should guide your work.
+
+### Meeting Prep
+
+Before discussing a specific topic:
+
+```bash
+mem search "topic name"
+mem context -n 10
+```
+
+## Context Output
+
+Results show:
+- **Score**: Relevance score (higher = more relevant)
+- **Type**: Memory type
+- **Weight**: Explicit importance setting
+- **Accesses**: How many times accessed
+- **Content preview**
+
+Example:
+```
+Startup Context (by relevance):
+
+[0.823] preference: Code style preferences
+         weight=9, accesses=15
+         Prefers TypeScript over JavaScript. Use ESLint...
+
+[0.756] decision: API Architecture
+         weight=8, accesses=7
+         Using REST not GraphQL. Rationale: simpler...
+
+[0.534] note: Current sprint goals
+         weight=5, accesses=3
+         Focus on MCP integration and documentation...
+
+20 memories
+```
+
+## Managing Relevance
+
+### Increase Relevance
+
+```bash
+# Set high weight (always surfaces)
+mem weight <id> 9
+
+# Accessing via search naturally increases relevance
+mem search "relevant query"
+```
+
+### Decrease Relevance
+
+```bash
+# Archive when done (excludes from context)
+mem archive <id>
+
+# Reset access count (lets it fade naturally)
+mem flush <id>
+```
+
+### Restore
+
+```bash
+# Bring back archived memory
+mem unarchive <id>
+```
+
+## Lifecycle Pattern
+
+1. **Add**: New memory enters with default weight (5)
+2. **Surface**: Frequently accessed = higher relevance
+3. **Fade**: Unused items decay in relevance over time
+4. **Archive**: When done, archive to exclude from context
+5. **Flush**: If over-accessed temporarily, flush to let it decay
+
+## Integration Pattern
+
+For AI agents, a typical session start:
+
+```bash
+# 1. Load context
+mem context -n 15
+
+# 2. Note any gaps or outdated info
+# 3. Update weights if needed
+mem weight <stale_id> 3
+mem weight <important_id> 9
+
+# 4. Archive completed items
+mem archive <done_id>
+```
+
+## Related Commands
+
+```bash
+# Search for specific content
+mem search "query"
+
+# Get specific memory
+mem get <id>
+
+# Set importance
+mem weight <id> <1-10>
+
+# Archive
+mem archive <id>
+```

package/skills/remember/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: remember
+description: Save information to Mem memory
+triggers:
+  - "remember this"
+  - "remember that"
+  - "save this"
+  - "note that"
+  - "don't forget"
+  - "/remember"
+---
+
+# Remember Skill
+
+Save information to Mem memory for future retrieval.
+
+## Quick Commands
+
+```bash
+# Basic - add any type of memory
+mem add note '{"content": "The actual information to remember"}'
+
+# With topic for organization
+mem add note '{"content": "...", "topic": "Meeting Notes"}'
+
+# Decision with high importance
+mem add decision '{"topic": "API Design", "content": "Use REST not GraphQL because...", "weight": 9}'
+
+# Preference (usually high weight)
+mem add preference '{"content": "Prefers TypeScript over JavaScript", "weight": 8}'
+
+# Link two memories
+mem link <id1> related_to <id2> --bi    # bidirectional
+mem link <id1> supersedes <id2>          # directional (old -> new)
+```
+
+## Workflow
+
+### 1. Determine What to Save
+
+Extract the key information. Ask if unclear:
+- What exactly should be remembered?
+- Is this a fact, preference, decision, or context?
+- How important is it? (1=low, 5=default, 10=always surface)
+
+### 2. Choose Type and Weight
+
+| Type | When to Use | Typical Weight |
+|------|-------------|----------------|
+| `note` | General information, context | 5 |
+| `decision` | Choices made with rationale | 7-9 |
+| `preference` | How user likes things done | 8-10 |
+| `insight` | Learnings, realizations | 6-8 |
+| `context` | Background info about people/projects | 5-7 |
+
+Weight guide:
+- **1-3**: Nice to know, can fade
+- **4-6**: Standard importance (default is 5)
+- **7-8**: Important, should surface often
+- **9-10**: Critical, always surface
+
+### 3. Execute Command
+
+```bash
+mem add <type> '{"content": "...", "weight": N}'
+```
+
+### 4. Confirm What Was Saved
+
+Tell the user:
+- What was saved
+- The ID (for reference)
+- The weight if non-default
+
+## Examples
+
+**User:** "Remember that I prefer TypeScript over Python for new projects"
+
+```bash
+mem add preference '{"content": "Prefers TypeScript over Python for new projects", "weight": 8}'
+```
+
+Response: "Saved preference with weight 8. ID: abc123"
+
+---
+
+**User:** "We decided to use Supabase for the database because of real-time features"
+
+```bash
+mem add decision '{"topic": "Database Choice", "content": "Using Supabase for database. Rationale: real-time features, built-in auth, and good DX.", "weight": 9}'
+```
+
+Response: "Saved decision about database choice with weight 9."
+
+---
+
+**User:** "Note that Jane prefers async communication"
+
+```bash
+mem add context '{"content": "Jane prefers async communication (Slack/email over calls)", "about": "Jane"}'
+```
+
+Response: "Noted context about Jane."
+
+---
+
+**User:** "This supersedes our earlier decision about X"
+
+```bash
+mem add decision '{"topic": "X", "content": "New approach..."}'
+# Then link to old decision
+mem link <new_id> supersedes <old_id>
+```
+
+## Auto-Remember Triggers
+
+Proactively save when you notice:
+- **Preferences**: "I like X", "I prefer Y", "Don't do Z"
+- **Decisions**: "Let's go with A", "We decided B"
+- **Context**: Background about people, companies, relationships
+- **Learnings**: "This worked because...", "Next time we should..."
+- **Corrections**: "Actually, it's X not Y"
+
+When auto-remembering, briefly note what you're saving:
+"I'll remember that you prefer TypeScript for new projects."
+
+## Other Useful Commands
+
+```bash
+# Update existing memory
+mem update <id> '{"content": "Updated content"}'
+
+# Archive when no longer relevant
+mem archive <id>
+
+# Change importance
+mem weight <id> 9
+
+# View a memory
+mem get <id>
+
+# List by type
+mem list decision
+```

package/skills/search/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: mem-search
+description: Search Mem memory
+triggers:
+  - "search memory"
+  - "what do I know about"
+  - "find in memory"
+  - "mem"
+  - "/search"
+---
+
+# Search Skill
+
+Search the Mem memory system using hybrid (semantic + keyword) search.
+
+## Quick Commands
+
+```bash
+# Basic search
+mem search "query"
+
+# Filter by type
+mem search "query" -t decision
+
+# More results
+mem search "query" -n 20
+
+# Combine options
+mem search "API design" -t decision -n 5
+```
+
+## How Search Works
+
+Mem uses **hybrid search** that combines:
+- **Semantic similarity** (70% weight): Finds conceptually related content
+- **Keyword matching** (30% weight): Finds exact term matches
+
+This means searching "database choice" will find memories about "Supabase selection" even if those exact words aren't used.
+
+## When to Search
+
+**Always search for:**
+- Names, companies, or projects you don't recognize
+- Past decisions about a topic before making new ones
+- Context before meetings or conversations
+- Background on technical approaches
+
+**Search patterns:**
+- "What did we decide about X?"
+- "What do I know about [person/company]?"
+- "Any notes on [topic]?"
+- "Previous decisions about [area]"
+
+## Examples
+
+**User:** "What did we decide about the database?"
+
+```bash
+mem search "database decision" -t decision
+```
+
+---
+
+**User:** "Who is Jane?"
+
+```bash
+mem search "Jane"
+```
+
+---
+
+**User:** "Any notes on MCP integration?"
+
+```bash
+mem search "MCP integration"
+```
+
+---
+
+**User:** "What are my preferences for code style?"
+
+```bash
+mem search "code style preference" -t preference
+```
+
+## Search Output
+
+Results show:
+- **Score**: Combined relevance (0-1, higher = more relevant)
+- **Type**: The memory type
+- **Content preview**: First 100 chars of content
+
+Example output:
+```
+[0.847] decision: Database Choice
+         Using Supabase for database. Rationale: real-time features...
+
+[0.634] note: Database evaluation notes
+         Compared PostgreSQL, MongoDB, and Supabase...
+
+2 results
+```
+
+## Access Tracking
+
+Search automatically increments the access count for returned results. This means:
+- Frequently accessed memories rise in relevance
+- Unused memories naturally fade over time
+
+If you don't want to affect relevance scores, the `search` function accepts `trackAccess: false` (available via TypeScript API).
+
+## Proactive Search
+
+When encountering unfamiliar references:
+
+1. **Search first** before saying "I don't have information"
+2. **Report findings** if results found
+3. **Note gaps** if no results
+
+Example:
+> "I searched for 'Acme Corp' and found: They're a potential customer Jane introduced. Last meeting was Jan 15."
+
+Or:
+> "I searched for 'Project Apollo' but found no matches in memory."
+
+## Related Commands
+
+```bash
+# Get full context for session startup
+mem context
+
+# Get a specific memory by ID
+mem get <id>
+
+# Get linked memories
+mem linked <id>
+```

package/skills/setup/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: mem-setup
+description: Set up Mem memory system with Supabase
+triggers:
+  - "set up mem"
+  - "initialize memory"
+  - "install mem"
+  - "/mem-setup"
+---
+
+# Mem Setup Skill
+
+Guide the user through setting up Mem with Supabase.
+
+## Prerequisites Check
+
+First, verify the user has what they need:
+
+```bash
+# Check Node.js version (need 18+)
+node --version
+
+# Check if mem is installed
+npm list mem-memory 2>/dev/null || echo "Not installed"
+```
+
+## Workflow
+
+### Step 1: Install Mem
+
+```bash
+npm install mem-memory
+```
+
+Or with a specific project:
+```bash
+cd your-project
+npm install mem-memory
+```
+
+### Step 2: Create Supabase Project
+
+If the user doesn't have a Supabase project:
+
+1. Go to [supabase.com](https://supabase.com) and sign in
+2. Click "New Project"
+3. Note the project URL and service role key
+
+### Step 3: Enable pgvector Extension
+
+In Supabase SQL Editor, run:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+```
+
+This enables semantic search capabilities.
+
+### Step 4: Configure Environment
+
+Create a `.env` file in the project root:
+
+```bash
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_SERVICE_KEY=your-service-role-key
+OPENAI_API_KEY=your-openai-key  # Optional, for semantic search
+```
+
+**Important:**
+- Use the **service role key**, not the anon key (for server-side operations)
+- The OpenAI key is optional but recommended for better search quality
+
+### Step 5: Apply Schema
+
+```bash
+npx mem migrate
+```
+
+This creates the `mem_records` and `mem_links` tables plus all the functions.
+
+If the migration fails (some Supabase configs don't allow exec_sql), it will save the SQL to `mem-migration.sql`. Run that SQL manually in the Supabase SQL Editor.
+
+### Step 6: Verify Setup
+
+```bash
+# Add a test memory
+npx mem add note '{"content": "Test memory for setup verification"}'
+
+# Search for it
+npx mem search "test"
+
+# Get context
+npx mem context
+```
+
+### Step 7: Add to CLAUDE.md (for Claude Code users)
+
+Add this snippet to your project's `CLAUDE.md`:
+
+```markdown
+## Memory System
+
+This project uses Mem for memory. Run context at session start:
+
+\`\`\`bash
+npx mem context
+\`\`\`
+
+### Quick Commands
+
+\`\`\`bash
+# Add memory
+npx mem add <type> '{"content": "..."}'
+
+# Search
+npx mem search "query"
+
+# Get context
+npx mem context
+
+# Set importance (1-10)
+npx mem weight <id> 9
+
+# Archive when done
+npx mem archive <id>
+\`\`\`
+
+### When to Remember
+
+Save to memory when:
+- User says "remember this", "note that", "save this"
+- A decision is made with rationale
+- A preference is expressed
+- Important context is shared
+- A lesson is learned
+```
+
+## Troubleshooting
+
+### "SUPABASE_URL must be set"
+
+Create a `.env` file with your Supabase credentials.
+
+### "pgvector extension not found"
+
+Run `CREATE EXTENSION IF NOT EXISTS vector;` in the Supabase SQL Editor.
+
+### "Failed to generate embedding"
+
+Check that `OPENAI_API_KEY` is set. Semantic search requires OpenAI embeddings.
+If you don't have an OpenAI key, search will fall back to keyword-only mode.
+
+### Migration fails
+
+Copy the SQL from `mem-migration.sql` and run it directly in Supabase SQL Editor.
+
+## Done!
+
+Once setup is complete, use the other Mem skills:
+- `/remember` - Add memories
+- `/search` - Search memories
+- `/context` - Get startup context