@hyperspell/openclaw-hyperspell 0.4.2 → 0.5.0

package/client.ts

@@ -195,6 +195,45 @@ export class HyperspellClient {
     }
   }
 
+  async *listMemories(
+    options?: { source?: HyperspellSource; collection?: string; pageSize?: number },
+  ): AsyncGenerator<{
+    resourceId: string
+    source: HyperspellSource
+    title: string | null
+    metadata: Record<string, unknown>
+  }> {
+    log.debugRequest("memories.list", { source: options?.source, collection: options?.collection })
+
+    const params: Record<string, unknown> = {
+      size: options?.pageSize ?? 100,
+    }
+    if (options?.source) params.source = options.source
+    if (options?.collection) params.collection = options.collection
+
+    for await (const memory of this.client.memories.list(params as any)) {
+      yield {
+        resourceId: memory.resource_id,
+        source: memory.source as HyperspellSource,
+        title: memory.title ?? null,
+        metadata: (memory.metadata ?? {}) as Record<string, unknown>,
+      }
+    }
+  }
+
+  async getMemory(
+    resourceId: string,
+    source: HyperspellSource,
+  ): Promise<Record<string, unknown>> {
+    log.debugRequest("memories.get", { resourceId, source })
+
+    const response = await this.client.memories.get(resourceId, { source })
+    const raw = response as unknown as Record<string, unknown>
+
+    log.debugResponse("memories.get", { resourceId, hasData: "data" in raw })
+    return raw
+  }
+
   async listConnections(): Promise<Connection[]> {
     log.debugRequest("connections.list", {})
 

package/commands/setup.ts

@@ -1,4 +1,4 @@
-import { exec } from "node:child_process"
+import { exec, execFileSync } from "node:child_process"
 import * as fs from "node:fs"
 import * as path from "node:path"
 import { homedir, platform, userInfo } from "node:os"
@@ -7,7 +7,10 @@ import type { Command } from "commander"
 import Hyperspell from "hyperspell"
 import { syncAllMemoryFiles, getMemoryFiles } from "../sync/markdown.ts"
 import { HyperspellClient } from "../client.ts"
-import { getWorkspaceDir } from "../config.ts"
+import { getWorkspaceDir, parseConfig } from "../config.ts"
+import { buildExtractionPrompt, CRON_JOB_NAME } from "../graph/cron.ts"
+import { NetworkStateManager } from "../graph/state.ts"
+import { scanMemories, formatScanResults, completeMemories } from "../graph/ops.ts"
 
 /**
  * Resolve OpenClaw state directory, matching OpenClaw's logic.
@@ -380,6 +383,7 @@ async function runSetup(): Promise<void> {
         sources: [],
         maxResults: 10,
         debug: false,
+        knowledgeGraph: { enabled: false, scanIntervalMinutes: 60, batchSize: 20 },
       })
 
       const result = await syncAllMemoryFiles(hyperspellClient, workspaceDir)
@@ -397,18 +401,129 @@ async function runSetup(): Promise<void> {
     }
   }
 
+  // Step 8: Memory Network setup
+  p.note(
+    "The Memory Network automatically extracts entities (people, projects,\n" +
+      "organizations, topics) from your memories into structured markdown\n" +
+      "files. This runs as a periodic cron job in the main session.",
+    "Memory Network",
+  )
+
+  const enableNetwork = await p.confirm({
+    message: "Enable the Memory Network?",
+    initialValue: false,
+  })
+
+  if (!p.isCancel(enableNetwork) && enableNetwork) {
+    // Update config to enable knowledgeGraph
+    try {
+      const configPath = resolveConfigPath()
+      if (fs.existsSync(configPath)) {
+        const configContent = fs.readFileSync(configPath, "utf-8")
+        const config = JSON.parse(configContent)
+        const pluginEntry = config?.plugins?.entries?.["openclaw-hyperspell"]?.config
+        if (pluginEntry) {
+          pluginEntry.knowledgeGraph = { enabled: true }
+          fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n")
+        }
+      }
+      p.log.success("Memory Network enabled in config")
+    } catch {
+      p.log.warn("Could not update config — add knowledgeGraph.enabled: true manually")
+    }
+
+    // Write the extraction prompt to a file and create the cron job
+    const networkWorkspaceDir = getWorkspaceDir()
+    const promptPath = path.join(networkWorkspaceDir, "HYPERSPELL-MEMORY-NETWORK.md")
+    const prompt = buildExtractionPrompt(networkWorkspaceDir)
+    fs.mkdirSync(path.dirname(promptPath), { recursive: true })
+    fs.writeFileSync(promptPath, prompt)
+
+    const s4 = p.spinner()
+    s4.start("Creating Memory Network cron job")
+
+    let cronJobId: string | null = null
+    try {
+      const output = execFileSync("openclaw", [
+        "cron", "add",
+        "--name", CRON_JOB_NAME,
+        "--every", "1h",
+        "--session", "isolated",
+        "--message", `Read the file at ${promptPath} and follow the instructions inside it.`,
+      ], { stdio: ["pipe", "pipe", "pipe"], timeout: 10_000 })
+
+      // Extract job ID from the JSON output
+      const text = output.toString().trim()
+      // Find the JSON object in the output (skip any non-JSON prefix lines)
+      const jsonStart = text.indexOf("{")
+      if (jsonStart >= 0) {
+        try {
+          const job = JSON.parse(text.slice(jsonStart))
+          cronJobId = job?.id || null
+        } catch {}
+      }
+
+      s4.stop("Cron job created — Memory Network will scan every hour")
+    } catch (cronErr) {
+      s4.stop("Could not create cron job automatically")
+
+      p.log.warn(`Cron creation failed. Create it manually:`)
+
+      p.note(
+        `openclaw cron add \\\n` +
+          `  --name "${CRON_JOB_NAME}" \\\n` +
+          `  --every 1h \\\n` +
+          `  --session isolated \\\n` +
+          `  --message "Read the file at ${promptPath} and follow the instructions inside it."`,
+        "Manual cron setup",
+      )
+    }
+
+    // Ask if they want to run the first extraction now
+    const runNow = await p.confirm({
+      message: "Run the Memory Network now? (If not, it will run automatically on the next cron cycle)",
+      initialValue: true,
+    })
+
+    if (!p.isCancel(runNow) && runNow) {
+      if (cronJobId) {
+        const s5 = p.spinner()
+        s5.start("Triggering Memory Network extraction")
+
+        try {
+          execFileSync("openclaw", [
+            "cron", "run", cronJobId,
+          ], { stdio: "pipe", timeout: 10_000 })
+
+          s5.stop("Memory Network extraction triggered — running in the background")
+        } catch {
+          s5.stop("Could not trigger automatically")
+          p.log.info(`You can trigger it manually with: openclaw cron run ${cronJobId}`)
+        }
+      } else {
+        p.log.info("Create the cron job first, then run it with: openclaw cron run <job-id>")
+      }
+    }
+  }
+
   const syncNote = syncMemories
     ? "\n\nMemory sync is enabled — markdown files in memory/ will be\n" +
       "automatically synced to Hyperspell when they change."
     : ""
 
+  const networkNote = !p.isCancel(enableNetwork) && enableNetwork
+    ? "\n\nMemory Network is enabled — entities will be extracted into\n" +
+      "memory/people/, memory/projects/, memory/organizations/, memory/topics/"
+    : ""
+
   p.note(
     "/getcontext <query>  Search your memories for relevant context\n" +
       "/remember <text>     Save something directly to your vault\n\n" +
       "To connect more apps, run: openclaw openclaw-hyperspell connect\n\n" +
       "Auto-context is enabled by default — relevant memories are\n" +
       "automatically injected before each AI response." +
-      syncNote,
+      syncNote +
+      networkNote,
     "How to use Hyperspell",
   )
 
@@ -533,4 +648,70 @@ export function registerCliCommands(program: Command, pluginConfig: unknown): vo
     .action(async () => {
       await runConnect(pluginConfig)
     })
+
+  // Memory Network CLI commands (used by isolated cron sessions via exec)
+  const networkCmd = hyperspellCmd
+    .command("network")
+    .description("Memory Network operations")
+
+  networkCmd
+    .command("scan")
+    .description("Scan for unprocessed memories and output summaries")
+    .option("--batch-size <n>", "Max memories to return", "20")
+    .action(async (opts) => {
+      try {
+        const cfg = parseConfig(pluginConfig)
+        const client = new HyperspellClient(cfg)
+        const workspaceDir = getWorkspaceDir()
+        const stateManager = new NetworkStateManager(workspaceDir)
+        const batchSize = Number.parseInt(opts.batchSize, 10) || 20
+
+        const memories = await scanMemories(client, stateManager, batchSize)
+        const text = formatScanResults(memories, stateManager.getProcessedCount(), stateManager.getLastScanAt())
+        process.stdout.write(text + "\n")
+      } catch (err) {
+        process.stderr.write(`Scan failed: ${err instanceof Error ? err.message : String(err)}\n`)
+        process.exit(1)
+      }
+    })
+
+  networkCmd
+    .command("complete")
+    .description("Mark memory IDs as processed")
+    .requiredOption("--ids <ids>", "Comma-separated resource_ids")
+    .action((opts) => {
+      try {
+        const workspaceDir = getWorkspaceDir()
+        const stateManager = new NetworkStateManager(workspaceDir)
+        const memoryIds = (opts.ids as string).split(",").map((s: string) => s.trim()).filter(Boolean)
+
+        const { newCount, totalCount } = completeMemories(stateManager, memoryIds)
+        process.stdout.write(`Marked ${newCount} new memories as processed (${totalCount} total)\n`)
+      } catch (err) {
+        process.stderr.write(`Complete failed: ${err instanceof Error ? err.message : String(err)}\n`)
+        process.exit(1)
+      }
+    })
+
+  networkCmd
+    .command("sync")
+    .description("Sync entity files in memory/ to Hyperspell")
+    .action(async () => {
+      try {
+        const cfg = parseConfig(pluginConfig)
+        const client = new HyperspellClient(cfg)
+        const workspaceDir = getWorkspaceDir()
+
+        const result = await syncAllMemoryFiles(client, workspaceDir)
+        process.stdout.write(`Synced ${result.synced} files, ${result.failed} failed\n`)
+        if (result.errors.length > 0) {
+          for (const error of result.errors) {
+            process.stderr.write(`  ${error}\n`)
+          }
+        }
+      } catch (err) {
+        process.stderr.write(`Sync failed: ${err instanceof Error ? err.message : String(err)}\n`)
+        process.exit(1)
+      }
+    })
 }

package/config.ts

@@ -10,6 +10,12 @@ export type HyperspellSource =
   | "vault"
   | "web_crawler"
 
+export type KnowledgeGraphConfig = {
+  enabled: boolean
+  scanIntervalMinutes: number
+  batchSize: number
+}
+
 export type HyperspellConfig = {
   apiKey: string
   userId?: string
@@ -18,6 +24,7 @@ export type HyperspellConfig = {
   sources: HyperspellSource[]
   maxResults: number
   debug: boolean
+  knowledgeGraph: KnowledgeGraphConfig
 }
 
 const ALLOWED_KEYS = [
@@ -28,6 +35,7 @@ const ALLOWED_KEYS = [
   "sources",
   "maxResults",
   "debug",
+  "knowledgeGraph",
 ]
 
 const VALID_SOURCES: HyperspellSource[] = [
@@ -128,6 +136,8 @@ export function parseConfig(raw: unknown): HyperspellConfig {
     )
   }
 
+  const kgRaw = (cfg.knowledgeGraph ?? {}) as Record<string, unknown>
+
   return {
     apiKey,
     userId: cfg.userId as string | undefined,
@@ -136,6 +146,11 @@ export function parseConfig(raw: unknown): HyperspellConfig {
     sources: parseSources(cfg.sources as string | string[] | undefined),
     maxResults: (cfg.maxResults as number) ?? 10,
     debug: (cfg.debug as boolean) ?? false,
+    knowledgeGraph: {
+      enabled: (kgRaw.enabled as boolean) ?? false,
+      scanIntervalMinutes: (kgRaw.scanIntervalMinutes as number) ?? 60,
+      batchSize: (kgRaw.batchSize as number) ?? 20,
+    },
   }
 }
 

package/graph/cron.ts

@@ -0,0 +1,364 @@
+export const CRON_JOB_NAME = "Hyperspell Memory Network"
+
+export function buildExtractionPrompt(workspaceDir: string): string {
+  const memoryDir = `${workspaceDir}/memory`
+
+  return `You are a memory network builder. Your job is to scan memories and extract structured entities into markdown files.
+
+## How it works
+
+This runs in an isolated session. Use \`exec\` for data access (scan/complete/sync) and use \`write\` to create entity files directly.
+
+## Steps
+
+1. Run \`openclaw openclaw-hyperspell network scan\` to get a batch of unprocessed memories with content summaries.
+2. Analyze each memory's title, source, participants, and content summary.
+3. Extract entities into these directories:
+   - \`${memoryDir}/people/\` — individuals (include email, phone if known)
+   - \`${memoryDir}/projects/\` — products, initiatives, workstreams
+   - \`${memoryDir}/organizations/\` — companies, teams, groups (include domain)
+   - \`${memoryDir}/topics/\` — technologies, concepts, recurring themes
+4. For each entity, write a markdown file using the format below. If the file already exists, read it first and merge the new data (add new source_memories, relationships, update description if richer).
+5. After extracting all entities from a batch, mark them processed:
+   \`\`\`
+   openclaw openclaw-hyperspell network complete --ids <comma-separated-resource-ids>
+   \`\`\`
+6. **Repeat from step 1** — keep scanning and extracting until the scan returns "No unprocessed memories found." Process ALL available memories, not just one batch.
+7. Once all memories are processed, sync the entity files to Hyperspell:
+   \`\`\`
+   openclaw openclaw-hyperspell network sync
+   \`\`\`
+8. Report a brief summary of what you extracted.
+
+## Entity file format
+
+File names should be lowercase with hyphens, e.g. \`alice-chen.md\`, \`hyperspell.md\`.
+
+---
+
+### People (\`${memoryDir}/people/<slug>.md\`)
+
+Always include email when available. Extract it from sender info, participant lists, and message signatures.
+
+#### Example: Team member with full contact info
+
+\`\`\`markdown
+---
+title: Alice Chen
+type: person
+graph_entity: true
+email: alice@hyperspell.com
+phone: +1-555-123-4567
+source_memories: {"slack":["C073WR69EPM","C074KNCREMN"],"google_mail":["19bbe68026553623"]}
+relationships: ["works-at:organizations/hyperspell","leads:projects/memory-network","collaborates-with:people/bob-martinez"]
+last_extracted: 2026-02-10T12:00:00Z
+---
+# Alice Chen
+
+Engineering Manager at Hyperspell. Leads the Memory Network project. Active in #dev and #general Slack channels. Frequent collaborator with Bob Martinez on architecture decisions.
+
+## Contact
+
+- Email: alice@hyperspell.com
+- Phone: +1-555-123-4567
+
+## Relationships
+
+- works-at: [hyperspell](../organizations/hyperspell.md)
+- leads: [memory network](../projects/memory-network.md)
+- collaborates-with: [bob martinez](../people/bob-martinez.md)
+\`\`\`
+
+#### Example: External contact from email
+
+\`\`\`markdown
+---
+title: Greg Thompson
+type: person
+graph_entity: true
+email: greg@sentry.io
+source_memories: {"google_mail":["19bbe68026553623","19bf6954484abf9f"]}
+relationships: ["works-at:organizations/sentry"]
+last_extracted: 2026-02-10T12:00:00Z
+---
+# Greg Thompson
+
+Contact at Sentry. Organized dinner events with Databricks and Neon teams. Communicated via email about networking meetups.
+
+## Contact
+
+- Email: greg@sentry.io
+
+## Relationships
+
+- works-at: [sentry](../organizations/sentry.md)
+\`\`\`
+
+#### Example: Colleague with minimal info
+
+\`\`\`markdown
+---
+title: Conor Brennan-Burke
+type: person
+graph_entity: true
+email: conor@hyperspell.com
+source_memories: {"slack":["C073WR69EPM","C073WUPLQAW"]}
+relationships: ["works-at:organizations/hyperspell"]
+last_extracted: 2026-02-10T12:00:00Z
+---
+# Conor Brennan-Burke
+
+Team member at Hyperspell. Active in #general and #dev Slack channels.
+
+## Contact
+
+- Email: conor@hyperspell.com
+
+## Relationships
+
+- works-at: [hyperspell](../organizations/hyperspell.md)
+\`\`\`
+
+---
+
+### Organizations (\`${memoryDir}/organizations/<slug>.md\`)
+
+Always include the domain. Derive it from email addresses (e.g. alice@hyperspell.com → hyperspell.com).
+
+#### Example: Own company with many connections
+
+\`\`\`markdown
+---
+title: Hyperspell
+type: organization
+graph_entity: true
+domain: hyperspell.com
+source_memories: {"slack":["C073WR69EPM","C073WUPLQAW","C074KNCREMN"],"notion":["2ef17898-857d-8040-bd94-c03ec8b35a13","2f017898-857d-807e-9ebc-f6ce00fa585f"]}
+relationships: ["employs:people/alice-chen","employs:people/conor-brennan-burke","owns:projects/memory-network","works-on-topic:topics/ai-agents"]
+last_extracted: 2026-02-10T12:00:00Z
+---
+# Hyperspell
+
+AI memory and context platform for agents. Building tools for RAG, knowledge graphs, and multi-source memory integration.
+
+## Contact
+
+- Domain: hyperspell.com
+
+## Relationships
+
+- employs: [alice chen](../people/alice-chen.md)
+- employs: [conor brennan burke](../people/conor-brennan-burke.md)
+- owns: [memory network](../projects/memory-network.md)
+- works-on-topic: [ai agents](../topics/ai-agents.md)
+\`\`\`
+
+#### Example: External company from emails
+
+\`\`\`markdown
+---
+title: Sentry
+type: organization
+graph_entity: true
+domain: sentry.io
+source_memories: {"google_mail":["19bbe68026553623"]}
+relationships: ["employs:people/greg-thompson"]
+last_extracted: 2026-02-10T12:00:00Z
+---
+# Sentry
+
+Application monitoring and error tracking platform. Connected through networking events and industry meetups.
+
+## Contact
+
+- Domain: sentry.io
+
+## Relationships
+
+- employs: [greg thompson](../people/greg-thompson.md)
+\`\`\`
+
+#### Example: Partner company mentioned in docs
+
+\`\`\`markdown
+---
+title: Grove Trials
+type: organization
+graph_entity: true
+domain: grovetrials.com
+source_memories: {"slack":["C073WR69EPM"]}
+relationships: ["employs:people/tran-nguyen","employs:people/sohit-patel"]
+last_extracted: 2026-02-10T12:00:00Z
+---
+# Grove Trials
+
+Partner organization. Team members active in shared Slack channels.
+
+## Contact
+
+- Domain: grovetrials.com
+
+## Relationships
+
+- employs: [tran nguyen](../people/tran-nguyen.md)
+- employs: [sohit patel](../people/sohit-patel.md)
+\`\`\`
+
+---
+
+### Projects (\`${memoryDir}/projects/<slug>.md\`)
+
+#### Example: Internal product initiative
+
+\`\`\`markdown
+---
+title: Memory Network
+type: project
+graph_entity: true
+source_memories: {"notion":["2f017898-857d-807e-9ebc-f6ce00fa585f"],"slack":["C073WUPLQAW"]}
+relationships: ["owned-by:organizations/hyperspell","led-by:people/alice-chen","uses:topics/knowledge-graphs","uses:topics/rag"]
+last_extracted: 2026-02-10T12:00:00Z
+---
+# Memory Network
+
+Feature for automatically extracting entities (people, projects, orgs, topics) from indexed memories and building a structured knowledge graph as markdown files.
+
+## Relationships
+
+- owned-by: [hyperspell](../organizations/hyperspell.md)
+- led-by: [alice chen](../people/alice-chen.md)
+- uses: [knowledge graphs](../topics/knowledge-graphs.md)
+- uses: [rag](../topics/rag.md)
+\`\`\`
+
+#### Example: Hiring initiative from docs
+
+\`\`\`markdown
+---
+title: Hiring Plan
+type: project
+graph_entity: true
+source_memories: {"notion":["2f017898-857d-807e-9ebc-f6ce00fa585f"]}
+relationships: ["owned-by:organizations/hyperspell"]
+last_extracted: 2026-02-10T12:00:00Z
+---
+# Hiring Plan
+
+Company hiring initiative documented in Notion. Covers open roles, recruiting pipeline, and growth targets.
+
+## Relationships
+
+- owned-by: [hyperspell](../organizations/hyperspell.md)
+\`\`\`
+
+#### Example: Competitive analysis
+
+\`\`\`markdown
+---
+title: Competitor Analysis
+type: project
+graph_entity: true
+source_memories: {"notion":["2ef17898-857d-8040-bd94-c03ec8b35a13"]}
+relationships: ["owned-by:organizations/hyperspell","covers:topics/rag","covers:topics/ai-agents"]
+last_extracted: 2026-02-10T12:00:00Z
+---
+# Competitor Analysis
+
+Analysis of memory and context competitors in the AI agent space. Covers feature comparisons, data processing capabilities, and market positioning.
+
+## Relationships
+
+- owned-by: [hyperspell](../organizations/hyperspell.md)
+- covers: [rag](../topics/rag.md)
+- covers: [ai agents](../topics/ai-agents.md)
+\`\`\`
+
+---
+
+### Topics (\`${memoryDir}/topics/<slug>.md\`)
+
+#### Example: Core technology
+
+\`\`\`markdown
+---
+title: Knowledge Graphs
+type: topic
+graph_entity: true
+source_memories: {"notion":["2ef17898-857d-8040-bd94-c03ec8b35a13"],"slack":["C073WUPLQAW"]}
+relationships: ["used-by:projects/memory-network","discussed-by:organizations/hyperspell"]
+last_extracted: 2026-02-10T12:00:00Z
+---
+# Knowledge Graphs
+
+Entity extraction and relationship mapping for building structured knowledge from unstructured data. Central to the Memory Network project.
+
+## Relationships
+
+- used-by: [memory network](../projects/memory-network.md)
+- discussed-by: [hyperspell](../organizations/hyperspell.md)
+\`\`\`
+
+#### Example: Broad domain topic
+
+\`\`\`markdown
+---
+title: AI Agents
+type: topic
+graph_entity: true
+source_memories: {"notion":["2ef17898-857d-8040-bd94-c03ec8b35a13","2f017898-857d-807e-9ebc-f6ce00fa585f"],"slack":["C073WUPLQAW"]}
+relationships: ["discussed-by:organizations/hyperspell","related-to:topics/rag","related-to:topics/knowledge-graphs"]
+last_extracted: 2026-02-10T12:00:00Z
+---
+# AI Agents
+
+Autonomous AI systems that use tools, memory, and context to accomplish tasks. Core focus area for Hyperspell's product.
+
+## Relationships
+
+- discussed-by: [hyperspell](../organizations/hyperspell.md)
+- related-to: [rag](../topics/rag.md)
+- related-to: [knowledge graphs](../topics/knowledge-graphs.md)
+\`\`\`
+
+#### Example: Specific technology
+
+\`\`\`markdown
+---
+title: RAG
+type: topic
+graph_entity: true
+source_memories: {"notion":["2ef17898-857d-8040-bd94-c03ec8b35a13"]}
+relationships: ["used-by:projects/memory-network","related-to:topics/knowledge-graphs"]
+last_extracted: 2026-02-10T12:00:00Z
+---
+# RAG
+
+Retrieval-Augmented Generation — technique for grounding LLM responses in retrieved documents. Used across Hyperspell's search and context injection features.
+
+## Relationships
+
+- used-by: [memory network](../projects/memory-network.md)
+- related-to: [knowledge graphs](../topics/knowledge-graphs.md)
+\`\`\`
+
+## Guidelines
+
+- **Process everything**: On the first run there may be hundreds of memories. Keep looping through scan → extract → complete until done.
+- **Merge, don't duplicate**: If a file already exists, read it, merge source_memories and relationships, and write back. Preserve the existing hyperspell_id if present.
+- **Skip noise**: Ignore automated notifications, bot messages, join/leave events, and system messages.
+- **Be selective**: Only extract entities that are meaningful and identifiable. Don't create entities for vague references.
+- **Cross-reference**: Use relationships to connect people to organizations, projects to topics, etc.
+- **Contact info is critical**: For people, always capture email addresses from sender/participant data. For organizations, derive their domain from email addresses (e.g. alice@hyperspell.com → hyperspell.com).
+- **source_memories format**: JSON object with source provider as key and array of resource_ids as value.
+- **graph_entity: true**: Always include this — it prevents the scan from re-processing entity files that get synced back to Hyperspell.`
+}
+
+export function getCronSetupCommand(workspaceDir: string, interval: string = "1h"): string {
+  const prompt = buildExtractionPrompt(workspaceDir)
+  const escaped = prompt.replace(/'/g, "'\\''")
+  return `openclaw cron add --name '${CRON_JOB_NAME}' --every ${interval} --session isolated --message '${escaped}'`
+}
+
+export function getCronRemoveCommand(): string {
+  return `openclaw cron remove --name '${CRON_JOB_NAME}'`
+}

package/graph/index.ts

@@ -0,0 +1,5 @@
+export { NetworkStateManager } from "./state.ts"
+export { registerNetworkTools } from "./tools.ts"
+export { scanMemories, formatScanResults, writeEntity, completeMemories, slugify } from "./ops.ts"
+export type { EntityType, SourceMemories, ScannedMemory, WriteEntityParams } from "./ops.ts"
+export { buildExtractionPrompt, getCronSetupCommand, getCronRemoveCommand, CRON_JOB_NAME } from "./cron.ts"

package/graph/ops.ts

@@ -0,0 +1,253 @@
+import * as fs from "node:fs"
+import * as path from "node:path"
+import type { HyperspellClient } from "../client.ts"
+import { log } from "../logger.ts"
+import { NetworkStateManager } from "./state.ts"
+
+const ENTITY_TYPES = ["people", "projects", "organizations", "topics"] as const
+export type EntityType = (typeof ENTITY_TYPES)[number]
+
+export interface SourceMemories {
+  [source: string]: string[]
+}
+
+export interface ScannedMemory {
+  resourceId: string
+  source: string
+  title: string | null
+  summary: string
+}
+
+export interface WriteEntityParams {
+  type: EntityType
+  slug: string
+  name: string
+  description: string
+  relationships?: string[]
+  sourceMemories?: SourceMemories
+  email?: string
+  phone?: string
+  domain?: string
+}
+
+export function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+}
+
+function summarizeMemoryData(data: unknown[], source: string): string {
+  if (!Array.isArray(data) || data.length === 0) return ""
+
+  const items = data as Array<Record<string, unknown>>
+
+  if (source === "slack" || source === "google_mail") {
+    const senders = new Map<string, string>()
+    const messages: string[] = []
+    for (const item of items) {
+      const sender = item.sender as Record<string, unknown> | undefined
+      if (sender?.name && sender?.email) {
+        senders.set(String(sender.email), String(sender.name))
+      }
+      if (item.content && messages.length < 5) {
+        messages.push(String(item.content).slice(0, 200))
+      }
+    }
+    const parts: string[] = []
+    if (senders.size > 0) {
+      parts.push(`Participants: ${[...senders.entries()].map(([e, n]) => `${n} <${e}>`).join(", ")}`)
+    }
+    if (messages.length > 0) {
+      parts.push(`Recent messages:\n${messages.join("\n---\n")}`)
+    }
+    return parts.join("\n\n")
+  }
+
+  if (source === "notion") {
+    const parts: string[] = []
+    for (const item of items.slice(0, 10)) {
+      if (item.__type === "Title" && item.text) {
+        parts.push(`## ${item.text}`)
+      } else if (item.__type === "Markdown" && item.text) {
+        parts.push(String(item.text).slice(0, 300))
+      } else if (item.__type === "Table" && item.table_rows) {
+        const rows = item.table_rows as string[][]
+        if (rows[0]) parts.push(`Table: ${rows[0].join(" | ")}`)
+      }
+    }
+    return parts.join("\n")
+  }
+
+  const parts: string[] = []
+  for (const item of items.slice(0, 10)) {
+    if (item.text) {
+      parts.push(String(item.text).slice(0, 300))
+    }
+  }
+  return parts.join("\n")
+}
+
+export async function scanMemories(
+  client: HyperspellClient,
+  stateManager: NetworkStateManager,
+  batchSize: number,
+): Promise<ScannedMemory[]> {
+  const unprocessed: ScannedMemory[] = []
+
+  for await (const mem of client.listMemories()) {
+    if (stateManager.isProcessed(mem.resourceId)) continue
+    if (mem.metadata?.graph_entity === "true" || mem.metadata?.graph_entity === true) continue
+    if ((mem.metadata?.status as string) !== "completed") continue
+
+    let summary = ""
+    try {
+      const full = await client.getMemory(mem.resourceId, mem.source)
+      const data = full.data as unknown[] | undefined
+
+      const participants = full.participants as Array<{ name?: string; email?: string }> | undefined
+      const participantLine = participants?.length
+        ? `Participants: ${participants.map((p) => `${p.name || ""} <${p.email || ""}>`).join(", ")}`
+        : ""
+
+      const dataSummary = data ? summarizeMemoryData(data, mem.source) : ""
+      summary = [participantLine, dataSummary].filter(Boolean).join("\n\n")
+    } catch {
+      summary = "(content unavailable)"
+    }
+
+    unprocessed.push({
+      resourceId: mem.resourceId,
+      source: mem.source,
+      title: mem.title,
+      summary: summary.slice(0, 1000),
+    })
+
+    if (unprocessed.length >= batchSize) break
+  }
+
+  return unprocessed
+}
+
+export function formatScanResults(memories: ScannedMemory[], processedCount: number, lastScan: string | null): string {
+  if (memories.length === 0) {
+    return `No unprocessed memories found. ${processedCount} memories already processed. Last scan: ${lastScan || "never"}`
+  }
+
+  const formatted = memories
+    .map((m) => {
+      const lines = [`[${m.source}] ${m.title || "(untitled)"} (id: ${m.resourceId})`]
+      if (m.summary) lines.push(m.summary)
+      return lines.join("\n")
+    })
+    .join("\n\n---\n\n")
+
+  return `Found ${memories.length} unprocessed memories:\n\n${formatted}`
+}
+
+export function writeEntity(workspaceDir: string, params: WriteEntityParams): string {
+  const slug = slugify(params.slug)
+  const dir = path.join(workspaceDir, "memory", params.type)
+  const filePath = path.join(dir, `${slug}.md`)
+
+  fs.mkdirSync(dir, { recursive: true })
+
+  // Check for existing file and merge
+  let existingSourceMemories: SourceMemories = {}
+  let existingRelationships: string[] = []
+  let hyperspellId = ""
+
+  if (fs.existsSync(filePath)) {
+    const existing = fs.readFileSync(filePath, "utf-8")
+    const fmMatch = existing.match(/^---\n([\s\S]*?)\n---\n?/)
+    if (fmMatch) {
+      const fmText = fmMatch[1]
+      for (const line of fmText.split("\n")) {
+        const idx = line.indexOf(":")
+        if (idx <= 0) continue
+        const key = line.slice(0, idx).trim()
+        const val = line.slice(idx + 1).trim()
+        if (key === "hyperspell_id") hyperspellId = val
+        if (key === "source_memories") {
+          try { existingSourceMemories = JSON.parse(val) } catch {}
+        }
+        if (key === "relationships") {
+          try { existingRelationships = JSON.parse(val) } catch {}
+        }
+      }
+    }
+  }
+
+  // Merge source memories
+  const mergedSources: SourceMemories = { ...existingSourceMemories }
+  if (params.sourceMemories) {
+    for (const [source, ids] of Object.entries(params.sourceMemories)) {
+      const existing = mergedSources[source] || []
+      const merged = [...new Set([...existing, ...ids])]
+      mergedSources[source] = merged
+    }
+  }
+
+  // Merge relationships
+  const mergedRelationships = [
+    ...new Set([...existingRelationships, ...(params.relationships || [])]),
+  ]
+
+  // Build frontmatter
+  const fm: Record<string, string> = {
+    title: params.name,
+    type: params.type.slice(0, -1), // "people" → "person"
+    graph_entity: "true",
+    source_memories: JSON.stringify(mergedSources),
+    last_extracted: new Date().toISOString(),
+  }
+  if (hyperspellId) fm.hyperspell_id = hyperspellId
+  if (mergedRelationships.length > 0) {
+    fm.relationships = JSON.stringify(mergedRelationships)
+  }
+  if (params.email) fm.email = params.email
+  if (params.phone) fm.phone = params.phone
+  if (params.domain) fm.domain = params.domain
+
+  // Build body
+  const bodyParts = [`# ${params.name}\n`, params.description]
+
+  const contactParts: string[] = []
+  if (params.email) contactParts.push(`- Email: ${params.email}`)
+  if (params.phone) contactParts.push(`- Phone: ${params.phone}`)
+  if (params.domain) contactParts.push(`- Domain: ${params.domain}`)
+  if (contactParts.length > 0) {
+    bodyParts.push("\n## Contact\n")
+    bodyParts.push(...contactParts)
+  }
+
+  if (mergedRelationships.length > 0) {
+    bodyParts.push("\n## Relationships\n")
+    for (const rel of mergedRelationships) {
+      const [relationship, target] = rel.split(":")
+      if (target) {
+        const targetName = target.split("/").pop()?.replace(/-/g, " ") || target
+        bodyParts.push(`- ${relationship}: [${targetName}](../${target}.md)`)
+      } else {
+        bodyParts.push(`- ${rel}`)
+      }
+    }
+  }
+
+  // Build file content
+  const fmLines = Object.entries(fm).map(([k, v]) => `${k}: ${v}`)
+  const content = `---\n${fmLines.join("\n")}\n---\n${bodyParts.join("\n")}\n`
+
+  fs.writeFileSync(filePath, content)
+  log.info(`Wrote entity: ${params.type}/${slug}.md`)
+
+  return `${params.type}/${slug}.md`
+}
+
+export function completeMemories(stateManager: NetworkStateManager, memoryIds: string[]): { newCount: number; totalCount: number } {
+  const newCount = stateManager.markProcessed(memoryIds)
+  stateManager.updateLastScan()
+  stateManager.save()
+  return { newCount, totalCount: stateManager.getProcessedCount() }
+}

package/graph/state.ts

@@ -0,0 +1,79 @@
+import * as fs from "node:fs"
+import * as path from "node:path"
+import { log } from "../logger.ts"
+
+const STATE_VERSION = 1
+const STATE_FILENAME = ".network-state.json"
+
+export interface NetworkState {
+  processedIds: Record<string, string> // resource_id → ISO timestamp
+  lastScanAt: string | null
+  version: number
+}
+
+export class NetworkStateManager {
+  private statePath: string
+  private state: NetworkState
+
+  constructor(workspaceDir: string) {
+    const memoryDir = path.join(workspaceDir, "memory")
+    fs.mkdirSync(memoryDir, { recursive: true })
+    this.statePath = path.join(memoryDir, STATE_FILENAME)
+    this.state = this.load()
+  }
+
+  private load(): NetworkState {
+    try {
+      if (fs.existsSync(this.statePath)) {
+        const raw = fs.readFileSync(this.statePath, "utf-8")
+        const parsed = JSON.parse(raw)
+        if (parsed.version === STATE_VERSION) {
+          return parsed
+        }
+        log.warn(`Network state version mismatch (got ${parsed.version}, want ${STATE_VERSION}), resetting`)
+      }
+    } catch (err) {
+      log.warn("Failed to load network state, starting fresh", err)
+    }
+    return { processedIds: {}, lastScanAt: null, version: STATE_VERSION }
+  }
+
+  save(): void {
+    const tmpPath = this.statePath + ".tmp"
+    try {
+      fs.writeFileSync(tmpPath, JSON.stringify(this.state, null, 2))
+      fs.renameSync(tmpPath, this.statePath)
+    } catch (err) {
+      log.error("Failed to save network state", err)
+      try { fs.unlinkSync(tmpPath) } catch {}
+    }
+  }
+
+  isProcessed(resourceId: string): boolean {
+    return resourceId in this.state.processedIds
+  }
+
+  markProcessed(resourceIds: string[]): number {
+    let count = 0
+    const now = new Date().toISOString()
+    for (const id of resourceIds) {
+      if (!(id in this.state.processedIds)) {
+        this.state.processedIds[id] = now
+        count++
+      }
+    }
+    return count
+  }
+
+  updateLastScan(): void {
+    this.state.lastScanAt = new Date().toISOString()
+  }
+
+  getProcessedCount(): number {
+    return Object.keys(this.state.processedIds).length
+  }
+
+  getLastScanAt(): string | null {
+    return this.state.lastScanAt
+  }
+}

package/graph/tools.ts

@@ -0,0 +1,117 @@
+import { Type } from "@sinclair/typebox"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { HyperspellClient } from "../client.ts"
+import type { HyperspellConfig } from "../config.ts"
+import { getWorkspaceDir } from "../config.ts"
+import { log } from "../logger.ts"
+import { NetworkStateManager } from "./state.ts"
+import { scanMemories, formatScanResults, writeEntity, completeMemories } from "./ops.ts"
+import type { EntityType, SourceMemories } from "./ops.ts"
+
+const ENTITY_TYPES = ["people", "projects", "organizations", "topics"] as const
+
+export function registerNetworkTools(
+  api: OpenClawPluginApi,
+  client: HyperspellClient,
+  cfg: HyperspellConfig,
+): void {
+  const workspaceDir = getWorkspaceDir()
+  const stateManager = new NetworkStateManager(workspaceDir)
+
+  api.registerTool(
+    {
+      name: "hyperspell_network_scan",
+      label: "Memory Network Scan",
+      description:
+        "Scan Hyperspell memories and return a batch of unprocessed ones with their content summaries. Use this to find new memories that need entity extraction.",
+      parameters: Type.Object({
+        batchSize: Type.Optional(
+          Type.Number({ description: "Max memories to return (default: 20)" }),
+        ),
+      }),
+      async execute(_toolCallId: string, params: { batchSize?: number }) {
+        const batchSize = params.batchSize ?? cfg.knowledgeGraph.batchSize
+        try {
+          const memories = await scanMemories(client, stateManager, batchSize)
+          const text = formatScanResults(memories, stateManager.getProcessedCount(), stateManager.getLastScanAt())
+          return {
+            content: [{ type: "text" as const, text }],
+            details: { count: memories.length, memories },
+          }
+        } catch (err) {
+          log.error("network scan failed", err)
+          return {
+            content: [{ type: "text" as const, text: `Scan failed: ${err instanceof Error ? err.message : String(err)}` }],
+          }
+        }
+      },
+    },
+    { name: "hyperspell_network_scan" },
+  )
+
+  api.registerTool(
+    {
+      name: "hyperspell_network_write",
+      label: "Memory Network Write",
+      description:
+        "Write or update an entity file in the memory network. Creates markdown files in memory/people/, memory/projects/, memory/organizations/, or memory/topics/.",
+      parameters: Type.Object({
+        type: Type.Union(ENTITY_TYPES.map((t) => Type.Literal(t)), {
+          description: "Entity type: people, projects, organizations, or topics",
+        }),
+        slug: Type.String({ description: "URL-safe identifier (lowercase with hyphens, e.g. 'alice-chen')" }),
+        name: Type.String({ description: "Display name of the entity" }),
+        description: Type.String({ description: "Description of the entity" }),
+        relationships: Type.Optional(
+          Type.Array(Type.String(), {
+            description: "Relationships in format 'relationship:type/slug', e.g. 'works-at:organizations/hyperspell'",
+          }),
+        ),
+        sourceMemories: Type.Optional(
+          Type.Record(Type.String(), Type.Array(Type.String()), {
+            description: "Source memories by provider, e.g. { slack: ['C073WR69EPM'], google_mail: ['19bbe68026553623'] }",
+          }),
+        ),
+        email: Type.Optional(Type.String({ description: "Email address (for people)" })),
+        phone: Type.Optional(Type.String({ description: "Phone number (for people)" })),
+        domain: Type.Optional(Type.String({ description: "Domain/homepage (for organizations)" })),
+      }),
+      async execute(
+        _toolCallId: string,
+        params: { type: EntityType; slug: string; name: string; description: string; relationships?: string[]; sourceMemories?: SourceMemories; email?: string; phone?: string; domain?: string },
+      ) {
+        try {
+          const result = writeEntity(workspaceDir, params)
+          return { content: [{ type: "text" as const, text: `Wrote ${result} (${params.name})` }] }
+        } catch (err) {
+          log.error(`network write failed: ${params.type}/${params.slug}`, err)
+          return { content: [{ type: "text" as const, text: `Write failed: ${err instanceof Error ? err.message : String(err)}` }] }
+        }
+      },
+    },
+    { name: "hyperspell_network_write" },
+  )
+
+  api.registerTool(
+    {
+      name: "hyperspell_network_complete",
+      label: "Memory Network Complete",
+      description: "Mark a batch of memory IDs as processed so they won't appear in future scans.",
+      parameters: Type.Object({
+        memoryIds: Type.Array(Type.String(), { description: "List of resource_ids to mark as processed" }),
+      }),
+      async execute(_toolCallId: string, params: { memoryIds: string[] }) {
+        try {
+          const { newCount, totalCount } = completeMemories(stateManager, params.memoryIds)
+          return {
+            content: [{ type: "text" as const, text: `Marked ${newCount} new memories as processed (${totalCount} total). Last scan: ${stateManager.getLastScanAt()}` }],
+          }
+        } catch (err) {
+          log.error("network complete failed", err)
+          return { content: [{ type: "text" as const, text: `Complete failed: ${err instanceof Error ? err.message : String(err)}` }] }
+        }
+      },
+    },
+    { name: "hyperspell_network_complete" },
+  )
+}

package/index.ts

@@ -8,6 +8,7 @@ import { buildFileSyncHandler, syncMemoriesOnStartup } from "./hooks/memory-sync
 import { initLogger } from "./logger.ts"
 import { registerRememberTool } from "./tools/remember.ts"
 import { registerSearchTool } from "./tools/search.ts"
+import { registerNetworkTools } from "./graph/index.ts"
 
 export default {
   id: "openclaw-hyperspell",
@@ -84,6 +85,11 @@ export default {
       api.on("file_changed", fileSyncHandler)
     }
 
+    // Register memory network tools
+    if (cfg.knowledgeGraph.enabled) {
+      registerNetworkTools(api, client, cfg)
+    }
+
     // Register slash commands
     registerCommands(api, client, cfg)
 

package/openclaw.plugin.json

@@ -40,6 +40,11 @@
       "label": "Sync Memory Files",
       "help": "Automatically sync markdown files in workspace/memory/ to Hyperspell",
       "advanced": true
+    },
+    "knowledgeGraph": {
+      "label": "Memory Network",
+      "help": "Extract entities (people, projects, orgs, topics) from memories into structured markdown files. Requires a cron job for periodic scanning.",
+      "advanced": true
     }
   },
   "configSchema": {
@@ -68,6 +73,14 @@
       },
       "syncMemories": {
         "type": "boolean"
+      },
+      "knowledgeGraph": {
+        "type": "object",
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "scanIntervalMinutes": { "type": "number", "minimum": 5, "maximum": 1440 },
+          "batchSize": { "type": "number", "minimum": 5, "maximum": 100 }
+        }
       }
     },
     "required": []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspell/openclaw-hyperspell",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "type": "module",
   "description": "OpenClaw Hyperspell memory plugin",
   "license": "MIT",
@@ -11,6 +11,7 @@
     "hooks/",
     "tools/",
     "sync/",
+    "graph/",
     "lib/",
     "types/",
     "openclaw.plugin.json",