vilvona 1.0.0

package/docs/concepts/markdown-formatting.md

@@ -0,0 +1,139 @@
+---
+summary: "Markdown formatting pipeline for outbound channels"
+read_when:
+  - You are changing markdown formatting or chunking for outbound channels
+  - You are adding a new channel formatter or style mapping
+  - You are debugging formatting regressions across channels
+title: "Markdown formatting"
+---
+
+OpenClaw formats outbound Markdown by converting it into a shared intermediate
+representation (IR) before rendering channel-specific output. The IR keeps the
+source text intact while carrying style/link spans so chunking and rendering can
+stay consistent across channels.
+
+## Goals
+
+- **Consistency:** one parse step, multiple renderers.
+- **Safe chunking:** split text before rendering so inline formatting never
+  breaks across chunks.
+- **Channel fit:** map the same IR to Slack mrkdwn, Telegram HTML, and Signal
+  style ranges without re-parsing Markdown.
+
+## Pipeline
+
+1. **Parse Markdown -> IR**
+   - IR is plain text plus style spans (bold/italic/strike/code/spoiler) and link spans.
+   - Offsets are UTF-16 code units so Signal style ranges align with its API.
+   - Tables are parsed only when a channel opts into table conversion.
+2. **Chunk IR (format-first)**
+   - Chunking happens on the IR text before rendering.
+   - Inline formatting does not split across chunks; spans are sliced per chunk.
+3. **Render per channel**
+   - **Slack:** mrkdwn tokens (bold/italic/strike/code), links as `<url|label>`.
+   - **Telegram:** HTML tags (`<b>`, `<i>`, `<s>`, `<code>`, `<pre><code>`, `<a href>`).
+   - **Signal:** plain text + `text-style` ranges; links become `label (url)` when label differs.
+
+## IR example
+
+Input Markdown:
+
+```markdown
+Hello **world** - see [docs](https://docs.openclaw.ai).
+```
+
+IR (schematic):
+
+```json
+{
+  "text": "Hello world - see docs.",
+  "styles": [{ "start": 6, "end": 11, "style": "bold" }],
+  "links": [{ "start": 19, "end": 23, "href": "https://docs.openclaw.ai" }]
+}
+```
+
+## Where it is used
+
+- Slack, Telegram, and Signal outbound adapters render from the IR.
+- Other channels (WhatsApp, iMessage, Microsoft Teams, Discord) still use plain text or
+  their own formatting rules, with Markdown table conversion applied before
+  chunking when enabled.
+
+## Table handling
+
+Markdown tables are not consistently supported across chat clients. Use
+`markdown.tables` to control conversion per channel (and per account).
+
+- `code`: render tables as code blocks (default for most channels).
+- `bullets`: convert each row into bullet points (default for Matrix, Signal, and WhatsApp).
+- `off`: disable table parsing and conversion; raw table text passes through.
+
+Config keys:
+
+```yaml
+channels:
+  discord:
+    markdown:
+      tables: code
+    accounts:
+      work:
+        markdown:
+          tables: off
+```
+
+## Chunking rules
+
+- Chunk limits come from channel adapters/config and are applied to the IR text.
+- Code fences are preserved as a single block with a trailing newline so channels
+  render them correctly.
+- List prefixes and blockquote prefixes are part of the IR text, so chunking
+  does not split mid-prefix.
+- Inline styles (bold/italic/strike/inline-code/spoiler) are never split across
+  chunks; the renderer reopens styles inside each chunk.
+
+If you need more on chunking behavior across channels, see
+[Streaming + chunking](/concepts/streaming).
+
+## Link policy
+
+- **Slack:** `[label](url)` -> `<url|label>`; bare URLs remain bare. Autolink
+  is disabled during parse to avoid double-linking.
+- **Telegram:** `[label](url)` -> `<a href="url">label</a>` (HTML parse mode).
+- **Signal:** `[label](url)` -> `label (url)` unless label matches the URL.
+
+## Spoilers
+
+Spoiler markers (`||spoiler||`) are parsed only for Signal, where they map to
+SPOILER style ranges. Other channels treat them as plain text.
+
+## How to add or update a channel formatter
+
+1. **Parse once:** use the shared `markdownToIR(...)` helper with channel-appropriate
+   options (autolink, heading style, blockquote prefix).
+2. **Render:** implement a renderer with `renderMarkdownWithMarkers(...)` and a
+   style marker map (or Signal style ranges).
+3. **Chunk:** call `chunkMarkdownIR(...)` before rendering; render each chunk.
+4. **Wire adapter:** update the channel outbound adapter to use the new chunker
+   and renderer.
+5. **Test:** add or update format tests and an outbound delivery test if the
+   channel uses chunking.
+
+## Common gotchas
+
+- Slack angle-bracket tokens (`<@U123>`, `<#C123>`, `<https://...>`) must be
+  preserved; escape raw HTML safely.
+- Telegram HTML requires escaping text outside tags to avoid broken markup.
+- Signal style ranges depend on UTF-16 offsets; do not use code point offsets.
+- Preserve trailing newlines for fenced code blocks so closing markers land on
+  their own line.
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Streaming and chunking" href="/concepts/streaming" icon="bars-staggered">
+    Outbound streaming behavior, chunk boundaries, and channel-specific delivery.
+  </Card>
+  <Card title="System prompt" href="/concepts/system-prompt" icon="message-lines">
+    What the model sees before the conversation, including injected workspace files.
+  </Card>
+</CardGroup>

