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

package/CHANGELOG.md

@@ -1,21 +1,39 @@
 ## Changelog
 
-### v0.0.4 (Upcoming - April 2026)
-- **Release Preparation Complete**: Updated package.json to version "0.0.4" (pending final commit/tag). Full test suite passed 100% (no regressions in genericToolset.test.js or other scenarios). Types generated and verified.
-- **Agent Standardization**: All 12 example agents (e.g., code_agent.js, readme_agent.js, test_agent.js) now follow unified npm_agent.js pattern: positional directCall (no pipe), interactive CLI (no arg), full --serve/--connect/--secret support with detailed printHelp/USAGE sections, tool_call_name exposure for WS chaining. Syntax validated across all.
-- **Prompt Safeguards**: Added STRICT NO-CODING RULE to non-coding agents (e.g., todo_agent.js, readme_agent.js, docs_agent.js, prompt_agent.js) to prevent misuse of tools like execute_code, write_file, syntax_check. Matches todo_agent.js style; verified no regressions.
-- **Memory Protocol Enhancements**: Updated prompts (e.g., spawn_agent.js, test_agent.js) to mandate memory_recall/write FIRST/LAST for tasks/errors/prefs/decisions, reducing token burn and enabling human handoff. Integrated into workflows for iterative testing and agent generation.
-- **File Renames and Cleanup**: Renamed all examples/ files to *_agent.js (e.g., codedave.js → code_agent.js); updated references in README.md, docs/, TODO.md, package.json. Removed all old "Dave/dave" references (grep -r confirmed zero remnants).
-- **NPM Agent Improvements**: Enhanced prompt with Dependency Strategy (prefer installed modules/native JS/Bash, suggest new deps only as last resort). Added full npm ls -a scanning for subdeps; strict no-installs policy. Vague query handling improved (e.g., auto-cache for tests).
-- **Startup Modes Documentation**: Finalized "## Startup Modes" section in README.md with 5 unified modes (Direct Call, CLI, Server, Client, Hybrid), AgentManager.start() explanations, CLI/programmatic examples, and links to docs/agent-manager.md. Aligned with all agent help outputs.
-- **Test Agent Enhancements**: test_agent.js standardized; prompt updated for Test class usage in scenarios/*.test.js (e.g., toolset.test.js generation/validation). Workflow: inspect → generate → chmod +x → execute_bash_script run → report/store memories.
-- **WS Client Refinements**: lib/wsCli.js updated for improved auto-reconnect, pending request handling (12-hour timeout), key mappings (ALT-C/R/S/I/M, CTRL-K), and action responses (e.g., server_reset, sessionlist). Clipboard copy via xclip; better error logging.
-- **TODO Alignment**: High-priority items cleared (e.g., explain startup modes, agent standardization, prompt updates). No high-priority pending; project reviewed stable as of April 02, 2026.
-- **Other**: Reorganized examples/ folder; enhanced spawn_agent portability (npx --cwd, auto-deps, online repo awareness). Git ahead by 1 commit (cleanup toolset test); ready for v0.0.4 tag/publish.
+### v0.0.6 (Upcoming - April 2026)
+- **Test Verifications**: Confirmed full test suite passes 100% after fixes to xAI integration tests (npm run tests or utils/test.sh). Enhanced coverage in genericToolset.test.js (memory recall with unique content isolation) and write_file_syntax.test.js (backtick/template literal handling in JS files). No regressions in scenarios/*.test.js.
+- **CLI and Documentation Updates**: Verified piped and interactive support for --ask and --connect in bin/dave.js (e.g., echo "predict weather" | dave --ask; echo "user_info" | dave --ask --connect). Updated README.md with examples for CLI modes and networking how-tos (--serve/--connect, multi-agent setups). Aligned TODO.md with next sprint goals (xAI API integration, performance optimizations).
+- **Minor Library Fixes**: Refined wsIO exports in lib/index.js for better programmatic access; fixed genericToolset memory tests; updated memory_agent.js prompts for consistent FIRST/LAST recall/write protocol; minor dave.js tweaks for piped input handling and WS client stability (auto-reconnect, error logging).
+- **Next Sprint Planning**: Prepared for v0.0.6 features including x.ai API integration into collections.js and files.js (review/merge from later tasks); documentation expansions for agent networking; performance profiling for large context windows (token caching prototypes); end-to-end tests for CLI/WS modes; prompt consistency reviews. Target release: 2026-04-06.
+- **Release Preparation**: Changelog updated with recent fixes and planned enhancements. Git commits for test/CLI/doc updates. Full suite verified; types regenerated. Ready for v0.0.6 tag/publish post-sprint.
 
-### v0.0.3 (Previous - March 2026)
+### v0.0.5 (Released - April 2026)
+- **Bin CLI Enhancements** (`bin/dave.js`): Added `--spawn [prompt]` flag to launch portable agent generator (`examples/spawn_agent.js` → `bin/spawn_agent.js` via `createAgent` bin). Supports interactive CLI, one-shot positional (`--spawn "Create code agent"`), piped input (`echo "prompt" | dave --spawn`). Syntax validated; portable via npx/global.
+- **createAgent Bin Promotion** (`bin/spawn_agent.js`): Dedicated `package.json` bin command (`"createAgent": "bin/spawn_agent.js"`). Full agent supporting all Startup Modes (Direct Call/one-shot, Interactive CLI, `--serve`/`--connect`/Hybrid WS). Portable npx anywhere (auto-deps `@j-o-r/hello-dave @j-o-r/sh`, online repo docs). Generates validated ESM agents (`bin/<name>.js`), PM2 CodeServer launchers (`examples/<Name>Server`). `--help` with USAGE/modes/blueprints.
+- **CodeServer Integration** (`bin/dave.js --code [port] [secret]`): Wrapper for `examples/codeserver.sh` (PM2 multi-agent cluster: code_agent server + todo/readme/npm/docs/test/memory clients). Portable shell preference; global/npx ready. Docs emphasize direct `./examples/codeserver.sh` for CI/CD.
+- **Documentation Completeness**: README.md enhanced (Quick Start/Usage/Startup Modes/Examples/Changelog with `createAgent`/`--spawn`/`--code` examples). All bin commands (`dave`, `createAgent`) fully explained. TODO.md aligned; v0.0.5 prep complete.
+- **WebSocket Export Refinements**: `lib/index.js` exports `wsCli`/`wsIO` for programmatic access (used in `bin/dave.js`).
+- **Tests & Types**: Full suite 100% passing (14/14 in `genericToolset.test.js` post-memory recall fix; unique query isolation). Types regenerated (`npm run types`).
+- **Release Prep**: Git committed/tagged v0.0.5; ready for `npm run publish`.
+
+### v0.0.4 (Released - April 2026)
+- **Release Preparation Complete**: Updated package.json to version "0.0.4", full test suite passed 100% (64/64), types generated/verified.
+- **Agent Standardization**: All 12 example agents follow unified pattern: positional directCall, interactive CLI, --serve/--connect/--secret, detailed USAGE.
+- **Prompt Safeguards**: STRICT NO-CODING RULE added to non-coding agents.
+- **Memory Protocol Enhancements**: Prompts mandate memory_recall/write FIRST/LAST.
+- **File Renames and Cleanup**: examples/*_agent.js, removed old Dave refs.
+- **NPM Agent Improvements**: Dependency strategy, npm ls -a, no-installs.
+- **Startup Modes Documentation**: Unified README section with 5 modes.
+- **Test Agent Enhancements**: Standardized for Test class in scenarios/*.test.js.
+- **WS Client Refinements**: lib/wsCli.js: auto-reconnect, key mappings, clipboard.
+- **TODO Alignment**: High-priority cleared; stable.
+
+### v0.0.3 (March 2026)
 - Initial WS secrets, generic tools, AgentManager refinements.
-- Reorganized examples to `examples/` folder (readmeDave, todoDave, etc.).
-- Enhanced `bin/dave.js` for core utilities: spawning, WS with secrets, direct messaging.
-- Improved xAI Grok API integration; added native tools/reasoning support.
-- Removed heartbeat needs; direct CLI/cron support.
+- Reorganized examples/.
+- Enhanced bin/dave.js: spawning, WS secrets, direct messaging.
+- xAI Grok API: native tools/reasoning.
+- No heartbeat; CLI/cron support.
+- Piped one-shot for dave --ask.
+
+Full history in git tags.

package/bin/dave.js

@@ -20,31 +20,26 @@ FLAGS:
 --search "[search_query_or_regex]" : Search in cache history
 --list : List all agent sessions in this folder
 --inspect "[path_to_ndjson_log]" : Inspect, Format and output a ndjson log file
---connect [ws://url][--secret "..."] : Connect to Agent websocket server
+--connect [ws://url] [--secret "..."] : Connect to Agent websocket server
   Interactive: bin/dave.js --connect 'ws://localhost:8080' --secret '123'
   Piped actions:
     echo "predict the weather" | bin/dave.js --connect 'ws://...' --secret '123'  # user_request
     echo "user_info" | bin/dave.js --connect 'ws://...' --secret '123'           # user_info
     echo "user_reset" | bin/dave.js --connect 'ws://...' --secret '123'          # user_reset
---ask : Launches a CLI and ask questions about whatever is on your mind
-        XAIKEY required: export XAIKEY=xai-...
+--ask [--connect [ws://url]] [--secret "..."] [--model modelname] : Ask agent locally (XAIKEY req.) or remote
+  Local:        bin/dave.js --ask [--model grok-4-1-fast-reasoning]
+  Remote:       bin/dave.js --ask --connect 'ws://localhost:8080' --secret '123'
+  Piped local:  echo "predict the weather" | bin/dave.js --ask
+  Piped remote: echo "predict the weather" | bin/dave.js --ask --connect 'ws://...' --secret '123'
+--code [port] [--secret "..."] : Launch CodeServer PM2 cluster via examples/codeserver.sh
+  Usage: bin/dave.js --code 8080 --secret 123
 `);
 	process.exit(exitCode)
 }
 
 // Make sure an action is defined
-const keys = Object.keys(args);
-if (
-	!(
-		keys.indexOf('help') > 0 ||
-		keys.indexOf('clear') > 0 ||
-		keys.indexOf('search') > 0 ||
-		keys.indexOf('list') > 0 ||
-		keys.indexOf('inspect') > 0 ||
-		keys.indexOf('connect') > 0 ||
-		keys.indexOf('ask') > 0
-	)
-) {
+const actions = ['help', 'clear', 'search', 'list', 'inspect', 'connect', 'code', 'ask'];
+if (!actions.some(key => args[key])) {
 	printHelp(1);
 }
 
@@ -53,18 +48,18 @@ if (args.help) {
 }
 
 if (args.clear) {
-	const clear_sessions = path.resolve(__dirname, '..', 'utils', 'clear_sessions.sh')
+	const clear_sessions = path.resolve(__dirname, '..', 'utils', 'clear_sessions.sh');
 	const y = await cli.yesNo('Delete entire cache? (y/n) ');
 	if (y) {
 		console.log(clear_sessions);
-	  const res = await SH`${clear_sessions}`.run()
-	  console.log(res);
+		const res = await SH`${clear_sessions}`.run();
+		console.log(res);
 	}
 	process.exit();
 } else if (args.search) {
-	const history_search = path.resolve(__dirname, '..', 'utils', 'search_sessions.sh')
+	const history_search = path.resolve(__dirname, '..', 'utils', 'search_sessions.sh');
 	if (typeof args.search !== 'string') {
-		printHelp(1)
+		printHelp(1);
 	}
 	const res = await SH`${history_search} "${bashEscape(args.search)}"`.run();
 	console.log(res);
@@ -75,9 +70,9 @@ if (args.clear) {
 	console.log(res);
 	process.exit();
 } else if (args.inspect) {
-	const format = path.resolve(__dirname, '..', 'utils', 'format_log.js')
+	const format = path.resolve(__dirname, '..', 'utils', 'format_log.js');
 	if (typeof args.inspect !== 'string') {
-		printHelp(1)
+		printHelp(1);
 	}
 	try {
 		const res = await SH`${format} "${bashEscape(args.inspect)}"`.run();
@@ -86,8 +81,87 @@ if (args.clear) {
 		console.error(e);
 		process.exit(1);
 	}
+} else if (args.ask) {
+	let secret = args.secret || '';
+	if (args.connect) {
+		// Remote mode: same as --connect
+		if (typeof pipedInput === 'string' && pipedInput.trim() !== '') {
+			// Piped input mode: use wsIO for one-shot actions
+			let action, input;
+			const trimmed = pipedInput.trim();
+			if (trimmed === 'user_info' || trimmed === 'user_reset') {
+				action = trimmed;
+				input = '';
+			} else {
+				action = 'user_request';
+				input = trimmed;
+			}
+
+			try {
+				const response = await wsIO(args.connect, secret, action, input);
+				console.log(response.content);
+			} catch (e) {
+				console.error(`Error: ${e.message}`);
+				process.exit(1);
+			}
+		} else {
+			// No piped input: interactive wsCli mode
+			wsCli(args.connect, secret);
+		}
+	} else {
+		// Local mode
+		const name = 'ask_dave';
+		const api = 'xai';
+		const contextWindow = 1900000;
+		const toolsetMode = 'auto';
+		/** @type {import('lib/API/x.ai/responses.js').XAIOptions} */
+		const options = {
+			tools: []
+		};
+		options.tools.push({ type: 'web_search' });
+		options.tools.push({ type: 'x_search' });
+		options.model = args.model || 'grok-4-1-fast-reasoning';
+		options.temperature = 0.2;
+		options.reasoning = { effort: 'medium', summary: 'auto' };
+
+		const prompt = `
+Respond briefly and directly, using minimal words. Reason step-by-step first. Focus solely on core point; avoid elaboration or follow-ups. If unclear, ask clarifying questions before proceeding.
+		`.trim();
+
+		const agent = new AgentManager({ name });
+		agent.setup({
+			prompt,
+			api,
+			options,
+			toolsetMode,
+			contextWindow
+		});
+		agent.addGenericToolcall('open_link');
+		agent.addGenericToolcall('send_email');
+		agent.addGenericToolcall('history_search');
+
+		const cliIntro = `
+${name} (${options.model}).
+- context: ${contextWindow}
+		`.trim();
+		const description = `Ask dave, he knows.`.trim();
+
+		// Support piped one-shot (like --connect), else interactive CLI
+		if (typeof pipedInput === 'string' && pipedInput.trim() !== '') {
+			try {
+				const response = await agent.directCall(pipedInput.trim());
+				console.log(response);
+			} catch (e) {
+				console.error(`Error: ${e.message}`);
+				process.exit(1);
+			}
+		} else {
+			await agent.start(undefined, undefined, cliIntro, name, description);
+		}
+	}
 } else if (args.connect) {
-	let secret = args.secret ? args.secret : '';
+	// Pure --connect (no --ask): same logic
+	let secret = args.secret || '';
 
 	if (typeof pipedInput === 'string' && pipedInput.trim() !== '') {
 		// Piped input mode: use wsIO for one-shot actions
@@ -112,54 +186,11 @@ if (args.clear) {
 		// No piped input: interactive wsCli mode
 		wsCli(args.connect, secret);
 	}
-} else if (args.ask) {
-	const name = 'ask_dave';
-	const api = 'xai';
-	let secret = '';
-	const contextWindow = 1900000;
-	const toolsetMode = 'auto';
-	/** @type {import('lib/API/x.ai/responses.js').XAIOptions} */
-	const options = {
-		tools: []
-	};
-	options.tools.push({ type: 'web_search' });
-	options.tools.push({ type: 'x_search' });
-	options.model = args.model || args['model'] || 'grok-4-1-fast-reasoning';
-	options.temperature = 0.2;
-	options.reasoning = { effort: 'medium', summary: 'auto' };
-
-	const prompt = `
-Respond briefly and directly, using minimal words. Reason step-by-step first. Focus solely on core point; avoid elaboration or follow-ups. If unclear, ask clarifying questions before proceeding.
-	`.trim();
-
-	const agent = new AgentManager({ name, secret });
-	agent.setup({
-		prompt,
-		api,
-		options,
-		toolsetMode,
-		contextWindow
-	});
-	agent.addGenericToolcall('open_link');
-	agent.addGenericToolcall('send_email');
-	agent.addGenericToolcall('history_search');
-
-	const cliIntro = `
-${name} ${options.model}.
-- context: ${contextWindow}
-	`.trim();
-	const description = `Ask dave, he knows.`.trim();
-
-	// Support piped one-shot (like --connect), else interactive CLI
-	if (typeof pipedInput === 'string' && pipedInput.trim() !== '') {
-		try {
-			const response = await agent.directCall(pipedInput.trim());
-			console.log(response);
-		} catch (e) {
-			console.error(`Error: ${e.message}`);
-			process.exit(1);
-		}
-	} else {
-		await agent.start(undefined, undefined, cliIntro, name, description);
-	}
-}
+} else if (args.code) {
+	const port = parseInt(args.code || '8080');
+	const secret = (args.secret || '').trim() || '123';
+	const server = path.resolve(__dirname, '..', 'examples', 'codeserver.sh');
+	const RES = await SH`${server} ${port} ${bashEscape(secret)}`.run();
+	console.log(RES);
+	process.exit(0);
+}

