@memclaw/memclaw 0.9.17 → 0.9.18

package/skills/memclaw/references/best-practices.md

@@ -1,319 +1,242 @@
 # MemClaw Best Practices
 
-This guide provides proven strategies and decision frameworks for using MemClaw effectively in OpenClaw.
+## Token Optimization Strategy
 
-## Tool Selection Decision Tree
+### The Layer Selection Decision Tree
 
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                    What do you need to do?                      │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-        ┌─────────────────────┼─────────────────────┐
-        ▼                     ▼                     ▼
-   Find Info            Save Info             Manage Sessions
-        │                     │                     │
-        ▼                     ▼                     ▼
-┌───────────────┐    ┌───────────────┐    ┌───────────────┐
-│ Need context? │    │   What kind?  │    │    What?      │
-└───────────────┘    └───────────────┘    └───────────────┘
-        │                     │                     │
-   ┌────┴────┐           ┌────┴────┐          ┌────┴────┐
-   ▼         ▼           ▼         ▼          ▼         ▼
- Quick    Full        Facts    Conversation  List    Close &
- Search   Context               History     Sessions  Extract
-   │         │           │         │           │         │
-   ▼         ▼           ▼         ▼           ▼         ▼
-cortex_   cortex_   cortex_   cortex_     cortex_   cortex_
-search    recall    add_      add_        list_     close_
-                    memory    memory      sessions  session
+Start → What do you need?
+           │
+           ├── Quick relevance check?
+           │   └── Use L0 (cortex_get_abstract or cortex_search with return_layers=["L0"])
+           │
+           ├── Understanding gist or context?
+           │   └── Use L1 (cortex_get_overview or return_layers=["L0","L1"])
+           │
+           └── Exact details, quotes, or full implementation?
+               └── Use L2 (cortex_get_content or return_layers=["L0","L1","L2"])
 ```
 
-### Quick Reference
+### Token Budget Guidelines
 
-| Scenario | Tool | Why |
-|----------|------|-----|
-| Quick lookup, need summary only | `cortex_search` | Fast, returns snippets |
-| Need full context/details | `cortex_recall` | Returns content + snippet |
-| User stated preference/decision | `cortex_add_memory` | Explicit persistence |
-| Important conversation content | Let it accumulate | Auto-stored in session |
-| Task/topic completed | `cortex_close_session` | Trigger extraction |
-| Check if memories exist | `cortex_list_sessions` | Verify before search |
+| Layer | Tokens | Use Case |
+|-------|--------|----------|
+| L0 | ~100 | Filtering, quick preview, relevance check |
+| L1 | ~2000 | Understanding context, moderate detail |
+| L2 | Full | Exact quotes, complete code, full conversation |
 
-## Session Lifecycle Management
+**Recommended Pattern:**
+1. Start with L0 to filter candidates
+2. Use L1 for promising matches
+3. Use L2 only when absolutely necessary
 
-### The Golden Rule
+### Example: Efficient Search Flow
 
-> **OpenClaw does NOT automatically trigger memory extraction.** You must proactively call `cortex_close_session` at natural checkpoints.
+```typescript
+// Step 1: Quick search with L0 only
+const results = cortex_search({
+  query: "database schema design",
+  return_layers: ["L0"],
+  limit: 10
+});
 
-### When to Close a Session
+// Step 2: Identify top 2-3 relevant URIs
+const topUris = results.results
+  .filter(r => r.score > 0.7)
+  .slice(0, 3)
+  .map(r => r.uri);
 
