m3tam3re/AGENTS
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(memory): update skills for opencode-memory plugin, deprecate mem0

Browse Source
This commit is contained in:
m3tm3re
2026-02-14 08:22:59 +01:00
parent 1719f70452
commit c64d71f438
12 changed files with 2857 additions and 191 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
skills/mem0-memory/SKILL.md
View File

@@ -1,10 +1,16 @@
---
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'."
description: "DEPRECATED: Replaced by opencode-memory plugin. See skills/memory/SKILL.md for current memory system."
compatibility: opencode
---
# Mem0 Memory
> ⚠️ **DEPRECATED**
>
> This skill is deprecated. The memory system has been replaced by the opencode-memory plugin.
>
> **See:** `skills/memory/SKILL.md` for the current memory system.
# Mem0 Memory (Legacy)
Store and retrieve memories via Mem0 REST API at `http://localhost:8000`.

214
skills/memory/SKILL.md
View File

@@ -1,201 +1,75 @@
---
name: memory
description: "Dual-layer memory system (Mem0 + Obsidian CODEX). Use when: (1) storing information for future recall ('remember this'), (2) auto-capturing session insights, (3) recalling past decisions/preferences/facts, (4) injecting relevant context before tasks. Triggers: 'remember', 'recall', 'what do I know about', 'memory', session end."
description: "Persistent memory system for Opencode agents. SQLite-based hybrid search over Obsidian vault. Use when: (1) storing user preferences/decisions, (2) recalling past context, (3) searching knowledge base. Triggers: remember, recall, memory, store, preference."
compatibility: opencode
---
# Memory
Dual-layer memory system for persistent AI agent context. Memories are stored in BOTH Mem0 (semantic search) AND Obsidian CODEX vault (human-readable, versioned).
## Overview
**Architecture:**
- **Mem0 Layer** (`localhost:8000`): Fast semantic search, operational memory
- **Obsidian Layer** (`~/CODEX/80-memory/`): Human-readable notes, version controlled, wiki-linked
opencode-memory is a SQLite-based hybrid memory system for Opencode agents. It indexes markdown files from your Obsidian vault (`~/CODEX/80-memory/`) and session transcripts, providing fast hybrid search (vector + keyword BM25).
**Cross-Reference:**
- `mem0_id` in Obsidian frontmatter links to Mem0
- `obsidian_ref` in Mem0 metadata links to vault file
## Architecture
## Prerequisites
- **Source of truth**: Markdown files at `~/CODEX/80-memory/`
- **Derived index**: SQLite at `~/.local/share/opencode-memory/index.db`
- **Hybrid search**: FTS5 (BM25) + vec0 (vector similarity)
- **Embeddings**: OpenAI text-embedding-3-small (1536 dimensions)
1. **Mem0 running** at `http://localhost:8000` - Verify with `curl http://localhost:8000/health`
2. **Obsidian MCP configured** - See [references/mcp-config.md](references/mcp-config.md)
3. **Vault structure** - `80-memory/` folder with category subfolders
## Available Tools
## Memory Categories
| Category | Definition | Examples |
|----------|------------|----------|
| `preference` | Personal preferences (UI, workflow, communication style) | Dark mode, async communication, detailed responses |
| `fact` | Objective information about user/work (role, tech stack, constraints) | Job title, preferred languages, system architecture |
| `decision` | Architectural/tool choices made (with rationale) | Using React over Vue, PostgreSQL over MySQL |
| `entity` | People, organizations, systems, concepts | Key contacts, important APIs, domain concepts |
| `other` | Everything else | General learnings, context notes |
## Workflow 1: Store Memory (Explicit)
When user says "remember this" or "store this":
### Steps
1. **Classify category** - Determine which of the 5 categories applies
2. **Store in Mem0** - POST to `/memories`:
```bash
curl -X POST http://localhost:8000/memories \
-H "Content-Type: application/json" \
-d '{
"messages": [{"role": "user", "content": "[memory content]"}],
"user_id": "m3tam3re",
"metadata": {
"category": "preference",
"source": "explicit"
}
}'
```
3. **Create Obsidian note** - Use memory template in `80-memory/<category>/`:
- Set `mem0_id` from Mem0 response
- Set `source: explicit`
4. **Update Mem0 with Obsidian ref** - Add `obsidian_ref` to metadata
### Example
### memory_search
Hybrid search over all indexed content (vault + sessions).
```
User: "Remember that I prefer detailed explanations with code examples"
Agent:
1. Category: preference
2. Mem0: Store with category=preference, source=explicit
3. Obsidian: Create 80-memory/preferences/prefers-detailed-explanations.md
4. Cross-reference IDs
memory_search(query, maxResults?, source?)
```
## Workflow 2: Recall Memory
- `query`: Search query (natural language)
- `maxResults`: Max results (default 6)
- `source`: Filter by "memory", "sessions", or "all"
When user asks "what do I know about X":
### Steps
1. **Search Mem0** - POST to `/search`:
```bash
curl -X POST http://localhost:8000/search \
-H "Content-Type: application/json" \
-d '{
"query": "[search query]",
"user_id": "m3tam3re"
}'
```
2. **Return results** - Include Obsidian note paths from `obsidian_ref` metadata
3. **Optionally read full note** - Use Obsidian REST API for complete context
### Example
### memory_store
Store new memory as markdown file in vault.
```
User: "What do you know about my UI preferences?"
Agent:
1. Search Mem0 for "UI preferences"
2. Return: "You prefer dark mode (80-memory/preferences/prefers-dark-mode.md)"
memory_store(content, title?, category?)
```
## Workflow 3: Auto-Capture (Session End)
- `content`: Memory content to store
- `title`: Optional title (slugified for filename)
- `category`: "preferences", "facts", "decisions", "entities", "other"
Automatically extract and store valuable memories at session end.
### memory_get
Read specific file/lines from vault.
### Process
1. **Scan conversation** for memory-worthy content:
- Preferences stated
- Decisions made
- Important facts revealed
- Entities mentioned
2. **Select top 3** highest-value memories
3. **For each**: Store in Mem0 AND create Obsidian note (source: "auto-capture")
4. **Present to user**: "I captured these memories: [list]. Confirm or reject?"
### Memory-Worthy Signals
- "I prefer..." / "I like..." / "I hate..." → preference
- "We decided to use..." / "Chose X because..." → decision
- "My role is..." / "We use..." / "The system is..." → fact
- Names, companies, tools mentioned repeatedly → entity
## Workflow 4: Auto-Recall (Session Start)
Inject relevant memories before starting work.
### Process
1. **On session start**, search Mem0 with user's first message/topic
2. **If relevant memories found** (score > 0.7), inject as context:
```markdown
<relevant-memories>
- [preference] User prefers dark mode in all apps
- [fact] User's tech stack: TypeScript, React, Node.js
</relevant-memories>
```
3. **Limit to top 5** most relevant memories
## Error Handling
### Mem0 Unavailable
```bash
# Check health first
curl http://localhost:8000/health
# If fails: Skip all memory operations, warn user
```
memory_get(filePath, startLine?, endLine?)
```
Response: "Mem0 is not running. Memory features unavailable. Start with: [instructions]"
## Auto-Behaviors
### Obsidian Unavailable
- **Auto-recall**: On session.created, relevant memories are searched and injected
- **Auto-capture**: On session.idle, preferences/decisions are extracted and stored
- **Token budget**: Max 2000 tokens injected to respect context limits
- Store in Mem0 only
- Log that Obsidian sync failed
- Continue with degraded functionality
## Workflows
### Both Unavailable
### Recall information
Before answering about past work, preferences, or decisions:
1. Call `memory_search` with relevant query
2. Use `memory_get` to retrieve full context if needed
- Skip memory entirely
- Continue without memory features
- Warn user: "Memory system unavailable"
### Store new information
When user expresses preference or decision:
1. Call `memory_store` with content and category
## Integration
## Vault Structure
### How Other Skills Use Memory
```bash
# Load memory skill to access workflows
# Use mem0-memory skill for direct Mem0 API calls
# Use obsidian skill for direct vault operations
```
### Apollo Agent
Apollo is the primary memory specialist. When complex memory operations needed, delegate to Apollo with memory skill loaded.
### Skill Handoff
| From Skill | Handoff Pattern |
|------------|----------------|
| Any skill | Load `memory` skill, call store/recall workflows |
| mem0-memory | Direct Mem0 API, optionally sync to Obsidian |
| obsidian | Direct vault operations, use memory template |
## Quick Reference
| Operation | Mem0 API | Obsidian Path |
|-----------|----------|---------------|
| Store | POST /memories | 80-memory/<category>/*.md |
| Search | POST /search | Search 80-memory/ |
| Get | GET /memories/{id} | Read note by path |
| Update | PUT /memories/{id} | Update note |
| Health | GET /health | Check REST API |
## See Also
- [references/mcp-config.md](references/mcp-config.md) - Obsidian MCP server configuration
- `~/p/AI/AGENTS/skills/mem0-memory/SKILL.md` - Mem0 REST API details
- `~/p/AI/AGENTS/skills/obsidian/SKILL.md` - Obsidian vault operations
- `~/CODEX/AGENTS.md` - Vault conventions and memory folder docs
~/CODEX/80-memory/
├── preferences/ # User preferences
├── facts/ # Factual knowledge
├── decisions/ # Design decisions
├── entities/ # People, projects, concepts
└── other/ # Uncategorized memories
```

54
skills/memory/references/deployment.md Normal file
View File

@@ -0,0 +1,54 @@
# opencode-memory Deployment Guide
## Installation
### Option 1: Nix (Recommended)
Add to your Nix flake:
```nix
inputs.opencode-memory = {
url = "git+https://code.m3ta.dev/m3tam3re/opencode-memory";
flake = false;
};
```
### Option 2: npm
```bash
npm install -g @m3tam3re/opencode-memory
```
## Configuration
Add to `~/.config/opencode/opencode.json`:
```json
{
"plugins": [
"opencode-memory"
]
}
```
## Environment Variables
- `OPENAI_API_KEY`: Required for embeddings
## Vault Location
Default: `~/CODEX/80-memory/`
Override in plugin config if needed.
## Rebuild Index
```bash
bun run src/cli.ts --rebuild
```
## Verification
1. Start Opencode
2. Call `memory_search` with any query
3. Verify no errors in logs