Rename some things (#2)

* getMemories -> recall

* Rename key to scope

* better file name

Author: murrayju

migrations/1757006007963-rename-key-scope.js

@@ -0,0 +1,31 @@
+import { Client } from 'pg';
+
+const schema = process.env.DB_SCHEMA || 'tiger_memory';
+
+export const description = 'Rename key column to scope in memory table';
+
+export async function up() {
+  const client = new Client();
+
+  try {
+    await client.connect();
+    await client.query(/* sql */ `
+      ALTER TABLE ${schema}.memory RENAME COLUMN key TO scope;
+    `);
+  } finally {
+    await client.end();
+  }
+}
+
+export async function down() {
+  const client = new Client();
+
+  try {
+    await client.connect();
+    await client.query(/* sql */ `
+      ALTER TABLE ${schema}.memory RENAME COLUMN scope TO key;
+    `);
+  } finally {
+    await client.end();
+  }
+}

src/apis/forget.ts

@@ -1,14 +1,14 @@
 import { z } from 'zod';
 import { ApiFactory } from '../shared/boilerplate/src/types.js';
-import { ServerContext, zKey } from '../types.js';
+import { ServerContext, zScope } from '../types.js';
 import { StatusError } from '../shared/boilerplate/src/StatusError.js';
 
 const inputSchema = {
   id: z.coerce
     .string()
     .min(1)
     .describe('The id of a specific memory to delete.'),
-  key: zKey,
+  scope: zScope,
 } as const;
 
 const outputSchema = {
@@ -30,15 +30,15 @@ export const forgetFactory: ApiFactory<
     inputSchema,
     outputSchema,
   },
-  fn: async ({ id, key }) => {
+  fn: async ({ id, scope }) => {
     const result = await pgPool.query<{ id: string }>(
       /* sql */ `
 UPDATE ${schema}.memory
 SET deleted_at = NOW(), updated_at = NOW()
-WHERE id = $1 AND key = $2 AND deleted_at IS NULL
+WHERE id = $1 AND scope = $2 AND deleted_at IS NULL
 RETURNING id
 `,
-      [id, key],
+      [id, scope],
     );
 
     if (result.rows[0]?.id == null) {

src/apis/index.ts

@@ -1,11 +1,11 @@
 import { forgetFactory } from './forget.js';
-import { getMemoriesFactory } from './getMemories.js';
+import { recallFactory } from './recall.js';
 import { rememberFactory } from './remember.js';
 import { updateFactory } from './update.js';
 
 export const apiFactories = [
   rememberFactory,
   updateFactory,
   forgetFactory,
-  getMemoriesFactory,
+  recallFactory,
 ] as const;

src/apis/getMemories.ts src/apis/recall.tssrc/apis/getMemories.ts renamed to src/apis/recall.ts

@@ -1,44 +1,44 @@
 import { z } from 'zod';
 import { ApiFactory } from '../shared/boilerplate/src/types.js';
-import { Memory, ServerContext, zKey, zMemory } from '../types.js';
+import { Memory, ServerContext, zScope, zMemory } from '../types.js';
 
 const inputSchema = {
-  key: zKey,
+  scope: zScope,
 } as const;
 
 const outputSchema = {
   memories: z.array(zMemory).describe('The list of memories found.'),
-  key: zKey,
+  scope: zScope,
 } as const;
 
-export const getMemoriesFactory: ApiFactory<
+export const recallFactory: ApiFactory<
   ServerContext,
   typeof inputSchema,
   typeof outputSchema
 > = ({ pgPool, schema }) => ({
-  name: 'getMemories',
+  name: 'recall',
   method: 'get',
-  route: ['/memory', '/memory/:key'],
+  route: ['/memory', '/memory/:scope'],
   config: {
-    title: 'Retrieve memories by key',
+    title: 'Retrieve memories by scope',
     description:
-      'This endpoint retrieves memories from the database, using the provided key as the scope.',
+      'This endpoint retrieves memories from the database, using the provided scope.',
     inputSchema,
     outputSchema,
   },
-  fn: async ({ key }) => {
+  fn: async ({ scope }) => {
     const result = await pgPool.query<Memory>(
       /* sql */ `
 SELECT id, content, source, created_at, updated_at
 FROM ${schema}.memory
-WHERE key = $1 AND deleted_at IS NULL
+WHERE scope = $1 AND deleted_at IS NULL
 `,
-      [key],
+      [scope],
     );
 
     return {
       memories: result.rows,
-      key,
+      scope,
     };
   },
 });

src/apis/remember.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 import { ApiFactory } from '../shared/boilerplate/src/types.js';
-import { ServerContext, zKey, zSource } from '../types.js';
+import { ServerContext, zScope, zSource } from '../types.js';
 
 const inputSchema = {
-  key: zKey,
+  scope: zScope,
   content: z.string().min(1).describe('The content to remember.'),
   source: zSource,
 } as const;
@@ -23,18 +23,18 @@ export const rememberFactory: ApiFactory<
   config: {
     title: 'Store a new memory',
     description:
-      'This endpoint stores a new memory in the database, using the provided key as the scope.',
+      'This endpoint stores a new memory in the database, using the provided scope.',
     inputSchema,
     outputSchema,
   },
-  fn: async ({ key, content, source }) => {
+  fn: async ({ scope, content, source }) => {
     const result = await pgPool.query<{ id: string }>(
       /* sql */ `
-INSERT INTO ${schema}.memory (key, content, source)
+INSERT INTO ${schema}.memory (scope, content, source)
 VALUES ($1, $2, $3)
 RETURNING id
 `,
-      [key, content, source || null],
+      [scope, content, source || null],
     );
 
     return {

src/apis/update.ts

@@ -1,14 +1,14 @@
 import { z } from 'zod';
 import { ApiFactory } from '../shared/boilerplate/src/types.js';
-import { ServerContext, zKey, zSource } from '../types.js';
+import { ServerContext, zScope, zSource } from '../types.js';
 import { StatusError } from '../shared/boilerplate/src/StatusError.js';
 
 const inputSchema = {
   id: z.coerce
     .string()
     .min(1)
     .describe('The id of a specific memory to replace.'),
-  key: zKey,
+  scope: zScope,
   content: z.string().min(1).describe('The new content to remember.'),
   source: zSource,
 } as const;
@@ -32,15 +32,15 @@ export const updateFactory: ApiFactory<
     inputSchema,
     outputSchema,
   },
-  fn: async ({ id, key, content, source }) => {
+  fn: async ({ id, scope, content, source }) => {
     const result = await pgPool.query<{ id: string }>(
       /* sql */ `
 UPDATE ${schema}.memory
 SET content = $1, source = $2, updated_at = NOW()
-WHERE id = $3 AND key = $4 AND deleted_at IS NULL
+WHERE id = $3 AND scope = $4 AND deleted_at IS NULL
 RETURNING id
 `,
-      [content, source || null, id, key],
+      [content, source || null, id, scope],
     );
 
     if (result.rows[0]?.id == null) {

src/resources.ts

@@ -11,26 +11,26 @@ export const additionalSetup = ({
 }: AdditionalSetupArgs<ServerContext>) => {
   server.registerResource(
     'memories',
-    new ResourceTemplate('memory://{key}', { list: undefined }),
+    new ResourceTemplate('memory://{scope}', { list: undefined }),
     {
       title: 'Memories',
       description: 'A collection of memories',
     },
-    async (uri, { key }) => {
+    async (uri, { scope }) => {
       const result = await pgPool.query<Memory>(
         /* sql */ `
 SELECT id, content, created_at, updated_at
 FROM ${schema}.memory
-WHERE key = $1 AND deleted_at IS NULL
+WHERE scope = $1 AND deleted_at IS NULL
 `,
-        [key],
+        [scope],
       );
 
       return {
         contents: [
           {
             uri: uri.href,
-            text: `Memories: key=\`${key}\`, count=${result.rows.length}
+            text: `Memories: scope=\`${scope}\`, count=${result.rows.length}
 ${result.rows.map((m) => `- (${m.id}) ${m.content}`).join('\n')}
 `,
           },

src/types.ts

@@ -28,9 +28,9 @@ export const zMemory = z.object({
 
 export type Memory = z.infer<typeof zMemory>;
 
-export const zKey = z
+export const zScope = z
   .string()
   .min(1)
   .describe(
-    'A unique identifier for the target set of memories. Can be any combination of user and application ids, as needed for scoping and personalization.',
+    'A unique identifier for the target set of memories. Can be any combination of user, application, contextual ids, as needed for scoping and personalization.',
   );