@prmichaelsen/remember-mcp 3.15.4 → 3.15.6

package/agent/scripts/acp.version-update.sh

@@ -3,6 +3,20 @@
 # Agent Context Protocol (ACP) Update Script
 # This script updates AGENT.md, template files, and utility scripts from the repository
 
+# Self-relocation guard: this script overwrites itself during the update
+# (it copies the latest version from the repo to agent/scripts/). Bash reads
+# files lazily by byte offset, so the overwrite garbles execution. Fix: re-exec
+# from a temp copy so the file on disk can safely change.
+if [ -z "$_ACP_UPDATE_RELOCATED" ]; then
+    _tmp_copy=$(mktemp)
+    cp "$0" "$_tmp_copy"
+    export _ACP_UPDATE_RELOCATED=1
+    bash "$_tmp_copy" "$@"
+    _rc=$?
+    rm -f "$_tmp_copy"
+    exit $_rc
+fi
+
 set -e
 
 # Colors for output using tput (more reliable than ANSI codes)
@@ -61,6 +75,10 @@ if [ ! -f "agent/.gitignore" ]; then
 
 # Reports directory - generated by @acp.report command
 reports/
+clarifications/
+feedback/
+drafts/
+preferences/
 EOF
     echo "${GREEN}✓${NC} Created agent/.gitignore"
 fi
@@ -123,13 +141,13 @@ if [ -f "agent/manifest.yaml" ]; then
     UPDATE_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
     
     # Update acp-core version and timestamps
-    sed -i "/^  acp-core:/,/^  [a-z]/ {
+    _sed_i "/^  acp-core:/,/^  [a-z]/ {
         s/package_version: .*/package_version: ${NEW_VERSION}/
         s/updated_at: .*/updated_at: ${UPDATE_DATE}/
     }" agent/manifest.yaml
-    
+
     # Update manifest timestamp
-    sed -i "s/^last_updated: .*/last_updated: ${UPDATE_DATE}/" agent/manifest.yaml
+    _sed_i "s/^last_updated: .*/last_updated: ${UPDATE_DATE}/" agent/manifest.yaml
     
     echo "${GREEN}✓${NC} Updated acp-core to v${NEW_VERSION} in manifest.yaml"
     echo ""

package/agent/scripts/acp.yaml-parser.sh

@@ -4,6 +4,20 @@
 # Version: 1.0.0
 # Created: 2026-02-21
 
+# ============================================================================
+# PORTABILITY HELPERS
+# ============================================================================
+
+# Portable in-place sed (works on both GNU and BSD/macOS sed)
+# Usage: _yaml_sed_i "expression" "file"
+_yaml_sed_i() {
+    if [ "$(uname)" = "Darwin" ]; then
+        sed -i '' "$@"
+    else
+        sed -i "$@"
+    fi
+}
+
 # ============================================================================
 # GLOBAL STATE
 # ============================================================================
