docs: expand agent memory, skills, and tools guides

Add missing guidance for memory_notes, reasoning fields, skills/tools best practices,
troubleshooting, and highlight the comment-to-memory loop in README.

Made-with: Cursor

Author: EBWi11

README.md

@@ -21,6 +21,7 @@ If you work in security operations, you probably deal with massive volumes of ra
 - **All-in-one pipeline** — Input, normalization, enrichment, correlation, and output in one flow; no more glue scripts between Kafka, ES, ClickHouse, and “rule engines”
 - **First-class CEP** — Detect ordered event sequences, absence patterns, and multi-source correlations over time with `<sequence>`, `<threshold>`, `<iterator>`, and `<checklist>`
 - **LLM agents in the stream** — Drop LLM-powered agents into the same pipeline for alert triage, enrichment, rule authoring, and auto-whitelisting
+- **Comment-to-memory learning loop** — Convert reviewer comments from Agent Tools Logs into durable `memory_notes`, auto-commit updates, and continuously improve agent behavior
 - **Skills system** — Attach knowledge bases and operational tools to agents via Skills, with progressive disclosure so prompts stay small and fast
 - **Rich plugin ecosystem** — Threat intel (VirusTotal, ThreatBook, Shodan), GeoIP, encoding, regex, time/window helpers, LLM calls, and more
 - **Production features out of the box** — Cluster mode, health checks, daily stats, sample data, Push Changes / review workflow, and a modern Web UI for rule and project orchestration
