server-memory-enhanced 3.1.0 → 3.2.0

package/dist/index.js

@@ -299,14 +299,15 @@ server.registerTool("delete_relations", {
 // Register read_graph tool
 server.registerTool("read_graph", {
     title: "Read Graph",
-    description: "Read the knowledge graph for a specific thread (thread isolation enforced)",
+    description: "Read the knowledge graph for a specific thread (thread isolation enforced). Supports filtering by minimum importance threshold.",
     inputSchema: ReadGraphInputSchema,
     outputSchema: {
         entities: z.array(EntitySchemaCompat),
         relations: z.array(RelationSchemaCompat)
     }
 }, async (input) => {
-    const graph = await knowledgeGraphManager.readGraph(input.threadId);
+    const { threadId, minImportance } = input;
+    const graph = await knowledgeGraphManager.readGraph(threadId, minImportance);
     return {
         content: [{ type: "text", text: JSON.stringify(graph, null, 2) }],
         structuredContent: { ...graph }

package/dist/lib/knowledge-graph-manager.js

@@ -74,8 +74,12 @@ export class KnowledgeGraphManager {
         return ObservationOps.updateObservation(this.storage, params);
     }
     // Graph Reading Operations
-    async readGraph(threadId) {
+    async readGraph(threadId, minImportance) {
         await this.ensureInitialized();
+        // Pass minImportance if provided, otherwise let readGraph use its default
+        if (minImportance !== undefined) {
+            return GraphReader.readGraph(this.storage, threadId, minImportance);
+        }
         return GraphReader.readGraph(this.storage, threadId);
     }
     // Search Operations

package/dist/lib/queries/graph-reader.js

@@ -1,18 +1,152 @@
 /**
  * Graph reading operations
  */
+/**
+ * Default threshold for marking items as ARCHIVED
+ * Items with importance below this but >= minImportance get ARCHIVED status
+ */
+export const ARCHIVED_THRESHOLD = 0.1;
+/**
+ * Check if an observation has a status field
+ */
+function hasStatus(obs) {
+    return obs.status !== undefined;
+}
+/**
+ * Check if an entity or any of its observations has a status field
+ */
+function entityHasStatus(entity) {
+    return entity.status !== undefined || entity.observations.some(hasStatus);
+}
+/**
+ * Check if a relation has a status field
+ */
+function relationHasStatus(relation) {
+    return relation.status !== undefined;
+}
+/**
+ * Strip status from an observation (used to clean persisted status values)
+ */
+function stripObservationStatus(obs) {
+    if (!hasStatus(obs))
+        return obs;
+    const { status: _oldStatus, ...obsWithoutStatus } = obs;
+    return obsWithoutStatus;
+}
+/**
+ * Strip status from an entity and its observations (used to clean persisted status values)
+ * Optimized to avoid unnecessary copies when only entity status needs stripping
+ */
+function stripEntityStatus(entity) {
+    if (!entityHasStatus(entity))
+        return entity;
+    const entityHasOwnStatus = entity.status !== undefined;
+    const observationsHaveStatus = entity.observations.some(hasStatus);
+    // If only observations have status, keep entity as-is and just map observations
+    if (!entityHasOwnStatus && observationsHaveStatus) {
+        return {
+            ...entity,
+            observations: entity.observations.map(stripObservationStatus),
+        };
+    }
+    // If only entity has status, strip it but keep observations as-is
+    if (entityHasOwnStatus && !observationsHaveStatus) {
+        const { status: _oldStatus, ...entityWithoutStatus } = entity;
+        return entityWithoutStatus;
+    }
+    // Both entity and observations have status
+    const { status: _oldStatus, ...entityWithoutStatus } = entity;
+    return {
+        ...entityWithoutStatus,
+        observations: entity.observations.map(stripObservationStatus),
+    };
+}
+/**
+ * Strip status from a relation (used to clean persisted status values)
+ */
+function stripRelationStatus(relation) {
+    if (!relationHasStatus(relation))
+        return relation;
+    const { status: _oldStatus, ...relationWithoutStatus } = relation;
+    return relationWithoutStatus;
+}
+/**
+ * Strip status from all entities and relations in a graph (used to clean persisted status values)
+ * Optimized to avoid unnecessary deep copies when no status fields exist
+ */
+export function stripGraphStatus(graph) {
+    // Check if any items have status fields - if not, return as-is
+    const hasAnyStatus = graph.entities.some(entityHasStatus) || graph.relations.some(relationHasStatus);
+    if (!hasAnyStatus) {
+        return graph;
+    }
+    return {
+        entities: graph.entities.map(stripEntityStatus),
+        relations: graph.relations.map(stripRelationStatus),
+    };
+}
 /**
  * Read the knowledge graph filtered by threadId for thread isolation
+ * and optionally filtered by minimum importance threshold
  */
-export async function readGraph(storage, threadId) {
+export async function readGraph(storage, threadId, minImportance = ARCHIVED_THRESHOLD) {
     const graph = await storage.loadGraph();
-    // Filter entities by threadId
-    const filteredEntities = graph.entities.filter(e => e.agentThreadId === threadId);
+    // Filter entities by threadId and importance
+    const filteredEntities = graph.entities
+        .filter(e => e.agentThreadId === threadId)
+        .filter(e => e.importance >= minImportance)
+        .map(entity => {
+        // Add ARCHIVED status if importance is less than ARCHIVED_THRESHOLD but >= minImportance.
+        // Otherwise, explicitly clear status so pre-existing values don't leak through.
+        const isArchived = entity.importance < ARCHIVED_THRESHOLD && entity.importance >= minImportance;
+        const { status: _oldStatus, ...entityWithoutStatus } = entity;
+        const entityWithStatus = {
+            ...entityWithoutStatus,
+            ...(isArchived ? { status: 'ARCHIVED' } : {}),
+        };
+        // Process observations: filter by importance and add ARCHIVED status
+        // Defensive: handle potential legacy string observations
+        entityWithStatus.observations = entity.observations
+            .filter(obs => {
+            // Keep legacy string observations (defensive against legacy data)
+            if (typeof obs !== 'object' || obs === null)
+                return true;
+            // Use observation importance if set, otherwise inherit from entity
+            const obsImportance = obs.importance !== undefined ? obs.importance : entity.importance;
+            return obsImportance >= minImportance;
+        })
+            .map(obs => {
+            // Pass through legacy string observations unchanged
+            if (typeof obs !== 'object' || obs === null)
+                return obs;
+            const obsImportance = obs.importance !== undefined ? obs.importance : entity.importance;
+            const isObsArchived = obsImportance < ARCHIVED_THRESHOLD && obsImportance >= minImportance;
+            const { status: _oldObsStatus, ...obsWithoutStatus } = obs;
+            return {
+                ...obsWithoutStatus,
+                ...(isObsArchived ? { status: 'ARCHIVED' } : {}),
+            };
+        });
+        return entityWithStatus;
+    });
     // Create a Set of filtered entity names for quick lookup
     const filteredEntityNames = new Set(filteredEntities.map(e => e.name));
-    // Filter relations to only include those between filtered entities and from the same thread
-    const filteredRelations = graph.relations.filter(r => r.agentThreadId === threadId &&
-        filteredEntityNames.has(r.from) && filteredEntityNames.has(r.to));
+    // Filter relations to only include those between filtered entities, from the same thread, and by importance
+    const filteredRelations = graph.relations
+        .filter(r => r.agentThreadId === threadId &&
+        filteredEntityNames.has(r.from) &&
+        filteredEntityNames.has(r.to) &&
+        r.importance >= minImportance)
+        .map(relation => {
+        // Add ARCHIVED status if importance is less than ARCHIVED_THRESHOLD but >= minImportance.
+        // Otherwise, explicitly clear status so pre-existing values don't leak through.
+        const isArchived = relation.importance < ARCHIVED_THRESHOLD && relation.importance >= minImportance;
+        const { status: _oldStatus, ...relationWithoutStatus } = relation;
+        return {
+            ...relationWithoutStatus,
+            ...(isArchived ? { status: 'ARCHIVED' } : {}),
+        };
+    });
     return {
         entities: filteredEntities,
         relations: filteredRelations

package/dist/lib/queries/search-service.js

@@ -1,6 +1,7 @@
 /**
  * Search and filter operations for the knowledge graph
  */
+import { stripGraphStatus } from './graph-reader.js';
 /**
  * Search for nodes in the knowledge graph by query string
  * Searches entity names, types, and observation content
@@ -22,7 +23,8 @@ export async function searchNodes(storage, threadId, query) {
         entities: filteredEntities,
         relations: filteredRelations,
     };
-    return filteredGraph;
+    // Strip any persisted status values to prevent leaking stale data
+    return stripGraphStatus(filteredGraph);
 }
 /**
  * Open specific nodes by name
@@ -42,7 +44,8 @@ export async function openNodes(storage, threadId, names) {
         entities: filteredEntities,
         relations: filteredRelations,
     };
-    return filteredGraph;
+    // Strip any persisted status values to prevent leaking stale data
+    return stripGraphStatus(filteredGraph);
 }
 /**
  * Query nodes with advanced filters
@@ -106,8 +109,10 @@ export async function queryNodes(storage, threadId, filters) {
             return false;
         return true;
     });
-    return {
+    const filteredGraph = {
         entities: filteredEntities,
         relations: filteredRelations,
     };
+    // Strip any persisted status values to prevent leaking stale data
+    return stripGraphStatus(filteredGraph);
 }

package/dist/lib/schemas.js

@@ -2,6 +2,7 @@
  * Zod schema definitions for MCP tools
  */
 import { z } from "zod";
+import { ARCHIVED_THRESHOLD } from "./queries/graph-reader.js";
 // Schema for Observation with versioning support
 export const ObservationSchema = z.object({
     id: z.string().describe("Unique observation ID"),
@@ -12,8 +13,11 @@ export const ObservationSchema = z.object({
     superseded_by: z.string().optional().describe("ID of observation that supersedes this one"),
     agentThreadId: z.string().describe("Thread that created this observation"),
     confidence: z.number().min(0).max(1).optional().describe("Confidence in accuracy (0-1, optional, inherits from entity if not set)"),
-    importance: z.number().min(0).max(1).optional().describe("Importance for memory integrity (0-1, optional, inherits from entity if not set)")
+    importance: z.number().min(0).max(1).optional().describe("Importance for memory integrity (0-1, optional, inherits from entity if not set)"),
+    status: z.literal('ARCHIVED').optional().describe("Status indicator - set to 'ARCHIVED' for low-importance items")
 });
+// Input schema for observations (excludes status field which is computed)
+export const ObservationInputSchema = ObservationSchema.omit({ status: true }).strict();
 // Schema for existing tools
 export const EntitySchema = z.object({
     name: z.string().describe("Unique identifier for the entity"),
@@ -22,8 +26,13 @@ export const EntitySchema = z.object({
     agentThreadId: z.string().describe("Agent thread that created/modified this entity"),
     timestamp: z.string().describe("ISO 8601 timestamp of creation/modification"),
     confidence: z.number().min(0).max(1).describe("Confidence in the accuracy of this entity (0-1)"),
-    importance: z.number().min(0).max(1).describe("Importance for memory integrity if lost: 0 (not important) to 1 (critical)")
+    importance: z.number().min(0).max(1).describe("Importance for memory integrity if lost: 0 (not important) to 1 (critical)"),
+    status: z.literal('ARCHIVED').optional().describe("Status indicator - set to 'ARCHIVED' for low-importance items")
 });
+// Input schema for entities (excludes status field which is computed, uses input observations)
+export const EntityInputSchema = EntitySchema.omit({ status: true, observations: true }).extend({
+    observations: z.array(ObservationInputSchema).describe("Versioned observations about this entity")
+}).strict();
 export const RelationSchema = z.object({
     from: z.string().describe("Source entity name"),
     to: z.string().describe("Target entity name"),
@@ -31,8 +40,11 @@ export const RelationSchema = z.object({
     agentThreadId: z.string().describe("Agent thread that created/modified this relation"),
     timestamp: z.string().describe("ISO 8601 timestamp of creation/modification"),
     confidence: z.number().min(0).max(1).describe("Confidence in the accuracy of this relation (0-1)"),
-    importance: z.number().min(0).max(1).describe("Importance for memory integrity if lost: 0 (not important) to 1 (critical)")
+    importance: z.number().min(0).max(1).describe("Importance for memory integrity if lost: 0 (not important) to 1 (critical)"),
+    status: z.literal('ARCHIVED').optional().describe("Status indicator - set to 'ARCHIVED' for low-importance items")
 });
+// Input schema for relations (excludes status field which is computed)
+export const RelationInputSchema = RelationSchema.omit({ status: true }).strict();
 // Schema for save_memory tool (Section 1 of spec)
 export const SaveMemoryRelationSchema = z.object({
     targetEntity: z.string().describe("Name of entity to connect to (must exist in this request)"),
@@ -147,7 +159,8 @@ export const UpdateObservationOutputSchema = z.object({
 });
 // Schema for read_graph tool
 export const ReadGraphInputSchema = z.object({
-    threadId: z.string().min(1).describe("Thread ID for this conversation/project")
+    threadId: z.string().min(1).describe("Thread ID for this conversation/project"),
+    minImportance: z.number().min(0).max(1).optional().default(ARCHIVED_THRESHOLD).describe(`Minimum importance threshold (0-1). Items with importance below this value are excluded. Items with importance between minImportance and ${ARCHIVED_THRESHOLD} are marked as ARCHIVED. Default: ${ARCHIVED_THRESHOLD}`)
 });
 // Schema for search_nodes tool
 export const SearchNodesInputSchema = z.object({
@@ -202,7 +215,7 @@ export const GetContextInputSchema = z.object({
 // Schema for create_entities tool
 export const CreateEntitiesInputSchema = z.object({
     threadId: z.string().min(1).describe("Thread ID for this conversation/project"),
-    entities: z.array(EntitySchema).describe("Array of entities to create")
+    entities: z.array(EntityInputSchema).describe("Array of entities to create")
 }).superRefine((data, ctx) => {
     const { threadId, entities } = data;
     entities.forEach((entity, index) => {
@@ -218,7 +231,7 @@ export const CreateEntitiesInputSchema = z.object({
 // Schema for create_relations tool
 export const CreateRelationsInputSchema = z.object({
     threadId: z.string().min(1).describe("Thread ID for this conversation/project"),
-    relations: z.array(RelationSchema).describe("Array of relations to create")
+    relations: z.array(RelationInputSchema).describe("Array of relations to create")
 }).superRefine((data, ctx) => {
     const { threadId, relations } = data;
     relations.forEach((relation, index) => {
@@ -269,7 +282,7 @@ export const DeleteObservationsInputSchema = z.object({
 // Schema for delete_relations tool
 export const DeleteRelationsInputSchema = z.object({
     threadId: z.string().min(1).describe("Thread ID for this conversation/project"),
-    relations: z.array(RelationSchema).describe("An array of relations to delete")
+    relations: z.array(RelationInputSchema).describe("An array of relations to delete")
 });
 // Schema for prune_memory tool
 export const PruneMemoryInputSchema = z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "server-memory-enhanced",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Persistent memory for long conversations - MCP server for knowledge graph with atomic facts, cross-chat memory sharing, and multi-agent delegation",
   "license": "MIT",
   "mcpName": "io.github.modelcontextprotocol/server-memory-enhanced",