add version history API: GET /memories/:id/versions and /agent/memories/:id/versions

Exposes the existing memory_versions snapshots through new read endpoints.
Dashboard and agent routes both supported. OpenAPI spec updated (14 ops).

Made-with: Cursor

Author: van-reflect

openapi-agent.yaml

@@ -20,6 +20,7 @@ servers:
   - url: https://api.reflectmemory.com
 
 components:
+  schemas: {}
   securitySchemes:
     oauth:
       type: oauth2
@@ -278,6 +279,48 @@ paths:
           description: Cannot delete a memory you did not create
         "404":
           description: Memory not found or already deleted
+  /agent/memories/{id}/versions:
+    get:
+      operationId: getVersionHistory
+      x-openai-isConsequential: false
+      summary: Get edit history for a memory
+      description: >
+        Returns all previous versions of a memory in reverse chronological order.
+        Each version is a full snapshot captured before an edit.
+        Use to review changes, audit edits, or compare past states.
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The memory UUID
+      responses:
+        "200":
+          description: Version history
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  versions:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id: { type: string }
+                        memory_id: { type: string }
+                        title: { type: string }
+                        content: { type: string }
+                        tags: { type: array, items: { type: string } }
+                        origin: { type: string }
+                        version_number: { type: integer }
+                        created_at: { type: string }
+                  current_version:
+                    type: integer
+                    description: The current version number (versions + 1)
+        "404":
+          description: Memory not found or not accessible
   /agent/memories/search:
     post:
       operationId: searchMemories

src/memory-service.ts

@@ -801,3 +801,49 @@ export function countTeamMemories(
     .get(teamId) as { cnt: number };
   return row.cnt;
 }
+
+export interface MemoryVersion {
+  id: string;
+  memory_id: string;
+  title: string;
+  content: string;
+  tags: string[];
+  origin: string;
+  allowed_vendors: string[];
+  memory_type: MemoryType;
+  version_number: number;
+  created_at: string;
+}
+
+export function getVersionHistory(
+  db: Database.Database,
+  userId: string,
+  memoryId: string,
+): MemoryVersion[] {
+  const owner = db
+    .prepare(`SELECT id FROM memories WHERE id = ? AND user_id = ?`)
+    .get(memoryId, userId);
+  if (!owner) return [];
+
+  const rows = db
+    .prepare(
+      `SELECT id, memory_id, title, content, tags, memory_type, origin, allowed_vendors, version_number, created_at
+       FROM memory_versions
+       WHERE memory_id = ?
+       ORDER BY version_number DESC`,
+    )
+    .all(memoryId) as Array<Record<string, string | number>>;
+
+  return rows.map((row) => ({
+    id: row.id as string,
+    memory_id: row.memory_id as string,
+    title: row.title as string,
+    content: row.content as string,
+    tags: safeJsonArray(row.tags as string),
+    origin: row.origin as string,
+    allowed_vendors: safeJsonArray(row.allowed_vendors as string),
+    memory_type: (row.memory_type as MemoryType) || "semantic",
+    version_number: row.version_number as number,
+    created_at: row.created_at as string,
+  }));
+}

src/server.ts

@@ -69,6 +69,7 @@ import {
   unshareMemory,
   listTeamMemories,
   countTeamMemories,
+  getVersionHistory,
 } from "./memory-service.js";
 import { buildPrompt, type PromptResult } from "./context-builder.js";
 import {
@@ -1609,6 +1610,35 @@ export async function createServer(config: ServerConfig): Promise<FastifyInstanc
     },
   );
 
+  // ===========================================================================
+  // GET /agent/memories/:id/versions -- Version history for agents
+  // ===========================================================================
+
+  server.get(
+    "/agent/memories/:id/versions",
+    {
+      schema: { params: memoryIdParamSchema },
+      config: { rateLimit: { max: 30, timeWindow: "1 minute" } },
+    },
+    async (request, reply) => {
+      const { id } = request.params as { id: string };
+      const memory = readMemoryById(db, request.userId, id);
+      if (!memory || memory.deleted_at) {
+        reply.code(404);
+        return { error: "Memory not found" };
+      }
+      if (request.vendor) {
+        const allowed = memory.allowed_vendors.includes("*") || memory.allowed_vendors.includes(request.vendor);
+        if (!allowed) {
+          reply.code(404);
+          return { error: "Memory not found" };
+        }
+      }
+      const versions = getVersionHistory(db, request.userId, id);
+      return { versions, current_version: versions.length + 1 };
+    },
+  );
+
   // ===========================================================================
   // PUT /agent/memories/:id -- Update a memory (agent path)
   // ===========================================================================
@@ -1973,6 +2003,30 @@ export async function createServer(config: ServerConfig): Promise<FastifyInstanc
     },
   );
 
+  // ===========================================================================
+  // GET /memories/:id/versions -- Version history for a memory (dashboard)
+  // ===========================================================================
+
+  server.get(
+    "/memories/:id/versions",
+    {
+      schema: { params: memoryIdParamSchema },
+      config: { rateLimit: { max: 30, timeWindow: "1 minute" } },
+    },
+    async (request, reply) => {
+      const { id } = request.params as { id: string };
+      const versions = getVersionHistory(db, request.userId, id);
+      if (versions.length === 0) {
+        const memory = readMemoryById(db, request.userId, id);
+        if (!memory) {
+          reply.code(404);
+          return { error: "Memory not found" };
+        }
+      }
+      return { versions };
+    },
+  );
+
   // ===========================================================================
   // POST /memories/list -- List memories with an explicit filter
   // ===========================================================================