@waynesutton/agent-memory 0.0.1-alpha.1

package/src/component/apiKeyMutations.ts

@@ -0,0 +1,175 @@
+import { mutation } from "./_generated/server.js";
+import { v } from "convex/values";
+
+// ── Hash helper ─────────────────────────────────────────────────────
+// Simple FNV-1a based hash for API key storage.
+// We use the same checksum function as the rest of the component
+// for consistency. For API keys the security model is "bearer token
+// stored in database" — the hash prevents plaintext key exposure
+// if the database is inspected, but the real security boundary is
+// Convex's deployment isolation.
+
+function hashKey(key: string): string {
+  let hash = 2166136261;
+  for (let i = 0; i < key.length; i++) {
+    hash ^= key.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+function generateKey(): string {
+  // Generate a URL-safe random key with "am_" prefix
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+  let key = "am_";
+  for (let i = 0; i < 40; i++) {
+    key += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return key;
+}
+
+// ── createApiKey ────────────────────────────────────────────────────
+
+export const createApiKey = mutation({
+  args: {
+    projectId: v.string(),
+    name: v.string(),
+    permissions: v.array(v.string()),
+    rateLimitOverride: v.optional(
+      v.object({
+        requestsPerWindow: v.float64(),
+        windowMs: v.float64(),
+      }),
+    ),
+    expiresAt: v.optional(v.float64()),
+  },
+  returns: v.object({
+    key: v.string(), // plaintext key — only returned once
+    keyHash: v.string(),
+  }),
+  handler: async (ctx, args) => {
+    const key = generateKey();
+    const keyHash = hashKey(key);
+
+    await ctx.db.insert("apiKeys", {
+      keyHash,
+      projectId: args.projectId,
+      name: args.name,
+      permissions: args.permissions,
+      rateLimitOverride: args.rateLimitOverride,
+      expiresAt: args.expiresAt,
+      revoked: false,
+    });
+
+    return { key, keyHash };
+  },
+});
+
+// ── revokeApiKey ────────────────────────────────────────────────────
+
+export const revokeApiKey = mutation({
+  args: {
+    keyHash: v.string(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("apiKeys")
+      .withIndex("by_key", (q: any) => q.eq("keyHash", args.keyHash))
+      .first();
+
+    if (!existing) throw new Error(`API key not found: ${args.keyHash}`);
+
+    await ctx.db.patch(existing._id, { revoked: true });
+    return null;
+  },
+});
+
+// ── consumeRateLimit ────────────────────────────────────────────────
+// Atomically checks and increments the rate limit counter.
+// Returns whether the request is allowed and how many tokens remain.
+
+export const consumeRateLimit = mutation({
+  args: {
+    keyHash: v.string(),
+    requestsPerWindow: v.float64(),
+    windowMs: v.float64(),
+  },
+  returns: v.object({
+    allowed: v.boolean(),
+    remaining: v.float64(),
+    retryAfterMs: v.float64(),
+  }),
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const windowStart =
+      Math.floor(now / args.windowMs) * args.windowMs;
+
+    // Look for existing token record for this window
+    const existing = await ctx.db
+      .query("rateLimitTokens")
+      .withIndex("by_key_window", (q: any) =>
+        q.eq("keyHash", args.keyHash).eq("windowStart", windowStart),
+      )
+      .first();
+
+    if (!existing) {
+      // First request in this window
+      await ctx.db.insert("rateLimitTokens", {
+        keyHash: args.keyHash,
+        windowStart,
+        tokenCount: 1,
+      });
+      return {
+        allowed: true,
+        remaining: args.requestsPerWindow - 1,
+        retryAfterMs: 0,
+      };
+    }
+
+    if (existing.tokenCount >= args.requestsPerWindow) {
+      // Rate limited
+      const windowEnd = windowStart + args.windowMs;
+      return {
+        allowed: false,
+        remaining: 0,
+        retryAfterMs: windowEnd - now,
+      };
+    }
+
+    // Consume a token
+    await ctx.db.patch(existing._id, {
+      tokenCount: existing.tokenCount + 1,
+    });
+
+    return {
+      allowed: true,
+      remaining: args.requestsPerWindow - existing.tokenCount - 1,
+      retryAfterMs: 0,
+    };
+  },
+});
+
+// ── cleanupRateLimitTokens (internal, used by cron) ─────────────────
+
+import { internalMutation } from "./_generated/server.js";
+
+export const cleanupRateLimitTokens = internalMutation({
+  args: {},
+  returns: v.object({ deleted: v.float64() }),
+  handler: async (ctx) => {
+    // Delete token records older than 1 hour (well past any window)
+    const cutoff = Date.now() - 60 * 60 * 1000;
+    const old = await ctx.db.query("rateLimitTokens").take(500);
+
+    let deleted = 0;
+    for (const record of old) {
+      if (record.windowStart < cutoff) {
+        await ctx.db.delete(record._id);
+        deleted++;
+      }
+    }
+
+    return { deleted };
+  },
+});

package/src/component/apiKeyQueries.ts

@@ -0,0 +1,156 @@
+import { query } from "./_generated/server.js";
+import { v } from "convex/values";
+
+// ── Hash helper (same as in apiKeyMutations.ts) ─────────────────────
+
+function hashKey(key: string): string {
+  let hash = 2166136261;
+  for (let i = 0; i < key.length; i++) {
+    hash ^= key.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+// ── validateApiKey ──────────────────────────────────────────────────
+// Called by HTTP handlers to verify an API key and get its permissions.
+
+export const validateApiKey = query({
+  args: {
+    key: v.string(), // plaintext key from Authorization header
+  },
+  returns: v.union(
+    v.object({
+      valid: v.literal(true),
+      keyHash: v.string(),
+      projectId: v.string(),
+      permissions: v.array(v.string()),
+      rateLimit: v.object({
+        requestsPerWindow: v.float64(),
+        windowMs: v.float64(),
+      }),
+    }),
+    v.object({
+      valid: v.literal(false),
+      reason: v.string(),
+    }),
+  ),
+  handler: async (ctx, args) => {
+    const keyHash = hashKey(args.key);
+
+    const apiKey = await ctx.db
+      .query("apiKeys")
+      .withIndex("by_key", (q: any) => q.eq("keyHash", keyHash))
+      .first();
+
+    if (!apiKey) {
+      return { valid: false as const, reason: "Invalid API key" };
+    }
+
+    if (apiKey.revoked) {
+      return { valid: false as const, reason: "API key has been revoked" };
+    }
+
+    if (apiKey.expiresAt && apiKey.expiresAt < Date.now()) {
+      return { valid: false as const, reason: "API key has expired" };
+    }
+
+    // Determine rate limit: key override > project setting > global default
+    let rateLimit = { requestsPerWindow: 100, windowMs: 60000 };
+
+    if (apiKey.rateLimitOverride) {
+      rateLimit = apiKey.rateLimitOverride;
+    } else {
+      // Check project settings
+      const project = await ctx.db
+        .query("projects")
+        .withIndex("by_projectId", (q: any) =>
+          q.eq("projectId", apiKey.projectId),
+        )
+        .first();
+
+      if (project?.settings.apiRateLimit) {
+        rateLimit = project.settings.apiRateLimit;
+      }
+    }
+
+    return {
+      valid: true as const,
+      keyHash,
+      projectId: apiKey.projectId,
+      permissions: apiKey.permissions,
+      rateLimit,
+    };
+  },
+});
+
+// ── listApiKeys ─────────────────────────────────────────────────────
+// List all API keys for a project (without revealing the key itself).
+
+export const listApiKeys = query({
+  args: {
+    projectId: v.string(),
+  },
+  returns: v.array(
+    v.object({
+      _id: v.string(),
+      keyHash: v.string(),
+      projectId: v.string(),
+      name: v.string(),
+      permissions: v.array(v.string()),
+      rateLimitOverride: v.optional(
+        v.object({
+          requestsPerWindow: v.float64(),
+          windowMs: v.float64(),
+        }),
+      ),
+      lastUsedAt: v.optional(v.float64()),
+      expiresAt: v.optional(v.float64()),
+      revoked: v.boolean(),
+    }),
+  ),
+  handler: async (ctx, args) => {
+    const keys = await ctx.db
+      .query("apiKeys")
+      .withIndex("by_project", (q: any) =>
+        q.eq("projectId", args.projectId).eq("revoked", false),
+      )
+      .take(100);
+
+    return keys.map((k) => ({
+      _id: k._id as unknown as string,
+      keyHash: k.keyHash,
+      projectId: k.projectId,
+      name: k.name,
+      permissions: k.permissions,
+      rateLimitOverride: k.rateLimitOverride,
+      lastUsedAt: k.lastUsedAt,
+      expiresAt: k.expiresAt,
+      revoked: k.revoked,
+    }));
+  },
+});
+
+// ── updateKeyLastUsed ───────────────────────────────────────────────
+// Update the lastUsedAt timestamp on an API key (fire-and-forget from HTTP handler).
+
+import { mutation } from "./_generated/server.js";
+
+export const updateKeyLastUsed = mutation({
+  args: {
+    keyHash: v.string(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const apiKey = await ctx.db
+      .query("apiKeys")
+      .withIndex("by_key", (q: any) => q.eq("keyHash", args.keyHash))
+      .first();
+
+    if (apiKey) {
+      await ctx.db.patch(apiKey._id, { lastUsedAt: Date.now() });
+    }
+
+    return null;
+  },
+});

package/src/component/checksum.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect } from "vitest";
+import { computeChecksum } from "./checksum.js";
+
+describe("computeChecksum", () => {
+  it("returns a hex string", () => {
+    const hash = computeChecksum("hello world");
+    expect(hash).toMatch(/^[0-9a-f]{8}$/);
+  });
+
+  it("returns consistent results", () => {
+    const a = computeChecksum("test content");
+    const b = computeChecksum("test content");
+    expect(a).toBe(b);
+  });
+
+  it("returns different results for different inputs", () => {
+    const a = computeChecksum("content A");
+    const b = computeChecksum("content B");
+    expect(a).not.toBe(b);
+  });
+
+  it("handles empty string", () => {
+    const hash = computeChecksum("");
+    expect(hash).toMatch(/^[0-9a-f]{8}$/);
+  });
+
+  it("handles unicode content", () => {
+    const hash = computeChecksum("こんにちは世界 🌍");
+    expect(hash).toMatch(/^[0-9a-f]{8}$/);
+  });
+});

package/src/component/checksum.ts

@@ -0,0 +1,13 @@
+/**
+ * Compute a simple hash of content for change detection.
+ * Uses a fast string hash (FNV-1a) — not cryptographic, just for diffing.
+ */
+export function computeChecksum(content: string): string {
+  let hash = 2166136261;
+  for (let i = 0; i < content.length; i++) {
+    hash ^= content.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  // Convert to unsigned 32-bit hex
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}

package/src/component/convex.config.ts

@@ -0,0 +1,5 @@
+import { defineComponent } from "convex/server";
+
+const component = defineComponent("agentMemory");
+
+export default component;

package/src/component/cronActions.ts

@@ -0,0 +1,52 @@
+import { internalAction } from "./_generated/server.js";
+import { internal } from "./_generated/api.js";
+import { v } from "convex/values";
+
+// ── Decay: iterate all projects and apply decay ─────────────────────
+
+export const runDecayForAllProjects = internalAction({
+  args: {},
+  returns: v.null(),
+  handler: async (ctx) => {
+    // Get all projects that have decay enabled
+    const projects = await ctx.runQuery(
+      internal.cronQueries.listDecayEnabledProjects,
+    );
+
+    for (const project of projects) {
+      const halfLifeDays =
+        project.settings.decayHalfLifeDays ?? 30;
+
+      await ctx.runMutation(internal.mutations.applyDecay, {
+        projectId: project.projectId,
+        halfLifeDays,
+      });
+    }
+
+    return null;
+  },
+});
+
+// ── History cleanup: iterate all projects ───────────────────────────
+
+export const runHistoryCleanupForAllProjects = internalAction({
+  args: {},
+  returns: v.null(),
+  handler: async (ctx) => {
+    const projects = await ctx.runQuery(
+      internal.cronQueries.listAllProjectIds,
+    );
+
+    // 90 days in milliseconds
+    const ninetyDaysMs = 90 * 24 * 60 * 60 * 1000;
+
+    for (const projectId of projects) {
+      await ctx.runMutation(internal.mutations.cleanupOldHistory, {
+        projectId,
+        olderThanMs: ninetyDaysMs,
+      });
+    }
+
+    return null;
+  },
+});

package/src/component/cronQueries.ts

@@ -0,0 +1,42 @@
+import { internalQuery } from "./_generated/server.js";
+import { v } from "convex/values";
+
+// List projects that have relevance decay enabled
+export const listDecayEnabledProjects = internalQuery({
+  args: {},
+  returns: v.array(
+    v.object({
+      projectId: v.string(),
+      settings: v.object({
+        autoSync: v.boolean(),
+        syncFormats: v.array(v.string()),
+        embeddingModel: v.optional(v.string()),
+        embeddingDimensions: v.optional(v.float64()),
+        factExtractionPrompt: v.optional(v.string()),
+        updateDecisionPrompt: v.optional(v.string()),
+        decayEnabled: v.optional(v.boolean()),
+        decayHalfLifeDays: v.optional(v.float64()),
+      }),
+    }),
+  ),
+  handler: async (ctx) => {
+    const allProjects = await ctx.db.query("projects").take(100);
+
+    return allProjects
+      .filter((p) => p.settings.decayEnabled === true)
+      .map((p) => ({
+        projectId: p.projectId,
+        settings: p.settings,
+      }));
+  },
+});
+
+// List all project IDs (for cleanup cron)
+export const listAllProjectIds = internalQuery({
+  args: {},
+  returns: v.array(v.string()),
+  handler: async (ctx) => {
+    const allProjects = await ctx.db.query("projects").take(100);
+    return allProjects.map((p) => p.projectId);
+  },
+});

package/src/component/crons.ts

@@ -0,0 +1,34 @@
+import { cronJobs } from "convex/server";
+import { internal } from "./_generated/api.js";
+
+const crons = cronJobs();
+
+// Run relevance decay daily at 3 AM UTC
+// This reduces priority of stale, low-access memories so they don't
+// dominate context bundles over time.
+// Note: The cron calls an internal action that iterates projects with
+// decay enabled and applies the decay function to each.
+crons.daily(
+  "relevance-decay",
+  { hourUTC: 3, minuteUTC: 0 },
+  internal.cronActions.runDecayForAllProjects,
+);
+
+// Clean up old history entries weekly (Sundays at 4 AM UTC)
+// Keeps the memoryHistory table from growing unbounded.
+// Retains the last 90 days of history by default.
+crons.weekly(
+  "cleanup-old-history",
+  { dayOfWeek: "sunday", hourUTC: 4, minuteUTC: 0 },
+  internal.cronActions.runHistoryCleanupForAllProjects,
+);
+
+// Clean up expired rate limit token records hourly
+// Removes window records older than 1 hour to prevent unbounded growth.
+crons.interval(
+  "cleanup-rate-limit-tokens",
+  { hours: 1 },
+  internal.apiKeyMutations.cleanupRateLimitTokens,
+);
+
+export default crons;

package/src/component/format.test.ts

@@ -0,0 +1,133 @@
+import { describe, it, expect } from "vitest";
+import { formatMemoryForTool } from "./format.js";
+
+const baseMemory = {
+  _id: "test-id" as any,
+  _creationTime: Date.now(),
+  projectId: "test-project",
+  scope: "project" as const,
+  title: "api-rules",
+  content: "# API Rules\n\n- Use camelCase\n- Return JSON",
+  memoryType: "instruction" as const,
+  tags: ["api", "style"],
+  priority: 0.9,
+  source: "claude-code",
+  checksum: "abc12345",
+  archived: false,
+};
+
+describe("formatMemoryForTool", () => {
+  describe("claude-code", () => {
+    it("formats instructions as .claude/rules/*.md", () => {
+      const result = formatMemoryForTool(baseMemory, "claude-code", "my-project");
+      expect(result.path).toBe(".claude/rules/api-rules.md");
+      expect(result.content).toContain("# API Rules");
+    });
+
+    it("formats learnings under .claude/projects/", () => {
+      const learning = { ...baseMemory, memoryType: "learning" as const };
+      const result = formatMemoryForTool(learning, "claude-code", "my-project");
+      expect(result.path).toBe(".claude/projects/my-project/memory/api-rules.md");
+    });
+
+    it("includes paths as YAML frontmatter", () => {
+      const withPaths = { ...baseMemory, paths: ["src/**/*.ts"] };
+      const result = formatMemoryForTool(withPaths, "claude-code");
+      expect(result.content).toContain("---");
+      expect(result.content).toContain("paths:");
+      expect(result.content).toContain("src/**/*.ts");
+    });
+  });
+
+  describe("cursor", () => {
+    it("formats as .cursor/rules/*.mdc", () => {
+      const result = formatMemoryForTool(baseMemory, "cursor");
+      expect(result.path).toBe(".cursor/rules/api-rules.mdc");
+      expect(result.content).toContain("description: api-rules");
+      expect(result.content).toContain("alwaysApply: true"); // priority 0.9 >= 0.8
+    });
+
+    it("sets alwaysApply false for low priority", () => {
+      const low = { ...baseMemory, priority: 0.3 };
+      const result = formatMemoryForTool(low, "cursor");
+      expect(result.content).toContain("alwaysApply: false");
+    });
+  });
+
+  describe("opencode", () => {
+    it("formats instructions as AGENTS.md sections", () => {
+      const result = formatMemoryForTool(baseMemory, "opencode");
+      expect(result.path).toBe("AGENTS.md");
+      expect(result.content).toContain("## api-rules");
+    });
+
+    it("formats journals as separate files", () => {
+      const journal = { ...baseMemory, memoryType: "journal" as const };
+      const result = formatMemoryForTool(journal, "opencode");
+      expect(result.path).toBe("journal/api-rules.md");
+    });
+  });
+
+  describe("codex", () => {
+    it("formats as AGENTS.md by default", () => {
+      const result = formatMemoryForTool(baseMemory, "codex");
+      expect(result.path).toBe("AGENTS.md");
+    });
+
+    it("uses common path prefix for scoped rules", () => {
+      const withPaths = { ...baseMemory, paths: ["src/api/routes.ts", "src/api/handlers.ts"] };
+      const result = formatMemoryForTool(withPaths, "codex");
+      expect(result.path).toBe("src/api/AGENTS.md");
+    });
+  });
+
+  describe("conductor", () => {
+    it("formats as .conductor/rules/*.md", () => {
+      const result = formatMemoryForTool(baseMemory, "conductor");
+      expect(result.path).toBe(".conductor/rules/api-rules.md");
+    });
+  });
+
+  describe("zed", () => {
+    it("formats as .zed/rules/*.md", () => {
+      const result = formatMemoryForTool(baseMemory, "zed");
+      expect(result.path).toBe(".zed/rules/api-rules.md");
+    });
+  });
+
+  describe("vscode-copilot", () => {
+    it("formats as .github/copilot-instructions.md", () => {
+      const result = formatMemoryForTool(baseMemory, "vscode-copilot");
+      expect(result.path).toBe(".github/copilot-instructions.md");
+      expect(result.content).toContain("## api-rules");
+    });
+  });
+
+  describe("pi", () => {
+    it("formats as .pi/rules/*.md", () => {
+      const result = formatMemoryForTool(baseMemory, "pi");
+      expect(result.path).toBe(".pi/rules/api-rules.md");
+    });
+  });
+
+  describe("raw", () => {
+    it("includes full frontmatter", () => {
+      const result = formatMemoryForTool(baseMemory, "raw");
+      expect(result.path).toBe("memories/api-rules.md");
+      expect(result.content).toContain("title: api-rules");
+      expect(result.content).toContain("type: instruction");
+      expect(result.content).toContain("scope: project");
+      expect(result.content).toContain("tags:");
+    });
+  });
+
+  describe("filename sanitization", () => {
+    it("sanitizes special characters in titles", () => {
+      const special = { ...baseMemory, title: "My Rule (v2) & Notes!" };
+      const result = formatMemoryForTool(special, "zed");
+      expect(result.path).not.toContain("(");
+      expect(result.path).not.toContain("!");
+      expect(result.path).not.toContain("&");
+    });
+  });
+});