simplemem-skill — Claude Code skill: memory and setup
simplemem-skill keeps conversation context across sessions and retrieves it through semantic queries. Use it when an agent needs past decisions or imported chat history.
MIT 1 installs ★ 3,881 updated 2026-07-24
npx skills add aiming-lab/SimpleMem --skill simplemem-skill -a claude-codeWhat simplemem-skill does
simplemem-skill stores dialogue entries with a speaker, message content, and timestamp. An agent can preserve decisions and difficult-to-recreate context, then search those records before continuing earlier work. Queries can return an answer, use deeper reflection, or retrieve matching entries directly.
The skill runs through ~/.claude/skills/simplemem-skill/scripts/cli_persistent_memory.py. The CLI adds records, searches them, reports statistics, and can clear the store. JSONL chat histories can be imported, while separate contexts can use custom table names. Data goes to data/lancedb/. Setup requires the packages in requirements.txt and an OPENROUTER_API_KEY; without that key, the OpenRouter configuration cannot be completed.
What it helps with
- preserve decisions from a coding conversation
- retrieve details from earlier sessions
- resume work with stored project context
- import chat history from JSONL files
- separate memories by conversation table
Example prompts for the agent
- Remember that this project will use
PostgreSQLfor persistence. - What did we decide about the database migration in the previous session?
- Import the JSONL conversation history and save it to memory.
How to install simplemem-skill
1Skills CLI (Vercel)
npx skills add aiming-lab/SimpleMem --skill simplemem-skill -a claude-code2Manually: put the files in place
~/.claude/skills/simplemem-skill/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/simplemem-skill/
1Skills CLI (Vercel)
npx skills add aiming-lab/SimpleMem --skill simplemem-skill -a codex2Manually: put the files in place
.agents/skills/simplemem-skill/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add aiming-lab/SimpleMem --skill simplemem-skill -a cursor2Manually: put the files in place
.cursor/skills/simplemem-skill/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install aiming-lab/SimpleMem SKILL/simplemem-skill/SKILL.md2Manually: put the files in place
.github/skills/simplemem-skill/SKILL.md1Skills CLI (Vercel)
npx skills add aiming-lab/SimpleMem --skill simplemem-skill -a gemini-cli2Platform CLI
gemini skills install https://github.com/aiming-lab/SimpleMem --path SKILL/simplemem-skillManually: put the files in place
.devin/skills/simplemem-skill/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add aiming-lab/SimpleMem --skill simplemem-skill -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about simplemem-skill
How do I install simplemem-skill in Claude Code?
Run npx skills add aiming-lab/SimpleMem --skill simplemem-skill -a claude-code, then check ~/.claude/skills/simplemem-skill/SKILL.md.
What does simplemem-skill do?
It keeps dialogue records and project context between sessions, then finds relevant entries through semantic questions or direct retrieval.
What does the skill need before it can run?
Install the packages from requirements.txt, copy src/config.py.example to src/config.py, and set OPENROUTER_API_KEY. Memories are stored in data/lancedb/.
Source text
SKILL.md · MIT
--- 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).
© aiming-lab · MIT · aiming-lab/SimpleMem