convex-agent-knowledge 0.0.1

package/src/client/types.ts

@@ -0,0 +1,141 @@
+export type SearchType = "semantic" | "graph" | "hybrid";
+
+export type MemorySource = {
+  type: string;
+  id?: string;
+  url?: string;
+  title?: string;
+};
+
+export type ExtractedEntity = {
+  externalId: string;
+  name: string;
+  type: string;
+  description?: string;
+  aliases?: string[];
+  confidence?: number;
+  metadata?: unknown;
+};
+
+export type ExtractedRelationship = {
+  fromEntityExternalId: string;
+  toEntityExternalId: string;
+  type: string;
+  description?: string;
+  confidence?: number;
+  weight?: number;
+  metadata?: unknown;
+};
+
+export type ExtractedKnowledge = {
+  entities: ExtractedEntity[];
+  relationships: ExtractedRelationship[];
+};
+
+export type ChunkInput = {
+  text: string;
+  summary?: string;
+  tokenCount?: number;
+  metadata?: unknown;
+};
+
+export type EmbeddedChunkInput = ChunkInput & {
+  embedding: number[];
+};
+
+export type Neo4jConfig = {
+  uri: string;
+  user: string;
+  password: string;
+  database?: string;
+};
+
+export type GraphSyncJob = {
+  jobId: string;
+  namespace: string;
+  operation: "upsert_memory" | "delete_memory" | "promote_memory";
+  attempts: number;
+  payload: unknown;
+};
+
+export type GraphMemoryScore = {
+  memoryId: string;
+  graphScore: number;
+};
+
+export type GraphExpandInput = {
+  namespace: string;
+  seedMemoryIds: string[];
+  entityHints?: string[];
+  hops?: number;
+  limit?: number;
+};
+
+export type GraphStore = {
+  syncJob: (job: GraphSyncJob) => Promise<void>;
+  expand: (input: GraphExpandInput) => Promise<GraphMemoryScore[]>;
+};
+
+export type MemoryCard = {
+  memoryId: string;
+  namespace: string;
+  key?: string;
+  agentId?: string;
+  text: string;
+  score: number;
+  semanticScore?: number;
+  graphScore?: number;
+  importance: number;
+  source?: MemorySource;
+  metadata?: unknown;
+  entities: Array<{
+    externalId: string;
+    name: string;
+    type: string;
+    description?: string;
+    confidence: number;
+  }>;
+  relationships: Array<{
+    fromEntityExternalId: string;
+    toEntityExternalId: string;
+    type: string;
+    description?: string;
+    confidence: number;
+    weight: number;
+  }>;
+};
+
+export type AgentKnowledgeComponent = {
+  actions: {
+    recall: unknown;
+  };
+  mutations: {
+    remember: unknown;
+    observe: unknown;
+    promote: unknown;
+    deleteByKey: unknown;
+    markGraphSyncJobRunning: unknown;
+    markGraphSyncJobSucceeded: unknown;
+    markGraphSyncJobFailed: unknown;
+  };
+  queries: {
+    getMemory: unknown;
+    listMemories: unknown;
+    fetchMemoryCards: unknown;
+    listPendingGraphSyncJobs: unknown;
+  };
+};
+
+export type ConvexActionCtx = {
+  runAction: (functionReference: unknown, args: Record<string, unknown>) => Promise<any>;
+  runMutation: (functionReference: unknown, args: Record<string, unknown>) => Promise<any>;
+  runQuery: (functionReference: unknown, args: Record<string, unknown>) => Promise<any>;
+};
+
+export type ConvexMutationCtx = {
+  runMutation: (functionReference: unknown, args: Record<string, unknown>) => Promise<any>;
+};
+
+export type ConvexQueryCtx = {
+  runQuery: (functionReference: unknown, args: Record<string, unknown>) => Promise<any>;
+};

package/src/component/_generated/api.ts

@@ -0,0 +1,56 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as actions from "../actions.js";
+import type * as mutations from "../mutations.js";
+import type * as queries from "../queries.js";
+import type * as validators from "../validators.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+import { anyApi, componentsGeneric } from "convex/server";
+
+const fullApi: ApiFromModules<{
+  actions: typeof actions;
+  mutations: typeof mutations;
+  queries: typeof queries;
+  validators: typeof validators;
+}> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+> = anyApi as any;
+
+export const components = componentsGeneric() as unknown as {};

package/src/component/_generated/component.ts

