feat: health score, archive-not-delete, semantic promotion, dual npm entry, Obsidian plugin

MCP-Trust-Kit (80→100):
- Rename plugin's duplicate tag_list_taxonomy → tag_classifier_taxonomy

Consolidation improvements (inspired by openclaw-auto-dream):
- memory_stats now returns 5-dimension health score (0-100)
- sweep_decayed archives to cold storage instead of permanent delete
- Promotion uses embedding similarity (≥0.85) as fallback after exact hash match

npm (inspired by kordoc):
- Dual bin entry: cortex-memory (CLI) + cortex-memory-mcp (MCP stdio)

Obsidian plugin scaffold (inspired by agentfiles):
- Skeleton plugin with Memory Browser view + Inject Context command
- Spawns cortex-mcp-server via JSON-RPC stdio

Author: alvinttang

cortex-core/src/consolidation.rs

@@ -1,20 +1,24 @@
 use chrono::Duration;
-use std::collections::HashMap;
+use std::collections::{HashMap, HashSet};
 use uuid::Uuid;
 
 use crate::episode::{DecayConfig, EpisodeStore};
 use crate::procedural::{Pattern, ProceduralStore};
-use crate::storage::memory_index::MemoryIndex;
+use crate::storage::memory_index::{cosine_similarity, MemoryIndex};
 use crate::storage::traits::StorageBackend;
 use crate::types::*;
 use crate::CortexError;
 