-```
-┌────────────────────────────────────────────────────────────────┐
-│                    Timing Decision Flow                        │
-└────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-                    ┌─────────────────┐
-                    │ Task completed? │
-                    └─────────────────┘
-                         │      │
-                        Yes     No
-                         │      │
-                         ▼      ▼
-                  ┌──────────┐  ┌─────────────────┐
-                  │ CLOSE IT │  │ Topic shifted?  │
-                  └──────────┘  └─────────────────┘
-                                     │      │
-                                    Yes     No
-                                     │      │
-                                     ▼      ▼
-                              ┌──────────┐  ┌─────────────────┐
-                              │ CLOSE IT │  │ 10+ exchanges?  │
-                              └──────────┘  └─────────────────┘
-                                                 │      │
-                                                Yes     No
-                                                 │      │
-                                                 ▼      ▼
-                                          ┌──────────┐  ┌────────┐
-                                          │ CLOSE IT │  │ WAIT   │
-                                          └──────────┘  └────────┘
-```
-
-### Rhythm Guidelines
-
-| Conversation Type | Close Frequency | Reason |
-|-------------------|-----------------|--------|
-| Quick Q&A | End of conversation | Minimal content to extract |
-| Task-oriented | After each task completion | Captures task-specific memories |
-| Long discussion | Every 10-20 exchanges | Prevents memory loss |
-| Exploratory chat | When topic shifts | Organizes memories by topic |
-
-### Anti-Patterns to Avoid
-
-| ❌ Don't Do This | ✅ Do This Instead |
-|-------------------|-------------------|
-| Call `close_session` after every message | Call at natural checkpoints |
-| Wait until conversation ends (user may forget) | Proactively close during conversation |
-| Close without accumulating content | Let 5-10 exchanges happen first |
-| Never close sessions | Establish a rhythm |
-
-## Memory Storage Strategy
-
-### What to Explicitly Store
-
-Use `cortex_add_memory` for:
-
-1. **Explicit User Preferences**
-   ```
-   "User prefers dark theme in all editors"
-   "User wants commit messages in conventional format"
-   ```
-
-2. **Important Decisions**
-   ```
-   "Decided to use PostgreSQL instead of MySQL for this project"
-   "User chose React over Vue for the frontend"
-   ```
-
-3. **Key Information That May Be Lost**
-   ```
-   "User's timezone is UTC+8"
-   "Project deadline: March 30, 2026"
-   ```
-
-### What to Let Accumulate
-
-Don't use `cortex_add_memory` for:
-
-- Regular conversation content (auto-stored in session)
-- Contextual information (captured on close_session)
-- Temporary preferences (not worth persisting)
+// Step 3: Get L1 overview for top candidates
+for (const uri of topUris) {
+  const overview = cortex_get_overview({ uri });
+  // Process overview...
+}
 
-### Role Parameter Usage
-
-| Role | When to Use |
-|------|-------------|
-| `user` | User's statements, preferences, questions (default) |
-| `assistant` | Your responses, explanations, code you wrote |
-| `system` | Important context, rules, constraints |
-
-## Search Strategies
-
-### Query Formulation
-
-```
-┌────────────────────────────────────────────────────────────────┐
-│                    Query Formulation Tips                      │
-└────────────────────────────────────────────────────────────────┘
-
-BAD:  "it"                          — Too vague
-GOOD: "database choice"             — Specific topic
-
-BAD:  "the user said something"     — Unfocused
-GOOD: "user preference for testing" — Clear intent
-
-BAD:  "code"                        — Too broad
-GOOD: "authentication implementation" — Specific domain
+// Step 4: If needed, get L2 for the most relevant
+const fullContent = cortex_get_content({ uri: mostRelevantUri });
 ```
 
-### Score Threshold Guidelines
-
-| Score | Use Case |
-|-------|----------|
-| 0.8+ | Need high-confidence matches only |
-| 0.6 (default) | Balanced precision/recall |
-| 0.4-0.5 | Exploratory search, finding related items |
-| <0.4 | Usually too noisy, not recommended |
+## Tool Selection Patterns
 
-### Scope Parameter Usage
+### Pattern 1: Discovery (Don't know where information is)
 
 ```
-# Search across all sessions (default)
-{ "query": "database decisions" }
-
-# Search within specific session
-{ "query": "preferences", "scope": "project-alpha" }
+cortex_search(query="...", return_layers=["L0"])
+    ↓
+Identify relevant URIs
+    ↓
+cortex_get_overview(uri="...") for more context
+    ↓
+cortex_get_content(uri="...") if needed
 ```
 
-Use `scope` when:
-- You know the relevant session ID
-- Working within a specific project context
-- Want to limit noise from other sessions
-
-## Common Pitfalls
-
-### 1. Memory Not Found After Close
-
-**Symptom:** You closed a session but search returns nothing.
-
-**Cause:** Memory extraction is asynchronous and may take 30-60 seconds.
+### Pattern 2: Browsing (Know the structure)
 
-**Solution:** Wait briefly after close_session before searching, or:
 ```
-1. Close session
-2. Continue with other work
-3. Memory will be indexed automatically
+cortex_ls(uri="cortex://session")
+    ↓
+cortex_ls(uri="cortex://session/{id}", include_abstracts=true)
+    ↓
+cortex_get_abstract(uri="...") for quick check
+    ↓
+cortex_get_content(uri="...") for details
 ```
 