@@ -0,0 +1,310 @@
+/* eslint-disable */
+/**
+ * Generated `ComponentApi` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type { FunctionReference } from "convex/server";
+
+/**
+ * A utility for referencing a Convex component's exposed API.
+ *
+ * Useful when expecting a parameter like `components.myComponent`.
+ * Usage:
+ * ```ts
+ * async function myFunction(ctx: QueryCtx, component: ComponentApi) {
+ *   return ctx.runQuery(component.someFile.someQuery, { ...args });
+ * }
+ * ```
+ */
+export type ComponentApi<Name extends string | undefined = string | undefined> =
+  {
+    actions: {
+      recall: FunctionReference<
+        "action",
+        "internal",
+        {
+          agentId?: string;
+          embeddingDimension: number;
+          limit?: number;
+          namespace: string;
+          query: string;
+          queryEmbedding?: Array<number>;
+          searchType?: "semantic" | "graph" | "hybrid";
+        },
+        {
+          results: Array<{
+            agentId?: string;
+            entities: Array<{
+              confidence: number;
+              description?: string;
+              externalId: string;
+              name: string;
+              type: string;
+            }>;
+            graphScore?: number;
+            importance: number;
+            key?: string;
+            memoryId: string;
+            metadata?: any;
+            namespace: string;
+            relationships: Array<{
+              confidence: number;
+              description?: string;
+              fromEntityExternalId: string;
+              toEntityExternalId: string;
+              type: string;
+              weight: number;
+            }>;
+            score: number;
+            semanticScore?: number;
+            source?: {
+              id?: string;
+              title?: string;
+              type: string;
+              url?: string;
+            };
+            text: string;
+          }>;
+        },
+        Name
+      >;
+    };
+    mutations: {
+      deleteByKey: FunctionReference<
+        "mutation",
+        "internal",
+        { key: string; namespace: string },
+        { deleted: boolean; graphSyncJobId?: string; memoryId?: string },
+        Name
+      >;
+      markGraphSyncJobFailed: FunctionReference<
+        "mutation",
+        "internal",
+        { error: string; jobId: string },
+        null,
+        Name
+      >;
+      markGraphSyncJobRunning: FunctionReference<
+        "mutation",
+        "internal",
+        { jobId: string },
+        null,
+        Name
+      >;
+      markGraphSyncJobSucceeded: FunctionReference<
+        "mutation",
+        "internal",
+        { jobId: string },
+        null,
+        Name
+      >;
+      observe: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          feedback?: string;
+          memoryId: string;
+          metadata?: any;
+          namespace: string;
+          outcome: "helpful" | "not_helpful" | "neutral";
+          query: string;
+        },
+        null,
+        Name
+      >;
+      promote: FunctionReference<
+        "mutation",
+        "internal",
+        { limit?: number; namespace: string },
+        { promoted: number },
+        Name
+      >;
+      remember: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          agentId?: string;
+          chunks: Array<{
+            embedding: Array<number>;
+            metadata?: any;
+            summary?: string;
+            text: string;
+            tokenCount?: number;
+          }>;
+          contentHash: string;
+          embeddingDimension: number;
+          entities: Array<{
+            aliases?: Array<string>;
+            confidence?: number;
+            description?: string;
+            externalId: string;
+            metadata?: any;
+            name: string;
+            type: string;
+          }>;
+          importance?: number;
+          key?: string;
+          metadata?: any;
+          namespace: string;
+          relationships: Array<{
+            confidence?: number;
+            description?: string;
+            fromEntityExternalId: string;
+            metadata?: any;
+            toEntityExternalId: string;
+            type: string;
+            weight?: number;
+          }>;
+          source?: { id?: string; title?: string; type: string; url?: string };
+          text: string;
+        },
+        {
+          chunkCount: number;
+          entityCount: number;
+          graphSyncJobId: string;
+          memoryId: string;
+          relationshipCount: number;
+          replacedMemoryId?: string;
+        },
+        Name
+      >;
+    };
+    queries: {
+      fetchMemoryCards: FunctionReference<
+        "query",
+        "internal",
+        {
+          matches: Array<{
+            graphScore?: number;
+            memoryId: string;
+            score: number;
+            semanticScore?: number;
+          }>;
+        },
+        Array<{
+          agentId?: string;
+          entities: Array<{
+            confidence: number;
+            description?: string;
+            externalId: string;
+            name: string;
+            type: string;
+          }>;
+          graphScore?: number;
+          importance: number;
+          key?: string;
+          memoryId: string;
+          metadata?: any;
+          namespace: string;
+          relationships: Array<{
+            confidence: number;
+            description?: string;
+            fromEntityExternalId: string;
+            toEntityExternalId: string;
+            type: string;
+            weight: number;
+          }>;
+          score: number;
+          semanticScore?: number;
+          source?: { id?: string; title?: string; type: string; url?: string };
+          text: string;
+        }>,
+        Name
+      >;
+      getMemory: FunctionReference<
+        "query",
+        "internal",
+        { memoryId: string },
+        {
+          agentId?: string;
+          entities: Array<{
+            confidence: number;
+            description?: string;
+            externalId: string;
+            name: string;
+            type: string;
+          }>;
+          graphScore?: number;
+          importance: number;
+          key?: string;
+          memoryId: string;
+          metadata?: any;
+          namespace: string;
+          relationships: Array<{
+            confidence: number;
+            description?: string;
+            fromEntityExternalId: string;
+            toEntityExternalId: string;
+            type: string;
+            weight: number;
+          }>;
+          score: number;
+          semanticScore?: number;
+          source?: { id?: string; title?: string; type: string; url?: string };
+          text: string;
+        } | null,
+        Name
+      >;
+      listMemories: FunctionReference<
+        "query",
+        "internal",
+        { cursor?: string; limit?: number; namespace: string },
+        {
+          continueCursor: string | null;
+          isDone: boolean;
+          page: Array<{
+            agentId?: string;
+            entities: Array<{
+              confidence: number;
+              description?: string;
+              externalId: string;
+              name: string;
+              type: string;
+            }>;
+            graphScore?: number;
+            importance: number;
+            key?: string;
+            memoryId: string;
+            metadata?: any;
+            namespace: string;
+            relationships: Array<{
+              confidence: number;
+              description?: string;
+              fromEntityExternalId: string;
+              toEntityExternalId: string;
+              type: string;
+              weight: number;
+            }>;
+            score: number;
+            semanticScore?: number;
+            source?: {
+              id?: string;
+              title?: string;
+              type: string;
+              url?: string;
+            };
+            text: string;
+          }>;
+        },
+        Name
+      >;
+      listPendingGraphSyncJobs: FunctionReference<
+        "query",
+        "internal",
+        { limit: number },
+        Array<{
+          attempts: number;
+          jobId: string;
+          namespace: string;
+          operation: string;
+          payload: any;
+        }>,
+        Name
+      >;
+    };
+  };

package/src/component/_generated/dataModel.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;