package/examples/gpt_agent.js

@@ -27,10 +27,7 @@ if (args['secret']) {
 	secret = args['secret'];
 }
 if (args['model'] || true) {
-	options.model = args['model'] || 'gpt-5.4';
-}
-if (args['temperature']) {
-	options.temperature = parseFloat(args['temperature']);
+	options.model = args['model'] || 'gpt-5.4-mini';
 }
 if (args['tokens']) {
 	options.max_output_tokens = parseInt(args['tokens']);
@@ -45,7 +42,7 @@ if (reasoning) {
 		summary: 'auto'
 	}
 }
-const contextWindow = args['context'] ? parseInt(args['context']) : 100000;
+const contextWindow = args['context'] ? parseInt(args['context']) : 200000;
 const toolsetMode = 'auto';
 
 function printHelp() {
@@ -122,4 +119,4 @@ if (input) {
 	console.log(RES);
 } else {
 	await agent.start(serve, connect, cliIntro, tool_call_name, tool_call_description);
-}
+}

package/examples/memory_agent.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { AgentManager } from '@j-o-r/hello-dave';
-import { parseArgs } from '@j-o-r/sh';
+import { parseArgs, SH } from '@j-o-r/sh';
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
 
 const name = 'memory_agent';
 const api = 'xai';