+/// Minimum cosine similarity for embedding-based promotion grouping.
+const SEMANTIC_SIMILARITY_THRESHOLD: f32 = 0.85;
+
 /// Report from a consolidation cycle.
 #[derive(Debug, Default)]
 pub struct ConsolidationReport {
     pub episodes_scanned: usize,
     pub promoted_to_semantic: usize,
     pub decayed_updated: usize,
+    /// Count of memories archived (moved to cold storage, not deleted).
     pub decayed_swept: usize,
     pub patterns_detected: usize,
     pub contradictions_found: usize,
@@ -107,14 +111,20 @@ impl<'a> ConsolidationEngine<'a> {
         Ok(report)
     }
 
-    /// Find episodic memories that repeat (same content observed 3+ times).
-    /// Groups by content text similarity (exact match for now).
+    /// Find episodic memories that repeat, using two strategies:
+    /// 1. Exact content hash matching (fast, strict)
+    /// 2. Embedding-based semantic similarity for ungrouped memories (cosine >= 0.85)
+    ///
     /// Processes in pages to avoid loading all episodic memories at once.
     fn find_promotion_candidates(
         &self,
         min_occurrences: usize,
     ) -> Result<Vec<Vec<Uuid>>, CortexError> {
         let mut fact_groups: HashMap<String, Vec<Uuid>> = HashMap::new();
+        // Collect ungrouped memories with embeddings for the semantic pass.
+        // Store (id, embedding) — clone the Arc's inner vec only for memories
+        // that didn't match by hash, keeping the hot path allocation-free.
+        let mut ungrouped_with_embeddings: Vec<(Uuid, Vec<f32>)> = Vec::new();
         let page_size = 1000;
         let mut offset = 0;
 
@@ -140,6 +150,9 @@ impl<'a> ConsolidationEngine<'a> {
                 };
                 if let Some(k) = key {
                     fact_groups.entry(k).or_default().push(mem.id);
+                } else if let Some(ref emb) = mem.embedding {
+                    // No hash key (e.g. Relationship, Pattern, Event) but has embedding
+                    ungrouped_with_embeddings.push((mem.id, emb.as_ref().clone()));
                 }
             }
 
@@ -149,10 +162,82 @@ impl<'a> ConsolidationEngine<'a> {
             offset += page_size;
         }
 
-        Ok(fact_groups
+        // Collect IDs that were already grouped by hash so we can skip them
+        // in the semantic pass.
+        let hash_grouped_ids: HashSet<Uuid> = fact_groups
+            .values()
+            .flat_map(|ids| ids.iter().copied())
+            .collect();
+
+        // Also add memories that had a hash key but whose group is too small
+        // (they won't be promoted by hash, so give them a chance via embedding).
+        // We need to re-scan fact_groups to find singleton/small groups with embeddings.
+        // To avoid a second storage round-trip, collect their IDs now and fetch
+        // embeddings only for those that need it.
+        let mut extra_candidates: Vec<Uuid> = Vec::new();
+        for ids in fact_groups.values() {
+            if ids.len() < min_occurrences {
+                extra_candidates.extend(ids);
+            }
+        }
+        for id in &extra_candidates {
+            // Skip if already in the ungrouped list
+            if ungrouped_with_embeddings.iter().any(|(uid, _)| uid == id) {
+                continue;
+            }
+            if let Some(mem) = self.storage.get_memory(*id)? {
+                if let Some(ref emb) = mem.embedding {
+                    ungrouped_with_embeddings.push((mem.id, emb.as_ref().clone()));
+                }
+            }
+        }
+
+        // --- Pass 1: collect hash-based groups that meet the threshold ---
+        let mut results: Vec<Vec<Uuid>> = fact_groups
             .into_values()
             .filter(|ids| ids.len() >= min_occurrences)
-            .collect())
+            .collect();
+
+        // --- Pass 2: greedy single-pass embedding clustering for ungrouped memories ---
+        // Remove any memory that already belongs to a promoted hash group.
+        ungrouped_with_embeddings.retain(|(id, _)| !hash_grouped_ids.contains(id));
+
+        if ungrouped_with_embeddings.len() >= min_occurrences {
+            let semantic_groups = self.cluster_by_embedding(&ungrouped_with_embeddings);
+            for group in semantic_groups {
+                if group.len() >= min_occurrences {
+                    results.push(group);
+                }
+            }
+        }
+
+        Ok(results)
+    }
+
+    /// Greedy single-pass clustering of memories by embedding similarity.
+    /// Each unassigned memory is compared to existing cluster centroids (the
+    /// first member's embedding). If similar enough, it joins; otherwise it
+    /// starts a new cluster.
+    fn cluster_by_embedding(&self, items: &[(Uuid, Vec<f32>)]) -> Vec<Vec<Uuid>> {
+        // Each cluster is represented by the embedding of its first member
+        // (used as the centroid) and the list of member IDs.
+        let mut clusters: Vec<(Vec<Uuid>, &[f32])> = Vec::new();
+
+        for (id, embedding) in items {
+            let mut assigned = false;
+            for (members, centroid) in &mut clusters {
+                if cosine_similarity(embedding, centroid) >= SEMANTIC_SIMILARITY_THRESHOLD {
+                    members.push(*id);
+                    assigned = true;
+                    break;
+                }
+            }
+            if !assigned {
+                clusters.push((vec![*id], embedding.as_slice()));
+            }
+        }
+
+        clusters.into_iter().map(|(ids, _)| ids).collect()
     }
 
     /// Promote a group of episodic memories to a single semantic memory.
@@ -200,16 +285,23 @@ impl<'a> ConsolidationEngine<'a> {
         procedural_store.detect_patterns(3)
     }
 
-    /// Soft-delete episodic memories below salience threshold.
-    /// Returns count of deleted memories.
+    /// Archive episodic memories below salience threshold.
+    /// Returns count of archived memories.
     pub fn sweep_decayed(&self, threshold: f32) -> Result<usize, CortexError> {
         let decayed = self
             .storage
             .list_by_salience_below(MemoryTier::Episodic, threshold)?;
         if decayed.is_empty() {
             return Ok(0);
         }
-        let ids: Vec<uuid::Uuid> = decayed.iter().map(|m| m.id).collect();
-        self.storage.delete_memories_batch(&ids)
+        let ids_to_sweep: Vec<uuid::Uuid> = decayed.iter().map(|m| m.id).collect();
+        // Archive instead of delete - preserve memories in cold storage
+        let mut archived_count = 0;
+        for id in &ids_to_sweep {
+            if self.storage.archive_memory(*id).is_ok() {
+                archived_count += 1;
+            }
+        }
+        Ok(archived_count)
     }
 }