@@ -85,7 +99,7 @@ add_child() {
     fi
     
     local updated="$id|$type|$key|$value|$parent|$children"
-    sed -i "$((parent_id + 1))s@.*@$updated@" "$AST_FILE"
+    _yaml_sed_i "$((parent_id + 1))s@.*@$updated@" "$AST_FILE"
 }
 
 update_node_type() {
@@ -103,7 +117,7 @@ update_node_type() {
     children=$(echo "$node" | cut -d'|' -f6)
     
     local updated="$id|$new_type|$key|$value|$parent|$children"
-    sed -i "$((node_id + 1))s@.*@$updated@" "$AST_FILE"
+    _yaml_sed_i "$((node_id + 1))s@.*@$updated@" "$AST_FILE"
 }
 
 # ============================================================================
@@ -388,7 +402,7 @@ create_node_and_link() {
         # Update parent node with new children list
         local parent_prefix
         parent_prefix=$(echo "$parent_line" | cut -d'|' -f1-5)
-        sed -i "$((parent_id + 1))s@.*@${parent_prefix}|${parent_children}@" "$AST_FILE"
+        _yaml_sed_i "$((parent_id + 1))s@.*@${parent_prefix}|${parent_children}@" "$AST_FILE"
     fi
     
     echo "$next_id"
@@ -496,11 +510,11 @@ yaml_set() {
     if [ "$new_value" = "[]" ]; then
         # Convert node to array type and clear children
         local updated="$id|array|$key||$parent|"
-        sed -i "$((current_node + 1))s@.*@$updated@" "$AST_FILE"
+        _yaml_sed_i "$((current_node + 1))s@.*@$updated@" "$AST_FILE"
     else
         new_value=$(echo "$new_value" | sed 's/|/\\|/g')
         local updated="$id|$type|$key|$new_value|$parent|$children"
-        sed -i "$((current_node + 1))s@.*@$updated@" "$AST_FILE"
+        _yaml_sed_i "$((current_node + 1))s@.*@$updated@" "$AST_FILE"
     fi
 }
 
@@ -838,7 +852,7 @@ yaml_delete() {
     
     # Update parent node
     local updated="$id|$type|$key|$value|$parent|$new_children"
-    sed -i "$((current_node + 1))s@.*@$updated@" "$AST_FILE"
+    _yaml_sed_i "$((current_node + 1))s@.*@$updated@" "$AST_FILE"
     
     return 0
 }

package/agent/tasks/milestone-19-new-search-ghost-tools/task-203-create-search-by-tool.md

@@ -0,0 +1,143 @@
+# Task 203: Create `remember_search_by` Tool
+
+**Milestone**: M19 — New Search Modes, Ghost Tools & Emotional Exposure
+**Status**: Not Started
+**Created**: 2026-03-07
+**Estimated Hours**: 3-4
+**Dependencies**: remember-core MemoryService.byTime/byDensity/byRating/byDiscovery methods
+
+---
+
+## Objective
+
+Create the `remember_search_by` MCP tool with initial modes: byTime, byDensity, byRating, byDiscovery. This is the foundation tool that later tasks extend with additional modes (byProperty, bySignificance, byBroad, byRandom).
+
+## Context
+
+remember-core already has `MemoryService.byTime()`, `byDensity()`, `byRating()`, `byDiscovery()`. This task creates the MCP tool definition and a thin handler that dispatches by mode.
+
+## Complete Tool Definition
+
+```typescript
+{
+  name: 'remember_search_by',
+  description: `Search memories using specialized modes beyond hybrid search.
+
+  Modes:
+  - byTime: Chronological sort (newest/oldest first)
+  - byDensity: Sort by relationship count (most connected memories)
+  - byRating: Sort by Bayesian rating average (social ratings from spaces)
+  - byDiscovery: Interleaved rated + unrated content for exploration (4:1 ratio)
+
+  Use remember_search_memory for hybrid semantic+keyword search.
+  Use remember_find_similar for vector similarity.
+  Use this tool for structured browsing, sorting, and discovery.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      mode: {
+        type: 'string',
+        enum: ['byTime', 'byDensity', 'byRating', 'byDiscovery'],
+        description: 'Search mode to use'
+      },
+      query: {
+        type: 'string',
+        description: 'Optional search query (used within mode for filtering)'
+      },
+      sort_order: {
+        type: 'string',
+        enum: ['asc', 'desc'],
+        description: 'Sort order (byTime, byDensity, byRating). Default: desc'
+      },
+      limit: { type: 'number', description: 'Max results. Default: 10' },
+      offset: { type: 'number', description: 'Pagination offset' },
+      filters: {
+        type: 'object',
+        description: 'Standard search filters',
+        properties: {
+          types: { type: 'array', items: { type: 'string' }, description: 'Include specific content types' },
+          exclude_types: { type: 'array', items: { type: 'string' }, description: 'Exclude specific content types' },
+          tags: { type: 'array', items: { type: 'string' } },
+          weight_min: { type: 'number' },
+          weight_max: { type: 'number' },
+          trust_min: { type: 'number' },
+          trust_max: { type: 'number' },
+          date_from: { type: 'string', description: 'ISO 8601' },
+          date_to: { type: 'string', description: 'ISO 8601' },
+          rating_min: { type: 'number', description: 'Minimum Bayesian rating' },
+          relationship_count_min: { type: 'number' },
+          relationship_count_max: { type: 'number' },
+          has_relationships: { type: 'boolean' }
+        }
+      },
+      deleted_filter: {
+        type: 'string',
+        enum: ['exclude', 'include', 'only'],
+        description: 'Default: exclude'
+      }
+    },
+    required: ['mode']
+  }
+}
+```
+
+## Handler Logic
+
+```typescript
+async function handleSearchBy(userId: string, args: SearchByArgs): Promise<ToolResult> {
+  const services = await createCoreServices(userId);
+  const { mode, query, sort_order, limit, offset, filters, deleted_filter } = args;
+
+  let results;
+  switch (mode) {
+    case 'byTime':
+      results = await services.memoryService.byTime({ query, sort_order, limit, offset, filters, deleted_filter });
+      break;
+    case 'byDensity':
+      results = await services.memoryService.byDensity({ query, sort_order, limit, offset, filters, deleted_filter });
+      break;
+    case 'byRating':
+      results = await services.memoryService.byRating({ query, sort_order, limit, offset, filters, deleted_filter });
+      break;
+    case 'byDiscovery':
+      // byDiscovery interleaves rated (4) + unrated (1) results
+      results = await services.memoryService.byDiscovery({ query, limit, offset, filters, deleted_filter });
+      break;
+    default:
+      return { content: [{ type: 'text', text: `Unknown mode: ${mode}` }], isError: true };
+  }
+
+  return { content: [{ type: 'text', text: JSON.stringify(results) }] };
+}
+```
+
+## Key Decisions
+
+- **Mode enum is extensible**: Later tasks (206, 208) add byProperty, bySignificance, byBroad, byRandom to the enum. Design the switch statement to be easily extendable.
+- **Filters object matches core's SearchFilters**: Pass through directly — don't transform. The MCP schema mirrors core's interface.
+- **byDiscovery interleaves**: 4:1 ratio of rated to unrated content. sort_order is not applicable for byDiscovery.
+- **byRating uses Bayesian averaging**: `rating_bayesian` field, not raw `rating_sum`. Social rating from spaces.
+- **Default limit**: 10 for all initial modes. byBroad (added later) defaults to 50.
+
+## Steps
+
+1. Create `src/tools/search-by.ts` with tool definition and handler per above
+2. Register in `src/server-factory.ts` (imports, ListTools, CallTool switch)
+3. Write unit tests in `src/tools/search-by.spec.ts`:
+   - Each mode dispatches to correct core method
+   - Invalid mode returns error
+   - Filters pass through to core
+   - sort_order parameter passed correctly
+   - Default limit/offset behavior
+   - byDiscovery ignores sort_order
+
+## Verification
+
+- [ ] Tool definition exports `searchByTool` and `handleSearchBy`
+- [ ] Modes byTime, byDensity, byRating, byDiscovery all dispatch correctly
+- [ ] Full filter object passed through (types, exclude_types, tags, weight, trust, date, rating, relationship count)
+- [ ] sort_order works for byTime, byDensity, byRating
+- [ ] Tool registered in server-factory.ts
+- [ ] Unit tests passing
+- [ ] TypeScript clean
+- [ ] Build passing

package/agent/tasks/milestone-19-new-search-ghost-tools/task-204-add-new-filters-existing-tools.md

@@ -0,0 +1,77 @@
+# Task 204: Add New Filters to Existing Tool Schemas
+
+**Milestone**: M19 — New Search Modes, Ghost Tools & Emotional Exposure
+**Status**: Not Started
+**Created**: 2026-03-07
+**Estimated Hours**: 2-3
+**Dependencies**: None (filters already exist in remember-core)
+
+---
+
+## Objective
+
+Update existing MCP tool input schemas to expose filters that already exist in remember-core but aren't in the MCP tool definitions.
+
+## Context
+
+remember-core's `SearchFilters` interface has `rating_min`, `relationship_count_min`, `relationship_count_max`, and `exclude_types` — none are exposed in the current MCP tool schemas. These filters need to be added to the appropriate tools.
+
+## Filter-to-Tool Mapping
+
+| Filter | Type | Description | Add To |
+|--------|------|-------------|--------|
+| `rating_min` | number | Minimum Bayesian rating average | search_memory, find_similar, query_memory, search_space |
+| `relationship_count_min` | number | Minimum relationship count | search_memory, find_similar |
+| `relationship_count_max` | number | Maximum relationship count | search_memory, find_similar |
+| `exclude_types` | string[] | Exclude specific content types | search_memory, search_space |
+
+## Steps
+
+### 1. Update `src/tools/search-memory.ts`
+Add to inputSchema.properties (inside filters object or at top level, matching existing pattern):
+```typescript
+rating_min: { type: 'number', description: 'Minimum Bayesian rating average' },
+relationship_count_min: { type: 'number', description: 'Minimum relationship count' },
+relationship_count_max: { type: 'number', description: 'Maximum relationship count' },
+exclude_types: { type: 'array', items: { type: 'string' }, description: 'Exclude specific content types' }
+```
+Pass new filters through to core `memoryService.search()` call.
+
+### 2. Update `src/tools/find-similar.ts`
+Add:
+```typescript
+rating_min: { type: 'number' },
+relationship_count_min: { type: 'number' },
+relationship_count_max: { type: 'number' }
+```
+
+### 3. Update `src/tools/query-memory.ts`
+Add:
+```typescript
+rating_min: { type: 'number' }
+```
+
+### 4. Update `src/tools/search-space.ts`
+Add:
+```typescript
+rating_min: { type: 'number' },
+exclude_types: { type: 'array', items: { type: 'string' } }
+```
+
+### 5. Update unit tests for each modified tool to verify new filters are passed through to core service calls
+
+## Key Decisions
+
+- **rating_min uses Bayesian average**: The `rating_bayesian` field in core, not raw sum. This provides fairer comparison for items with different rating counts.
+- **relationship_count filters are for personal search only**: Not applicable to space search (relationships are per-user, not per-space).
+- **exclude_types complements existing types filter**: `types` is an include list, `exclude_types` is an exclude list. If both provided, `exclude_types` takes precedence (core behavior).
+
+## Verification
+
+- [ ] `rating_min` available on search_memory, find_similar, query_memory, search_space
+- [ ] `relationship_count_min/max` available on search_memory, find_similar
+- [ ] `exclude_types` available on search_memory, search_space
+- [ ] All new filters pass through to core service calls correctly
+- [ ] Existing tests still pass (no regressions)
+- [ ] New filter tests added for each tool
+- [ ] TypeScript clean

package/agent/tasks/milestone-19-new-search-ghost-tools/task-205-add-feel-fields-create-update.md

@@ -0,0 +1,137 @@
+# Task 205: Add `feel_*` Fields to create_memory and update_memory Schemas
+
+**Milestone**: M19 — New Search Modes, Ghost Tools & Emotional Exposure
+**Status**: Not Started
+**Created**: 2026-03-07
+**Estimated Hours**: 2-3
+**Dependencies**: remember-core schema with 31 `feel_*` Weaviate properties
+
+---
+
+## Objective
+
+Add all 31 optional `feel_*` emotional dimension fields to `remember_create_memory` and `remember_update_memory` input schemas. These are create-time hints that REM re-scores authoritatively during its consolidation cycle.
+
+## Context
+
+remember-core's emotional weighting design adds 31 `feel_*` properties to the Memory Weaviate schema (21 discrete emotions + 10 functional signals). The creating LLM can provide sane defaults at creation time. All fields are optional floats (0-1, except `feel_valence` which is -1 to 1).
+
+## Complete Field List
+
+### Layer 1: Discrete Emotions (21 dimensions)
+
+| Property | Range | Category | Description |
+|----------|-------|----------|-------------|
+| `feel_emotional_significance` | 0-1 | Meta | Overall emotional weight |
+| `feel_vulnerability` | 0-1 | Meta | Personal exposure/openness |
+| `feel_trauma` | 0-1 | Meta | Negative formative experience intensity |
+| `feel_humor` | 0-1 | Positive | Comedic/playful quality |
+| `feel_happiness` | 0-1 | Core | Positive affect / joy |
+| `feel_sadness` | 0-1 | Core | Negative affect / grief / loss |
+| `feel_fear` | 0-1 | Core | Threat perception / anxiety |
+| `feel_anger` | 0-1 | Core | Frustration / injustice |
+| `feel_surprise` | 0-1 | Core | Unexpectedness / novelty |
+| `feel_disgust` | 0-1 | Core | Aversion / rejection |
+| `feel_contempt` | 0-1 | Core | Superiority / dismissal |
+| `feel_embarrassment` | 0-1 | Self-conscious | Social discomfort |
+| `feel_shame` | 0-1 | Self-conscious | Deep self-judgment |
+| `feel_guilt` | 0-1 | Self-conscious | Responsibility for harm |
+| `feel_excitement` | 0-1 | Positive | Anticipatory positive arousal |
+| `feel_pride` | 0-1 | Positive | Accomplishment / self-evaluation |
+| `feel_valence` | **-1 to 1** | VAD | Positive-negative spectrum |
+| `feel_arousal` | 0-1 | VAD | Calm to excited |
+| `feel_dominance` | 0-1 | VAD | Control vs submission |
+| `feel_intensity` | 0-1 | Dimensional | Overall emotional magnitude |
+| `feel_coherence_tension` | 0-1 | Cognitive | Conflict with existing beliefs |
+
+### Layer 2: Functional Signals (10 dimensions)
+
+| Property | Range | Biological Analog | Function |
+|----------|-------|-------------------|----------|
+| `feel_salience` | 0-1 | Fear/Surprise | How unexpected/novel (prediction error) |
+| `feel_urgency` | 0-1 | Anger/Fear | Time-sensitivity of relevance (decay rate) |
+| `feel_social_weight` | 0-1 | Trust/Disgust | Relationship/reputation impact |
+| `feel_agency` | 0-1 | Pride/Shame | Caused by the bot's own actions? |
+| `feel_novelty` | 0-1 | — | Uniqueness relative to collection |
+| `feel_retrieval_utility` | 0-1 | — | Likelihood of future usefulness |
+| `feel_narrative_importance` | 0-1 | — | Advances/anchors a personal story arc |
+| `feel_aesthetic_quality` | 0-1 | — | Beauty, craft, artistry |
+| `feel_valence` | (shared) | — | Scored independently in functional context |
+| `feel_coherence_tension` | (shared) | — | Scored independently in functional context |
+
+> **Note**: `feel_valence` and `feel_coherence_tension` appear in both layers but are scored independently. In Weaviate they are single properties — the REM scoring considers both emotional and functional context when setting the value.
+
+## Schema Addition Pattern
+
+```typescript
+// Added to inputSchema.properties for both create_memory and update_memory:
+
+// Layer 1: Discrete Emotions (all optional, 0-1 floats except feel_valence)
+feel_emotional_significance: { type: 'number', minimum: 0, maximum: 1 },
+feel_vulnerability: { type: 'number', minimum: 0, maximum: 1 },
+feel_trauma: { type: 'number', minimum: 0, maximum: 1 },
+feel_humor: { type: 'number', minimum: 0, maximum: 1 },
+feel_happiness: { type: 'number', minimum: 0, maximum: 1 },
+feel_sadness: { type: 'number', minimum: 0, maximum: 1 },
+feel_fear: { type: 'number', minimum: 0, maximum: 1 },
+feel_anger: { type: 'number', minimum: 0, maximum: 1 },
+feel_surprise: { type: 'number', minimum: 0, maximum: 1 },
+feel_disgust: { type: 'number', minimum: 0, maximum: 1 },
+feel_contempt: { type: 'number', minimum: 0, maximum: 1 },
+feel_embarrassment: { type: 'number', minimum: 0, maximum: 1 },
+feel_shame: { type: 'number', minimum: 0, maximum: 1 },
+feel_guilt: { type: 'number', minimum: 0, maximum: 1 },
+feel_excitement: { type: 'number', minimum: 0, maximum: 1 },
+feel_pride: { type: 'number', minimum: 0, maximum: 1 },
+feel_valence: { type: 'number', minimum: -1, maximum: 1 },  // Note: -1 to 1
+feel_arousal: { type: 'number', minimum: 0, maximum: 1 },
+feel_dominance: { type: 'number', minimum: 0, maximum: 1 },
+feel_intensity: { type: 'number', minimum: 0, maximum: 1 },
+feel_coherence_tension: { type: 'number', minimum: 0, maximum: 1 },
+
+// Layer 2: Functional Signals (all optional, 0-1 floats)
+feel_salience: { type: 'number', minimum: 0, maximum: 1 },
+feel_urgency: { type: 'number', minimum: 0, maximum: 1 },
+feel_social_weight: { type: 'number', minimum: 0, maximum: 1 },
+feel_agency: { type: 'number', minimum: 0, maximum: 1 },
+feel_novelty: { type: 'number', minimum: 0, maximum: 1 },
+feel_retrieval_utility: { type: 'number', minimum: 0, maximum: 1 },
+feel_narrative_importance: { type: 'number', minimum: 0, maximum: 1 },
+feel_aesthetic_quality: { type: 'number', minimum: 0, maximum: 1 },
+```
+
+## Key Decisions
+
+- **These are hints, not permanent values**: Tool description must say "create-time hints, REM re-scores authoritatively during consolidation cycles"
+- **`feel_valence` range is -1 to 1**: All other feel_* fields are 0-1. This is intentional — valence represents positive-negative spectrum.
+- **`feel_valence` and `feel_coherence_tension` are shared**: They appear in both Layer 1 (discrete emotions) and Layer 2 (functional signals) conceptually, but are single Weaviate properties.
+- **No composite fields on create/update**: `feel_significance`, `functional_significance`, `total_significance` are computed by REM only — they are NOT accepted on create/update.
+- **Consider grouping**: Optionally group under a nested `emotions` object to avoid polluting the top-level parameter list. Evaluate whether the existing tool pattern uses nested objects or flat params.
+- **31 unique properties total**: 21 Layer 1 + 10 Layer 2, but `feel_valence` and `feel_coherence_tension` overlap → 29 unique Weaviate property names.
+
+## Steps
+
+1. Update `src/tools/create-memory.ts`:
+   - Add all feel_* fields to inputSchema (per schema above)
+   - Add description note about hints vs REM authoritative scoring
+   - Extract feel_* fields from args and pass to core `create()` call
+2. Update `src/tools/update-memory.ts`:
+   - Add same feel_* fields to inputSchema
+   - Extract and pass to core `update()` call
+3. Write tests:
+   - Verify feel_* fields are passed through to core on create
+   - Verify feel_* fields are passed through to core on update
+   - Verify feel_valence accepts -1 to 1
+   - Verify composite fields (total_significance, etc.) are NOT accepted
+
+## Verification
+
+- [ ] All 31 `feel_*` fields accepted on create_memory
+- [ ] All 31 `feel_*` fields accepted on update_memory
+- [ ] Fields passed through to core service calls
+- [ ] `feel_valence` correctly allows -1 to 1 range
+- [ ] All other `feel_*` fields correctly allow 0 to 1 range
+- [ ] Composite fields NOT accepted (feel_significance, functional_significance, total_significance)
+- [ ] Tool descriptions clearly state these are create-time hints
+- [ ] Tests passing
+- [ ] TypeScript clean

package/agent/tasks/milestone-19-new-search-ghost-tools/task-206-add-byproperty-bysignificance-modes.md

@@ -0,0 +1,135 @@
+# Task 206: Add byProperty and bySignificance Modes to search_by
+
+**Milestone**: M19 — New Search Modes, Ghost Tools & Emotional Exposure
+**Status**: Not Started
+**Created**: 2026-03-07
+**Estimated Hours**: 2-3
+**Dependencies**: Task 203 (search_by tool exists), remember-core schema with `feel_*` properties and `byProperty()` method
+
+---
+
+## Objective
+
+Add `byProperty` and `bySignificance` modes to the `remember_search_by` tool, enabling sorting by any Weaviate property (especially emotional dimensions and composite significance scores).
+
+## Context
+
+remember-core's emotional weighting design includes a generic `byProperty` sort mode that sorts by any Weaviate property name. `bySignificance` is a shorthand for `byProperty` on `total_significance`. This enables powerful emotional exploration — "show me my most traumatic memories", "find my funniest content", "what has the highest retrieval utility?"
+
+## Schema Changes
+
+Update `src/tools/search-by.ts`:
+
+1. Add to mode enum: `'byProperty', 'bySignificance'`
+2. Add `sort_field` parameter:
+```typescript
+sort_field: {
+  type: 'string',
+  description: 'Property to sort by (byProperty mode only). Any Weaviate property name, e.g. "feel_trauma", "feel_salience", "weight", "total_significance", "feel_coherence_tension"'
+}
+```
+3. Update tool description to include:
+```
+- byProperty: Sort by any memory property (e.g., feel_trauma, weight, feel_salience)
+- bySignificance: Sort by total_significance (combined emotional + functional score from REM)
+```
+
+## Handler Logic
+
+```typescript
+case 'byProperty':
+  if (!args.sort_field) {
+    return { content: [{ type: 'text', text: 'sort_field is required for byProperty mode' }], isError: true };
+  }
+  results = await services.memoryService.byProperty({
+    sort_field: args.sort_field,
+    sort_order: args.sort_order,
+    query: args.query,
+    limit: args.limit,
+    offset: args.offset,
+    filters: args.filters,
+    deleted_filter: args.deleted_filter
+  });
+  break;
+
+case 'bySignificance':
+  // Shorthand for byProperty on total_significance
+  results = await services.memoryService.byProperty({
+    sort_field: 'total_significance',
+    sort_order: args.sort_order ?? 'desc',
+    query: args.query,
+    limit: args.limit,
+    offset: args.offset,
+    filters: args.filters,
+    deleted_filter: args.deleted_filter
+  });
+  break;
+```
+
+## Usage Examples (for tool description)
+
+```typescript
+// Most emotionally significant memories
+{ mode: 'byProperty', sort_field: 'total_significance', sort_order: 'desc' }
+
+// Highest coherence tension (conflicting beliefs needing reconciliation)
+{ mode: 'byProperty', sort_field: 'feel_coherence_tension', sort_order: 'desc' }
+
+// Most novel memories
+{ mode: 'byProperty', sort_field: 'feel_novelty', sort_order: 'desc' }
+
+// Most traumatic memories
+{ mode: 'byProperty', sort_field: 'feel_trauma', sort_order: 'desc' }
+
+// Most humorous memories
+{ mode: 'byProperty', sort_field: 'feel_humor', sort_order: 'desc' }
+
+// Highest retrieval utility (most likely to be useful in future queries)
+{ mode: 'byProperty', sort_field: 'feel_retrieval_utility', sort_order: 'desc' }
+
+// Least visited by REM (candidates for scoring attention)
+{ mode: 'byProperty', sort_field: 'rem_visits', sort_order: 'asc' }
+
+// Equivalent calls:
+{ mode: 'bySignificance', sort_order: 'desc' }
+{ mode: 'byProperty', sort_field: 'total_significance', sort_order: 'desc' }
+```
+
+## Three Composite Scores (sortable via byProperty)
+
+| Property | Inputs | Purpose |
+|----------|--------|---------|
+| `feel_significance` | Weighted sum of Layer 1 (21 discrete emotions) | Emotional intensity composite |
+| `functional_significance` | Weighted sum of Layer 2 (10 functional signals) | Functional importance composite |
+| `total_significance` | Both layers combined | Overall significance for sorting |
+
+## Key Decisions
+
+- **bySignificance defaults to desc**: Most significant first is the natural use case.
+- **byProperty accepts ANY Weaviate property**: Not limited to feel_* fields. Can sort by `weight`, `trust`, `created_at`, `rem_visits`, etc.
+- **No property validation in MCP layer**: Let core validate the property name. MCP is a thin adapter.
+- **sort_field required for byProperty only**: Other modes don't use it. Return error if omitted for byProperty.
+
+## Steps
+
+1. Update `src/tools/search-by.ts`:
+   - Add `byProperty` and `bySignificance` to mode enum
+   - Add `sort_field` parameter to inputSchema
+   - Add handler cases per logic above
+   - Update tool description with examples
+2. Write tests:
+   - `byProperty` with various `sort_field` values (feel_trauma, feel_humor, weight, etc.)
+   - `byProperty` without `sort_field` returns error
+   - `bySignificance` dispatches to byProperty with `total_significance`
+   - `bySignificance` defaults sort_order to desc
+   - Sort order works with both modes
+
+## Verification
+
+- [ ] `byProperty` mode sorts by any specified property
+- [ ] `byProperty` requires `sort_field` parameter (error if missing)
+- [ ] `bySignificance` is shorthand for `total_significance` sort
+- [ ] `bySignificance` defaults to desc sort order
+- [ ] Tool description includes examples of emotional dimension sorting
+- [ ] Tests passing
+- [ ] TypeScript clean