@j-o-r/hello-dave 0.0.2 → 0.0.4

package/docs.bak.1774780058/tools-syntax-validation.md.bak2

@@ -0,0 +1,125 @@
+# Syntax Validation in Generic Tools
+
+## Overview
+Recent enhancements to `lib/genericToolset.js` introduce **automatic syntax validation** for files written via the `write_file` tool. This prevents invalid code deployment, resolves common **escaping issues** in JavaScript, and supports shebang executables. Validation occurs **post-write**, throwing descriptive errors to prompt LLM retries/fixes.
+
+**Key Benefits**:
+- **JS Safety**: `node --check` catches syntax errors (e.g., unescaped backticks in template literals).
+- **Executable Prep**: Auto `chmod +x` for shebangs.
+- **Retry-Friendly**: Errors include code preview + fix hints, enabling agent self-correction.
+- **No Overhead**: Only for JS/shebang files; fast native checks.
+
+**Commit History** (relevant):
+- `3c8e1ae`: Added `read_file`, `write_file` with initial path security.
+- Recent refinements: Syntax check + escaping guidance.
+
+## write_file Tool Updates (`lib/genericToolset.js`)
+
+### Updated Description
+```
+Write raw content to a file strictly within the current working directory (CWD). Paths must be relative (no leading /, no ..). Content written as-is (no escaping). **AUTO-VALIDATES JS FILES** with `node --check`; chmod +x shebangs. Retries syntax errors force LLM fix.
+```
+
+### Validation Logic
+```javascript
+// After fs.writeFile(resolvedPath, content, 'utf8');
+const ext = path.extname(file).toLowerCase();
+const isJS = ext === '.js' || content.startsWith('#!/usr/bin/env node');
+const hasShebang = content.startsWith('#!');
+
+if (isJS) {
+  try {
+    await SH`node --check ${[resolvedPath]}`.run();
+    validationMsg = ' ✓ JS syntax OK';
+  } catch (e) {
+    const errPreview = content.slice(0, 1000).split('\\n').slice(0, 20).join('\\n');
+    throw new Error(`❌ JS SYNTAX ERROR in '${file}' (node --check failed):
+${e.message}
+
+PREVIEW:
+${errPreview}
+
+... Fix escaping/backticks in template literals (use \\\\` for \` in JS strings) and retry.`);
+  }
+}
+if (hasShebang) {
+  await SH`chmod +x ${[resolvedPath]}`.run();
+  validationMsg += ' ✓ chmod +x';
+}
+```
+
+### Escaping Issues Resolved
+- **Backticks in JS Strings**: Common LLM error—generates `` `hi` `` inside strings without escaping. Hint: `use \\\\` for \` in JS strings`.
+- **Template Literals**: Ensures `` \` ${var} \` `` is valid; catches mismatched quotes.
+- **Raw Content**: Verbatim write (newlines, `$|<> & " '\\`` preserved), but syntax-enforced.
+- **No False Positives**: Only triggers on `.js` ext or Node shebang; preview limits noise.
+
+**Example Error (LLM Sees)**:
+```
+❌ JS SYNTAX ERROR in 'test.js' (node --check failed):
+SyntaxError: Unexpected token `
+
+PREVIEW:
+const msg = `Hello ${name}
+...
+
+... Fix escaping/backticks in template literals (use \\\\` for \` in JS strings) and retry.
+```
+- **LLM Fix**: Rewrites with `"Hello \${name}"` or proper `` \` `` nesting.
+
+### Usage in Agents
+```javascript
+agent.addGenericToolcall('write_file');  // Auto-includes validation
+await agent.directCall("Write test.js: const x = `hi`; console.log(x);");  // Passes
+// Fails + retries: "Write test.js: const x = `hi; console.log(x);"  → SyntaxError → Fix
+```
+
+## Multi-Language Syntax Validation (utils/syntax_check.sh)
+
+**New Utility**: `./utils/syntax_check.sh` – Standalone script for **JS, Python, Bash, JSON**. Detects lang via ext/shebang, runs native checkers. Exit 0=OK, 1=error. Integrates as future `write_file` extension or new tool.
+
+### Features
+| Lang | Checker | Optional | Notes |
+|------|---------|----------|-------|
+| **JS** | `node --check` | - | Syntax only (no runtime). |
+| **Python** | `python3 -m py_compile` | - | Bytecode compile. |
+| **Bash/Sh** | `bash -n` + `shellcheck` | Shellcheck | Static + linter. |
+| **JSON** | `node -e JSON.parse(...)` | - | Parse validation. |
+| **Unknown** | Skip | - | Non-fatal. |
+
+### Usage
+```bash
+./utils/syntax_check.sh path/to/file.js          # 🔍 JS OK / ❌ error
+./utils/syntax_check.sh script.py --verbose      # Extra output
+# Future: --fix (auto-retry via agent?)
+```
+
+### Script Source (utils/syntax_check.sh)
+```bash
+#!/bin/bash
+set -euo pipefail
+# Full script: Detects lang, validates, echoes status.
+# Created: March 27, 2026
+```
+
+### Integration Proposal: New Tool `syntax_check`
+Add to `ToolSet` / `genericToolset.js`:
+```javascript
+tools.add('syntax_check', 'Validate file syntax (JS/Py/Bash/JSON).', {
+  type: 'object',
+  properties: { file: {type: 'string'} },
+  required: ['file']
+}, async ({file}) => {
+  const script = path.resolve(__dirname, '..', 'utils', 'syntax_check.sh');
+  return await SH`${script} "${file}"`.run();
+});
+```
+- **Post-write Call**: `write_file` → `syntax_check` → LLM fix loop.
+- **Extend write_file**: Run `./syntax_check.sh "$file"` after JS check.
+
+**Cross-Links**:
+- [ToolSet](../toolset.md#generic-tools)
+- [AgentManager](../agent-manager.md#custom-tools--generics)
+- Source: [lib/genericToolset.js](../lib/genericToolset.js)
+
+**Updated**: March 27, 2026

package/docs.bak.1774780058/tools-syntax-validation.md.bak3

@@ -0,0 +1,125 @@
+# Syntax Validation in Generic Tools
+
+## Overview
+Recent enhancements to `lib/genericToolset.js` introduce **automatic syntax validation** for files written via the `write_file` tool. This prevents invalid code deployment, resolves common **escaping issues** in JavaScript, and supports shebang executables. Validation occurs **post-write**, throwing descriptive errors to prompt LLM retries/fixes.
+
+**Key Benefits**:
+- **JS Safety**: `node --check` catches syntax errors (e.g., unescaped backticks in template literals).
+- **Executable Prep**: Auto `chmod +x` for shebangs.
+- **Retry-Friendly**: Errors include code preview + fix hints, enabling agent self-correction.
+- **No Overhead**: Only for JS/shebang files; fast native checks.
+
+**Commit History** (relevant):
+- `3c8e1ae`: Added `read_file`, `write_file` with initial path security.
+- Recent refinements: Syntax check + escaping guidance.
+
+## write_file Tool Updates (`lib/genericToolset.js`)
+
+### Updated Description
+```
+Write raw content to a file strictly within the current working directory (CWD). Paths must be relative (no leading /, no ..). Content written as-is (no escaping). **AUTO-VALIDATES JS FILES** with `node --check`; chmod +x shebangs. Retries syntax errors force LLM fix.
+```
+
+### Validation Logic
+```javascript
+// After fs.writeFile(resolvedPath, content, 'utf8');
+const ext = path.extname(file).toLowerCase();
+const isJS = ext === '.js' || content.startsWith('#!/usr/bin/env node');
+const hasShebang = content.startsWith('#!');
+
+if (isJS) {
+  try {
+    await SH`node --check ${[resolvedPath]}`.run();
+    validationMsg = ' ✓ JS syntax OK';
+  } catch (e) {
+    const errPreview = content.slice(0, 1000).split('\\n').slice(0, 20).join('\\n');
+    throw new Error(`❌ JS SYNTAX ERROR in '${file}' (node --check failed):
+${e.message}
+
+PREVIEW:
+${errPreview}
+
+... Fix escaping/backticks in template literals (use \\\\` for \` in JS strings) and retry.`);
+  }
+}
+if (hasShebang) {
+  await SH`chmod +x ${[resolvedPath]}`.run();
+  validationMsg += ' ✓ chmod +x';
+}
+```
+
+### Escaping Issues Resolved
+- **Backticks in JS Strings**: Common LLM error—generates `` `hi` `` inside strings without escaping. Hint: `use \\\\` for \` in JS strings`.
+- **Template Literals**: Ensures `` \` ${var} \` `` is valid; catches mismatched quotes.
+- **Raw Content**: Verbatim write (newlines, `$|<> & " '\\`` preserved), but syntax-enforced.
+- **No False Positives**: Only triggers on `.js` ext or Node shebang; preview limits noise.
+
+**Example Error (LLM Sees)**:
+```
+❌ JS SYNTAX ERROR in 'test.js' (node --check failed):
+SyntaxError: Unexpected token `
+
+PREVIEW:
+const msg = `Hello ${name}
+...
+
+... Fix escaping/backticks in template literals (use \\\\` for \` in JS strings) and retry.
+```
+- **LLM Fix**: Rewrites with `"Hello \${name}"` or proper `` \` `` nesting.
+
+### Usage in Agents
+```javascript
+agent.addGenericToolcall('write_file');  // Auto-includes validation
+await agent.directCall("Write test.js: const x = `hi`; console.log(x);");  // Passes
+// Fails + retries: "Write test.js: const x = `hi; console.log(x);"  → SyntaxError → Fix
+```
+
+## Multi-Language Syntax Validation (utils/syntax_check.sh)
+
+**New Utility**: `./utils/syntax_check.sh` – Standalone script for **JS, Python, Bash, JSON**. Detects lang via ext/shebang, runs native checkers. Exit 0=OK, 1=error. Integrates as future `write_file` extension or new tool.
+
+### Features
+| Lang | Checker | Optional | Notes |
+|------|---------|----------|-------|
+| **JS** | `node --check` | - | Syntax only (no runtime). |
+| **Python** | `python3 -m py_compile` | - | Bytecode compile. |
+| **Bash/Sh** | `bash -n` + `shellcheck` | Shellcheck | Static + linter. |
+| **JSON** | `node -e JSON.parse(...)` | - | Parse validation. |
+| **Unknown** | Skip | - | Non-fatal. |
+
+### Usage
+```bash
+./utils/syntax_check.sh path/to/file.js          # 🔍 JS OK / ❌ error
+./utils/syntax_check.sh script.py --verbose      # Extra output
+# Future: --fix (auto-retry via agent?)
+```
+
+### Script Source (utils/syntax_check.sh)
+```bash
+#!/bin/bash
+set -euo pipefail
+# Full script: Detects lang, validates, echoes status.
+# Created: March 27, 2026
+```
+
+### Integration Proposal: New Tool `syntax_check`
+Add to `ToolSet` / `genericToolset.js`:
+```javascript
+tools.add('syntax_check', 'Validate file syntax (JS/Py/Bash/JSON).', {
+  type: 'object',
+  properties: { file: {type: 'string'} },
+  required: ['file']
+}, async ({file}) => {
+  const script = path.resolve(__dirname, '..', 'utils', 'syntax_check.sh');
+  return await SH`${script} "${file}"`.run();
+});
+```
+- **Post-write Call**: `write_file` → `syntax_check` → LLM fix loop.
+- **Extend write_file**: Run `./syntax_check.sh "$file"` after JS check.
+
+**Cross-Links**:
+- [ToolSet](../toolset.md#generic-tools)
+- [AgentManager](../agent-manager.md#custom-tools--generics)
+- Source: [lib/genericToolset.js](../lib/genericToolset.js)
+
+**Updated**: March 27, 2026

package/docs.bak.1774780058/tools-syntax-validation.md.bak4

@@ -0,0 +1,106 @@
+# Syntax Validation in Generic Tools
+
+## Overview
+**Integration Complete**: `lib/genericToolset.js` now includes **automatic JS syntax validation** in `write_file` **and a new `syntax_check` tool** using `./utils/syntax_check.sh` for multi-language support (JS/Python/Bash/JSON). Prevents invalid code, resolves escaping issues, auto `chmod +x` shebangs. Post-write errors prompt LLM retries.
+
+**Key Benefits**:
+- **JS Safety**: `node --check` (in `write_file`); full multi-lang in `syntax_check`.
+- **Executable Prep**: Auto `chmod +x`.
+- **Retry-Friendly**: Descriptive errors + previews.
+- **Generic Access**: `toolsetMode: 'auto'` loads both.
+
+**Commit History** (relevant):
+- `3c8e1ae`: Initial `read_file`/`write_file`.
+- Recent: JS validation + `syntax_check` tool.
+
+## write_file Tool Updates
+
+### Description (Updated)
+```
+Write raw content to a file strictly within the current working directory (CWD). Paths must be relative (no leading /, no ..). Content written as-is (no escaping). **AUTO-VALIDATES JS FILES** with `node --check`; chmod +x shebangs. Retries syntax errors force LLM fix.
+```
+
+### Examples
+**Success** (CLI/Agent):
+```bash
+echo 'const x = \`hi\`; console.log(x);' | agent.directCall("Use write_file on test.js with this content")
+# Returns: "Successfully wrote to 'test.js' (42 bytes). ✓ JS syntax OK"
+```
+
+**Failure + Retry**:
+```javascript
+// LLM generates invalid:
+const msg = `Hello ${name`;  // Missing `
+```
+**Error**:
+```
+❌ JS SYNTAX ERROR in 'test.js' (node --check failed):
+SyntaxError: Unexpected token '}'
+
+PREVIEW:
+const msg = `Hello ${name
+...
+
+... Fix escaping/backticks in template literals (use \\\\` for \` in JS strings) and retry.
+```
+**LLM Sees → Fixes**: Uses `"Hello \${name}"` or proper `` \` ``.
+
+**Shebang**:
+```javascript
+content: '#!/usr/bin/env node\nconst hello = () => console.log("Hi");'
+# Returns: "... ✓ JS syntax OK ✓ chmod +x"
+```
+
+## New: syntax_check Tool
+
+**Description**:
+```
+Validate syntax of a file (JS, Python, Bash/Sh, JSON). Detects language from extension/shebang. Uses native checkers... Exit 1 on fail.
+```
+
+### Parameters
+```json
+{
+  "type": "object",
+  "properties": { "file": { "type": "string" } },
+  "required": ["file"]
+}
+```
+
+### Examples
+**Agent Call**:
+```
+agent.directCall("Use syntax_check on test.js")  → "🔍 Validating test.js (lang: js)\n✅ JS OK\n✅ Syntax validation passed for test.js"
+```
+
+**Multi-Lang**:
+- **Python**: `syntax_check script.py` → `✅ Python OK`
+- **Bash**: `syntax_check script.sh` → `✅ Bash OK` ( + Shellcheck if avail.)
+- **JSON**: `syntax_check config.json` → `✅ JSON OK`
+- **Fail**: Invalid JSON → `❌ JSON invalid`
+
+**Integration**: Post-`write_file`, agent can call `syntax_check(file)` for non-JS.
+
+## utils/syntax_check.sh (Underlying Script)
+[Full source in prior doc]. Detects lang, runs checkers. Standalone/executable.
+
+### Usage (Direct)
+```bash
+./utils/syntax_check.sh test.js      # ✅ JS OK
+./utils/syntax_check.sh bad.py       # ❌ Python syntax error
+```
+
+## Agent Workflow Example
+```
+User: "Create & validate test.js: const add = (a,b) => a+b; export {add};"
+Agent:
+1. write_file(test.js, content)  → ✓ JS OK
+2. syntax_check(test.js)        → ✅ (redundant but confirms)
+```
+
+## Cross-Links
+- [ToolSet](../toolset.md#generic-tools) ← [Linked below](#update-to-toolsetmd)
+- [AgentManager](../agent-manager.md)
+- Source: [lib/genericToolset.js](../lib/genericToolset.js), [utils/syntax_check.sh](../utils/syntax_check.sh)
+
+**Updated**: March 27, 2026 (syntax_check integrated).

package/docs.bak.1774780058/tools-syntax-validation.md.bak_path

@@ -0,0 +1,106 @@
+# Syntax Validation in Generic Tools
+
+## Overview
+**Integration Complete**: `lib/genericToolset.js` now includes **automatic JS syntax validation** in `write_file` **and a new `syntax_check` tool** using `./utils/syntax_check.sh` for multi-language support (JS/Python/Bash/JSON). Prevents invalid code, resolves escaping issues, auto `chmod +x` shebangs. Post-write errors prompt LLM retries.
+
+**Key Benefits**:
+- **JS Safety**: `node --check` (in `write_file`); full multi-lang in `syntax_check`.
+- **Executable Prep**: Auto `chmod +x`.
+- **Retry-Friendly**: Descriptive errors + previews.
+- **Generic Access**: `toolsetMode: 'auto'` loads both.
+
+**Commit History** (relevant):
+- `3c8e1ae`: Initial `read_file`/`write_file`.
+- Recent: JS validation + `syntax_check` tool.
+
+## write_file Tool Updates
+
+### Description (Updated)
+```
+Write raw content to a file strictly within the current working directory (CWD). Paths must be relative (no leading /, no ..). Content written as-is (no escaping). **AUTO-VALIDATES JS FILES** with `node --check`; chmod +x shebangs. Retries syntax errors force LLM fix.
+```
+
+### Examples
+**Success** (CLI/Agent):
+```bash
+echo 'const x = \`hi\`; console.log(x);' | agent.directCall("Use write_file on test.js with this content")
+# Returns: "Successfully wrote to 'test.js' (42 bytes). ✓ JS syntax OK"
+```
+
+**Failure + Retry**:
+```javascript
+// LLM generates invalid:
+const msg = `Hello ${name`;  // Missing `
+```
+**Error**:
+```
+❌ JS SYNTAX ERROR in 'test.js' (node --check failed):
+SyntaxError: Unexpected token '}'
+
+PREVIEW:
+const msg = `Hello ${name
+...
+
+... Fix escaping/backticks in template literals (use \\\\` for \` in JS strings) and retry.
+```
+**LLM Sees → Fixes**: Uses `"Hello \${name}"` or proper `` \` ``.
+
+**Shebang**:
+```javascript
+content: '#!/usr/bin/env node\nconst hello = () => console.log("Hi");'
+# Returns: "... ✓ JS syntax OK ✓ chmod +x"
+```
+
+## New: syntax_check Tool
+
+**Description**:
+```
+Validate syntax of a file (JS, Python, Bash/Sh, JSON). Detects language from extension/shebang. Uses native checkers... Exit 1 on fail.
+```
+
+### Parameters
+```json
+{
+  "type": "object",
+  "properties": { "file": { "type": "string" } },
+  "required": ["file"]
+}
+```
+
+### Examples
+**Agent Call**:
+```
+agent.directCall("Use syntax_check on test.js")  → "🔍 Validating test.js (lang: js)\n✅ JS OK\n✅ Syntax validation passed for test.js"
+```
+
+**Multi-Lang**:
+- **Python**: `syntax_check script.py` → `✅ Python OK`
+- **Bash**: `syntax_check script.sh` → `✅ Bash OK` ( + Shellcheck if avail.)
+- **JSON**: `syntax_check config.json` → `✅ JSON OK`
+- **Fail**: Invalid JSON → `❌ JSON invalid`
+
+**Integration**: Post-`write_file`, agent can call `syntax_check(file)` for non-JS.
+
+## utils/syntax_check.sh (Underlying Script)
+[Full source in prior doc]. Detects lang, runs checkers. Standalone/executable.
+
+### Usage (Direct)
+```bash
+./utils/syntax_check.sh test.js      # ✅ JS OK
+./utils/syntax_check.sh bad.py       # ❌ Python syntax error
+```
+
+## Agent Workflow Example
+```
+User: "Create & validate test.js: const add = (a,b) => a+b; export {add};"
+Agent:
+1. write_file(test.js, content)  → ✓ JS OK
+2. syntax_check(test.js)        → ✅ (redundant but confirms)
+```
+
+## Cross-Links
+- [ToolSet](../toolset.md#generic-tools) ← [Linked below](#update-to-toolsetmd)
+- [AgentManager](../agent-manager.md)
+- Source: [lib/genericToolset.js](../lib/genericToolset.js), [utils/syntax_check.sh](../utils/syntax_check.sh)
+
+**Updated**: March 27, 2026 (syntax_check integrated).

package/docs.bak.1774780058/toolset.md

@@ -0,0 +1,164 @@
+# ToolSet (\`lib/ToolSet.js\`)
+
+## Overview
+**ToolSet** manages LLM function calls (tools): registration, execution, listing. Integrates with \`Prompt.js\` (via \`execute(prompt)\`) and \`AgentManager.js\` (pre-configured modes, generics). Supports JSON Schema params, async methods. Exports from \`lib/genericToolset.js\`: \`toolsPool\` (11 pre-built tools).
+
+**Uses named exports from \`lib/index.js\` - NO default export.**
+
+Key Features:
+- **Modes**: \`toolChoice: 'auto'|'none'|'required'\` (default \`'auto'\`).
+- **Validation**: Name regex \`/^\[#![a-z_0-9]{2,}$/\`.
+- **Events** (via \`Prompt\`): \`tool_request\`, \`tool_error\`, \`tool_response\`.
+- **Execution**: \`execute(prompt)\` processes \`function_request\`s from last message → calls → adds \`function_response\`s.
+
+## Constructor
+\`\`\`javascript
+import { ToolSet } from '@j-o-r/hello-dave';
+
+new ToolSet(choice = 'auto');  // 'auto'|'none'|'required'
+\`\`\`
+
+## Methods
+| Method | Args | Returns | Description |
+|--------|------|---------|-------------|
+| \`add(name, desc, params, method)\` | \`string\`, \`string\`, \`TSSchema\`, \`async (params) => *\` | \`void\` | Register tool. Overwrites if exists. |
+| \`get(name)\` | \`string\` | \`TSTool\` | Get tool details. |
+| \`delete(name)\` | \`string\` | \`void\` | Remove tool. |
+| \`has(name)\` | \`string\` | \`boolean\` | Exists? |
+| \`list()\` | - | \`TSToolListItem[]\` (sorted) | All tools (name/desc/params). |
+| \`call(name, params)\` | \`string\`, \`object\` | \`Promise<*\>\` | Execute tool. |
+| \`execute(prompt)\` | \`Prompt\` | \`Promise<void>\` | Process last message \`function_request\`s → execute → add \`function_response\`s to \`tool\` role. |
+| \`length\` | - | \`number\` | Tool count. |
+| \`toolChoice\` | - | \`string\` | Getter for mode. |
+
+**TSTool**: \`{description: string, parameters: TSSchema, method: async (params) => *}\`  
+**TSSchema**: OpenAI-style JSON Schema (\`{type: 'object', properties: {...}, required: [...]}\`).
+
+## Generic Tools (\`lib/genericToolset.js\` → \`toolsPool\`)
+| `syntax_check` | Validate syntax (JS/Py/Bash/JSON) via utils/syntax_check.sh. |\n|-----|-----|
+Pre-built \`ToolSet('auto')\` with **11 tools**. Copied via \`AgentManager.addGenericToolcall(name)\` or \`toolsetMode: 'auto'\`.
+
+| Tool Name                  | Description |
+|----------------------------|-------------|
+| \`javascript_interpreter\` | Execute ESM ES6 JavaScript on \`node\`. \`console.log\` captures output. cwd: \`~/devpri/js/hello-dave\`. |
+| \`get_user_env\`           | Get user environment (name, system, city/region/country/timezone, external IP). |
+| \`execute_bash_script\`    | Execute raw Bash script/command (no escaping; verbatim \`$\| < > & " ' \\\\` newlines \`$(())\` \`[[ ]]\`. Heredoc-safe). Ubuntu 25.10. |
+| \`send_email\`             | Send email via \`msmtp\` (to, subject, body). |
+| \`open_link\`              | Open URL/file with \`xdg-open\`. |
+| \`execute_remote_script\`  | Execute raw Bash on remote via SSH (\`ssh://user@host[:port]\`). |
+| \`history_search\`         | Search chat sessions: \`"(todo\\|task)"\` or \`"package.json"\`. Regex in \`.cache/[app]/[prompt]/sessions/*.ndjson\`. |
+| \`read_file\`              | Read raw file in CWD (relative path, no \`/\` \`..\` \`\\\\\`). |
+| \`write_file\`             | Write raw content to file in CWD (relative, as-is; no escaping). Returns bytes written. |
+| \`memory_recall\`          | Recall persistent memory entries from agent-specific storage (\`.cache/[agent]/memory.ndjson\`). |
+| \`memory_write\`           | Write/update persistent memory entries for long-term state (\`.cache/[agent]/memory.ndjson\`). |
+
+## Memory Tools (New)
+These tools provide persistent, agent-specific memory storage in NDJSON format (\`.cache/[agent-name]/memory.ndjson\`). Append-only; latest value per key. Ideal for token efficiency by offloading state/decisions from context.
+
+### \`memory_recall\`
+**Description**: Retrieve the latest values for specified keys from memory file. Returns JSON: \`{key: value, ...}\` or \`{}\` if missing.
+
+**Parameters**:
+\`\`\`json
+{
+  "type": "object",
+  "properties": {
+    "keys": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of memory keys to recall, e.g., ['current_task', 'last_decision']"
+    }
+  },
+  "required": ["keys"]
+}
+\`\`\`
+
+**Example Usage in Agent Prompt**:
+\`\`\`
+Before proceeding, recall your current task and previous decision:
+- Call memory_recall with keys: ["current_task", "last_decision"]
+Then, use the recalled info to avoid repetition.
+\`\`\`
+
+**Token Efficiency**: Stores tasks/decisions externally. Recall only needed state (e.g., 100 tokens) vs. full history (10k+ tokens), preventing loops/re-reasoning.
+
+### \`memory_write\`
+**Description**: Append/update key-value pairs to memory (overwrites prior same-key entries). Returns confirmation with stored entries.
+
+**Parameters**:
+\`\`\`json
+{
+  "type": "object",
+  "properties": {
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "key": { "type": "string", "description": "Unique key (e.g., 'current_task')" },
+          "value": { "type": "string", "description": "JSON-stringifiable value" }
+        },
+        "required": ["key", "value"]
+      },
+      "description": "List of {key, value} pairs to store"
+    }
+  },
+  "required": ["entries"]
+}
+\`\`\`
+
+**Example Usage in Agent Prompt**:
+\`\`\`
+After analyzing, store the plan:
+- Call memory_write with entries: [{"key": "current_task", "value": "Implement login feature"}, {"key": "step", "value": "1/5"}]
+\`\`\`
+
+**Token Efficiency**: Persist intermediate results across calls/sessions. Avoids context explosion/loops by recalling compact state instead of regenerating.
+
+## Integration with AgentManager
+In \`setup()\`:
+\`\`\`javascript
+agent.setup({
+  toolsetMode: 'auto',  // Loads all 11 generic tools
+  // or 'required': Empty ToolSet (add manually)
+});
+agent.addGenericToolcall('memory_recall');  // Selective copy post-setup
+\`\`\`
+
+**Custom Tools**:
+\`\`\`javascript
+import { AgentManager } from '@j-o-r/hello-dave';
+
+agent.setup({ toolsetMode: 'required' });
+const ts = agent.getToolset();
+ts.add('math', 'Add numbers', {
+  type: 'object',
+  properties: {a: {type: 'number'}, b: {type: 'number'}},
+  required: ['a', 'b']
+}, async ({a, b}) => a + b);
+\`\`\`
+
+**Workflow** (in \`Prompt.call()\` / API adapters):
+1. LLM → \`function_request\`s (assistant message).
+2. \`ToolSet.execute(prompt)\` → parallel \`call()\` → \`function_response\`s (tool message).
+3. Recurse until text response.
+
+## Examples
+### Standalone ToolSet
+\`\`\`javascript
+import { ToolSet } from '@j-o-r/hello-dave';
+
+const ts = new ToolSet('required');
+ts.add('hello', 'Say hello', {type: 'object', properties: {name: {type: 'string'}}, required: ['name']},
+  async ({name}) => \`Hello, \${name}!\`);
+console.log(await ts.call('hello', {name: 'World'}));  // "Hello, World!"
+\`\`\`
+
+### With Prompt/AgentManager
+See [AgentManager](./agent-manager.md#custom-tools--generics), [Prompt](./prompt-class.md).
+
+**Updated:** March 26, 2026 (11 generics from \`lib/genericToolset.js\`).
+
+See also: [GenericToolset Source](./generic-toolset.md).
+\n## Syntax Validation\nSee [tools-syntax-validation.md](tools-syntax-validation.md) for `write_file` JS checks + `syntax_check` tool.
+\n## Path Resolution\nSee [path-resolution-best-practices.md](path-resolution-best-practices.md) for __dirname vs cwd() in tools (e.g., syntax_check.sh).\\n