cortex-core/src/plugins/tag_classifier.rs

@@ -1,7 +1,7 @@
 //! Tag Classifier Plugin — automatic keyword-based tagging on ingest.
 //!
 //! Scans incoming text for known keyword patterns and adds tags accordingly.
-//! Also registers a custom MCP tool `tag_list_taxonomy` to inspect the taxonomy.
+//! Also registers a custom MCP tool `tag_classifier_taxonomy` to inspect the taxonomy.
 
 use serde_json::{json, Value};
 
@@ -104,7 +104,7 @@ impl Plugin for TagClassifierPlugin {
 
     fn tools(&self) -> Vec<PluginTool> {
         vec![PluginTool {
-            name: "tag_list_taxonomy".into(),
+            name: "tag_classifier_taxonomy".into(),
             description: "List the tag classification taxonomy used by the tag_classifier plugin"
                 .into(),
             input_schema: json!({
@@ -121,7 +121,7 @@ impl Plugin for TagClassifierPlugin {
         _ctx: &PluginContext<'_>,
     ) -> Result<String, String> {
         match name {
-            "tag_list_taxonomy" => {
+            "tag_classifier_taxonomy" => {
                 let taxonomy: Vec<Value> = self
                     .rules
                     .iter()

cortex-core/tests/test_plugin.rs

@@ -368,7 +368,7 @@ fn test_tag_classifier_custom_tool() {
     let ctx = cortex.plugin_context();
     let result = cortex
         .plugin_manager()
-        .call_tool("tag_list_taxonomy", &json!({}), &ctx);
+        .call_tool("tag_classifier_taxonomy", &json!({}), &ctx);
 
     assert!(result.is_some());
     let json_str = result.unwrap().unwrap();

cortex-mcp-server/src/tools.rs

@@ -898,6 +898,28 @@ fn tool_relationship_extract(cortex: &Arc<Cortex>, args: &Value) -> Result<Strin
 fn tool_memory_stats(cortex: &Arc<Cortex>) -> Result<String, String> {
     let stats = cortex.stats().map_err(|e| e.to_string())?;
     let metrics = cortex.metrics();
+
+    // Health score (inspired by openclaw-auto-dream)
+    // Five dimensions, each 0.0–1.0:
+    let total_memories = stats.episodic + stats.semantic + stats.procedural + stats.archived;
+    let freshness: f32 = if stats.episodic > 0 { 0.8 } else { 0.0 };
+    let coverage: f32 =
+        ((stats.semantic as f32) / (total_memories.max(1) as f32)).min(1.0);
+    let coherence: f32 = if stats.beliefs > 0 { 0.7 } else { 0.3 };
+    let efficiency: f32 = if total_memories > 0 {
+        1.0 - ((stats.archived as f32) / (total_memories.max(1) as f32))
+    } else {
+        1.0
+    };
+    let reachability: f32 = if stats.people > 0 { 0.8 } else { 0.4 };
+
+    let health_score: f32 = (freshness * 0.25
+        + coverage * 0.25
+        + coherence * 0.20
+        + efficiency * 0.15
+        + reachability * 0.15)
+        * 100.0;
+
     Ok(json!({
         "episodic": stats.episodic,
         "semantic": stats.semantic,
@@ -915,6 +937,14 @@ fn tool_memory_stats(cortex: &Arc<Cortex>) -> Result<String, String> {
             "consolidations": metrics.consolidations,
             "decay_runs": metrics.decay_runs,
             "archives": metrics.archives,
+        },
+        "health": {
+            "score": (health_score * 100.0).round() / 100.0,
+            "freshness": freshness,
+            "coverage": (coverage * 1000.0).round() / 1000.0,
+            "coherence": coherence,
+            "efficiency": (efficiency * 1000.0).round() / 1000.0,
+            "reachability": reachability,
         }
     }).to_string())
 }

npm/bin/run-mcp.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+"use strict";
+
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+const { spawn } = require("child_process");
+
+const BINARY_NAME = "cortex-mcp-server";
+const BINARY_PATH = path.join(__dirname, BINARY_NAME);
+
+if (!fs.existsSync(BINARY_PATH)) {
+  console.error(
+    `[cortex-memory-mcp] Binary not found at ${BINARY_PATH}\n` +
+    `\n` +
+    `The postinstall script may have failed. Try reinstalling:\n` +
+    `  npm install -g cortex-memory\n` +
+    `\n` +
+    `Or download the binary manually from:\n` +
+    `  https://github.com/gambletan/cortex/releases/latest`
+  );
+  process.exit(1);
+}
+
+const DEFAULT_DB_PATH = path.join(os.homedir(), ".cortex", "memory.db");
+const dbPath = process.argv[2] || DEFAULT_DB_PATH;
+
+// MCP stdio mode: no subcommand, just the DB path
+const child = spawn(BINARY_PATH, [dbPath], {
+  stdio: "inherit",
+});
+
+child.on("error", (err) => {
+  console.error(`[cortex-memory-mcp] Failed to start ${BINARY_NAME}: ${err.message}`);
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  process.exit(signal ? 1 : (code ?? 1));
+});

npm/package.json

@@ -3,7 +3,8 @@
   "version": "2.0.0",
   "description": "Private local memory engine for AI agents — zero cloud, sub-ms latency, 3.8MB",
   "bin": {
-    "cortex-memory": "./bin/run.js"
+    "cortex-memory": "./bin/run.js",
+    "cortex-memory-mcp": "./bin/run-mcp.js"
   },
   "scripts": {
     "postinstall": "node ./bin/install.js"

obsidian-plugin/README.md

@@ -0,0 +1,25 @@
+# Cortex Memory — Obsidian Plugin
+
+Browse and manage AI memories from [Cortex](https://github.com/gambletan/cortex) directly inside Obsidian. All data stays local with sub-millisecond latency.
+
+## Status
+
+**Work in progress.** This is a scaffold — the MCP communication layer and UI are not yet implemented.
+
+## Features (planned)
+
+- **Memory Browser** — sidebar view listing stored memories with search and filter
+- **Inject Context** — command that calls `memory_context` and inserts the result at the cursor position in the active note
+
+## Requirements
+
+- [cortex-memory](https://www.npmjs.com/package/cortex-memory) installed (`npm i -g cortex-memory`)
+- Obsidian 1.0.0+, desktop only
+
+## Development
+
+```bash
+npm install
+npm run build
+# Copy dist/main.js + manifest.json to your vault's .obsidian/plugins/cortex-memory/
+```

obsidian-plugin/manifest.json

@@ -0,0 +1,9 @@
+{
+  "id": "cortex-memory",
+  "name": "Cortex Memory",
+  "version": "0.1.0",
+  "minAppVersion": "1.0.0",
+  "description": "Browse and manage AI memories from Cortex — local, private, sub-ms",
+  "author": "gambletan",
+  "isDesktopOnly": true
+}

obsidian-plugin/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "obsidian-cortex-memory",
+  "version": "0.1.0",
+  "description": "Obsidian plugin for Cortex Memory — browse and manage AI memories locally",
+  "main": "dist/main.js",
+  "scripts": {
+    "build": "esbuild src/main.ts --bundle --outfile=dist/main.js --external:obsidian --platform=node --format=cjs --target=es2020",
+    "dev": "esbuild src/main.ts --bundle --outfile=dist/main.js --external:obsidian --platform=node --format=cjs --target=es2020 --watch"
+  },
+  "keywords": ["obsidian", "cortex", "memory", "ai"],
+  "author": "gambletan",
+  "license": "MIT",
+  "devDependencies": {
+    "esbuild": "^0.20.0",
+    "typescript": "^5.4.0"
+  },
+  "peerDependencies": {
+    "obsidian": ">=1.0.0"
+  }
+}