xmemory-cli 0.1.0

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "xmemory-cli",
+  "version": "0.1.0",
+  "description": "xMemory CLI - Command-line interface for xMemory knowledge base",
+  "keywords": [
+    "xmemory",
+    "cli",
+    "memory",
+    "knowledge-base",
+    "ai"
+  ],
+  "bin": {
+    "xmemory-cli": "./bin/xmemory-cli.cjs"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "start": "node bin/xmemory-cli.cjs",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0",
+    "ora": "^8.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "esbuild": "^0.24.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/api/client.ts

@@ -0,0 +1,144 @@
+import { Config } from "../config/index.js";
+
+export class Client {
+  private baseUrl: string;
+  private apiKey: string;
+  private timeout: number;
+
+  constructor(config: Config) {
+    this.baseUrl = config.apiBaseUrl.replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+    this.timeout = 30000;
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+  ): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(this.timeout),
+    });
+
+    if (!response.ok) {
+      throw new Error(`API Error ${response.status}`);
+    }
+
+    return response.json();
+  }
+
+  async searchMemories(query: string, limit = 5, space?: string) {
+    const params = new URLSearchParams({ query, limit: limit.toString() });
+    if (space) params.append("space", space);
+    return this.request<{ results: MemoryResult[] }>(
+      `GET`,
+      `/memory?${params}`,
+    );
+  }
+
+  async addMemory(
+    content: string,
+    options: {
+      space?: string;
+      spaceId?: string;
+      tags?: string[];
+      source?: string;
+    },
+  ) {
+    return this.request<{ id: string; memoryId: string }>("POST", "/memory", {
+      content,
+      ...options,
+    });
+  }
+
+  async getMemory(id: string) {
+    return this.request<MemoryResult>("GET", `/memory/${id}`);
+  }
+
+  async deleteMemory(id: string) {
+    return this.request<{ success: boolean }>("DELETE", `/memory/${id}`);
+  }
+
+  async listSpaces() {
+    return this.request<{ spaces: Space[] }>("GET", "/spaces");
+  }
+
+  async createSpace(name: string, description?: string) {
+    return this.request<{ space: Space }>("POST", "/spaces", {
+      name,
+      description,
+    });
+  }
+
+  async deleteSpace(id: string) {
+    return this.request<{ success: boolean }>("DELETE", `/space?id=${id}`);
+  }
+
+  async getSpaceDetails(id: string) {
+    return this.request<{ space: SpaceDetails }>("GET", `/space?id=${id}`);
+  }
+
+  async listTags(spaceId?: string) {
+    const params = spaceId ? `?spaceId=${spaceId}` : "";
+    return this.request<{ tags: Tag[] }>("GET", `/tags${params}`);
+  }
+
+  async queryGraph(entityName?: string, tag?: string, spaceId?: string) {
+    const params = new URLSearchParams();
+    if (entityName) params.append("entityName", entityName);
+    if (tag) params.append("tag", tag);
+    if (spaceId) params.append("spaceId", spaceId);
+    return this.request<GraphResult>("GET", `/graph?${params}`);
+  }
+}
+
+export interface MemoryResult {
+  id: string;
+  content: string;
+  createdAt: string;
+  updatedAt: string;
+  tags?: string[];
+  source?: string;
+  similarity?: number;
+}
+
+export interface Space {
+  id: string;
+  name: string;
+  description?: string;
+  createdAt: string;
+}
+
+export interface SpaceDetails extends Space {
+  stats?: {
+    memoryCount: number;
+  };
+  latestMemories?: MemoryResult[];
+}
+
+export interface Tag {
+  name: string;
+  count: number;
+}
+
+export interface GraphResult {
+  nodes?: { id: string; name: string; type: string }[];
+  entity?: { name: string; type: string };
+  relationships?: {
+    outgoing?: { relation: string; targetName: string; description?: string }[];
+    incoming?: { relation: string; sourceName: string; description?: string }[];
+  };
+  message?: string;
+}

package/src/commands/add.ts

@@ -0,0 +1,36 @@
+import { Client } from "../api/client.js";
+import chalk from "chalk";
+
+export async function AddCommand(
+  client: Client,
+  content: string,
+  options: {
+    space?: string;
+    spaceId?: string;
+    tags?: string[];
+    source?: string;
+    json?: boolean;
+  },
+) {
+  try {
+    const result = await client.addMemory(content, {
+      space: options.space,
+      spaceId: options.spaceId,
+      tags: options.tags,
+      source: options.source,
+    });
+
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    console.log(chalk.green(`Memory added successfully!`));
+    console.log(chalk.cyan(`ID: ${result.id || result.memoryId}`));
+    if (options.space) {
+      console.log(chalk.gray(`Space: ${options.space}`));
+    }
+  } catch (error) {
+    throw new Error(`Add memory failed: ${error}`);
+  }
+}

package/src/commands/delete.ts