-### 2. Duplicate Memories
+### Pattern 3: Guided Exploration
 
-**Symptom:** Same information appears multiple times.
-
-**Cause:** Both explicit `add_memory` and `close_session` extraction captured the same content.
-
-**Solution:** Use `add_memory` only for information that:
-- Won't naturally be captured in conversation
-- Needs explicit emphasis
-- Is a correction or override of previous information
-
-### 3. Irrelevant Search Results
-
-**Symptom:** Search returns unrelated content.
-
-**Cause:** Query too vague or score threshold too low.
-
-**Solution:**
-- Make queries more specific
-- Increase `min_score` threshold
-- Use `scope` to limit search range
-
-### 4. Lost Session Content
-
-**Symptom:** Important conversation not in memory.
-
-**Cause:** Session was never closed.
-
-**Solution:** Establish a habit of closing sessions at checkpoints. If you realize too late, the raw messages may still exist in the session - close it now.
-
-### 5. Configuration Issues
-
-**Symptom:** Tools return errors about service/API.
-
-**Cause:** LLM/Embedding credentials not configured.
-
-**Solution:** See SKILL.md → Troubleshooting section.
-
-## Workflow Examples
-
-### Example 1: New Project Discussion
-
-```
-1. User starts discussing a new project
-   → Just listen and respond naturally
-
-2. User makes architecture decisions
-   → Optionally: cortex_add_memory for explicit decisions
-
-3. Discussion shifts to another topic
-   → cortex_close_session (captures project discussion memories)
-
-4. Continue with new topic
-   → Fresh start, memories from step 3 are now searchable
 ```
-
-### Example 2: Finding Previous Context
-
+cortex_explore(query="...", start_uri="...", return_layers=["L0"])
+    ↓
+Review exploration_path for relevance scores
+    ↓
+Use matches with higher return_layers if needed
 ```
-1. User asks: "What did we decide about auth?"
 
-2. cortex_search({ query: "authentication decision" })
+## Session Management Best Practices
 
-3. If results show snippets but need details:
-   cortex_recall({ query: "authentication implementation details" })
+### When to Close Sessions
 
-4. Summarize findings to user
-```
+**DO close sessions:**
+- ✅ After completing a significant task or topic
+- ✅ After user shares important preferences/decisions
+- ✅ When conversation topic shifts significantly
+- ✅ Every 10-20 exchanges during long conversations
 
-### Example 3: User States Preference
+**DON'T close sessions:**
+- ❌ After every message (too frequent)
+- ❌ Only at the very end (user might forget)
 
-```
-1. User: "I always want TypeScript strict mode"
+### Memory Metadata
 
-2. cortex_add_memory({
-     content: "User requires TypeScript strict mode in all projects",
-     role: "user"
-   })
+Use metadata to enrich stored memories:
 
-3. Acknowledge and remember for future
+```typescript
+cortex_add_memory({
+  content: "User prefers functional programming style over OOP",
+  role: "assistant",
+  metadata: {
+    tags: ["preference", "programming-style"],
+    importance: "high",
+    category: "technical-preference"
+  }
+})
 ```
 
-## Memory Architecture Reference
+**Recommended metadata fields:**
+- `tags`: Array of searchable tags
+- `importance`: "high", "medium", "low"
+- `category`: Custom categorization
+- `source`: Where the information came from
 
-### L0/L1/L2 Tier System
+## Common Workflows
 
-| Tier | Content | Size | Purpose | Search Role |
-|------|---------|------|---------|-------------|
-| L0 | Abstract summary | ~100 tokens | Quick filtering | First pass |
-| L1 | Key points + context | ~2000 tokens | Context refinement | Second pass |
-| L2 | Full original content | Complete | Exact matching | Final retrieval |
+### Finding User Preferences
 
-### How Search Works Internally
+```typescript
+// 1. Search for preference-related content
+const results = cortex_search({
+  query: "user preferences settings configuration",
+  return_layers: ["L0"],
+  limit: 10
+});
 
+// 2. Get overviews for relevant results
+for (const result of results.results.slice(0, 3)) {
+  if (result.snippet.includes("preference")) {
+    const overview = cortex_get_overview({ uri: result.uri });
+    // Extract preferences from overview
+  }
+}
 ```
-Query → L0 Filter → L1 Refine → L2 Retrieve → Ranked Results
-          │             │             │
-          ▼             ▼             ▼
-      Quick scan    Contextual    Full content
-      by summary    refinement    for precision
-```
-
-### Automatic Processes
 
