Complete Hippo memory system design

- Comprehensive design doc with MCP tool specifications
- LLM usage prompts separated for independent iteration
- Realistic example dialog showing full workflow
- Delegate experiment validating natural AI behavior
- Array-based context for better semantic matching
- Hybrid reinforcement with AI suggestions + user control
- Importance-weighted scoring with lazy decay evaluation

Ready for implementation. See issue #11 for tracking.

Author: nikomatsakis

src/hippo/design-doc.md

@@ -32,7 +32,11 @@ The key insight: Generate insights cheaply and frequently, let natural selection
     {
       "uuid": "abc123-def456-789",
       "content": "User prefers dialogue format over instruction lists for collaboration prompts",
-      "context": "design discussion about hippo",
+      "context": [
+        "design discussion about hippo",
+        "defining collaboration patterns",
+        "comparing instruction vs dialogue formats"
+      ],
       "importance": 0.7,
       "created_at": "2025-07-23T17:00:00Z",
       "content_last_modified_at": "2025-07-23T17:00:00Z",
@@ -47,13 +51,30 @@ The key insight: Generate insights cheaply and frequently, let natural selection
 
 - **created_at**: When the insight was first generated (never changes)
 - **content_last_modified_at**: When the content or context was last edited
+- **context**: Array of independent situational aspects describing when/where the insight occurred
 - **importance**: AI-generated 0-1 rating of insight significance (set at creation)
 - **score_at_last_change**: The score when it was last modified (starts at 1.0)
 - **score_last_modified_at**: When the score was last explicitly changed (upvote/downvote)
 
 ### Score Computation
 
-Current score computed on-demand: `(score_at_last_change * importance) * (0.9 ^ days_since_score_last_modified)`
+Current score computed on-demand using research-backed weighting:
+
+```
+current_score = base_score * importance * recency_factor
+
+where:
+base_score = score_at_last_change  
+recency_factor = 0.9 ^ days_since_score_last_modified
+importance = AI-generated 0-1 rating (acts as importance weight from research)
+```
+
+For search ranking, we'll eventually incorporate the full research formula:
+```
+Relevance = 0.3×Recency + 0.2×Frequency + 0.35×Importance + 0.15×Context_Similarity
+```
+
+MVP implementation focuses on Recency (decay) and Importance (AI rating), with Frequency and Context_Similarity planned for future iterations.
 
 #### Score Evolution Examples
 
@@ -101,17 +122,195 @@ Current score (computed on-demand) is a primary factor in search results:
 - **MCP tool interface** - AI uses automatically, no manual commands needed
 - **JSON format** for simplicity in MVP
 
-## Technical Architecture
+## MCP Tool Interface
+
+### Server Configuration
+The Hippo MCP server takes a `--hippo-file` argument specifying the path to the JSON storage file:
+```bash
+hippo-server --hippo-file /path/to/hippo.json
+```
+
+### Tool Definitions
+
+#### `hippo_record_insight`
+```json
+{
+  "name": "hippo_record_insight",
+  "description": "Record a new insight during consolidation moments",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "content": {
+        "type": "string",
+        "description": "The insight content - should be atomic and actionable"
+      },
+      "context": {
+        "type": "array",
+        "items": {"type": "string"},
+        "description": "Array of independent situational aspects describing when/where this insight occurred. Include: 1) General activity (e.g. 'debugging authentication flow', 'design discussion about hippo'), 2) Specific problem/goal (e.g. 'users getting logged out randomly', 'defining MCP tool interface'), 3) Additional relevant details (e.g. 'race condition suspected', 'comparing dialogue vs instruction formats'). Each element should be independently meaningful for search matching."
+      },
+      "importance": {
+        "type": "number",
+        "minimum": 0,
+        "maximum": 1,
+        "description": "AI-assessed importance rating: 0.8+ breakthrough insights, 0.6-0.7 useful decisions, 0.4-0.5 incremental observations, 0.1-0.3 routine details"
+      }
+    },
+    "required": ["content", "context", "importance"]
+  }
+}
+```
+
+#### `hippo_search_insights`
+```json
+{
+  "name": "hippo_search_insights",
+  "description": "Search for relevant insights based on content and context",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "query": {
+        "type": "string",
+        "description": "Search query for insight content"
+      },
+      "context_filter": {
+        "type": "array",
+        "items": {"type": "string"},
+        "description": "Filter results by matching any context elements using partial matching. Examples: ['debugging authentication'] matches insights with 'debugging authentication flow', ['users getting logged out'] matches specific problem contexts. Can provide multiple filters - results match if ANY context element partially matches ANY filter."
+      },
+      "limit": {
+        "type": "object",
+        "properties": {
+          "offset": {"type": "integer", "default": 0},
+          "count": {"type": "integer", "default": 10}
+        },
+        "description": "Result pagination. Default: {offset: 0, count: 10} returns first 10 results. Examples: {offset: 10, count: 5} for next 5 results",
+        "default": {"offset": 0, "count": 10}
+      },
+      "score_range": {
+        "type": "object",
+        "properties": {
+          "min": {"type": "number", "default": 0.1},
+          "max": {"type": "number", "default": null}
+        },
+        "description": "Score range filter. Examples: {min: 0.6, max: 1.0} for decent insights, {min: 1.0} for highly reinforced insights, {max: 0.4} for low-quality insights"
+      }
+    },
+    "required": ["query"]
+  }
+}
+```
+
+**Returns:**
+```json
+{
+  "insights": [
+    {
+      "uuid": "abc123-def456-789",
+      "content": "User prefers dialogue format over instruction lists",
+      "context": [
+        "design discussion about hippo",
+        "defining collaboration patterns", 
+        "comparing instruction vs dialogue formats"
+      ],
+      "importance": 0.7,
+      "current_score": 1.2,
+      "created_at": "2025-07-23T17:00:00Z",
+      "days_since_created": 3,
+      "days_since_score_modified": 1
+    }
+  ],
+  "total_matching": 15,
+  "returned_count": 10,
+  "score_distribution": {
+    "below_0.2": 2,
+    "0.2_to_0.4": 1, 
+    "0.4_to_0.6": 2,
+    "0.6_to_0.8": 3,
+    "0.8_to_1.0": 4,
+    "above_1.0": 3
+  }
+}
+```
+
+#### `hippo_modify_insight`
+```json
+{
+  "name": "hippo_modify_insight",
+  "description": "Modify an existing insight's content, context, or importance",
+  "inputSchema": {
+    "type": "object", 
+    "properties": {
+      "uuid": {
+        "type": "string",
+        "description": "UUID of the insight to modify"
+      },
+      "content": {
+        "type": "string",
+        "description": "New insight content (optional - only provide if changing)"
+      },
+      "context": {
+        "type": "array",
+        "items": {"type": "string"},
+        "description": "New situational context array (optional - only provide if changing)"
+      },
+      "importance": {
+        "type": "number",
+        "minimum": 0,
+        "maximum": 1,
+        "description": "New importance rating (optional - only provide if changing)"
+      },
+      "reinforce": {
+        "type": "string",
+        "enum": ["upvote", "downvote", "none"],
+        "description": "Reinforcement to apply with modification. Default: 'upvote' (since modification usually signals value)",
+        "default": "upvote"
+      }
+    },
+    "required": ["uuid"]
+  }
+}
+```
+
+#### `hippo_reinforce_insight`
+```json
+{
+  "name": "hippo_reinforce_insight", 
+  "description": "Apply reinforcement feedback to multiple insights",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "upvotes": {
+        "type": "array",
+        "items": {"type": "string"},
+        "description": "Array of UUIDs to upvote (2.0x score multiplier)",
+        "default": []
+      },
+      "downvotes": {
+        "type": "array", 
+        "items": {"type": "string"},
+        "description": "Array of UUIDs to downvote (0.1x score multiplier)",
+        "default": []
+      }
+    },
+    "required": []
+  }
+}
+```
+
+### LLM Usage Prompts
+
+See [prompts.md](./prompts.md) for detailed guidance on how LLMs should use the Hippo MCP tools during insight generation, consolidation, and search.
 
 ### Core Operations
 ```
-record_insight(content, context) → uuid
-search_insights(query, context_filter?) → List[InsightResult]  
-reinforce_insight(uuid, feedback: upvote|downvote)
-decay_insights() → updates all scores
+record_insight(content, context, importance) → uuid
+search_insights(query, context_filter?, score_range?, limit?) → InsightResults
+reinforce_insight(upvotes[], downvotes[]) → success
+modify_insight(uuid, content?, context?, importance?, reinforce?) → success
 ```
 
-### Decay Function (Simple)
+## Technical Architecture
 ```
 score = score * (0.9 ^ days_since_last_reinforcement)
 ```
@@ -150,7 +349,9 @@ score = score * (0.9 ^ days_since_last_reinforcement)
 - **Reinforcement patterns**: Which types of insights get consistently upvoted?
 - **Search effectiveness**: Do context-based searches return relevant results?
 
-## Implementation Plan
+## Example Usage
+
+See [example-dialog.md](./example-dialog.md) for a detailed walkthrough showing all four MCP operations in realistic collaborative sessions.
 
 ### Phase 1: Basic Infrastructure
 - JSON storage with decay function
@@ -167,7 +368,7 @@ score = score * (0.9 ^ days_since_last_reinforcement)
 - Collect metrics on insight utility
 - Refine generation triggers and reinforcement
 
-## Future Extensions (Post-MVP)
+## Implementation Plan
 
 ### Memory Hierarchy
 ```