hyperstack-core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CascadeAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# hyperstack-core
+
+Typed graph memory for AI agents. Replace `GOALS.md` + `DECISIONS.md` with queryable cards and relations.
+
+```
+npm i hyperstack-core
+npx hyperstack-core init openclaw-multiagent
+```
+
+## The Problem
+
+OpenClaw multi-agent setups use markdown files for coordination:
+
+```
+# DECISIONS.md (append-only)
+- 2026-02-15: Use Clerk for auth (coder-agent)
+- 2026-02-15: Deploy needs auth migration first (deploy-agent)
+- 2026-02-16: Migration blocks production deploy (ops-agent)
+```
+
+Try answering: **"What blocks the production deploy?"**
+
+With markdown: `grep -r "blocks.*deploy" *.md` — manual, fragile, returns text blobs.
+
+## The Solution
+
+```js
+import { HyperStackClient } from "hyperstack-core";
+
+const hs = new HyperStackClient({ apiKey: "hs_..." });
+
+// Coder agent records a decision
+await hs.decide({
+  slug: "use-clerk",
+  title: "Use Clerk for auth",
+  body: "Better DX, lower cost, native Next.js support",
+  decidedBy: "agent-coder",
+  affects: ["auth-api"],
+});
+
+// Deploy agent records a blocker
+await hs.store({
+  slug: "migration-23",
+  title: "Auth migration to Clerk",
+  cardType: "task",
+  links: [
+    { target: "deploy-prod", relation: "blocks" },
+    { target: "use-clerk", relation: "depends_on" },
+  ],
+});
+
+// Ops agent asks: what blocks deploy?
+const result = await hs.blockers("deploy-prod");
+// → { blockers: [{ slug: "migration-23", title: "Auth migration to Clerk" }] }
+```
+
+**Typed relations, not text blobs.** `task→blocks→deploy` is queryable. A paragraph in DECISIONS.md is not.
+
+## OpenClaw Integration
+
+```js
+import { createOpenClawAdapter } from "hyperstack-core/adapters/openclaw";
+
+// Each agent gets its own adapter
+const researcher = createOpenClawAdapter({ agentId: "researcher" });
+const builder = createOpenClawAdapter({ agentId: "builder" });
+
+// Register on session start
+await researcher.onSessionStart({
+  agentName: "Research Agent",
+  agentRole: "Investigate questions, store findings as context cards",
+});
+
+// Use tools in agent logic
+await researcher.tools.hs_store({
+  slug: "finding-clerk-pricing",
+  title: "Clerk pricing analysis",
+  body: "Free for 10K MAU, $0.02/MAU after. Cheaper than Auth0 at our scale.",
+  type: "context",
+  links: "use-clerk:related",
+});
+
+// Builder queries shared knowledge
+const blockers = await builder.tools.hs_blockers({ slug: "deploy-prod" });
+// → "1 blocker: [migration-23] Auth migration to Clerk"
+```
+
+## CLI
+
+```bash
+# Initialize with multi-agent template
+npx hyperstack-core init openclaw-multiagent
+
+# Store cards
+npx hyperstack-core store --slug "use-clerk" --title "Use Clerk" --type decision
+
+# Record decisions
+npx hyperstack-core decide --slug "use-clerk" --title "Use Clerk" --rationale "Better DX"
+
+# Check blockers
+npx hyperstack-core blockers deploy-prod
+
+# Traverse graph
+npx hyperstack-core graph auth-api --depth 2
+
+# Search
+npx hyperstack-core search "authentication setup"
+
+# List all cards
+npx hyperstack-core list
+```
+
+## Why Not Mem0/Cognee?
+
+| | hyperstack-core | Mem0 | Cognee |
+|--|---|---|---|
+| "What blocks deploy?" | Exact: 2 typed blockers | Fuzzy: 17 similar tasks | Generic entities |
+| Relations | `task→blocks→deploy` (typed) | Auto-extracted (hallucinated) | Generic graph |
+| Cost per op | **$0** (deterministic) | ~$0.002 (LLM extraction) | ~$0.002 |
+| Multi-agent | Built-in agent tagging | Shared userId issues | No agent awareness |
+| Setup | `npm i` + 1 env var | Docker + config | Docker + Neo4j |
+
+Mem0 finds "similar" cards. HyperStack finds **exactly** what blocks task #42.
+
+## How It Works
+
+Cards are typed objects with explicit relations:
+
+```
+[task:deploy-prod] "Deploy to production"
+    ←blocks— [task:migration-23] "Auth migration to Clerk"
+    ←blocks— [blocker:staging-tests] "Staging tests failing"
+    —assigned_to→ [agent:deploy-agent]
+    —depends_on→ [decision:use-clerk]
+```
+
+Every card stores: slug, title, body, cardType, links (typed relations), keywords, meta.
+Every relation is explicit — no LLM extraction, no hallucinated connections.
+
+Backed by HyperStack API (Neon PostgreSQL + pgvector for hybrid search).
+
+## Setup
+
+1. Get a free API key: [cascadeai.dev/hyperstack](https://cascadeai.dev/hyperstack)
+2. `export HYPERSTACK_API_KEY=hs_your_key`
+3. `npm i hyperstack-core`
+4. `npx hyperstack-core init openclaw-multiagent`
+
+Free tier: 10 cards, keyword search.
+Pro ($29/mo): 100 cards, graph traversal, time-travel, semantic search.
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: hyperstack
+description: "Typed graph memory for multi-agent coordination. Replace GOALS.md + DECISIONS.md with queryable cards and relations. Ask 'what blocks task X?' and get exact answers, not text blobs."
+user-invocable: true
+homepage: https://cascadeai.dev/hyperstack
+metadata:
+  openclaw:
+    emoji: "🃏"
+    requires:
+      env:
+        - HYPERSTACK_API_KEY
+    primaryEnv: HYPERSTACK_API_KEY
+---
+
+# HyperStack — Typed Graph Memory for Multi-Agent Coordination
+
+## What this does
+
+Replaces markdown-file coordination (GOALS.md, DECISIONS.md, WORKING.md) with a typed knowledge graph that any agent can query.
+
+**Before** (current OpenClaw multi-agent):
+```
+# DECISIONS.md (append-only)
+- 2026-02-15: Use Clerk for auth (coder-agent)
+- 2026-02-16: Migration blocks production deploy (ops-agent)
+```
+"What blocks deploy?" → `grep -r "blocks.*deploy" *.md` → manual, fragile
+
+**After** (HyperStack):
+```
+"What blocks deploy?" → hs_blockers deploy-prod → [migration-23] Auth migration to Clerk
+```
+
+Typed relations. Exact answers. Zero LLM cost.
+
+## Tools
+
+### hs_search
+Search the shared knowledge graph.
+```
+hs_search({ query: "authentication setup" })
+```
+
+### hs_store  
+Store a card in the graph. Auto-tags with your agent ID.
+```
+hs_store({
+  slug: "use-clerk",
+  title: "Use Clerk for auth",
+  body: "Better DX, lower cost, native Next.js support",
+  type: "decision",
+  links: "auth-api:triggers,alice:decided"
+})
+```
+
+### hs_decide
+Record a decision with full provenance — who decided, what it affects, what it blocks.
+```
+hs_decide({
+  slug: "use-clerk",
+  title: "Use Clerk for auth",
+  rationale: "Better DX, lower cost vs Auth0",
+  affects: "auth-api,user-service",
+  blocks: ""
+})
+```
+
+### hs_blockers
+Check what blocks a task/card. Returns exact typed blockers, not fuzzy search results.
+```
+hs_blockers({ slug: "deploy-prod" })
+→ "1 blocker: [migration-23] Auth migration to Clerk"
+```
+
+### hs_graph
+Traverse the knowledge graph from a starting card. See connections, ownership, dependencies.
+```
+hs_graph({ from: "auth-api", depth: 2 })
+→ nodes: [auth-api, use-clerk, migration-23, alice]
+→ edges: [auth-api→triggers→use-clerk, migration-23→blocks→deploy-prod]
+```
+
+### hs_my_cards
+List all cards created by this agent.
+```
+hs_my_cards()
+→ "3 cards by agent researcher: [finding-clerk-pricing] [finding-auth0-limits] [finding-nextauth-deprecated]"
+```
+
+## Multi-Agent Setup
+
+Each agent gets its own ID. Cards are auto-tagged so you can see who created what.
+
+Recommended roles:
+- **coordinator**: Routes tasks, monitors blockers (`hs_blockers`, `hs_graph`, `hs_decide`)
+- **researcher**: Investigates, stores findings (`hs_search`, `hs_store`)
+- **builder**: Implements, records tech decisions (`hs_store`, `hs_decide`, `hs_blockers`)
+
+## Setup
+
+1. Get free API key: https://cascadeai.dev/hyperstack
+2. Set `HYPERSTACK_API_KEY=hs_your_key` in your OpenClaw env
+3. Tools are available immediately
+
+Free: 10 cards, keyword search.
+Pro ($29/mo): 100 cards, graph traversal, semantic search, time-travel debugging.
+
+## When to use
+
+- **Start of session**: `hs_search` for relevant context
+- **Decision made**: `hs_decide` with rationale and links
+- **Task blocked**: `hs_store` with `blocks` relation
+- **Before starting work**: `hs_blockers` to check dependencies
+- **New finding**: `hs_store` as context card
+
+## Data safety
+
+NEVER store passwords, API keys, tokens, PII, or credentials. Cards should be safe in a data breach. Always confirm with user before storing.

package/adapters/openclaw.js

@@ -0,0 +1,221 @@
+/**
+ * hyperstack-core/adapters/openclaw.js
+ * 
+ * OpenClaw adapter for HyperStack.
+ * Replaces GOALS.md / DECISIONS.md with typed graph memory.
+ * 
+ * Usage in OpenClaw config (openclaw.json):
+ * {
+ *   "skills": ["hyperstack-core/adapters/openclaw"],
+ *   "env": {
+ *     "HYPERSTACK_API_KEY": "hs_your_key"
+ *   }
+ * }
+ * 
+ * Or use programmatically:
+ *   import { createOpenClawAdapter } from "hyperstack-core/adapters/openclaw";
+ *   const adapter = createOpenClawAdapter({ agentId: "researcher" });
+ */
+
+import { HyperStackClient } from "../src/client.js";
+
+/**
+ * Create an OpenClaw-compatible adapter that provides tools
+ * for multi-agent coordination via HyperStack.
+ * 
+ * @param {object} opts
+ * @param {string} opts.agentId — this agent's unique ID
+ * @param {string} [opts.apiKey] — HyperStack API key
+ * @param {string} [opts.workspace] — workspace slug
+ */
+function createOpenClawAdapter(opts = {}) {
+  const agentId = opts.agentId || process.env.OPENCLAW_AGENT_ID || "main";
+  
+  const client = new HyperStackClient({
+    apiKey: opts.apiKey,
+    workspace: opts.workspace,
+    agentId,
+  });
+
+  return {
+    client,
+    agentId,
+
+    /**
+     * Tools that get exposed to the OpenClaw agent.
+     * These can be called via OpenClaw's tool system.
+     */
+    tools: {
+      /**
+       * Search the shared knowledge graph.
+       */
+      async hs_search({ query }) {
+        const result = await client.search(query);
+        const cards = result.results || [];
+        if (!cards.length) return { text: "No matching cards found." };
+
+        return {
+          text: cards.slice(0, 5).map(c => {
+            let line = `[${c.slug}] ${c.title} (${c.cardType || "general"})`;
+            if (c.body) line += `\n  ${c.body.slice(0, 200)}`;
+            if (c.links?.length) {
+              line += `\n  Links: ${c.links.map(l => `${l.relation}→${l.target}`).join(", ")}`;
+            }
+            return line;
+          }).join("\n\n"),
+          cards,
+        };
+      },
+
+      /**
+       * Store a card in the shared graph. Auto-tags with agent ID.
+       */
+      async hs_store({ slug, title, body, type, links, keywords }) {
+        const parsedLinks = [];
+        if (links) {
+          // Accept "target:relation,target:relation" format
+          for (const l of (typeof links === "string" ? links.split(",") : links)) {
+            if (typeof l === "string") {
+              const [target, relation] = l.trim().split(":");
+              parsedLinks.push({ target: target.trim(), relation: (relation || "related").trim() });
+            } else {
+              parsedLinks.push(l);
+            }
+          }
+        }
+
+        const result = await client.store({
+          slug,
+          title,
+          body: body || "",
+          cardType: type || "general",
+          keywords: typeof keywords === "string" ? keywords.split(",").map(k => k.trim()) : (keywords || []),
+          links: parsedLinks,
+        });
+
+        return {
+          text: `${result.updated ? "Updated" : "Created"} [${slug}]: ${title}`,
+          result,
+        };
+      },
+
+      /**
+       * Record a decision with full provenance.
+       */
+      async hs_decide({ slug, title, rationale, affects, blocks }) {
+        const result = await client.decide({
+          slug,
+          title,
+          body: rationale,
+          decidedBy: `agent-${agentId}`,
+          affects: affects ? (typeof affects === "string" ? affects.split(",").map(s => s.trim()) : affects) : [],
+          blocks: blocks ? (typeof blocks === "string" ? blocks.split(",").map(s => s.trim()) : blocks) : [],
+        });
+
+        return {
+          text: `Decision recorded: [${slug}] ${title} (by ${agentId})`,
+          result,
+        };
+      },
+
+      /**
+       * Check what blocks a task/card.
+       */
+      async hs_blockers({ slug }) {
+        const result = await client.blockers(slug);
+        const blockers = result.blockers || [];
+
+        if (!blockers.length) {
+          return { text: `Nothing blocks [${slug}].`, blockers: [] };
+        }
+
+        return {
+          text: `${blockers.length} blocker(s) for [${slug}]:\n` +
+            blockers.map(b => `  [${b.slug}] ${b.title || "?"}`).join("\n"),
+          blockers,
+        };
+      },
+
+      /**
+       * Traverse the graph from a card.
+       */
+      async hs_graph({ from, depth, relation }) {
+        const result = await client.graph(from, {
+          depth: depth || 2,
+          relation: relation || undefined,
+        });
+
+        const nodes = result.nodes || [];
+        const edges = result.edges || [];
+
+        if (!nodes.length) {
+          return { text: `No graph found from [${from}].`, nodes: [], edges: [] };
+        }
+
+        let text = `Graph from [${from}]: ${nodes.length} nodes, ${edges.length} edges\n\n`;
+        text += "Nodes:\n" + nodes.map(n =>
+          `  [${n.slug}] ${n.title || "?"} (${n.cardType || "?"})`
+        ).join("\n");
+        text += "\n\nEdges:\n" + edges.map(e =>
+          `  ${e.from} --${e.relation}--> ${e.to}`
+        ).join("\n");
+
+        return { text, nodes, edges };
+      },
+
+      /**
+       * List all cards by this agent.
+       */
+      async hs_my_cards() {
+        const result = await client.agentCards(agentId);
+        const cards = result.results || [];
+
+        return {
+          text: `${cards.length} cards by agent "${agentId}":\n` +
+            cards.map(c => `  [${c.slug}] ${c.title}`).join("\n"),
+          cards,
+        };
+      },
+    },
+
+    /**
+     * Hook: called when agent session starts.
+     * Registers the agent and loads relevant context.
+     */
+    async onSessionStart({ agentName, agentRole }) {
+      // Register this agent in the graph
+      await client.registerAgent({
+        id: agentId,
+        name: agentName || agentId,
+        role: agentRole || "OpenClaw agent",
+      });
+
+      // Load recent context for this agent
+      const context = await client.search(`agent:${agentId}`);
+      return {
+        cards: context.results || [],
+        text: `HyperStack: ${(context.results || []).length} cards loaded for agent "${agentId}"`,
+      };
+    },
+
+    /**
+     * Hook: called when agent session ends.
+     * Good place to save working state.
+     */
+    async onSessionEnd({ summary }) {
+      if (summary) {
+        await client.store({
+          slug: `session-${agentId}-${Date.now()}`,
+          title: `Session summary (${agentId})`,
+          body: summary.slice(0, 500),
+          cardType: "event",
+          stack: "general",
+          keywords: ["session", "summary"],
+        });
+      }
+    },
+  };
+}
+
+export { createOpenClawAdapter };
+export default createOpenClawAdapter;