docs: expand scope and add comprehensive documentation
Create README.md and enhance AGENTS.md to position this as an extensible framework for any Opencode skills and agents, not just PARA/task management. Includes installation, development workflow, code style guidelines, and Nix flake integration patterns.
This commit is contained in:
m3tm3re
166
skill/mem0-memory/SKILL.md
Normal file
166
skill/mem0-memory/SKILL.md
Normal file
@@ -0,0 +1,166 @@
|
||||
---
|
||||
name: mem0-memory
|
||||
description: "Store and retrieve memories using Mem0 REST API. Use when: (1) storing information for future recall, (2) searching past conversations or facts, (3) managing user/agent memory contexts, (4) building conversational AI with persistent memory. Triggers on keywords like 'remember', 'recall', 'memory', 'store for later', 'what did I say about'."
|
||||
compatibility: opencode
|
||||
---
|
||||
|
||||
# Mem0 Memory
|
||||
|
||||
Store and retrieve memories via Mem0 REST API at `http://localhost:8000`.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Operation | Method | Endpoint |
|
||||
| ----------------- | ------ | --------------------- |
|
||||
| Store memory | POST | `/memories` |
|
||||
| Search memories | POST | `/search` |
|
||||
| Get all memories | GET | `/memories?user_id=X` |
|
||||
| Get single memory | GET | `/memories/{id}` |
|
||||
| Update memory | PUT | `/memories/{id}` |
|
||||
| Delete memory | DELETE | `/memories/{id}` |
|
||||
| Delete all | DELETE | `/memories?user_id=X` |
|
||||
|
||||
## Core Operations
|
||||
|
||||
### Store a Memory
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/memories \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"messages": [
|
||||
{"role": "user", "content": "I prefer dark mode in all apps"},
|
||||
{"role": "assistant", "content": "Noted, you prefer dark mode."}
|
||||
],
|
||||
"user_id": "user123"
|
||||
}'
|
||||
```
|
||||
|
||||
**Required**: `messages` array with `role` (user/assistant) and `content`.
|
||||
**Optional**: `user_id`, `agent_id`, `run_id`, `metadata` object.
|
||||
|
||||
### Search Memories
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/search \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"query": "What are my UI preferences?",
|
||||
"user_id": "user123"
|
||||
}'
|
||||
```
|
||||
|
||||
**Required**: `query` string.
|
||||
**Optional**: `user_id`, `agent_id`, `run_id`, `filters` object.
|
||||
|
||||
### Retrieve All Memories
|
||||
|
||||
```bash
|
||||
curl "http://localhost:8000/memories?user_id=user123"
|
||||
```
|
||||
|
||||
Filter by `user_id`, `agent_id`, or `run_id`.
|
||||
|
||||
### Get Single Memory
|
||||
|
||||
```bash
|
||||
curl http://localhost:8000/memories/{memory_id}
|
||||
```
|
||||
|
||||
### Update Memory
|
||||
|
||||
```bash
|
||||
curl -X PUT http://localhost:8000/memories/{memory_id} \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"content": "Updated preference: light mode"}'
|
||||
```
|
||||
|
||||
### Delete Memory
|
||||
|
||||
```bash
|
||||
curl -X DELETE http://localhost:8000/memories/{memory_id}
|
||||
```
|
||||
|
||||
### Delete All Memories
|
||||
|
||||
```bash
|
||||
curl -X DELETE "http://localhost:8000/memories?user_id=user123"
|
||||
```
|
||||
|
||||
## Identity Scopes
|
||||
|
||||
Mem0 supports three identity scopes for organizing memories:
|
||||
|
||||
| Scope | Use Case |
|
||||
| ---------- | ---------------------------------------- |
|
||||
| `user_id` | Per-user memories across sessions |
|
||||
| `agent_id` | Per-agent memories (shared across users) |
|
||||
| `run_id` | Per-session memories (temporary) |
|
||||
|
||||
Combine scopes for fine-grained control:
|
||||
|
||||
```json
|
||||
{
|
||||
"messages": [...],
|
||||
"user_id": "alice",
|
||||
"agent_id": "support-bot",
|
||||
"run_id": "session-456"
|
||||
}
|
||||
```
|
||||
|
||||
## Workflow Patterns
|
||||
|
||||
### Pattern 1: Remember User Preferences
|
||||
|
||||
User says "Remember I like X" -> Store with their user_id:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/memories \
|
||||
-d '{"messages":[{"role":"user","content":"Remember I like dark mode"}], "user_id":"USER_ID"}'
|
||||
```
|
||||
|
||||
### Pattern 2: Recall Past Context
|
||||
|
||||
User asks "What did I tell you about X?" -> Search:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/search \
|
||||
-d '{"query":"dark mode preferences", "user_id":"USER_ID"}'
|
||||
```
|
||||
|
||||
### Pattern 3: Session Memory
|
||||
|
||||
Store conversation context for current session only:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/memories \
|
||||
-d '{"messages":[...], "run_id":"SESSION_ID"}'
|
||||
```
|
||||
|
||||
## Response Format
|
||||
|
||||
Memory objects include:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "mem_abc123",
|
||||
"memory": "User prefers dark mode",
|
||||
"user_id": "user123",
|
||||
"created_at": "2025-12-31T12:00:00Z",
|
||||
"updated_at": "2025-12-31T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
Search returns array of matching memories with relevance scores.
|
||||
|
||||
## Health Check
|
||||
|
||||
Verify API is running:
|
||||
|
||||
```bash
|
||||
curl http://localhost:8000/health
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
See [references/api_reference.md](references/api_reference.md) for complete OpenAPI schema.
|
||||
202
skill/mem0-memory/references/api_reference.md
Normal file
202
skill/mem0-memory/references/api_reference.md
Normal file
@@ -0,0 +1,202 @@
|
||||
# Mem0 REST API Reference
|
||||
|
||||
Base URL: `http://localhost:8000`
|
||||
|
||||
## Endpoints
|
||||
|
||||
### Health Check
|
||||
```
|
||||
GET /health
|
||||
```
|
||||
Returns 200 if server is running.
|
||||
|
||||
---
|
||||
|
||||
### Create Memories
|
||||
```
|
||||
POST /memories
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Request Body (MemoryCreate)**:
|
||||
```json
|
||||
{
|
||||
"messages": [
|
||||
{"role": "string", "content": "string"}
|
||||
],
|
||||
"user_id": "string | null",
|
||||
"agent_id": "string | null",
|
||||
"run_id": "string | null",
|
||||
"metadata": {"key": "value"} | null
|
||||
}
|
||||
```
|
||||
|
||||
- `messages` (required): Array of Message objects
|
||||
- `role`: Role of message sender ("user" or "assistant")
|
||||
- `content`: Message content string
|
||||
- `user_id`: Optional user identifier
|
||||
- `agent_id`: Optional agent identifier
|
||||
- `run_id`: Optional session/run identifier
|
||||
- `metadata`: Optional key-value metadata
|
||||
|
||||
---
|
||||
|
||||
### Get All Memories
|
||||
```
|
||||
GET /memories
|
||||
```
|
||||
|
||||
**Query Parameters**:
|
||||
- `user_id` (string, optional): Filter by user
|
||||
- `agent_id` (string, optional): Filter by agent
|
||||
- `run_id` (string, optional): Filter by run/session
|
||||
|
||||
---
|
||||
|
||||
### Get Single Memory
|
||||
```
|
||||
GET /memories/{memory_id}
|
||||
```
|
||||
|
||||
**Path Parameters**:
|
||||
- `memory_id` (string, required): Memory ID
|
||||
|
||||
---
|
||||
|
||||
### Update Memory
|
||||
```
|
||||
PUT /memories/{memory_id}
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Path Parameters**:
|
||||
- `memory_id` (string, required): Memory ID
|
||||
|
||||
**Request Body**: Object with updated fields
|
||||
|
||||
---
|
||||
|
||||
### Delete Memory
|
||||
```
|
||||
DELETE /memories/{memory_id}
|
||||
```
|
||||
|
||||
**Path Parameters**:
|
||||
- `memory_id` (string, required): Memory ID
|
||||
|
||||
---
|
||||
|
||||
### Delete All Memories
|
||||
```
|
||||
DELETE /memories
|
||||
```
|
||||
|
||||
**Query Parameters**:
|
||||
- `user_id` (string, optional): Delete for specific user
|
||||
- `agent_id` (string, optional): Delete for specific agent
|
||||
- `run_id` (string, optional): Delete for specific run
|
||||
|
||||
---
|
||||
|
||||
### Search Memories
|
||||
```
|
||||
POST /search
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Request Body (SearchRequest)**:
|
||||
```json
|
||||
{
|
||||
"query": "string",
|
||||
"user_id": "string | null",
|
||||
"agent_id": "string | null",
|
||||
"run_id": "string | null",
|
||||
"filters": {"key": "value"} | null
|
||||
}
|
||||
```
|
||||
|
||||
- `query` (required): Search query string
|
||||
- `user_id`: Optional user filter
|
||||
- `agent_id`: Optional agent filter
|
||||
- `run_id`: Optional run filter
|
||||
- `filters`: Optional additional filters
|
||||
|
||||
---
|
||||
|
||||
### Get Memory History
|
||||
```
|
||||
GET /memories/{memory_id}/history
|
||||
```
|
||||
|
||||
**Path Parameters**:
|
||||
- `memory_id` (string, required): Memory ID
|
||||
|
||||
Returns version history for a memory.
|
||||
|
||||
---
|
||||
|
||||
### Configure Mem0
|
||||
```
|
||||
POST /configure
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Request Body**: Configuration object (varies by setup)
|
||||
|
||||
---
|
||||
|
||||
### Reset All Memories
|
||||
```
|
||||
POST /reset
|
||||
```
|
||||
|
||||
**Warning**: Completely resets all stored memories.
|
||||
|
||||
---
|
||||
|
||||
## Error Responses
|
||||
|
||||
**422 Validation Error**:
|
||||
```json
|
||||
{
|
||||
"detail": [
|
||||
{
|
||||
"loc": ["body", "field_name"],
|
||||
"msg": "error message",
|
||||
"type": "error_type"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Data Schemas
|
||||
|
||||
### Message
|
||||
```json
|
||||
{
|
||||
"role": "string",
|
||||
"content": "string"
|
||||
}
|
||||
```
|
||||
|
||||
### MemoryCreate
|
||||
```json
|
||||
{
|
||||
"messages": [Message],
|
||||
"user_id": "string | null",
|
||||
"agent_id": "string | null",
|
||||
"run_id": "string | null",
|
||||
"metadata": "object | null"
|
||||
}
|
||||
```
|
||||
|
||||
### SearchRequest
|
||||
```json
|
||||
{
|
||||
"query": "string",
|
||||
"user_id": "string | null",
|
||||
"agent_id": "string | null",
|
||||
"run_id": "string | null",
|
||||
"filters": "object | null"
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user