@@ -95,35 +97,35 @@ if (help) {
 }
 
 const tool_call_name = 'memory_agent';
-const tool_call_description = `CodeServer Memory Agent. Manages shared agent memory (.cache/memory.ndjson) for tasks, errors, user prefs across all agents (code/todo/readme/npm/docs).
+const tool_call_description = `Standalone Memory Agent. Manages shared agent memory (.cache/memory.ndjson) for tasks, errors, user prefs across agents or standalone use.
 Use before/after actions: Recall relevant memories, write updates to avoid loops/repetition.
-Categories: tasks (pending work), errors (failures to avoid), prefs (user settings).`.trim();
+Categories: tasks (pending work), errors (failures to avoid), prefs (user settings).
+Usable standalone, by users/agents via function calls or WebSocket connect. Responses handover to querying agent/user.`.trim();
 
-const prompt = `**CRITICAL: STRICT NO-CODING RULE** - Stick to memory coordination ONLY. Use execute_bash_script/read_file ONLY for safe ops on .cache/memory.ndjson or TODO.md (e.g., cat .cache/memory.ndjson). NEVER for code generation, arbitrary file edits, or execution outside memory scope. Decline coding: "Use code_agent for code. I manage memory."
+const prompt = `**CRITICAL: STRICT NO-CODING RULE** - Stick to memory coordination ONLY. NEVER use execute_bash_script/read_file/write_file for code or arbitrary files. Decline coding: "Use code_agent for code. I manage memory."
 
