feat(memory): add expiry, supersession, and TTL support (#84)

- Add Expire() and Supersede() methods to the memory Store interface
- Expired entries excluded from Recall by default (IncludeExpired flag to override)
- Superseded entries store a forward pointer to the replacement
- StoreEntry accepts ExpiresAt for TTL-based auto-expiry at query time
- Dedup skips expired entries so replacements are not silently merged
- Stats now reports ExpiredCount and ActiveCount
- EventExpired lifecycle event for cache boundary managers
- REST endpoints: POST /v1/memory/expire, POST /v1/memory/supersede
- MCP tools: memory_expire, memory_supersede
- 12 new tests covering all expiry and supersession paths

Closes #79

Co-authored-by: Ona <no-reply@ona.com>

Author: Siddhant-K-code

cmd/api_memory.go

@@ -22,6 +22,8 @@ func (m *MemoryAPI) RegisterMemoryRoutes(mux *http.ServeMux, mw func(string, htt
 	mux.HandleFunc("/v1/memory/store", mw("/v1/memory/store", m.handleStore))
 	mux.HandleFunc("/v1/memory/recall", mw("/v1/memory/recall", m.handleRecall))
 	mux.HandleFunc("/v1/memory/forget", mw("/v1/memory/forget", m.handleForget))
+	mux.HandleFunc("/v1/memory/expire", mw("/v1/memory/expire", m.handleExpire))
+	mux.HandleFunc("/v1/memory/supersede", mw("/v1/memory/supersede", m.handleSupersede))
 	mux.HandleFunc("/v1/memory/stats", mw("/v1/memory/stats", m.handleStats))
 }
 
@@ -110,6 +112,66 @@ func (m *MemoryAPI) handleRecall(w http.ResponseWriter, r *http.Request) {
 	_ = json.NewEncoder(w).Encode(result)
 }
 
+func (m *MemoryAPI) handleExpire(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+
+	var req memory.ExpireRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeJSONError(w, "invalid request body", http.StatusBadRequest)
+		return
+	}
+
+	if len(req.IDs) == 0 {
+		writeJSONError(w, "ids is required", http.StatusBadRequest)
+		return
+	}
+
+	result, err := m.store.Expire(r.Context(), req)
+	if err != nil {
+		writeJSONError(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(result)
+}
+
+func (m *MemoryAPI) handleSupersede(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+
+	var req memory.SupersedeRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeJSONError(w, "invalid request body", http.StatusBadRequest)
+		return
+	}
+
+	if req.OldID == "" {
+		writeJSONError(w, "old_id is required", http.StatusBadRequest)
+		return
+	}
+
+	result, err := m.store.Supersede(r.Context(), req)
+	if err != nil {
+		code := http.StatusInternalServerError
+		if err == memory.ErrNotFound {
+			code = http.StatusNotFound
+		} else if err == memory.ErrAlreadyExpired {
+			code = http.StatusConflict
+		}
+		writeJSONError(w, err.Error(), code)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(result)
+}
+
 func (m *MemoryAPI) handleForget(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodDelete && r.Method != http.MethodPost {
 		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)

cmd/mcp.go

@@ -443,6 +443,27 @@ Use this to clean up outdated or incorrect memories.`),
 		)
 		s.AddTool(forgetMemoryTool, m.handleForgetMemory)
 
+		expireMemoryTool := mcp.NewTool("memory_expire",
+			mcp.WithDescription("Mark memory entries as expired. Expired entries are excluded from recall by default but remain in the store."),
+			mcp.WithArray("ids",
+				mcp.Description("Memory entry IDs to expire"),
+				mcp.Required(),
+			),
+		)
+		s.AddTool(expireMemoryTool, m.handleExpireMemory)
+
+		supersedeMemoryTool := mcp.NewTool("memory_supersede",
+			mcp.WithDescription("Mark a memory as superseded by a newer entry. The old entry is expired and a forward pointer to the replacement is stored."),
+			mcp.WithString("old_id",
+				mcp.Description("ID of the memory being superseded"),
+				mcp.Required(),
+			),
+			mcp.WithString("new_id",
+				mcp.Description("ID of the replacement memory"),
+			),
+		)
+		s.AddTool(supersedeMemoryTool, m.handleSupersedeMemory)
+
 		memoryStatsTool := mcp.NewTool("memory_stats",
 			mcp.WithDescription("Get statistics about the persistent memory store."),
 		)

cmd/mcp_memory.go

@@ -144,6 +144,53 @@ func (m *MCPServer) handleForgetMemory(ctx context.Context, request mcp.CallTool
 	return mcp.NewToolResultText(string(out)), nil
 }
 
+func (m *MCPServer) handleExpireMemory(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	args := request.GetArguments()
+
+	var ids []string
+	if idsRaw, ok := args["ids"].([]interface{}); ok {
+		for _, id := range idsRaw {
+			if s, ok := id.(string); ok {
+				ids = append(ids, s)
+			}
+		}
+	}
+
+	if len(ids) == 0 {
+		return mcp.NewToolResultError("ids is required"), nil
+	}
+
+	result, err := m.memStore.Expire(ctx, memory.ExpireRequest{IDs: ids})
+	if err != nil {
+		return mcp.NewToolResultError(fmt.Sprintf("expire error: %v", err)), nil
+	}
+
+	out, _ := json.MarshalIndent(result, "", "  ")
+	return mcp.NewToolResultText(string(out)), nil
+}
+
+func (m *MCPServer) handleSupersedeMemory(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	args := request.GetArguments()
+
+	oldID, _ := args["old_id"].(string)
+	newID, _ := args["new_id"].(string)
+
+	if oldID == "" {
+		return mcp.NewToolResultError("old_id is required"), nil
+	}
+
+	result, err := m.memStore.Supersede(ctx, memory.SupersedeRequest{
+		OldID: oldID,
+		NewID: newID,
+	})
+	if err != nil {
+		return mcp.NewToolResultError(fmt.Sprintf("supersede error: %v", err)), nil
+	}
+
+	out, _ := json.MarshalIndent(result, "", "  ")
+	return mcp.NewToolResultText(string(out)), nil
+}
+
 func (m *MCPServer) handleMemoryStats(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 	stats, err := m.memStore.Stats(ctx)
 	if err != nil {

pkg/memory/cache_events.go

@@ -20,6 +20,10 @@ const (
 	// EventEvicted fires when an entry is removed from the store entirely.
 	// Any cached prefix that included this entry must retreat.
 	EventEvicted MemoryEventType = "evicted"
+
+	// EventExpired fires when an entry is marked as expired or superseded.
+	// The entry remains in the store but is excluded from recall by default.
+	EventExpired MemoryEventType = "expired"
 )
 
 // MemoryEvent describes a single lifecycle transition for a memory entry.