Guide for developing, testing, and debugging custom tools that extend the agent's capabilities. Use when users want to create a new custom tool, add a tool to .memstack/tools/, write a tool using @tool_define, test a custom tool with CustomToolLoader, debug tool loading errors, or understand the custom tool API (ToolInfo, ToolContext, ToolResult).
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Guide for developing, testing, and debugging custom tools that extend the agent's capabilities. Use when users want to create a new custom tool, add a tool to .memstack/tools/, write a tool using @tool_define, test a custom tool with CustomToolLoader, debug tool loading errors, or understand the custom tool API (ToolInfo, ToolContext, ToolResult).
license
Apache-2.0
compatibility
Requires Python 3.12+, project with .memstack/tools/ directory
metadata
{"author":"memstack-team","version":"1.0"}
Custom Tool Development
Create custom tools by dropping Python files into .memstack/tools/. The agent discovers them automatically at startup via CustomToolLoader.
See .memstack/tools/example_tool.py for a complete, working custom tool with inline documentation.
Sandbox Development Environment
When developing custom tools inside a sandbox container, the following directory layout is available:
Container paths:
/workspace/ # Main workspace (read-write)
/workspace/.memstack/ # .memstack overlay (read-write, synced to host)
/workspace/.memstack/tools/ # Write your custom tools here
/host_src/ # Host project source code (read-only reference)
Key Points for Sandbox Development
Write tools to /workspace/.memstack/tools/ -- Files written here are immediately synced to the host's .memstack/tools/ directory via a direct bind mount.
Read host source from /host_src/ -- The host project's src/ directory is mounted read-only at /host_src/. Use this to reference existing code patterns, imports, and APIs.
Import paths in tools -- Custom tools use from memstack_tools import tool_define, ToolResult. The memstack_tools package is a thin public SDK that re-exports the internal types. These imports resolve against the host Python environment at agent startup, not inside the sandbox.
Test inside sandbox -- You can create test files and run pytest within /workspace/. Copy necessary test fixtures from /host_src/ if needed.
The /host_src/ path is read-only -- You cannot modify host source code from the sandbox. This is intentional for safety.
Sandbox Workflow
1. Read reference code: read /host_src/infrastructure/agent/tools/define.py
2. Create tool file: write /workspace/.memstack/tools/my_tool.py
3. Test tool (optional): bash pytest /workspace/test_my_tool.py -v
4. Tool appears on host: Automatically via bind mount
5. Agent restart picks up: CustomToolLoader discovers the new tool