@@ -0,0 +1,25 @@
+import { Client } from "../api/client.js";
+import chalk from "chalk";
+
+export async function DeleteCommand(
+  client: Client,
+  id: string,
+  options: { json?: boolean },
+) {
+  try {
+    const result = await client.deleteMemory(id);
+
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    if (result.success) {
+      console.log(chalk.green(`Memory ${id} deleted successfully.`));
+    } else {
+      console.log(chalk.yellow(`Failed to delete memory ${id}.`));
+    }
+  } catch (error) {
+    throw new Error(`Delete memory failed: ${error}`);
+  }
+}

package/src/commands/get.ts

@@ -0,0 +1,35 @@
+import { Client } from "../api/client.js";
+import chalk from "chalk";
+
+export async function GetCommand(
+  client: Client,
+  id: string,
+  options: { json?: boolean },
+) {
+  try {
+    const memory = await client.getMemory(id);
+
+    if (options.json) {
+      console.log(JSON.stringify(memory, null, 2));
+      return;
+    }
+
+    console.log(chalk.bold(`\nMemory [${memory.id}]\n`));
+    console.log(memory.content);
+    console.log();
+    if (memory.tags && memory.tags.length > 0) {
+      console.log(chalk.cyan(`Tags: ${memory.tags.join(", ")}`));
+    }
+    if (memory.source) {
+      console.log(chalk.gray(`Source: ${memory.source}`));
+    }
+    console.log(
+      chalk.gray(`Created: ${new Date(memory.createdAt).toLocaleString()}`),
+    );
+    console.log(
+      chalk.gray(`Updated: ${new Date(memory.updatedAt).toLocaleString()}`),
+    );
+  } catch (error) {
+    throw new Error(`Get memory failed: ${error}`);
+  }
+}

package/src/commands/graph.ts

@@ -0,0 +1,90 @@
+import { Client } from "../api/client.js";
+import chalk from "chalk";
+
+export async function GraphCommand(
+  client: Client,
+  options: { entity?: string; tag?: string; spaceId?: string; json?: boolean },
+) {
+  try {
+    const result = await client.queryGraph(
+      options.entity,
+      options.tag,
+      options.spaceId,
+    );
+
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    if (result.message) {
+      console.log(chalk.yellow(result.message));
+      return;
+    }
+
+    if (result.nodes && result.nodes.length > 0) {
+      console.log(
+        chalk.bold(`\nKnowledge Graph Nodes (${result.nodes.length}):\n`),
+      );
+      for (const node of result.nodes) {
+        console.log(
+          chalk.cyan(`  ${node.name}`) + chalk.gray(` (${node.type})`),
+        );
+      }
+      return;
+    }
+
+    if (result.entity && result.relationships) {
+      console.log(
+        chalk.bold(
+          `\nKnowledge Graph: ${result.entity.name} (${result.entity.type})\n`,
+        ),
+      );
+
+      if (
+        result.relationships.outgoing &&
+        result.relationships.outgoing.length > 0
+      ) {
+        console.log(chalk.green("Outgoing Relationships:"));
+        for (const rel of result.relationships.outgoing) {
+          console.log(
+            chalk.cyan(`  -> [${rel.relation}]`) + ` ${rel.targetName}`,
+          );
+          if (rel.description) {
+            console.log(chalk.gray(`    ${rel.description}`));
+          }
+        }
+        console.log();
+      }
+
+      if (
+        result.relationships.incoming &&
+        result.relationships.incoming.length > 0
+      ) {
+        console.log(chalk.blue("Incoming Relationships:"));
+        for (const rel of result.relationships.incoming) {
+          console.log(
+            chalk.cyan(`<- [${rel.relation}]`) + ` ${rel.sourceName}`,
+          );
+          if (rel.description) {
+            console.log(chalk.gray(`    ${rel.description}`));
+          }
+        }
+      }
+
+      if (
+        (!result.relationships.outgoing ||
+          result.relationships.outgoing.length === 0) &&
+        (!result.relationships.incoming ||
+          result.relationships.incoming.length === 0)
+      ) {
+        console.log(chalk.yellow("No relationships found."));
+      }
+      return;
+    }
+
+    console.log(chalk.yellow("No graph data found."));
+  } catch (error) {
+    throw new Error(`Graph query failed: ${error}`);
+  }
+}

package/src/commands/list.ts

@@ -0,0 +1,36 @@
+import { Client } from "../api/client.js";
+import chalk from "chalk";
+
+export async function ListCommand(
+  client: Client,
+  options: { space?: string; json?: boolean },
+) {
+  try {
+    const { spaces } = await client.listSpaces();
+
+    if (options.json) {
+      console.log(JSON.stringify(spaces, null, 2));
+      return;
+    }
+
+    if (spaces.length === 0) {
+      console.log(chalk.yellow("No spaces found."));
+      return;
+    }
+
+    console.log(chalk.bold(`\nSpaces (${spaces.length}):\n`));
+    for (const space of spaces) {
+      console.log(chalk.cyan(`[${space.id}]`));
+      console.log(chalk.bold(`  ${space.name}`));
+      if (space.description) {
+        console.log(chalk.gray(`  ${space.description}`));
+      }
+      console.log(
+        chalk.gray(`  Created: ${new Date(space.createdAt).toLocaleString()}`),
+      );
+      console.log();
+    }
+  } catch (error) {
+    throw new Error(`List spaces failed: ${error}`);
+  }
+}

