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.

skill/mem0-memory/SKILL.md

@@ -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.