feat: add SDK Skills + Memory System (#89)

* feat: catch up with Python

* feat: add SDK Skills + Memory System

Port SDK Skills and Agent Memory features from Python PR 646.

* prettier

* fix unit test for Windows

* add example

* format

Author: christian-bromann

.gitignore

@@ -55,4 +55,4 @@ agent-os
 .claude
 
 # Sandbox workspace directory - created at runtime
-sandbox-workspace/
+sandbox-workspace/

examples/skills-memory/skills-memory-agent.ts

@@ -0,0 +1,156 @@
+/* eslint-disable no-console */
+/**
+ * Skills + Memory Agent Example
+ *
+ * This example demonstrates how to use the Skills and Agent Memory middleware
+ * to create an agent with:
+ * - Discoverable skills from SKILL.md files
+ * - Persistent long-term memory from agent.md files
+ *
+ * To run this example:
+ *   npx tsx examples/skills-memory/skills-memory-agent.ts
+ *
+ * Prerequisites:
+ *   - Set OPENAI_API_KEY or ANTHROPIC_API_KEY environment variable
+ *   - Optionally create skills in ~/.deepagents/my-agent/skills/
+ *   - Optionally create agent.md in ~/.deepagents/my-agent/
+ */
+
+import { ChatOpenAI } from "@langchain/openai";
+import { ChatAnthropic } from "@langchain/anthropic";
+import { HumanMessage } from "@langchain/core/messages";
+import path from "node:path";
+
+import {
+  createDeepAgent,
+  createSettings,
+  createSkillsMiddleware,
+  createAgentMemoryMiddleware,
+  listSkills,
+} from "../../src/index.js";
+
+// Configuration
+const AGENT_NAME = "my-agent";
+
+async function main() {
+  console.log("🚀 Skills + Memory Agent Example\n");
+
+  // Create settings with project detection
+  const settings = createSettings();
+
+  console.log("📁 Environment:");
+  console.log(`   User deepagents dir: ${settings.userDeepagentsDir}`);
+  console.log(
+    `   Project root: ${settings.projectRoot || "(not in a project)"}`,
+  );
+  console.log(`   Has project: ${settings.hasProject}\n`);
+
+  // Get skills directories
+  const userSkillsDir = settings.getUserSkillsDir(AGENT_NAME);
+  const projectSkillsDir = settings.getProjectSkillsDir();
+
+  console.log("🛠️  Skills directories:");
+  console.log(`   User skills: ${userSkillsDir}`);
+  console.log(
+    `   Project skills: ${projectSkillsDir || "(not in a project)"}\n`,
+  );
+
+  // List available skills
+  const skills = listSkills({
+    userSkillsDir,
+    projectSkillsDir,
+  });
+
+  if (skills.length > 0) {
+    console.log("📚 Available skills:");
+    for (const skill of skills) {
+      console.log(
+        `   - ${skill.name} (${skill.source}): ${skill.description.slice(0, 60)}...`,
+      );
+    }
+    console.log();
+  } else {
+    console.log("📚 No skills found. You can create skills in:");
+    console.log(`   - ${userSkillsDir}/{skill-name}/SKILL.md`);
+    if (projectSkillsDir) {
+      console.log(`   - ${projectSkillsDir}/{skill-name}/SKILL.md`);
+    }
+    console.log();
+  }
+
+  // Get memory paths
+  const userMemoryPath = settings.getUserAgentMdPath(AGENT_NAME);
+  const projectMemoryPath = settings.getProjectAgentMdPath();
+
+  console.log("🧠 Memory locations:");
+  console.log(`   User memory: ${userMemoryPath}`);
+  console.log(
+    `   Project memory: ${projectMemoryPath || "(not in a project)"}\n`,
+  );
+
+  // Create the model
+  const model = process.env.ANTHROPIC_API_KEY
+    ? new ChatAnthropic({ model: "claude-sonnet-4-20250514" })
+    : new ChatOpenAI({ model: "gpt-4o-mini" });
+
+  console.log(
+    `🤖 Using model: ${process.env.ANTHROPIC_API_KEY ? "Claude" : "GPT-4o-mini"}\n`,
+  );
+
+  // Create middleware stack
+  // Note: createDeepAgent already includes FilesystemMiddleware by default
+  const skillsMiddleware = createSkillsMiddleware({
+    skillsDir: userSkillsDir,
+    assistantId: AGENT_NAME,
+    projectSkillsDir: projectSkillsDir || undefined,
+  });
+
+  const memoryMiddleware = createAgentMemoryMiddleware({
+    settings,
+    assistantId: AGENT_NAME,
+  });
+
+  // Create the agent with skills + memory middleware
+  // (FilesystemMiddleware is already included by createDeepAgent)
+  const agent = await createDeepAgent({
+    model,
+    middleware: [skillsMiddleware, memoryMiddleware],
+  });
+
+  console.log("💬 Agent ready! Asking about available skills...\n");
+  console.log("─".repeat(60));
+
+  // Test the agent
+  const result = await agent.invoke({
+    messages: [
+      new HumanMessage(
+        "What skills do you have access to? List them with their descriptions. " +
+          "Also, do you have any long-term memory configured?",
+      ),
+    ],
+  });
+
+  // Get the last AI message
+  const messages = result.messages;
+  const lastMessage = messages[messages.length - 1];
+
+  console.log("\n🤖 Agent response:\n");
+  console.log(lastMessage.content);
+  console.log("\n" + "─".repeat(60));
+
+  // Show how to create a skill
+  console.log("\n💡 Tips:");
+  console.log("\n   To add a skill, run these commands:");
+  console.log(`     mkdir -p "${userSkillsDir}/my-skill"`);
+  console.log(
+    `     printf '%s\\n' '---' 'name: my-skill' 'description: A custom skill' '---' '' '# My Skill' '' 'Instructions...' > "${userSkillsDir}/my-skill/SKILL.md"`,
+  );
+
+  console.log("\n   To add agent memory:");
+  console.log(`     mkdir -p "${path.dirname(userMemoryPath)}"`);
+  console.log(
+    `     printf '%s\\n' '# Agent Memory' '' 'Remember to be helpful!' > "${userMemoryPath}"`,
+  );
+}
+
+main().catch(console.error);

examples/skills/arxiv-search/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: arxiv-search
+description: Search arXiv preprint repository for papers in physics, mathematics, computer science, quantitative biology, and related fields
+---
+
+# arXiv Search Skill
+
+This skill provides access to arXiv, a free distribution service and open-access archive for scholarly articles in physics, mathematics, computer science, quantitative biology, quantitative finance, statistics, electrical engineering, systems science, and economics.
+
+## When to Use This Skill
+
+Use this skill when you need to:
+
+- Find preprints and recent research papers before journal publication
+- Search for papers in computational biology, bioinformatics, or systems biology
+- Access mathematical or statistical methods papers relevant to biology
+- Find machine learning papers applied to biological problems
+- Get the latest research that may not yet be in PubMed
+
+## How to Use
+
+The skill provides a TypeScript script that searches arXiv and returns formatted results.
+
+### Basic Usage
+
+**Note:** Always use the absolute path from your skills directory (shown in the system prompt above).
+
+```bash
+npx tsx [YOUR_SKILLS_DIR]/arxiv-search/arxiv_search.ts "your search query" [--max-papers N]
+```
+
+Replace `[YOUR_SKILLS_DIR]` with the absolute skills directory path from your system prompt (e.g., `~/.deepagents/agent/skills` or the full absolute path).
+
+**Arguments:**
+
+- `query` (required): The search query string (e.g., "neural networks protein structure", "single cell RNA-seq")
+- `--max-papers` (optional): Maximum number of papers to retrieve (default: 10)
+
+### Examples
+
+Search for machine learning papers:
+
+```bash
+npx tsx ~/.deepagents/agent/skills/arxiv-search/arxiv_search.ts "deep learning drug discovery" --max-papers 5
+```
+
+Search for computational biology papers:
+
+```bash
+npx tsx ~/.deepagents/agent/skills/arxiv-search/arxiv_search.ts "protein folding prediction"
+```
+
+Search for bioinformatics methods:
+
+```bash
+npx tsx ~/.deepagents/agent/skills/arxiv-search/arxiv_search.ts "genome assembly algorithms"
+```
+
+## Output Format
+
+The script returns formatted results with:
+
+- **Title**: Paper title
+- **Summary**: Abstract/summary text
+
+Each paper is separated by blank lines for readability.
+
+## Features
+
+- **Relevance sorting**: Results ordered by relevance to query
+- **Fast retrieval**: Direct API access with no authentication required
+- **Simple interface**: Clean, easy-to-parse output
+- **No API key required**: Free access to arXiv database
+
+## Notes
+
+- arXiv is particularly strong for:
+  - Computer science (cs.LG, cs.AI, cs.CV)
+  - Quantitative biology (q-bio)
+  - Statistics (stat.ML)
+  - Physics and mathematics
+- Papers are preprints and may not be peer-reviewed
+- Results include both recent uploads and older papers
+- Best for computational/theoretical work in biology

examples/skills/arxiv-search/arxiv_search.ts

@@ -0,0 +1,103 @@
+#!/usr/bin/env npx tsx
+/* eslint-disable no-console */
+/**
+ * arXiv Search.
+ *
+ * Searches the arXiv preprint repository for research papers.
+ * Uses the arXiv API directly without requiring any dependencies.
+ */
+
+interface ArxivEntry {
+  title: string;
+  summary: string;
+}
+
+/**
+ * Query arXiv for papers based on the provided search query.
+ *
+ * @param query - The search query string
+ * @param maxPapers - Maximum number of papers to retrieve (default: 10)
+ * @returns Formatted search results or an error message
+ */
+async function queryArxiv(query: string, maxPapers = 10): Promise<string> {
+  try {
+    // Build arXiv API URL
+    const encodedQuery = encodeURIComponent(query);
+    const url = `http://export.arxiv.org/api/query?search_query=all:${encodedQuery}&start=0&max_results=${maxPapers}&sortBy=relevance&sortOrder=descending`;
+
+    const response = await fetch(url);
+    if (!response.ok) {
+      return `Error: Failed to fetch from arXiv API (status ${response.status})`;
+    }
+
+    const xml = await response.text();
+
+    // Parse XML response (simple regex-based parsing for portability)
+    const entries: ArxivEntry[] = [];
+    const entryRegex = /<entry>([\s\S]*?)<\/entry>/g;
+    const titleRegex = /<title>([\s\S]*?)<\/title>/;
+    const summaryRegex = /<summary>([\s\S]*?)<\/summary>/;
+
+    let match;
+    while ((match = entryRegex.exec(xml)) !== null) {
+      const entryXml = match[1];
+
+      const titleMatch = titleRegex.exec(entryXml);
+      const summaryMatch = summaryRegex.exec(entryXml);
+
+      if (titleMatch && summaryMatch) {
+        entries.push({
+          title: titleMatch[1].trim().replace(/\s+/g, " "),
+          summary: summaryMatch[1].trim().replace(/\s+/g, " "),
+        });
+      }
+    }
+
+    if (entries.length === 0) {
+      return "No papers found on arXiv.";
+    }
+
+    return entries
+      .map((paper) => `Title: ${paper.title}\nSummary: ${paper.summary}`)
+      .join("\n\n");
+  } catch (error) {
+    return `Error querying arXiv: ${error}`;
+  }
+}
+
+function main(): void {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    console.log(`
+Usage: npx tsx arxiv_search.ts <query> [--max-papers N]
+
+Arguments:
+  query           Search query string (required)
+  --max-papers N  Maximum number of papers to retrieve (default: 10)
+
+Examples:
+  npx tsx arxiv_search.ts "deep learning drug discovery"
+  npx tsx arxiv_search.ts "protein folding" --max-papers 5
+`);
+    process.exit(0);
+  }
+
+  const query = args[0];
+  let maxPapers = 10;
+
+  const maxPapersIndex = args.indexOf("--max-papers");
+  if (maxPapersIndex !== -1 && args[maxPapersIndex + 1]) {
+    maxPapers = parseInt(args[maxPapersIndex + 1], 10);
+    if (isNaN(maxPapers) || maxPapers < 1) {
+      console.error("Error: --max-papers must be a positive integer");
+      process.exit(1);
+    }
+  }
+
+  queryArxiv(query, maxPapers).then((result) => {
+    console.log(result);
+  });
+}
+
+main();

examples/skills/langgraph-docs/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: langgraph-docs
+description: Use this skill for requests related to LangGraph in order to fetch relevant documentation to provide accurate, up-to-date guidance.
+---
+
+# langgraph-docs
+
+## Overview
+
+This skill explains how to access LangGraph Python documentation to help answer questions and guide implementation.
+
+## Instructions
+
+### 1. Fetch the Documentation Index
+
+Use the fetch_url tool to read the following URL:
+https://docs.langchain.com/llms.txt
+
+This provides a structured list of all available documentation with descriptions.
+
+### 2. Select Relevant Documentation
+
+Based on the question, identify 2-4 most relevant documentation URLs from the index. Prioritize:
+
+- Specific how-to guides for implementation questions
+- Core concept pages for understanding questions
+- Tutorials for end-to-end examples
+- Reference docs for API details
+
+### 3. Fetch Selected Documentation
+
+Use the fetch_url tool to read the selected documentation URLs.
+
+### 4. Provide Accurate Guidance
+
+After reading the documentation, complete the users request.