package/src/commands/search.ts

@@ -0,0 +1,46 @@
+import { Client } from "../api/client.js";
+import chalk from "chalk";
+
+export async function SearchCommand(
+  client: Client,
+  query: string,
+  options: { limit?: number; space?: string; json?: boolean },
+) {
+  try {
+    const { results } = await client.searchMemories(
+      query,
+      options.limit || 5,
+      options.space,
+    );
+
+    if (options.json) {
+      console.log(JSON.stringify(results, null, 2));
+      return;
+    }
+
+    if (results.length === 0) {
+      console.log(chalk.yellow("No memories found."));
+      return;
+    }
+
+    console.log(chalk.bold(`\nFound ${results.length} memories:\n`));
+    for (const mem of results) {
+      const similarity = mem.similarity
+        ? ` (${(mem.similarity * 100).toFixed(1)}% match)`
+        : "";
+      console.log(chalk.cyan(`[${mem.id}]${similarity}`));
+      console.log(
+        mem.content.substring(0, 200) + (mem.content.length > 200 ? "..." : ""),
+      );
+      if (mem.tags && mem.tags.length > 0) {
+        console.log(chalk.gray(`Tags: ${mem.tags.join(", ")}`));
+      }
+      console.log(
+        chalk.gray(`Created: ${new Date(mem.createdAt).toLocaleString()}`),
+      );
+      console.log();
+    }
+  } catch (error) {
+    throw new Error(`Search failed: ${error}`);
+  }
+}

package/src/commands/spaces.ts

@@ -0,0 +1,88 @@
+import { Client } from "../api/client.js";
+import chalk from "chalk";
+
+export async function SpacesCommand(
+  client: Client,
+  options: {
+    action?: string;
+    name?: string;
+    description?: string;
+    id?: string;
+    json?: boolean;
+  },
+) {
+  try {
+    if (options.action === "create") {
+      if (!options.name) {
+        throw new Error("Space name is required for create action");
+      }
+      const result = await client.createSpace(
+        options.name,
+        options.description,
+      );
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(chalk.green(`Space created successfully!`));
+        console.log(chalk.cyan(`ID: ${result.space.id}`));
+        console.log(chalk.gray(`Name: ${result.space.name}`));
+      }
+      return;
+    }
+
+    if (options.action === "delete") {
+      if (!options.id) {
+        throw new Error("Space ID is required for delete action");
+      }
+      const result = await client.deleteSpace(options.id);
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(chalk.green(`Space ${options.id} deleted successfully.`));
+      }
+      return;
+    }
+
+    if (options.action === "info") {
+      if (!options.id) {
+        throw new Error("Space ID is required for info action");
+      }
+      const { space } = await client.getSpaceDetails(options.id);
+      if (options.json) {
+        console.log(JSON.stringify(space, null, 2));
+      } else {
+        console.log(chalk.bold(`\nSpace: ${space.name}`));
+        console.log(chalk.cyan(`ID: ${space.id}`));
+        if (space.description) {
+          console.log(chalk.gray(`Description: ${space.description}`));
+        }
+        if (space.stats) {
+          console.log(chalk.gray(`Memory Count: ${space.stats.memoryCount}`));
+        }
+        console.log(
+          chalk.gray(`Created: ${new Date(space.createdAt).toLocaleString()}`),
+        );
+      }
+      return;
+    }
+
+    const { spaces } = await client.listSpaces();
+    if (options.json) {
+      console.log(JSON.stringify(spaces, null, 2));
+    } else {
+      if (spaces.length === 0) {
+        console.log(chalk.yellow("No spaces found."));
+        return;
+      }
+      console.log(chalk.bold(`\nSpaces (${spaces.length}):\n`));
+      for (const space of spaces) {
+        console.log(chalk.cyan(`[${space.id}] ${space.name}`));
+        if (space.description) {
+          console.log(chalk.gray(`  ${space.description}`));
+        }
+      }
+    }
+  } catch (error) {
+    throw new Error(`Spaces command failed: ${error}`);
+  }
+}

package/src/commands/tags.ts

@@ -0,0 +1,28 @@
+import { Client } from "../api/client.js";
+import chalk from "chalk";
+
+export async function TagsCommand(
+  client: Client,
+  options: { spaceId?: string; json?: boolean },
+) {
+  try {
+    const { tags } = await client.listTags(options.spaceId);
+
+    if (options.json) {
+      console.log(JSON.stringify(tags, null, 2));
+      return;
+    }
+
+    if (tags.length === 0) {
+      console.log(chalk.yellow("No tags found."));
+      return;
+    }
+
+    console.log(chalk.bold(`\nPopular Tags (${tags.length}):\n`));
+    for (const tag of tags) {
+      console.log(chalk.cyan(`  ${tag.name}`) + chalk.gray(` (${tag.count})`));
+    }
+  } catch (error) {
+    throw new Error(`Tags command failed: ${error}`);
+  }
+}