simplemem-skill

Original source / Raw SKILL.md

---
name: simplemem-skill
description: Store and retrieve conversation memories across sessions. Use when asked to 'remember this', 'save conversation', 'add to memory', 'what did we discuss about...', 'query memories', or 'import chat history'. Also use proactively to preserve important dialogue context and decisions.
---

# SimpleMem Skill

Persistent conversational memory across sessions.

## Proactive Usage

Save memories when discovering valuable dialogue:
- Important decisions or commitments made in conversation
- Complex information that may be referenced later
- Context from long discussions worth preserving
- Solutions to problems that took effort to uncover

Check memories before:
- Answering questions about past conversations
- Resuming work from previous sessions
- Building on earlier discussion topics

## Quick Start

```bash
# Add a dialogue
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py add --speaker "Alice" --content "Meet Bob tomorrow at 2pm"

# Query memories
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py query --question "When should Alice meet Bob?"
```

## Operations

### Save

Add single dialogue:

```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py add --speaker "User" --content "Your message here"
```

With timestamp (ISO 8601):

```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py add --speaker "Alice" --content "Message" --timestamp "2026-01-17T14:00:00Z"
```

### Query

Semantic query with answer:

```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py query --question "What did Alice say about meetings?"
```

With reflection for deeper analysis:

```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py query --question "Your question" --enable-reflection
```

Raw retrieval:

```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py retrieve --query "Alice meetings" --top-k 5
```

### Maintain

View statistics:

```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py stats
```

Clear all memories:

```bash
# Use with caution - irreversible
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py clear --yes
```

## Batch Import

For importing conversation histories from JSONL files, see [references/import-guide.md](references/import-guide.md).

## Custom Table Names

Use different tables to organize conversation contexts:

```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py --table-name my_custom_table add --speaker "User" --content "Message"
```

## Data Format

All dialogues are stored with:
- `speaker`: Who said it (string)
- `content`: What was said (string)
- `timestamp`: When it was said (ISO 8601 datetime, auto-generated if omitted)

## Advanced Usage

For detailed information:
- **OpenRouter setup and model selection**: [references/openrouter-guide.md](references/openrouter-guide.md)
- **JSONL import format and batch operations**: [references/import-guide.md](references/import-guide.md)
- **CLI command reference**: [references/cli-reference.md](references/cli-reference.md)
- **System architecture and configuration**: [references/architecture.md](references/architecture.md)

## Setup

**Install dependencies**:

```bash
cd ~/.claude/skills/simplemem-skill
pip install -r requirements.txt
```

**Configure OpenRouter API**:

```bash
cp src/config.py.example src/config.py
# Edit src/config.py and set your OPENROUTER_API_KEY
```

See [references/openrouter-guide.md](references/openrouter-guide.md) for API key setup and model customization.

**Data storage**: Memories persist in `data/lancedb/` (auto-created).


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/import-guide.md

```markdown
# Batch Import Guide

## JSONL Format

Each line is a JSON object with the following fields:

- `speaker`: (required) String identifying who spoke
- `content`: (required) String containing what was said
- `timestamp`: (optional) ISO 8601 datetime string (defaults to current time if omitted)

## Example JSONL File

Create a file named `dialogues.jsonl`:

```jsonl
{"speaker": "Alice", "content": "Let's meet tomorrow at 2pm", "timestamp": "2026-01-16T14:00:00Z"}
{"speaker": "Bob", "content": "Sounds good, I'll be there"}
{"speaker": "Alice", "content": "Don't forget to bring the documents"}
```

## Import Command

```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py add_batch --file dialogues.jsonl
```

With custom table:

```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py --table-name project_conversations add_batch --file dialogues.jsonl
```

## Notes

- If `timestamp` is omitted, the current system time is used
- Lines with parsing errors are skipped and reported
- All successfully parsed entries are added in a single batch operation
- The file path can be absolute or relative to the current working directory
```

### references/openrouter-guide.md

```markdown
# OpenRouter Integration - Quick Reference

## Why OpenRouter?

SimpleMem uses **OpenRouter** as a unified API gateway for all LLM and embedding operations:

✅ **Single API Key**: One key for all models  
✅ **Cost Tracking**: Built-in dashboard to monitor usage and costs  
✅ **Model Flexibility**: Easy to switch between providers and models  
✅ **Simpler Setup**: No need to manage multiple API keys  

## Getting Started

### 1. Get Your API Key

Visit [openrouter.ai/keys](https://openrouter.ai/keys) and create an account. Your API key will start with `sk-or-`.

### 2. Configure the Skill

```bash
cd SKILL/simplemem-skill
cp src/config.py.example src/config.py
```

Edit `src/config.py`:

```python
OPENROUTER_API_KEY = "sk-or-your-actual-key-here"
```

### 3. Choose Your Models

Edit `src/config.py` to select models:

```python
# LLM Model (for chat/reasoning)
LLM_MODEL = "openai/gpt-4.1-mini"

# Embedding Model (for vector search)
EMBEDDING_MODEL = "qwen/qwen3-embedding-8b"