package/docs/concepts/memory-builtin.md

@@ -0,0 +1,151 @@
+---
+summary: "The default SQLite-based memory backend with keyword, vector, and hybrid search"
+title: "Builtin memory engine"
+read_when:
+  - You want to understand the default memory backend
+  - You want to configure embedding providers or hybrid search
+---
+
+The builtin engine is the default memory backend. It stores your memory index in
+a per-agent SQLite database and needs no extra dependencies to get started.
+
+## What it provides
+
+- **Keyword search** via FTS5 full-text indexing (BM25 scoring).
+- **Vector search** via embeddings from any supported provider.
+- **Hybrid search** that combines both for best results.
+- **CJK support** via trigram tokenization for Chinese, Japanese, and Korean.
+- **sqlite-vec acceleration** for in-database vector queries (optional).
+
+## Getting started
+
+By default, the builtin engine uses OpenAI embeddings. If you already have
+`OPENAI_API_KEY` or `models.providers.openai.apiKey` configured, vector search
+works with no extra memory config.
+
+To set a provider explicitly:
+
+```json5
+{
+  agents: {
+    defaults: {
+      memorySearch: {
+        provider: "openai",
+      },
+    },
+  },
+}
+```
+
+Without an embedding provider, only keyword search is available.
+
+To force local GGUF embeddings, install the official llama.cpp provider plugin,
+then point `local.modelPath` at a GGUF file:
+
+```bash
+openclaw plugins install @openclaw/llama-cpp-provider
+```
+
+```json5
+{
+  agents: {
+    defaults: {
+      memorySearch: {
+        provider: "local",
+        fallback: "none",
+        local: {
+          modelPath: "~/.node-llama-cpp/models/embeddinggemma-300m-qat-Q8_0.gguf",
+        },
+      },
+    },
+  },
+}
+```
+
+## Supported embedding providers
+
+| Provider          | ID                  | Notes                               |
+| ----------------- | ------------------- | ----------------------------------- |
+| Bedrock           | `bedrock`           | Uses AWS credential chain           |
+| DeepInfra         | `deepinfra`         | Default: `BAAI/bge-m3`              |
+| Gemini            | `gemini`            | Supports multimodal (image + audio) |
+| GitHub Copilot    | `github-copilot`    | Uses Copilot subscription           |
+| Local             | `local`             | `@openclaw/llama-cpp-provider`      |
+| Mistral           | `mistral`           |                                     |
+| Ollama            | `ollama`            | Local/self-hosted                   |
+| OpenAI            | `openai`            | Default: `text-embedding-3-small`   |
+| OpenAI-compatible | `openai-compatible` | Generic `/v1/embeddings` endpoint   |
+| Voyage            | `voyage`            |                                     |
+
+Set `memorySearch.provider` to switch away from OpenAI.
+
+## How indexing works
+
+OpenClaw indexes `MEMORY.md` and `memory/*.md` into chunks (~400 tokens with
+80-token overlap) and stores them in a per-agent SQLite database.
+
+- **Index location:** `~/.openclaw/memory/<agentId>.sqlite`
+- **Storage maintenance:** SQLite WAL sidecars are bounded with periodic and
+  shutdown checkpoints.
+- **File watching:** changes to memory files trigger a debounced reindex (1.5s).
+- **Auto-reindex:** when the embedding provider, model, or chunking config
+  changes, the entire index is rebuilt automatically.
+- **Reindex on demand:** `openclaw memory index --force`
+
+<Info>
+You can also index Markdown files outside the workspace with
+`memorySearch.extraPaths`. See the
+[configuration reference](/reference/memory-config#additional-memory-paths).
+</Info>
+
+## When to use
+
+The builtin engine is the right choice for most users:
+
+- Works out of the box with no extra dependencies.
+- Handles keyword and vector search well.
+- Supports all embedding providers.
+- Hybrid search combines the best of both retrieval approaches.
+
+Consider switching to [QMD](/concepts/memory-qmd) if you need reranking, query
+expansion, or want to index directories outside the workspace.
+
+Consider [Honcho](/concepts/memory-honcho) if you want cross-session memory with
+automatic user modeling.
+
+## Troubleshooting
+
+**Memory search disabled?** Check `openclaw memory status`. If no provider is
+detected, set one explicitly or add an API key.
+
+**Local provider not detected?** Confirm the local path exists and run:
+
+```bash
+openclaw memory status --deep --agent main
+openclaw memory index --force --agent main
+```
+
+Both standalone CLI commands and the Gateway use the same `local` provider id.
+Set `memorySearch.provider: "local"` when you want local embeddings.
+
+**Stale results?** Run `openclaw memory index --force` to rebuild. The watcher
+may miss changes in rare edge cases.
+
+**sqlite-vec not loading?** OpenClaw falls back to in-process cosine similarity
+automatically. `openclaw memory status --deep` reports the local vector store
+separately from the embedding provider, so `Vector store: unavailable` points
+at sqlite-vec loading while `Embeddings: unavailable` points at provider/auth
+or model readiness. Check logs for the specific load error.
+
+## Configuration
+
+For embedding provider setup, hybrid search tuning (weights, MMR, temporal
+decay), batch indexing, multimodal memory, sqlite-vec, extra paths, and all
+other config knobs, see the
+[Memory configuration reference](/reference/memory-config).
+
+## Related
+
+- [Memory overview](/concepts/memory)
+- [Memory search](/concepts/memory-search)
+- [Active memory](/concepts/active-memory)

package/docs/concepts/memory-honcho.md

@@ -0,0 +1,144 @@
+---
+summary: "AI-native cross-session memory via the Honcho plugin"
+title: "Honcho memory"
+read_when:
+  - You want persistent memory that works across sessions and channels
+  - You want AI-powered recall and user modeling
+---
+
+[Honcho](https://honcho.dev) adds AI-native memory to OpenClaw. It persists
+conversations to a dedicated service and builds user and agent models over time,
+giving your agent cross-session context that goes beyond workspace Markdown
+files.
+
+## What it provides
+
+- **Cross-session memory** -- conversations are persisted after every turn, so
+  context carries across session resets, compaction, and channel switches.
+- **User modeling** -- Honcho maintains a profile for each user (preferences,
+  facts, communication style) and for the agent (personality, learned
+  behaviors).
+- **Semantic search** -- search over observations from past conversations, not
+  just the current session.
+- **Multi-agent awareness** -- parent agents automatically track spawned
+  sub-agents, with parents added as observers in child sessions.
+
+## Available tools
+
+Honcho registers tools that the agent can use during conversation:
+
+**Data retrieval (fast, no LLM call):**
+
+| Tool                        | What it does                                           |
+| --------------------------- | ------------------------------------------------------ |
+| `honcho_context`            | Full user representation across sessions               |
+| `honcho_search_conclusions` | Semantic search over stored conclusions                |
+| `honcho_search_messages`    | Find messages across sessions (filter by sender, date) |
+| `honcho_session`            | Current session history and summary                    |
+
+**Q&A (LLM-powered):**
+
+| Tool         | What it does                                                              |
+| ------------ | ------------------------------------------------------------------------- |
+| `honcho_ask` | Ask about the user. `depth='quick'` for facts, `'thorough'` for synthesis |
+
+## Getting started
+
+Install the plugin and run setup:
+
+```bash
+openclaw plugins install @honcho-ai/openclaw-honcho
+openclaw honcho setup
+openclaw gateway --force
+```
+
+The setup command prompts for your API credentials, writes the config, and
+optionally migrates existing workspace memory files.
+
+<Info>
+Honcho can run entirely locally (self-hosted) or via the managed API at
+`api.honcho.dev`. No external dependencies are required for the self-hosted
+option.
+</Info>
+
+## Configuration
+
+Settings live under `plugins.entries["openclaw-honcho"].config`:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "openclaw-honcho": {
+        config: {
+          apiKey: "your-api-key", // omit for self-hosted
+          workspaceId: "openclaw", // memory isolation
+          baseUrl: "https://api.honcho.dev",
+        },
+      },
+    },
+  },
+}
+```
+
+For self-hosted instances, point `baseUrl` to your local server (for example
+`http://localhost:8000`) and omit the API key.
+
+## Migrating existing memory
+
+If you have existing workspace memory files (`USER.md`, `MEMORY.md`,
+`IDENTITY.md`, `memory/`, `canvas/`), `openclaw honcho setup` detects and
+offers to migrate them.
+
+<Info>
+Migration is non-destructive -- files are uploaded to Honcho. Originals are
+never deleted or moved.
+</Info>
+
+## How it works
+
+After every AI turn, the conversation is persisted to Honcho. Both user and
+agent messages are observed, allowing Honcho to build and refine its models over
+time.
+
+During conversation, Honcho tools query the service in the `before_prompt_build`
+phase, injecting relevant context before the model sees the prompt. This ensures
+accurate turn boundaries and relevant recall.
+
+## Honcho vs builtin memory
+
+|                   | Builtin / QMD                | Honcho                              |
+| ----------------- | ---------------------------- | ----------------------------------- |
+| **Storage**       | Workspace Markdown files     | Dedicated service (local or hosted) |
+| **Cross-session** | Via memory files             | Automatic, built-in                 |
+| **User modeling** | Manual (write to MEMORY.md)  | Automatic profiles                  |
+| **Search**        | Vector + keyword (hybrid)    | Semantic over observations          |
+| **Multi-agent**   | Not tracked                  | Parent/child awareness              |
+| **Dependencies**  | None (builtin) or QMD binary | Plugin install                      |
+
+Honcho and the builtin memory system can work together. When QMD is configured,
+additional tools become available for searching local Markdown files alongside
+Honcho's cross-session memory.
+
+## CLI commands
+
+```bash
+openclaw honcho setup                        # Configure API key and migrate files
+openclaw honcho status                       # Check connection status
+openclaw honcho ask <question>               # Query Honcho about the user
+openclaw honcho search <query> [-k N] [-d D] # Semantic search over memory
+```
+
+## Further reading
+
+- [Plugin source code](https://github.com/plastic-labs/openclaw-honcho)
+- [Honcho documentation](https://docs.honcho.dev)
+- [Honcho OpenClaw integration guide](https://docs.honcho.dev/v3/guides/integrations/openclaw)
+- [Memory](/concepts/memory) -- OpenClaw memory overview
+- [Context Engines](/concepts/context-engine) -- how plugin context engines work
+
+## Related
+
+- [Memory overview](/concepts/memory)
+- [Builtin memory engine](/concepts/memory-builtin)
+- [QMD memory engine](/concepts/memory-qmd)