feat: follow-rate efficacy scoring for memory entities (PMB-inspired) (#332)

Add mimir_follow MCP tool to track whether an agent actually FOLLOWED
or MISSED a stored convention/insight/lesson, distinct from
retrieval_count (which only measures recall frequency, not behavior
change). This is the 'honest follow-rate' signal from PMB (pmbai.dev).

- Schema v2->v3: entities gain follow_count, miss_count, follow_rate,
  efficacy_status columns.
- New tool mimir_follow(category, key, followed, context?) records a
  follow/miss and recomputes follow_rate. After >=5 attempts,
  efficacy_status flips to 'useful' (rate >= 0.75) or 'dead'
  (rate < 0.20); otherwise stays 'unverified'.
- decay_tick now applies an efficacy-weighted composite: 'useful'
  entities resist decay (weight 1.0 + follow_rate*0.3), 'dead'
  entities collapse toward the archive floor (weight 0.05). Verified/
  curated entities remain exempt via the existing floor.
- 3 new unit tests; full suite still 123 passed / 0 failed.
- Version bump 2.9.0 -> 2.10.0.

Author: tcconnally

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "perseus-vault"
-version = "2.9.0"
+version = "2.10.0"
 edition = "2021"
 description = "Persistent memory engine for AI agents — MCP JSON-RPC stdio server (formerly Mneme/Mimir)"
 repository = "https://github.com/Perseus-Computing-LLC/perseus-vault"

Cargo.toml

@@ -773,6 +773,10 @@ fn main() {
                 visibility: visibility.clone(),
                 created_at_unix_ms: now,
                 last_accessed_unix_ms: now,
+                follow_count: 0,
+                miss_count: 0,
+                follow_rate: 0.0,
+                efficacy_status: "unverified".to_string(),
                 embedding: None,
             };
 

src/db.rs

@@ -1809,6 +1809,68 @@ fn list_tools(id: Option<Value>) -> JsonRpcResponse {
     },
     "title": "Score Entity Quality"
   },
+  {
+    "name": "mimir_follow",
+    "description": "Record whether an entity (typically a convention/insight/lesson) was actually FOLLOWED or MISSED by the agent — the honest follow-rate signal. Unlike retrieval_count (how often a memory is recalled), this tracks whether recall changed behavior. After enough attempts, efficacy_status flips to 'useful' or 'dead' and feeds into decay scoring so ignored rules decay out of recall while followed ones resist decay.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "category": {
+          "type": "string",
+          "description": "Entity category"
+        },
+        "key": {
+          "type": "string",
+          "description": "Entity key"
+        },
+        "followed": {
+          "type": "boolean",
+          "description": "true if the agent's action followed/honored this entity's guidance, false if it was ignored/missed"
+        },
+        "context": {
+          "type": "string",
+          "description": "Optional description of the action/context this observation relates to"
+        }
+      },
+      "required": [
+        "category",
+        "key",
+        "followed"
+      ]
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "found": {
+          "type": "boolean",
+          "description": "Whether the entity was found"
+        },
+        "category": {
+          "type": "string"
+        },
+        "key": {
+          "type": "string"
+        },
+        "follow_count": {
+          "type": "integer"
+        },
+        "miss_count": {
+          "type": "integer"
+        },
+        "follow_rate": {
+          "type": "number"
+        },
+        "efficacy_status": {
+          "type": "string",
+          "description": "'unverified' | 'useful' | 'dead'"
+        }
+      }
+    },
+    "annotations": {
+      "destructiveHint": true
+    },
+    "title": "Record Follow/Miss Efficacy Signal"
+  },
   {
     "name": "mimir_conflicts",
     "description": "Detect conflicting entities in the same category — pairs with low trigram similarity in their body_json. Flags potential contradictions, duplicate-but-divergent entries, and stale-overwritten facts. Read-only by default. Opt in with resolve=true to actively invalidate the lower-certainty side of clear conflicts (superseding it into history, reversible + time-travelable via mimir_as_of); that path defaults to dry_run=true so you preview first, and never resolves pairs whose certainties are within certainty_margin.",
@@ -2859,6 +2921,7 @@ fn call_tool(name: &str, db: &Database, args: Value, _id: Option<Value>) -> Stri
 
         "mimir_traverse" => Ok(tools::handle_traverse(db, args)),
         "mimir_score" => Ok(tools::handle_score(db, args)),
+        "mimir_follow" => tools::handle_follow(db, args).map_err(|e| e.to_string()),
         "mimir_conflicts" => Ok(tools::handle_conflicts(db, args)),
         "mimir_consolidate" => Ok(tools::handle_consolidate(db, args)),
         "mimir_vault_export" => Ok(tools::handle_vault_export(db, args)),

src/main.rs

@@ -51,6 +51,19 @@ pub struct Entity {
     pub visibility: String,
     pub created_at_unix_ms: i64,
     pub last_accessed_unix_ms: i64,
+    /// Efficacy tracking (v2.10.0 — PMB-inspired follow-rate scoring). How many
+    /// times this entity (typically a convention/insight/lesson) was confirmed
+    /// or auto-detected as actually FOLLOWED vs missed by the agent.
+    #[serde(default)]
+    pub follow_count: i64,
+    #[serde(default)]
+    pub miss_count: i64,
+    /// follow_count / (follow_count + miss_count); 0.0 when no attempts yet.
+    #[serde(default)]
+    pub follow_rate: f64,
+    /// 'unverified' | 'useful' | 'dead' — set once enough attempts accrue.
+    #[serde(default = "default_efficacy_status")]
+    pub efficacy_status: String,
     #[serde(skip)]
     #[allow(dead_code)]
     pub embedding: Option<Vec<f32>>,
@@ -99,6 +112,10 @@ fn default_certainty() -> f64 {
     0.5
 }
 
+fn default_efficacy_status() -> String {
+    "unverified".to_string()
+}
+
 /// Default recall trust weight. Non-zero so verified sources are preferred
 /// over unverified AI drafts everywhere by default; kept low so it acts as a
 /// tie-breaker rather than overriding relevance/recency.
@@ -340,6 +357,19 @@ pub struct DecayReport {
     pub completed_at_unix_ms: i64,
 }
 
+/// Result of recording a follow/miss observation against an entity
+/// (v2.10.0 — PMB-inspired efficacy scoring).
+#[derive(Debug, Clone, Serialize)]
+pub struct FollowReport {
+    pub found: bool,
+    pub category: String,
+    pub key: String,
+    pub follow_count: i64,
+    pub miss_count: i64,
+    pub follow_rate: f64,
+    pub efficacy_status: String,
+}
+
 /// Compact report.
 #[derive(Debug, Clone, Serialize)]
 pub struct CompactReport {

src/mcp.rs

@@ -40,7 +40,17 @@ CREATE TABLE IF NOT EXISTS entities (
     recorded_at_unix_ms INTEGER,     -- transaction time: when Mneme first knew it (backfilled = created_at)
     invalidated_at_unix_ms INTEGER,  -- transaction time: when Mneme retired it (NULL = live)
     supersedes TEXT DEFAULT '',      -- id of the entity this one replaced
-    superseded_by TEXT DEFAULT ''    -- id of the entity that replaced this one
+    superseded_by TEXT DEFAULT '',   -- id of the entity that replaced this one
+
+    -- Efficacy tracking (v2.10.0 — PMB-inspired follow-rate scoring). Tracks
+    -- whether a lesson/convention/insight actually gets FOLLOWED by the agent,
+    -- not just recalled. follow_rate feeds into decay_tick as a composite
+    -- weight so rules that get ignored decay out of recall, and rules that
+    -- earn their place resist decay even without recency.
+    follow_count INTEGER DEFAULT 0,      -- times confirmed/detected as followed
+    miss_count INTEGER DEFAULT 0,        -- times confirmed/detected as NOT followed
+    follow_rate REAL DEFAULT 0.0,        -- follow_count / (follow_count + miss_count), 0.0 if no attempts
+    efficacy_status TEXT DEFAULT 'unverified'  -- 'unverified' | 'useful' | 'dead'
 );
 
 CREATE UNIQUE INDEX IF NOT EXISTS idx_entities_category_key ON entities(category, key);
@@ -127,7 +137,7 @@ CREATE INDEX IF NOT EXISTS idx_entity_history_catkey ON entity_history(category,
 /// the column-add migrations below have been applied. Bump this whenever you add
 /// a new ALTER-probe migration in `initialize_schema`, or existing databases
 /// (already at the previous level) will skip it.
-const SCHEMA_VERSION: i64 = 2;
+const SCHEMA_VERSION: i64 = 3;
 
 /// Initialize the v0.2.0 schema on a fresh database.
 pub fn initialize_schema(conn: &Connection) -> Result<(), Box<dyn std::error::Error>> {
@@ -221,6 +231,22 @@ pub fn initialize_schema(conn: &Connection) -> Result<(), Box<dyn std::error::Er
     if conn.prepare("SELECT superseded_by FROM entities LIMIT 1").is_err() {
         conn.execute_batch("ALTER TABLE entities ADD COLUMN superseded_by TEXT DEFAULT '';")?;
     }
+
+    // Add efficacy-tracking columns (v2.10.0 — PMB-inspired follow-rate scoring).
+    if conn.prepare("SELECT follow_count FROM entities LIMIT 1").is_err() {
+        conn.execute_batch("ALTER TABLE entities ADD COLUMN follow_count INTEGER DEFAULT 0;")?;
+    }
+    if conn.prepare("SELECT miss_count FROM entities LIMIT 1").is_err() {
+        conn.execute_batch("ALTER TABLE entities ADD COLUMN miss_count INTEGER DEFAULT 0;")?;
+    }
+    if conn.prepare("SELECT follow_rate FROM entities LIMIT 1").is_err() {
+        conn.execute_batch("ALTER TABLE entities ADD COLUMN follow_rate REAL DEFAULT 0.0;")?;
+    }
+    if conn.prepare("SELECT efficacy_status FROM entities LIMIT 1").is_err() {
+        conn.execute_batch(
+            "ALTER TABLE entities ADD COLUMN efficacy_status TEXT DEFAULT 'unverified';",
+        )?;
+    }
     // Backfill transaction time for pre-existing rows: a fact's recorded_at is
     // when Mneme first stored it, i.e. its created_at. (No-op on a fresh DB.)
     conn.execute_batch(

src/models.rs

@@ -368,6 +368,10 @@ pub fn handle_remember(db: &Database, args: Value) -> Result<String, String> {
         visibility: a.visibility.clone(),
         created_at_unix_ms: now,
         last_accessed_unix_ms: now,
+        follow_count: 0,
+        miss_count: 0,
+        follow_rate: 0.0,
+        efficacy_status: "unverified".to_string(),
         embedding: None,
     };
 
@@ -1150,6 +1154,31 @@ pub fn handle_score(db: &Database, args: Value) -> String {
     }
 }
 
+#[derive(Debug, Deserialize)]
+pub struct FollowArgs {
+    pub category: String,
+    pub key: String,
+    pub followed: bool,
+    #[serde(default)]
+    #[allow(dead_code)]
+    pub context: Option<String>,
+}
+
+/// Record whether an entity (convention/insight/lesson) was actually FOLLOWED
+/// or MISSED by the agent — the PMB-inspired "honest follow-rate" signal.
+/// `context` is accepted for future auto-detection/audit use but not yet
+/// persisted; the tool records a manual confirm/deny each call.
+pub fn handle_follow(db: &Database, args: Value) -> Result<String, String> {
+    let a: FollowArgs =
+        serde_json::from_value(args).map_err(|e| format!("Invalid follow arguments: {}", e))?;
+
+    let report = db
+        .follow(&a.category, &a.key, a.followed)
+        .map_err(|e| format!("Follow failed: {}", e))?;
+
+    serde_json::to_string(&report).map_err(|e| format!("Serialization failed: {}", e))
+}
+
 #[derive(Debug, Deserialize)]
 pub struct ConflictArgs {
     pub category: String,
@@ -1330,6 +1359,10 @@ pub fn handle_ingest_file(db: &Database, args: Value) -> Result<String, String>
         visibility: "workspace".to_string(),
         created_at_unix_ms: now,
         last_accessed_unix_ms: now,
+        follow_count: 0,
+        miss_count: 0,
+        follow_rate: 0.0,
+        efficacy_status: "unverified".to_string(),
         embedding: None,
     };
     let (eid, action) = db