# Embedding dimension (must match the embedding model)
EMBEDDING_DIMENSION = 4096
```

**Important**: The `EMBEDDING_DIMENSION` must match your chosen embedding model. Check the model documentation on [openrouter.ai/models](https://openrouter.ai/models).

## Cost Management

Track your usage on the [OpenRouter dashboard](https://openrouter.ai/activity).

## Troubleshooting

**"Invalid key format" error**:
- Make sure your key starts with `sk-or-`
- Get a new key from [openrouter.ai/keys](https://openrouter.ai/keys)

**"Model not found" error**:
- Check the model name at [openrouter.ai/models](https://openrouter.ai/models)
- Ensure you're using the full path (e.g., `openai/gpt-4.1-mini`, not just `gpt-4.1-mini`)

**Embedding dimension mismatch error**:
```
RuntimeError: lance error: LanceError(Arrow): Arrow error: C Data interface error: 
Invalid: ListType can only be casted to FixedSizeListType if the lists are all 
the expected size.
```
- This means `EMBEDDING_DIMENSION` doesn't match your embedding model
- Check your model's actual dimension on OpenRouter and update `EMBEDDING_DIMENSION`
- If you change the embedding dimension, clear the old database: `rm -rf data/lancedb/*`

**"Connection error" or timeout**:
- Check your internet connection
- OpenRouter may be experiencing downtime
- Try again after a few minutes

```

### references/cli-reference.md

```markdown
# CLI Command Reference

## Global Options

- `--table-name TABLE_NAME`: Use a custom table name instead of the default `memory_entries`

## Commands

### add

Add a single dialogue entry.

```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py add --speaker SPEAKER --content CONTENT [--timestamp TIMESTAMP]
```

**Arguments:**
- `--speaker`: (required) Who said it
- `--content`: (required) What was said
- `--timestamp`: (optional) ISO 8601 datetime string (e.g., "2026-01-17T14:30:00Z")

**Example:**
```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py add --speaker "Alice" --content "Project deadline is Friday"
```

### import

Import multiple dialogues from a JSONL file.

```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py import --file FILE_PATH
```

**Arguments:**
- `--file`: (required) Path to JSONL file containing dialogue entries

**Example:**
```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py import --file conversations.jsonl
```

### query

Query the memory system and generate an answer.

```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py query --question QUESTION [--enable-reflection] [--top-k K]
```

**Arguments:**
- `--question`: (required) Natural language question to ask
- `--enable-reflection`: (optional) Enable multi-step reflection for deeper analysis
- `--top-k`: (optional) Number of relevant entries to retrieve (default: 5)

**Examples:**
```bash
# Simple query
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py query --question "What did Alice say about the deadline?"

# With reflection enabled
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py query --question "Summarize all project updates" --enable-reflection
```

### retrieve

Retrieve raw dialogue entries matching a query.

```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py retrieve --query QUERY [--top-k K]
```

**Arguments:**
- `--query`: (required) Search query string
- `--top-k`: (optional) Number of results to return (default: 5)

**Example:**
```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py retrieve --query "deadline meeting" --top-k 10
```

### stats

Display memory store statistics (total entries, table name, database path).

```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py stats
```

### clear

Delete all entries from the memory store.

```bash
python ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py clear --yes
```

**Arguments:**
- `--yes`: (required) Confirmation flag to prevent accidental deletion

**Warning:** This operation is irreversible. All memory entries will be permanently deleted.
```

### references/architecture.md

```markdown
# SimpleMem Architecture

## Overview

SimpleMem is a persistent conversational memory system that stores dialogues in a vector database (LanceDB) for semantic retrieval and question answering. It uses **OpenRouter** as a unified API gateway for both LLM and embedding services.

## Components

### API Layer - OpenRouter

- **Unified Gateway**: All LLM and embedding calls go through OpenRouter API
- **Multi-Provider**: Access models from Anthropic, OpenAI, Google, Qwen, and more
- **Single API Key**: One API key for all services
- **Cost Tracking**: Built-in usage tracking and budgeting

### Storage Layer

- **Vector Database**: LanceDB for efficient similarity search
- **Table Structure**: Each dialogue entry contains:
  - `speaker`: String
  - `content`: String
  - `timestamp`: Datetime
  - `embedding`: Vector representation of the content

### Retrieval Layer

- **Hybrid Retriever**: Combines semantic (vector) and keyword (BM25) search
- **Configurable top-k**: Control how many relevant entries to retrieve

### Generation Layer

- **Answer Generator**: Uses retrieved context to generate natural language answers
- **Reflection Mode**: Optional multi-step reasoning for complex queries

## Data Storage

By default, the system stores data in:
- Database path: `SKILL/simplemem-skill/data/lancedb/`
- Default table: `memory_entries`

## Configuration

The system requires an OpenRouter API key:
- **Get key**: [openrouter.ai/keys](https://openrouter.ai/keys)
- **Key format**: Starts with `sk-or-`
- **Models**: Configure LLM and embedding models in `config.py`

### Recommended Models

**LLM Models (via OpenRouter)**:
- `anthropic/claude-3.5-sonnet` - Powerful reasoning (recommended)
- `anthropic/claude-3-haiku` - Fast and economical
- `openai/gpt-4o-mini` - Fast OpenAI
- `qwen/qwen-2.5-72b-instruct` - Free, good quality

**Embedding Models (via OpenRouter)**:
- `openai/text-embedding-3-small` - Economical (1536 dims)
- `openai/text-embedding-3-large` - Best quality (3072 dims)

## Workflow

1. **Input**: Dialogue entry (speaker, content, timestamp)
2. **Embedding**: Content is converted to a vector via OpenRouter
3. **Storage**: Entry and embedding are stored in LanceDB
4. **Retrieval**: Queries are embedded and used to find similar entries
5. **Generation**: Retrieved entries provide context for answer generation via OpenRouter

## Performance Considerations

- **API Costs**: Both embedding and LLM calls cost credits (track on OpenRouter dashboard)
- **Vector Search**: Efficient even with large numbers of entries
- **Batch Operations**: More efficient than individual additions
- **Response Time**: Depends on top-k, reflection settings, and model choice
```