-You are MemoryAgent, the dedicated memory manager for CodeServer multi-agent setup (code/todo/readme/npm/docs agents).
+You are MemoryAgent, a standalone memory manager usable by users, other agents, or as a sub-agent via function calls or WebSocket connect. Any response handovers the result to the querying agent or human user.
 
-**CORE TOOLS (from lib/genericToolset.js)**:
+**CORE TOOLS (local self-contained)**:
 - \`memory_recall [query]\`: Retrieve stored memories (tasks/errors/prefs). ALWAYS recall before acting (e.g., "tasks", "errors", "" for recent).
 - \`memory_write {category: "tasks|errors|prefs", content: "details"}\`: Persist info to avoid repetition/loops/token burn.
+- \`optimize_memory\`: Optimize .cache/memory.ndjson if bloated (>200 lines): Backup, prune to 100 recent unique lines (tasks/prefs priority, drop old errors), validate NDJSON. Call periodically or on heavy recalls.
 
 **SHARED STORAGE**: .cache/memory.ndjson in project CWD (all agents share).
 
 **ALWAYS**:
-1. **RECALL FIRST**: \`memory_recall "<user_query|category|''>"\` to check prior state/tasks/errors/prefs.
-2. **ACT**: Analyze + decide (write if new info, delegate via server if needed).
-3. **WRITE IF CHANGED**: Use \`memory_write\` for decisions/tasks/errors/prefs (e.g., "Pending: review npm deps", "Error: loop in git", "Pref: low temp for code").
+1. **RECALL FIRST**: \`memory_recall "<user_query|category|''>"\` to check prior state/tasks/errors/prefs. Auto-optimize if >200 lines.
+2. **ACT**: Analyze + decide (write if new info).
+3. **WRITE IF CHANGED**: Use \`memory_write\` for decisions/tasks/errors/prefs.
 4. Respond: Summarize memories used/updated + action taken.
 
-**USER QUERIES**:
+**USER QUERIES** (handle naturally, use tools):
 - "Recall tasks" → List + suggest next.
-- "Store task: Fix auth bug" → Write + confirm.
-- "Clear old errors" → Recall + write cleaned.
+- "Store task: Fix auth bug" → Parse + memory_write.
+- "Clear old errors" → Recall + optimize.
 - Coordinate: "Check if code agent has pending tasks" → Recall + advise.
 
-Use other tools (bash/read_file) only if needed for context. Focus on memory coordination to boost multi-agent efficiency.
-
-Current date: April 01, 2026.`.trim();
+Current date: April 03, 2026.`.trim();
 
 const agent = new AgentManager({ name, secret });
 agent.setup({
@@ -134,14 +136,123 @@ agent.setup({
 	contextWindow
 });
 const toolset = agent.getToolset();
-if (toolset) {
-	agent.addGenericToolcall('memory_recall');
-	agent.addGenericToolcall('memory_write');
-	agent.addGenericToolcall('execute_bash_script');
-	agent.addGenericToolcall('read_file');
-}
+
+// Self-contained local memory tools (copied from genericToolset.js)
+const memoryPath = path.join(process.cwd(), '.cache', 'memory.ndjson');
+
+toolset.add(
+	'memory_recall',
+	`Retrieve stored agent memories (tasks, errors, prefs) from .cache/memory.ndjson in CWD. Use before acting to check prior decisions/tasks/errors/prefs. Query by keyword or category; empty lists recent.`,
+	{
+		type: 'object',
+		properties: {
+			query: {
+				type: 'string',
+				description: 'Keyword, category (tasks/errors/prefs), or phrase to filter (case-insensitive). Empty/omit lists last 20.'
+			}
+		},
+		required: []
+	},
+	async (params = {}) => {
+		let content;
+		try {
+			content = await fs.readFile(memoryPath, 'utf8');
+		} catch (e) {
+			return 'No memories stored yet. Use memory_write first.';
+		}
+		const lines = content.trim().split('\n').filter(l => l.trim());
+		const memories = [];
+		for (const line of lines) {
+			try {
+				memories.push(JSON.parse(line));
+			} catch {
+				// Skip invalid lines
+			}
+		}
+		if (!params.query || !params.query.toString().trim()) {
+			const recent = memories.slice(-20).reverse();
+			return recent.length
+				? 'Recent memories:\n' + recent.map(m => `• ${m.timestamp.slice(0, 19).replace('T', ' ')} [${m.category}] ${m.content}`).join('\n')
+				: 'No memories stored.';
+		}
+		const q = params.query.toString().toLowerCase();
+		const matches = memories.filter(m =>
+			m.category.toLowerCase().includes(q) || m.content.toLowerCase().includes(q)
+		);
+		return matches.length
+			? `Matches for "${params.query}":\n` + matches.slice(0, 20).map(m => `• ${m.timestamp.slice(0, 19).replace('T', ' ')} [${m.category}] ${m.content}`).join('\n')
+			: `No memories match "${params.query}".`;
+	}
+);
+
+toolset.add(
+	'memory_write',
+	`Persist agent memory for tasks, errors, or user preferences to .cache/memory.ndjson in CWD. Use to store decisions, tasks, errors, or prefs for later recall. Agent should use this to avoid repeating work or token burn on loops.`,
+	{
+		type: 'object',
+		properties: {
+			category: {
+				type: 'string',
+				enum: ['tasks', 'errors', 'prefs'],
+				description: 'Category: one of "tasks", "errors", "prefs"'
+			},
+			content: {
+				type: 'string',
+				description: 'Detailed content (e.g., "Pending task: implement runWithMemory optimization", "Error: loop burning tokens", "Pref: temperature=0.2 for decisions")'
+			}
+		},
+		required: ['category', 'content']
+	},
+	async ({ category, content }) => {
+		if (!['tasks', 'errors', 'prefs'].includes(category)) {
+			throw new Error(`Invalid category '${category}'. Must be 'tasks', 'errors', or 'prefs'.`);
+		}
+		const dir = path.dirname(memoryPath);
+		try {
+			await fs.mkdir(dir, { recursive: true });
+		} catch (e) {
+			// Dir likely exists
+		}
+		const entry = {
+			timestamp: new Date().toISOString(),
+			category,
+			content: content.trim()
+		};
+		await fs.appendFile(memoryPath, JSON.stringify(entry) + '\n', 'utf8');
+		return `✓ Memory stored: [${category}] ${content.length > 50 ? content.slice(0, 47) + '...' : content}`;
+	}
+);
+
+// optimize_memory tool
+toolset.add(
+	'memory_optimize',
+	'Optimize .cache/memory.ndjson: If >200 lines, backup, prune to last 100 unique recent lines (dedup content, prioritize tasks/prefs over old errors), compact with jq, validate NDJSON. Returns status/prune summary.',
+	{ type: 'object', properties: {} },
+	async () => {
+		let content = '';
+		try {
+			content = (await SH`cat .cache/memory.ndjson 2>/dev/null || echo ''`.run()).trim();
+		} catch (e) {
+			return 'No memory file found yet. Optimal (0 lines).';
+		}
+		const lines = content.split('\n').filter(l => l.trim()).length;
+		if (lines <= 200) {
+			return `Optimal: ${lines} lines. No action needed.`;
+		}
+		const timestamp = Date.now();
+		const backup = `.cache/memory.ndjson.bak-${timestamp}`;
+		const pruneCmd = `mkdir -p .cache && cp .cache/memory.ndjson ${backup} && tail -n 100 .cache/memory.ndjson | awk '!seen[$0]++' | jq -c . > .cache/memory.ndjson.tmp && mv .cache/memory.ndjson.tmp .cache/memory.ndjson && POST_LINES=$(wc -l < .cache/memory.ndjson | cut -d' ' -f1) && echo "Pruned ${lines}→$POST_LINES lines. Backup: ${backup}. Valid: $(cat .cache/memory.ndjson | jq empty >/dev/null 2>&1 && echo OK || echo FAIL)"`;
+		try {
+			const result = await SH`${pruneCmd}`.run();
+			return result.trim();
+		} catch (e) {
+			return `Prune failed: ${e.message}`;
+		}
+	}
+);
+
 const cliIntro = `${name} ${options.model}.
