hyperstack-core 1.0.0

package/examples/openclaw-multiagent.js

@@ -0,0 +1,214 @@
+/**
+ * example-openclaw-multiagent.js
+ * 
+ * Complete example: 3 OpenClaw agents coordinating via HyperStack
+ * instead of GOALS.md + DECISIONS.md files.
+ * 
+ * Run: HYPERSTACK_API_KEY=hs_your_key node example-openclaw-multiagent.js
+ */
+
+import { HyperStackClient } from "hyperstack-core";
+
+const hs = new HyperStackClient({ workspace: "my-project" });
+
+// ─── Step 1: Register your agents ──────────────────────
+
+async function setup() {
+  // Register each agent as a card in the graph
+  await hs.registerAgent({
+    id: "coordinator",
+    name: "Coordinator",
+    role: "Routes tasks, monitors blockers, prevents duplicate work",
+  });
+
+  await hs.registerAgent({
+    id: "researcher",
+    name: "Research Agent",
+    role: "Investigates technical questions, stores findings",
+    owns: ["project-root"],
+  });
+
+  await hs.registerAgent({
+    id: "builder",
+    name: "Builder Agent",
+    role: "Implements code, records architecture decisions",
+  });
+
+  // Create project root
+  await hs.store({
+    slug: "project-root",
+    title: "SaaS Dashboard Project",
+    body: "Next.js 14 + Clerk auth + Neon PostgreSQL. Deploying to Vercel.",
+    cardType: "project",
+    stack: "projects",
+    keywords: ["project", "saas", "dashboard", "nextjs"],
+  });
+
+  console.log("✅ Setup complete: 3 agents + project root");
+}
+
+// ─── Step 2: Researcher investigates auth options ──────
+
+async function researcherFlow() {
+  const researcher = new HyperStackClient({
+    workspace: "my-project",
+    agentId: "researcher",
+  });
+
+  // Check if someone already researched this
+  const existing = await researcher.search("authentication options");
+  if (existing.results?.length) {
+    console.log("📋 Already researched:", existing.results[0].title);
+    return; // No duplicate work!
+  }
+
+  // Store findings
+  await researcher.store({
+    slug: "finding-clerk-pricing",
+    title: "Clerk pricing: free to 10K MAU",
+    body: "Clerk offers free tier up to 10,000 monthly active users. After that $0.02/MAU. Auth0 starts charging at 7,500 MAU at $23/mo. For our expected 5K users, Clerk is free vs Auth0 $23/mo.",
+    cardType: "event",
+    stack: "general",
+    keywords: ["clerk", "auth0", "pricing", "authentication"],
+    links: [{ target: "project-root", relation: "related" }],
+  });
+
+  await researcher.store({
+    slug: "finding-nextauth-deprecated",
+    title: "NextAuth.js → Auth.js migration ongoing",
+    body: "NextAuth.js is being renamed to Auth.js. Migration guide exists but community reports rough edges with App Router. Not recommended for new projects right now.",
+    cardType: "event",
+    stack: "general",
+    keywords: ["nextauth", "authjs", "migration", "risk"],
+    links: [{ target: "project-root", relation: "related" }],
+  });
+
+  console.log("✅ Researcher stored 2 findings");
+}
+
+// ─── Step 3: Builder makes a decision based on research ─
+
+async function builderFlow() {
+  const builder = new HyperStackClient({
+    workspace: "my-project",
+    agentId: "builder",
+  });
+
+  // Search for research findings before deciding
+  const research = await builder.search("authentication pricing comparison");
+  console.log(`📋 Builder found ${research.results?.length || 0} relevant cards`);
+
+  // Make and record a decision
+  await builder.decide({
+    slug: "decision-use-clerk",
+    title: "Use Clerk for authentication",
+    body: "Based on research: Clerk free at our scale (<10K MAU), better Next.js integration than Auth0, and NextAuth.js has migration risks. Clerk is the clear choice.",
+    decidedBy: "agent-builder",
+    affects: ["project-root"],
+    keywords: ["clerk", "auth", "decision"],
+  });
+
+  // Record the implementation task
+  await builder.store({
+    slug: "task-clerk-integration",
+    title: "Integrate Clerk with Next.js App Router",
+    body: "Install @clerk/nextjs, configure middleware, add sign-in/sign-up pages, protect API routes.",
+    cardType: "workflow",
+    stack: "workflows",
+    keywords: ["clerk", "integration", "nextjs", "task"],
+    links: [
+      { target: "decision-use-clerk", relation: "depends_on" },
+      { target: "agent-builder", relation: "assigned_to" },
+    ],
+  });
+
+  // Record a blocker
+  await builder.store({
+    slug: "blocker-env-vars",
+    title: "Need Clerk API keys from team lead",
+    body: "Cannot proceed with Clerk integration until CLERK_SECRET_KEY and NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY are provided.",
+    cardType: "event",
+    stack: "general",
+    keywords: ["blocker", "clerk", "env", "keys"],
+    links: [
+      { target: "task-clerk-integration", relation: "blocks" },
+    ],
+  });
+
+  console.log("✅ Builder: decision recorded, task created, blocker flagged");
+}
+
+// ─── Step 4: Coordinator checks status ─────────────────
+
+async function coordinatorFlow() {
+  const coordinator = new HyperStackClient({
+    workspace: "my-project",
+    agentId: "coordinator",
+  });
+
+  // What blocks the Clerk integration?
+  const blockers = await coordinator.blockers("task-clerk-integration");
+  console.log(`\n🚧 Blockers for Clerk integration: ${blockers.blockers?.length || 0}`);
+  for (const b of blockers.blockers || []) {
+    console.log(`   [${b.slug}] ${b.title}`);
+  }
+
+  // Full graph from project root
+  try {
+    const graph = await coordinator.graph("project-root", { depth: 2 });
+    console.log(`\n📊 Project graph: ${graph.nodes?.length || 0} nodes, ${graph.edges?.length || 0} edges`);
+    for (const e of graph.edges || []) {
+      console.log(`   ${e.from} --${e.relation}--> ${e.to}`);
+    }
+  } catch (err) {
+    // Graph traversal needs Pro plan
+    if (err.status === 403) {
+      console.log("\n📊 Graph traversal requires Pro plan. Using search fallback.");
+      const all = await coordinator.list();
+      console.log(`   Total cards: ${all.count}`);
+    }
+  }
+
+  // Check: has anyone already done research on databases?
+  const dbResearch = await coordinator.search("database postgresql selection");
+  if (!dbResearch.results?.length) {
+    console.log("\n⚠️  No database research found. Assigning to researcher.");
+    await coordinator.store({
+      slug: "task-research-database",
+      title: "Research database options (Neon vs Supabase vs PlanetScale)",
+      body: "Need comparison of managed PostgreSQL options for our Next.js project. Consider: pricing, connection pooling, branching, edge compatibility.",
+      cardType: "workflow",
+      stack: "workflows",
+      keywords: ["database", "research", "neon", "supabase", "planetscale"],
+      links: [
+        { target: "agent-researcher", relation: "assigned_to" },
+        { target: "project-root", relation: "related" },
+      ],
+    });
+  }
+}
+
+// ─── Run the full flow ─────────────────────────────────
+
+async function main() {
+  console.log("🃏 HyperStack Multi-Agent Demo\n");
+
+  await setup();
+  console.log();
+
+  await researcherFlow();
+  console.log();
+
+  await builderFlow();
+  console.log();
+
+  await coordinatorFlow();
+
+  console.log("\n✅ Demo complete. All agents share one typed graph.");
+  console.log("   No DECISIONS.md. No GOALS.md. Just queryable cards + relations.");
+}
+
+main().catch(err => {
+  console.error("Error:", err.message);
+  process.exit(1);
+});