-| Process | Trigger | Duration |
-|---------|---------|----------|
-| Vector embedding | On `add_memory` | Seconds |
-| L0/L1 generation | On `add_memory` (async) | Seconds |
-| Full extraction | On `close_session` | 30-60s |
-| Maintenance | Every 3 hours (auto) | Minutes |
+### Error Context Retrieval
 
-## Summary Checklist
+```typescript
+// Search for error-related content
+const results = cortex_search({
+  query: "TypeError: Cannot read property",
+  return_layers: ["L0"]
+});
 
-Before ending a conversation or topic transition, ask yourself:
+// If not found, try broader semantic search
+if (results.results.length === 0) {
+  const broader = cortex_search({
+    query: "property access error undefined object",
+    return_layers: ["L0", "L1"]
+  });
+}
+```
 
-- [ ] Have we accumulated meaningful content?
-- [ ] Did the user share important preferences or decisions?
-- [ ] Is this a natural checkpoint?
-- [ ] Should I close the session now?
+### Timeline Reconstruction
 
-If yes to any, call `cortex_close_session`.
+```typescript
+// 1. List timeline directory
+const timeline = cortex_ls({
+  uri: "cortex://session/{session_id}/timeline",
+  recursive: true,
+  include_abstracts: true
+});
+
+// 2. Sort by modified date (entries already sorted)
+// 3. Get full content for key moments
+for (const entry of timeline.entries) {
+  if (entry.abstract_text?.includes("important decision")) {
+    const content = cortex_get_content({ uri: entry.uri });
+    // Process important moment
+  }
+}
+```
+
+## Performance Tips
+
+### Minimize API Calls
+
+Instead of:
+```typescript
+// Bad: Multiple L2 calls
+for (const uri of uris) {
+  cortex_get_content({ uri });
+}
+```
+
+Do:
+```typescript
+// Good: Batch with search
+cortex_search({
+  query: "specific topic",
+  scope: session_id,
+  return_layers: ["L0", "L1", "L2"]
+});
+```
+
+### Use Scope Effectively
+
+```typescript
+// Faster: Search within known session
+cortex_search({
+  query: "authentication",
+  scope: "project-x-session",
+  return_layers: ["L0"]
+});
+
+// Slower: Search all sessions
+cortex_search({
+  query: "authentication",
+  return_layers: ["L0"]
+});
+```
+
+### Leverage Abstracts for Filtering
+
+```typescript
+// Get abstracts while browsing
+const entries = cortex_ls({
+  uri: "cortex://session",
+  include_abstracts: true
+});
+
+// Filter based on abstracts without additional calls
+const relevantEntries = entries.entries.filter(e => 
+  e.abstract_text?.includes("relevant keyword")
+);
+```

package/skills/memclaw/references/memory-structure.md