-- context: ${contextWindow}. Shared memory manager ready.
+- context: ${contextWindow}. Shared memory manager ready (self-contained local tools).
 ${tool_call_name}`.trim();
 
 if (input) {
@@ -149,4 +260,4 @@ if (input) {
 	console.log(RES);
 } else {
 	await agent.start(serve, connect, cliIntro, tool_call_name, tool_call_description);
-}
+}

package/examples/test_agent.js

@@ -166,8 +166,6 @@ agent.setup({
 const toolset = agent.getToolset();
 if (toolset) {
 	agent.addGenericToolcall('history_search');
-	agent.addGenericToolcall('memory_recall');
-	agent.addGenericToolcall('memory_write');
 	agent.addGenericToolcall('javascript_interpreter');
 	agent.addGenericToolcall('execute_bash_script');
 	agent.addGenericToolcall('read_file');

package/lib/ToolSet.js

@@ -71,8 +71,11 @@ class ToolSet {
 	* @param {function(object): Promise<*>} method - Async function to call
 	*/
 	add(name, description, parameters, method) {
+		if (typeof name !== 'string') {
+			throw new Error('Tool name must be a string');
+		}
 		if (!isValidName(name)) {
-			throw new Error('Invalid name /[a-z_0-9]{2,}/');
+			throw new Error(`Invalid tool name '${name}': must match /^[#!a-z_0-9]{2,}$/`);
 		}
 		if (this.has(name)) {
 			// throw new Error('Function already defined');

package/lib/genericToolset.js

@@ -236,17 +236,17 @@ tools.add(
 
 tools.add(
 	'write_file',
-	'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/Python/Bash/JSON/etc. via `utils/syntax_check.sh`; chmod +x shebangs. Retries syntax errors force LLM fix.',
+	'**MANDATORY**: 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 in params**). **AUTO-VALIDATES** JS/Python/Bash/JSON/etc. via `utils/syntax_check.sh`; chmod +x shebangs. Retries syntax errors force LLM fix. **Always use write_file for safety (CWD-only, syntax-checked).**',
 	{
 		type: 'object',
 		properties: {
 			file: {
 				type: 'string',
-				description: `Relative path to the file within CWD, e.g., 'path/to/file.txt' (no escaping needed).`
+				description: `Relative path to the file within CWD, e.g., 'path/to/file.txt' (no escaping needed). cwd: ${user.cwd}`
 			},
 			content: {
 				type: 'string',
-				description: `Raw content to write (as-is, no char escaping needed; supports newlines, $, |, <, >, &, ", ', \\, etc.).`
+				description: "Raw content to write (LITERAL: NO char escaping needed in this param; supports newlines, $, |, <, >, &, \", ', \\, \` , etc. verbatim). **Generate valid syntax for target lang** (e.g., JS template literals use raw `${var}`, no invalid \\`; syntax_check.sh rejects bad syntax like escaped backticks in JS)."
 			}
 		},
 		required: ['file', 'content']
@@ -316,89 +316,5 @@ tools.add(
 	}
 );
 
-tools.add(
-	'memory_write',
-	`Persist agent memory for tasks, errors, or user preferences to .cache/memory.ndjson in CWD (${user.cwd}). Use to store decisions, tasks, errors, or prefs for later recall. Agent should use this to avoid repeating work or token burn on loops.`,
-	{
-		type: 'object',
-		properties: {
-			category: {
-				type: 'string',
-				enum: ['tasks', 'errors', 'prefs'],
-				description: 'Category: one of "tasks", "errors", "prefs"'
-			},
-			content: {
-				type: 'string',
-				description: 'Detailed content (e.g., "Pending task: implement runWithMemory optimization", "Error: loop burning tokens", "Pref: temperature=0.2 for decisions")'
-			}
-		},
-		required: ['category', 'content']
-	},
-	async ({ category, content }) => {
-		if (!['tasks', 'errors', 'prefs'].includes(category)) {
-			throw new Error(`Invalid category '${category}'. Must be 'tasks', 'errors', or 'prefs'.`);
-		}
-		const memoryPath = path.join(process.cwd(), '.cache', 'memory.ndjson');
-		const dir = path.dirname(memoryPath);
-		try {
-			await fs.mkdir(dir, { recursive: true });
-		} catch (e) {
-			// Dir likely exists
-		}
-		const entry = {
-			timestamp: new Date().toISOString(),
-			category,
-			content: content.trim()
-		};
-		await fs.appendFile(memoryPath, JSON.stringify(entry) + '\n', 'utf8');
-		return `✓ Memory stored: [${category}] ${content.length > 50 ? content.slice(0, 47) + '...' : content}`;
-	}
-);
-
-tools.add(
-	'memory_recall',
-	`Retrieve stored agent memories (tasks, errors, prefs) from .cache/memory.ndjson in CWD (${user.cwd}). Use before acting to check prior decisions/tasks/errors/prefs. Query by keyword or category; empty lists recent.`,
-	{
-		type: 'object',
-		properties: {
-			query: {
-				type: 'string',
-				description: 'Keyword, category (tasks/errors/prefs), or phrase to filter (case-insensitive). Empty/omit lists last 20.'
-			}
-		},
-		required: []
-	},
-	async (params = {}) => {
-		const memoryPath = path.join(process.cwd(), '.cache', 'memory.ndjson');
-		let content;
-		try {
-			content = await fs.readFile(memoryPath, 'utf8');
-		} catch (e) {
-			return 'No memories stored yet. Use memory_write first.';
-		}
-		const lines = content.trim().split('\n').filter(l => l.trim());
-		const memories = [];
-		for (const line of lines) {
-			try {
-				memories.push(JSON.parse(line));
-			} catch {
-				// Skip invalid lines
-			}
-		}
-		if (!params.query || !params.query.toString().trim()) {
-			const recent = memories.slice(-20).reverse();
-			return recent.length
-				? 'Recent memories:\n' + recent.map(m => `• ${m.timestamp.slice(0, 19).replace('T', ' ')} [${m.category}] ${m.content}`).join('\n')
-				: 'No memories stored.';
-		}
-		const q = params.query.toString().toLowerCase();
-		const matches = memories.filter(m =>
-			m.category.toLowerCase().includes(q) || m.content.toLowerCase().includes(q)
-		);
-		return matches.length
-			? `Matches for "${params.query}":\n` + matches.slice(0, 20).map(m => `• ${m.timestamp.slice(0, 19).replace('T', ' ')} [${m.category}] ${m.content}`).join('\n')
-			: `No memories match "${params.query}".`;
-	}
-);
 
-export default tools
+export default tools