package/index.js

@@ -0,0 +1,18 @@
+/**
+ * hyperstack-core
+ * 
+ * Typed graph memory for AI agents.
+ * 
+ * Usage:
+ *   import { HyperStackClient } from "hyperstack-core";
+ *   const hs = new HyperStackClient({ apiKey: "hs_..." });
+ *   await hs.store({ slug: "use-clerk", title: "Use Clerk for auth", cardType: "decision" });
+ *   await hs.blockers("deploy-prod"); // → typed blockers
+ * 
+ * OpenClaw:
+ *   import { createOpenClawAdapter } from "hyperstack-core/adapters/openclaw";
+ *   const adapter = createOpenClawAdapter({ agentId: "researcher" });
+ */
+
+export { HyperStackClient } from "./src/client.js";
+export { createOpenClawAdapter } from "./adapters/openclaw.js";

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "hyperstack-core",
+  "version": "1.0.0",
+  "description": "Typed graph memory for AI agents. Replace GOALS.md with queryable cards + relations. Works with OpenClaw, Claude Desktop, Cursor.",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "hyperstack-core": "./cli.js"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./client": "./src/client.js",
+    "./adapters/openclaw": "./adapters/openclaw.js"
+  },
+  "files": [
+    "index.js",
+    "cli.js",
+    "src/",
+    "adapters/",
+    "templates/",
+    "examples/",
+    "SKILL.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "hyperstack",
+    "knowledge-graph",
+    "ai-agents",
+    "memory",
+    "openclaw",
+    "multi-agent",
+    "mcp",
+    "typed-relations",
+    "graph-memory",
+    "agent-coordination"
+  ],
+  "author": "CascadeAI <deeq.yaqub1@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deeqyaqub1-cmd/hyperstack-core"
+  },
+  "homepage": "https://cascadeai.dev/hyperstack",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {},
+  "devDependencies": {}
+}