@@ -0,0 +1,160 @@
+# Memory Structure
+
+MemClaw organizes memory using a multi-dimensional structure with three-tier retrieval layers.
+
+## URI Structure
+
+All memory resources are addressed using the `cortex://` URI scheme:
+
+```
+cortex://
+├── resources/{resource_name}/           # General resources (facts, knowledge)
+├── user/
+│   ├── preferences/{name}.md            # User preferences
+│   ├── entities/{name}.md               # People, projects, concepts
+│   ├── events/{name}.md                 # Decisions, milestones
+│   └── profile/{name}.md                # User profile info
+├── agent/
+│   ├── cases/{name}.md                  # Problem-solution cases
+│   ├── skills/{name}.md                 # Acquired skills
+│   └── instructions/{name}.md           # Instructions learned
+└── session/{session_id}/
+    ├── timeline/
+    │   ├── {YYYY-MM}/                   # Year-month directory
+    │   │   ├── {DD}/                    # Day directory
+    │   │   │   ├── {HH_MM_SS}_{id}.md   # L2: Original message
+    │   │   │   ├── .abstract.md         # L0: ~100 token summary
+    │   │   │   └── .overview.md         # L1: ~2000 token overview
+    │   │   └── .abstract.md             # Day-level L0 summary
+    │   └── .abstract.md                 # Session-level L0 summary
+    │   └── .overview.md                 # Session-level L1 overview
+    └── .session.json                    # Session metadata
+```
+
+## Dimensions
+
+| Dimension | Purpose | Examples |
+|-----------|---------|----------|
+| `resources` | General knowledge, facts | Documentation, reference materials |
+| `user` | User-specific memories | Preferences, entities, events, profile |
+| `agent` | Agent-specific memories | Cases, skills, instructions |
+| `session` | Conversation memories | Timeline messages, session context |
+
+## Three-Layer Architecture
+
+Each memory resource can have three representation layers:
+
+| Layer | Filename | Tokens | Purpose |
+|-------|----------|--------|---------|
+| **L0 (Abstract)** | `.abstract.md` | ~100 | Quick relevance check, filtering |
+| **L1 (Overview)** | `.overview.md` | ~2000 | Understanding gist, moderate detail |
+| **L2 (Detail)** | `{name}.md` | Full | Exact quotes, complete implementation |
+
+**Layer Resolution:**
+- For files: `cortex://user/preferences/typescript.md` → layers are `.abstract.md` and `.overview.md` in same directory
+- For directories: `cortex://session/default/timeline` → layers are `.abstract.md` and `.overview.md` in that directory
+
+**Access Pattern:**
+```
+1. Start with L0 (quick relevance check)
+2. Use L1 if L0 is relevant (more context)
+3. Use L2 only when necessary (full detail)
+```
+
+## Session Memory
+
+### session_id Configuration
+
+`{session_id}` is a memory isolation identifier for separating different conversation contexts:
+
+| Configuration Location | Field Name | Default Value |
+|-----------------------|------------|---------------|
+| OpenClaw plugin config | `defaultSessionId` | `"default"` |
+
+**Configuration Example** (`openclaw.json`):
+```json
+{
+  "plugins": {
+    "entries": {
+      "memclaw": {
+        "config": {
+          "defaultSessionId": "my-project"
+        }
+      }
+    }
+  }
+}
+```
+
+**Usage Rules:**
+- `session_id` parameter in tools is optional; defaults to configured value
+- Different session_ids provide memory isolation for multi-project/multi-topic management
+- Replace `{session_id}` in URIs with actual value, e.g., `cortex://session/default/timeline`
+
+### Timeline Organization
+
+Timeline messages are organized hierarchically by date:
+
+```
+session/{session_id}/timeline/
+├── 2024-03/                     # Year-Month
+│   ├── 15/                      # Day
+│   │   ├── 10_30_45_abc123.md   # Message at 10:30:45
+│   │   ├── .abstract.md         # Day-level L0
+│   │   └── 16/
+│   │       └── ...
+│   └── .abstract.md             # Month-level L0
+├── .abstract.md                 # Session-level L0
+└── .overview.md                 # Session-level L1
+```
+
+**Message File Format:** `{HH_MM_SS}_{random_id}.md`
+
+## User Memory Categories
+
+| Category | Description | URI Pattern |
+|----------|-------------|-------------|
+| `preferences` | User preferences by topic | `cortex://user/preferences/{name}.md` |
+| `entities` | People, projects, concepts | `cortex://user/entities/{name}.md` |
+| `events` | Decisions, milestones | `cortex://user/events/{name}.md` |
+| `profile` | User profile information | `cortex://user/profile/{name}.md` |
+
+## Agent Memory Categories
+
+| Category | Description | URI Pattern |
+|----------|-------------|-------------|
+| `cases` | Problem-solution pairs | `cortex://agent/cases/{name}.md` |
+| `skills` | Acquired skills | `cortex://agent/skills/{name}.md` |
+| `instructions` | Learned instructions | `cortex://agent/instructions/{name}.md` |
+
+## Session Metadata
+
+Each session has a `.session.json` file containing:
+
+```json
+{
+  "thread_id": "session_id",
+  "status": "active|closed|archived",
+  "created_at": "2024-03-15T10:30:00Z",
+  "updated_at": "2024-03-15T12:45:00Z",
+  "closed_at": null,
+  "message_count": 25,
+  "participants": ["user_001", "agent_001"],
+  "tags": ["typescript", "api-design"],
+  "title": "Optional session title",
+  "description": "Optional description"
+}
+```
+
+## Layer Generation
+
+Layers are generated **asynchronously** to avoid blocking agent responses:
+
+1. **L2 (Detail)**: Created immediately when memory is added
+2. **L0/L1**: Generated when `cortex_close_session` is called or via background maintenance
+
+**When to call `cortex_close_session`:**
+- After completing a significant task
+- After user shares important preferences
+- When conversation topic shifts
+- Every 10-20 exchanges