@@ -83,7 +84,7 @@ For the full syntax (all operations, modes, and best practices), see the [Comple
 
 ### LLM Agents & Skills
 
-Agents are LLM-powered components that sit in the pipeline alongside rulesets. They receive event batches, call an LLM with tool-use support, and forward enriched results downstream.
+Agents are LLM-powered components that sit in the pipeline alongside rulesets. They process events independently, call an LLM with tool-use support, and forward enriched results downstream.
 
 ```yaml
 # Agent: AI-powered alert triage
@@ -93,15 +94,24 @@ system_prompt: |
 skills:
   - hub_ruleset_expert    # Knowledge skill: rules engine reference
 tools: all                # Expose all plugins as LLM tools
-batch:
-  size: 5
-  timeout: 30s
+max_rounds: 3
+timeout: 30s
+
+# Optional long-term memory (recommended as YAML sequence)
+memory_notes:
+  - Keep output JSON compact and stable.
+  - Treat routine CI scanner traffic as lower priority unless other signals exist.
 ```
 
 **Skills** provide modular capabilities to agents:
 - **Knowledge skills** — Reference docs loaded on-demand (progressive disclosure)
 - **Builtin skills** — Go-implemented tools (e.g., `hub_ruleset_editor` for reading/writing rulesets)
 
+Quick production tips:
+- Prefer `tools: []` by default and allowlist only needed plugin tools.
+- Use `tools: all` only for broad assistant agents (rule-authoring / deep triage).
+- In cluster mode, memory write/generate actions must go to the **leader** node.
+
 Use agents in your project like any other component:
 
 ```yaml
@@ -110,6 +120,8 @@ content: |
   AGENT.alert_reviewer -> OUTPUT.enriched_alerts
 ```
 
+For full agent details (fields like `reasoning_mode`, `reasoning_budget_tokens`, `memory_notes`, and memory workflow in UI/API), see the [Complete Guide](docs/agentsmith-hub-guide.md#14-agent-syntax-description).
+
 ## Built-in Detection Rulesets
 
 AgentSmith-HUB ships with production-ready detection rulesets that you can deploy immediately — no rule-writing required. All rules are mapped to [MITRE ATT&CK](https://attack.mitre.org/) for seamless integration with your security workflows.

docs/agentsmith-hub-guide-zh.md

@@ -384,6 +384,15 @@ tools: []                          # 插件工具："all" 或名称列表；用
 
 max_rounds: 1                      # 每条消息最大 ReAct 工具调用轮数（默认: 5）
 timeout: 30s                       # 单条消息处理超时（如 30s、1m）
+
+# 可选：支持“思考/推理”参数的模型可启用
+reasoning_mode: auto               # disabled | enabled | auto（默认: disabled）
+reasoning_budget_tokens: 2048      # 可选：推理预算 token
+
+# 可选：长期记忆，推荐使用 YAML 数组
+memory_notes:
+  - 输出 JSON 字段保持稳定、简短，避免冗余长文本。
+  - 对 CI 内网扫描流量默认降权，除非出现横向移动特征。
 ```
 
 #### 字段参考
@@ -398,6 +407,9 @@ timeout: 30s                       # 单条消息处理超时（如 30s、1m）
 | `tools` | 否 | `"all"` 暴露所有插件为工具；`[]` 或名称列表可限制。不需要工具时用 `[]` 可降低延迟。 |
 | `max_rounds` | 否 | 每条消息最大 ReAct 轮数（工具调用循环）。默认 `5`。 |
 | `timeout` | 否 | 时间字符串。若处理超过此时长会中止 LLM 调用。默认 `30s`。 |
+| `reasoning_mode` | 否 | 推理开关：`disabled`（默认）、`enabled`、`auto`（是否发送 provider/model 特定推理参数）。 |
+| `reasoning_budget_tokens` | 否 | 推理预算 token（仅对兼容的 provider/model 生效）。 |
+| `memory_notes` | 否 | 长期指导信息，会并入有效 system prompt。推荐 YAML 字符串数组；兼容旧版多行字符串。 |
 
 #### 工作原理
 
@@ -464,6 +476,28 @@ content: |
 
 Agent 支持与 Ruleset 相同的测试流程：打开 Agent 组件，点击测试按钮或使用 **Cmd+D**，填写输入 JSON 后执行。测试会启动临时 Agent 并返回完整事件（原始数据 + `llm` 块），便于核对合并结果。
 
+#### Memory Notes（长期记忆）说明
+
+`memory_notes` 用于沉淀稳定、可复用的长期指导，不是 `system_prompt` 的替代，而是“这个 Agent 学到的经验”。
+
+- 适合写可长期复用的规则：误报/真报判定线索、输出格式约束、置信度口径等。
+- 不建议写一次性事件细节（这类信息应放在评论或工单）。
+- 推荐使用 YAML 数组：
+
+```yaml
+memory_notes:
+  - 对常见 CI 扫描流量默认判定为低风险，除非出现异常外联或横向移动证据。
+  - 当 llm_confidence >= 0.7 时，必须给出一句可审计证据说明。
+```
+
+为兼容历史配置，旧版多行字符串仍可读取；新配置建议统一用数组格式，便于维护和合并。
+
+#### Memory 工作流（UI / API / 集群）
+
+- **UI 路径**：`Agent Tools Logs` 支持用户评论、从日志生成记忆、提交记忆。
+- **API 路径**：可通过 memory 相关接口更新/生成并自动提交组件变更。
+- **集群注意**：memory 写入与生成必须在 **leader** 节点执行，follower 会拒绝这类写操作。
+
 #### 示例：告警审核 Agent
 
 ```yaml
@@ -564,15 +598,26 @@ skills:
   - hub_ruleset_editor     # builtin skill: Ruleset 读写操作
 
 tools: all
-
-batch:
-  size: 1
-  timeout: 60s
-  max_rounds: 10
+max_rounds: 10
+timeout: 60s
 ```
 
 在此配置中，Agent 同时拥有知识（规则引擎参考文档）和操作能力（Ruleset CRUD）。LLM 可以通过 `get_reference` 查阅语法，列出/读取现有 Ruleset，验证 XML，以及写入变更 —— 全部在 ReAct 循环中完成。
 
+#### Skills / Tools 实操建议
+
+- 默认建议先用 `tools: []`，只按需开放必要插件，降低延迟和误调用概率。
+- 仅在通用助手型 Agent（例如规则编写 Copilot）中使用 `tools: all`。
+- 需要“会查资料 + 会执行操作”时，组合使用知识型 Skill（`content`）和内置 Skill（`builtin_ref`）。
+- 生产环境中，尽量将可写内置技能设置为只读（如 `config.read_only: true`）。
+
+#### Skills / Tools 调用排查
+
+- 工具不触发：在 `system_prompt` 明确“何时必须调用某工具”。
+- 工具调用过多：收紧提示词边界，并降低 `max_rounds`。
+- 调错插件：把 `tools` 从 `all` 改为明确白名单。
+- 集群下写操作失败：确认请求命中 leader，而不是 follower。
+
 ## 🔧 第二部分：基本操作指南
 
 ### 2.1 临时文件和正式文件

docs/agentsmith-hub-guide.md

@@ -385,6 +385,15 @@ tools: []                          # Plugin tools: "all" or list of names; use [
 
 max_rounds: 1                      # Max ReAct tool-call rounds per message (default: 5)
 timeout: 30s                       # Per-message processing timeout (e.g. 30s, 1m)
+
+# Optional reasoning params for models/providers that support "thinking" mode
+reasoning_mode: auto               # disabled | enabled | auto (default: disabled)
+reasoning_budget_tokens: 2048      # Optional reasoning token budget
+
+# Optional long-term memory notes; recommended as YAML sequence
+memory_notes:
+  - Prefer compact JSON output with stable field names.
+  - Reduce false positives for CI internal scanners.
 ```
 
 #### Field Reference
@@ -399,6 +408,9 @@ timeout: 30s                       # Per-message processing timeout (e.g. 30s, 1
 | `tools` | No | `"all"` exposes all plugins as tools; `[]` or a list of names to limit. Use `[]` when the agent does not need tools to reduce latency. |
 | `max_rounds` | No | Max ReAct rounds (tool-call loops) per message. Default `5`. |
 | `timeout` | No | Duration string. Aborts the LLM call if processing exceeds this. Default `30s`. |
+| `reasoning_mode` | No | Provider/model-specific reasoning toggle: `disabled` (default), `enabled`, or `auto`. |
+| `reasoning_budget_tokens` | No | Optional reasoning token budget for compatible providers/models. |
+| `memory_notes` | No | Durable guidance merged into the effective system prompt. Recommended format is a YAML string array; legacy multiline string is still accepted. |
 
 #### How It Works
 
@@ -465,6 +477,28 @@ content: |
 
 Agents support the same test flow as rulesets: open the agent component, use the test button or **Cmd+D**, provide input JSON, and run. The test runs a temporary agent and returns the full event (original + `llm` block) so you can verify the merged result.
 
+#### Memory Notes (Long-term Guidance)
+
+`memory_notes` is for stable, durable guidance distilled from human feedback and run history. It is not a replacement for `system_prompt`; think of it as "what this agent has learned."
+
+- Prefer concise bullets that survive across runs (FP/TP heuristics, output style constraints, escalation thresholds).
+- Avoid one-off incident details; put those in comments/tickets instead.
+- Recommended YAML format is a sequence:
+
+```yaml
+memory_notes:
+  - Mark routine CI scanner traffic as likely false positive unless lateral movement indicators exist.
+  - Always include a short evidence sentence for confidence >= 0.7.
+```
+
+Legacy multiline string remains supported for backward compatibility, but new configs should use sequences for readability and safer merges.
+
+#### Memory Workflow (UI/API/Cluster)
+
+- **UI path**: `Agent Tools Logs` supports user comments and memory generation/commit workflows.
+- **API path**: memory update and generate-from-log endpoints apply changes and auto-commit them as component changes.
+- **Cluster rule**: memory write/generate actions must run on the **leader** node; follower nodes reject these write operations.
+
 #### Example: Alert Review Agent
 
 ```yaml
@@ -565,15 +599,26 @@ skills:
   - hub_ruleset_editor     # builtin skill: read/write rulesets
 
 tools: all
-
-batch:
-  size: 1
-  timeout: 60s
-  max_rounds: 10
+max_rounds: 10
+timeout: 60s
 ```
 
 In this setup, the agent has access to both knowledge (rules engine reference docs) and action (ruleset CRUD). The LLM can look up syntax via `get_reference`, list/read existing rulesets, verify XML, and write changes — all within the ReAct loop.
 
+#### Skills & Tools Practical Guidance
+
+- Start with `tools: []` and add only the plugin tools you truly need; this reduces latency and accidental tool calls.
+- Use `tools: all` only for broad assistant agents (rule-authoring copilots, deep triage assistants).
+- Pair a **knowledge skill** (`content`) with a **builtin/action skill** (`builtin_ref`) when the agent both reasons and edits.
+- For production safety, set write-capable builtin skills to read-only where possible (for example, `config.read_only: true`).
+
+#### Troubleshooting Skills/Tools Calls
+
+- Tool not called: improve `system_prompt` with explicit "when to call tool X" conditions.
+- Tool called too often: tighten prompt constraints and lower `max_rounds`.
+- Wrong plugin chosen: restrict `tools` to a short allowlist instead of `all`.
+- Write actions rejected in cluster: verify request hits leader node, not follower.
+
 ## 🔧 Part 2: Basic Operating Instructions
 
 ### 2.1 Temporary and Official Files