package/src/client.js

@@ -0,0 +1,267 @@
+/**
+ * hyperstack-core — HyperStack SDK for typed graph memory
+ * 
+ * Lightweight client for the HyperStack API. Works in Node.js 18+.
+ * No dependencies. Used by the OpenClaw adapter and CLI.
+ */
+
+const DEFAULT_BASE = "https://hyperstack-cloud.vercel.app";
+
+// ESM-compatible sync file reading
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+function loadCredApiKey() {
+  try {
+    const credFile = join(homedir(), ".hyperstack", "credentials.json");
+    if (existsSync(credFile)) {
+      const creds = JSON.parse(readFileSync(credFile, "utf-8"));
+      if (creds.api_key) return creds.api_key;
+    }
+  } catch {}
+  return "";
+}
+
+class HyperStackClient {
+  /**
+   * @param {object} opts
+   * @param {string} opts.apiKey — HyperStack API key (hs_...)
+   * @param {string} [opts.workspace="default"] — workspace slug
+   * @param {string} [opts.baseUrl] — API base URL
+   * @param {string} [opts.agentId] — agent identifier for multi-agent setups
+   */
+  constructor(opts = {}) {
+    this.apiKey = opts.apiKey || process.env.HYPERSTACK_API_KEY || loadCredApiKey();
+    this.workspace = opts.workspace || process.env.HYPERSTACK_WORKSPACE || "default";
+    this.baseUrl = opts.baseUrl || process.env.HYPERSTACK_BASE_URL || DEFAULT_BASE;
+    this.agentId = opts.agentId || null;
+
+    if (!this.apiKey) {
+      throw new Error(
+        "HYPERSTACK_API_KEY required.\n" +
+        "Run: npx hyperstack-core login\n" +
+        "Or:  export HYPERSTACK_API_KEY=hs_your_key\n" +
+        "Get a free account: https://cascadeai.dev/hyperstack"
+      );
+    }
+  }
+
+  /** @private */
+  async _request(method, path, body = null) {
+    const url = `${this.baseUrl}${path}`;
+    const opts = {
+      method,
+      headers: {
+        "X-API-Key": this.apiKey,
+        "Content-Type": "application/json",
+        "User-Agent": "hyperstack-core/1.0.0",
+      },
+    };
+    if (body) opts.body = JSON.stringify(body);
+
+    const res = await fetch(url, opts);
+    const data = await res.json();
+    if (!res.ok) {
+      const err = new Error(data.error || `HTTP ${res.status}`);
+      err.status = res.status;
+      err.body = data;
+      throw err;
+    }
+    return data;
+  }
+
+  // ─── Cards ───────────────────────────────────────────
+
+  /**
+   * Create or update a card (upsert by slug).
+   * @param {object} card
+   * @param {string} card.slug — unique identifier
+   * @param {string} card.title — short title
+   * @param {string} [card.body] — description (2-5 sentences)
+   * @param {string} [card.cardType] — person|project|decision|preference|workflow|event|general
+   * @param {string} [card.stack] — projects|people|decisions|preferences|workflows|general
+   * @param {string[]} [card.keywords] — search terms
+   * @param {Array<{target: string, relation: string}>} [card.links] — typed relations
+   * @param {object} [card.meta] — freeform metadata
+   * @returns {Promise<{slug: string, updated: boolean}>}
+   */
+  async store(card) {
+    if (!card.slug) throw new Error("card.slug required");
+    if (!card.title) throw new Error("card.title required");
+
+    // Auto-tag with agentId if set
+    if (this.agentId) {
+      card.meta = card.meta || {};
+      card.meta.agentId = this.agentId;
+      card.keywords = card.keywords || [];
+      if (!card.keywords.includes(`agent:${this.agentId}`)) {
+        card.keywords.push(`agent:${this.agentId}`);
+      }
+    }
+
+    return this._request("POST", `/api/cards?workspace=${this.workspace}`, card);
+  }
+
+  /**
+   * Search cards by query (hybrid semantic + keyword).
+   * @param {string} query
+   * @returns {Promise<{results: Array}>}
+   */
+  async search(query) {
+    return this._request("GET", `/api/search?workspace=${this.workspace}&q=${encodeURIComponent(query)}`);
+  }
+
+  /**
+   * List all cards in workspace.
+   * @returns {Promise<{cards: Array, count: number, plan: string}>}
+   */
+  async list() {
+    return this._request("GET", `/api/cards?workspace=${this.workspace}`);
+  }
+
+  /**
+   * Delete a card by slug.
+   * @param {string} slug
+   * @returns {Promise<{deleted: boolean}>}
+   */
+  async delete(slug) {
+    return this._request("DELETE", `/api/cards?workspace=${this.workspace}&id=${slug}`);
+  }
+
+  // ─── Graph ───────────────────────────────────────────
+
+  /**
+   * Traverse the knowledge graph from a starting card.
+   * @param {string} from — starting card slug
+   * @param {object} [opts]
+   * @param {number} [opts.depth=1] — hops to traverse (1-3)
+   * @param {string} [opts.relation] — filter by relation type
+   * @param {string} [opts.type] — filter by card type
+   * @param {string} [opts.at] — ISO timestamp for time-travel
+   * @returns {Promise<{nodes: Array, edges: Array}>}
+   */
+  async graph(from, opts = {}) {
+    let url = `/api/graph?workspace=${this.workspace}&from=${from}`;
+    if (opts.depth) url += `&depth=${opts.depth}`;
+    if (opts.relation) url += `&relation=${opts.relation}`;
+    if (opts.type) url += `&type=${opts.type}`;
+    if (opts.at) url += `&at=${encodeURIComponent(opts.at)}`;
+    return this._request("GET", url);
+  }
+
+  // ─── Multi-Agent Helpers ──────────────────────────────
+
+  /**
+   * Query cards that block a specific card/task.
+   * Shorthand for graph traversal with relation="blocks".
+   * @param {string} slug — card being blocked
+   * @returns {Promise<{blockers: Array}>}
+   */
+  async blockers(slug) {
+    try {
+      const result = await this.graph(slug, { depth: 2, relation: "blocks" });
+      const blockers = (result.edges || [])
+        .filter(e => e.relation === "blocks" && e.to === slug)
+        .map(e => {
+          const node = (result.nodes || []).find(n => n.slug === e.from);
+          return node || { slug: e.from };
+        });
+      return { blockers, graph: result };
+    } catch (err) {
+      // If graph API not available (free tier), fallback to search
+      if (err.status === 403) {
+        const searchResult = await this.search(`blocks ${slug}`);
+        return {
+          blockers: (searchResult.results || []).filter(c =>
+            c.links?.some(l => l.relation === "blocks" && l.target === slug)
+          ),
+          fallback: true,
+        };
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Find cards owned by a specific agent.
+   * @param {string} [agentId] — defaults to this.agentId
+   * @returns {Promise<{cards: Array}>}
+   */
+  async agentCards(agentId) {
+    const id = agentId || this.agentId;
+    if (!id) throw new Error("agentId required");
+    return this.search(`agent:${id}`);
+  }
+
+  /**
+   * Record a decision with full provenance.
+   * Creates a decision card + links to who decided and what it affects.
+   * @param {object} decision
+   * @param {string} decision.slug
+   * @param {string} decision.title
+   * @param {string} decision.body — rationale
+   * @param {string} [decision.decidedBy] — agent/person slug
+   * @param {string[]} [decision.affects] — slugs of affected cards
+   * @param {string[]} [decision.blocks] — slugs of things this blocks
+   * @param {object} [decision.meta]
+   */
+  async decide(decision) {
+    const links = [];
+    if (decision.decidedBy) {
+      links.push({ target: decision.decidedBy, relation: "decided" });
+    }
+    if (decision.affects) {
+      for (const a of decision.affects) {
+        links.push({ target: a, relation: "triggers" });
+      }
+    }
+    if (decision.blocks) {
+      for (const b of decision.blocks) {
+        links.push({ target: b, relation: "blocks" });
+      }
+    }
+
+    return this.store({
+      slug: decision.slug,
+      title: decision.title,
+      body: decision.body,
+      cardType: "decision",
+      stack: "decisions",
+      links,
+      meta: { ...decision.meta, decidedAt: new Date().toISOString() },
+      keywords: decision.keywords || [],
+    });
+  }
+
+  /**
+   * Register an agent as a card in the graph.
+   * @param {object} agent
+   * @param {string} agent.id — unique agent ID
+   * @param {string} agent.name — display name
+   * @param {string} agent.role — what this agent does
+   * @param {string[]} [agent.owns] — slugs this agent owns
+   */
+  async registerAgent(agent) {
+    const links = [];
+    if (agent.owns) {
+      for (const o of agent.owns) {
+        links.push({ target: o, relation: "owns" });
+      }
+    }
+
+    return this.store({
+      slug: `agent-${agent.id}`,
+      title: `Agent: ${agent.name}`,
+      body: agent.role,
+      cardType: "person",
+      stack: "people",
+      links,
+      keywords: ["agent", agent.id, agent.name],
+      meta: { agentId: agent.id, registeredAt: new Date().toISOString() },
+    });
+  }
+}
+
+export { HyperStackClient };
+export default HyperStackClient;

package/templates/openclaw-multiagent.json

@@ -0,0 +1,98 @@
+{
+  "name": "openclaw-multiagent",
+  "description": "Pre-configured typed cards and relations for OpenClaw multi-agent coordination. Replaces GOALS.md + DECISIONS.md with structured, queryable graph memory.",
+  "version": "1.0.0",
+
+  "cardTypes": {
+    "task": {
+      "description": "A unit of work assigned to an agent",
+      "fields": ["status", "priority", "assignee", "deadline"],
+      "statuses": ["todo", "in-progress", "blocked", "done", "cancelled"]
+    },
+    "decision": {
+      "description": "A choice made by an agent with rationale",
+      "fields": ["rationale", "alternatives", "decidedBy", "decidedAt"]
+    },
+    "blocker": {
+      "description": "Something preventing progress on a task",
+      "fields": ["severity", "resolvedBy", "resolvedAt"]
+    },
+    "goal": {
+      "description": "A high-level objective (replaces GOALS.md)",
+      "fields": ["deadline", "progress", "owner"]
+    },
+    "agent": {
+      "description": "An agent registration card",
+      "fields": ["role", "model", "capabilities"]
+    },
+    "context": {
+      "description": "Shared context that multiple agents need",
+      "fields": ["scope", "expiresAt"]
+    }
+  },
+
+  "relationTypes": {
+    "owns": "Agent/person owns a task or project",
+    "assigned_to": "Task is assigned to an agent",
+    "blocks": "This card blocks another card",
+    "blocked_by": "This card is blocked by another card",
+    "depends_on": "This card depends on another card",
+    "decided": "Agent/person made this decision",
+    "triggers": "Change to this card triggers effects on target",
+    "subtask_of": "This task is a subtask of a larger task",
+    "related": "General association"
+  },
+
+  "rules": [
+    {
+      "name": "auto-blocked",
+      "description": "If a task has incoming 'blocks' relations, mark it as blocked",
+      "when": "card.cardType === 'task' && card.incomingLinks.some(l => l.relation === 'blocks')",
+      "suggest": "Consider updating task status to 'blocked'"
+    },
+    {
+      "name": "unowned-task",
+      "description": "Tasks without an owner should be flagged",
+      "when": "card.cardType === 'task' && !card.links.some(l => l.relation === 'assigned_to')",
+      "suggest": "This task has no assigned agent"
+    },
+    {
+      "name": "decision-needs-rationale",
+      "description": "Decisions should include rationale",
+      "when": "card.cardType === 'decision' && (!card.body || card.body.length < 20)",
+      "suggest": "Decision lacks rationale — add a body explaining why"
+    }
+  ],
+
+  "starterCards": [
+    {
+      "slug": "project-root",
+      "title": "Project Root",
+      "body": "Root node for the project knowledge graph. All agents, goals, and major decisions link here.",
+      "cardType": "project",
+      "stack": "projects",
+      "keywords": ["project", "root", "main"]
+    }
+  ],
+
+  "agentSetup": {
+    "description": "Recommended agent configuration for multi-agent OpenClaw + HyperStack",
+    "agents": {
+      "coordinator": {
+        "role": "Routes tasks, monitors blockers, ensures no duplicate work",
+        "model": "claude-sonnet-4-20250514",
+        "tools": ["hs_search", "hs_blockers", "hs_graph", "hs_decide"]
+      },
+      "researcher": {
+        "role": "Investigates questions, stores findings as context cards",
+        "model": "claude-sonnet-4-20250514",
+        "tools": ["hs_search", "hs_store", "hs_my_cards"]
+      },
+      "builder": {
+        "role": "Implements code, records technical decisions",
+        "model": "claude-sonnet-4-20250514",
+        "tools": ["hs_search", "hs_store", "hs_decide", "hs_blockers"]
+      }
+    }
+  }
+}