@yachiyo-5i/xlyra-agent 1.5.0 → 1.6.0

package/README.md

@@ -204,6 +204,44 @@ For OpenAI-compatible Chat Completions endpoints, `chat_completions.max_tokens_f
 `max_steps` caps a single run's steps (one model reply plus its tool executions), default `200`, maximum `1000`. The budget is declared in the system prompt and reported at 50/80/95% milestones; when the runner detects repeated identical calls or near-identical tool outputs it injects a nudge message (and emits `stall_detected` / `budget_notice` SSE events) instead of hard-stopping the run.
 Session requests accept up to four attachments, with a 16 MiB limit per attachment and 32 MiB total; the HTTP request body is capped at 36 MiB.
 
+### Learning
+
+The optional `learning` section controls background review, persistent memory, managed Skill learning, and lifecycle maintenance. All fields have defaults:
+
+```json
+{
+  "learning": {
+    "background_review_enabled": true,
+    "max_input_tokens": 600000,
+    "max_steps": 16,
+    "memory": {
+      "enabled": true,
+      "user_profile_enabled": true,
+      "nudge_interval": 10
+    },
+    "skills": {
+      "enabled": true,
+      "nudge_interval": 10
+    },
+    "curator": {
+      "enabled": true,
+      "interval_hours": 168,
+      "min_idle_hours": 2,
+      "stale_after_days": 30,
+      "archive_after_days": 90
+    }
+  }
+}
+```
+
+Counter thresholds are Agent-wide and accumulate across sessions, so scattered short sessions still trigger review. Background review never writes to the interactive transcript. Background work cannot modify pinned Skills; a foreground user can explicitly `adopt` a user-owned Skill before allowing background maintenance. `POST /learning/curator/consolidate` with `dry_run: true` writes for real but takes a snapshot first, so the whole run can be rolled back via `/learning/curator/consolidate/restore`.
+
+Each integration surface is a channel. The current xLyra frontend uses the `main` channel; a Telegram Bot, WeChat Bot, or another frontend can create the server with its own stable channel id, for example `telegram:123456`. Each channel gets an isolated Agent root under `~/.xlyra-agent/agents/`, including its workspace, sessions, Skills, learning state, and memory. The public API paths stay the same; an integration selects its channel when constructing the server.
+
+```ts
+createAgentServer(config, { dataDir, channel: "telegram:123456" });
+```
+
 Network tools are registered by default. `web_search` uses DuckDuckGo out of the box; add the top-level `web_search` section only to switch providers — `brave` and `tavily` require `api_key` (supports `${ENV_VAR}`). `web_fetch` returns cleaned, bounded body text (long pages are explicitly marked as truncated) with SSRF protection; private/loopback addresses are rejected unless `agent.web_fetch_allow_private_network: true` is set. Web content is reference material only and must not be treated as instructions; both tools are marked as network capabilities in the system prompt's capability map. Network-tool settings and provider credentials take effect on the next run after `PUT /config`. The SSRF guard resolves and validates the hostname before each request, while the connection itself performs a second, independent DNS resolution — DNS rebinding is therefore a theoretical gap; the guard keeps the model from being steered to internal addresses and does not replace network-level isolation. `duckduckgo` is a free web endpoint with no stability guarantee (it may be rate-limited or change layout; the tool reports an explicit error when hit) — for production use, configure `brave` or `tavily`.
 
 ### Start the Server
@@ -229,11 +267,23 @@ Runtime data is stored under `~/.xlyra-agent/`:
 ```text
 ~/.xlyra-agent/
 ├── config.json
-├── index.json
-├── sessions/
-└── workspace/
+└── agents/
+    ├── main/
+    │   ├── SOUL.md
+    │   ├── AGENTS.md
+    │   ├── USER.md
+    │   ├── MEMORY.md
+    │   ├── memory/<topic>.md
+    │   ├── sessions/
+    │   ├── skills/
+    │   ├── learning/
+    │   └── workspace/
+    └── channel-<sha256>/
+        └── ...
 ```
 
+Existing single-Agent data is migrated into `agents/main/` on first startup and the original files are retained. `MEMORY.md` contains a short summary and topic index. Detailed memory is stored in `memory/<topic>.md` and can be read, listed, searched, or paged through the `memory` tool; detailed topics are not injected into every prompt.
+
 ### HTTP API
 
 | Method | Path | Description |
@@ -252,6 +302,13 @@ Runtime data is stored under `~/.xlyra-agent/`:
 | `GET` | `/config` | Read the configuration with masked API keys |
 | `PUT` | `/config` | Validate and save the configuration |
 | `POST` | `/config/test` | Test an endpoint with a minimal model request |
+| `GET` | `/memory` | Read persistent memory (`MEMORY.md` and `USER.md`) |
+| `PUT` | `/memory/:target` | Overwrite a memory target (`memory` or `user`) |
+| `GET` | `/model-memory` | Read each session's last used model and the new-session default |
+| `GET` | `/learning/status`, `/learning/reviews` | Read learning state and background-review history |
+| `POST` | `/learning/review` | Queue a background review |
+| `GET` / `POST` | `/learning/curator/*` | Inspect, run, restore, and consolidate managed Skills |
+| `POST` / `GET` | `/skills/learn`, `/learning/learns` | Submit manual Skill learning and inspect its history |
 
 When `server.token` is configured, requests must include: