fengming 0.3.9 → 0.3.11

package/docs/concepts/commitments.md

@@ -1,150 +0,0 @@
----
-summary: "Inferred follow-up memory for check-ins that are not exact reminders"
-title: "Inferred commitments"
-sidebarTitle: "Commitments"
-read_when:
-  - You want FengMing to remember natural follow-ups
-  - You want to understand how inferred check-ins differ from reminders
-  - You want to review or dismiss follow-up commitments
----
-
-Commitments are short-lived follow-up memories. When enabled, FengMing can
-notice that a conversation created a future check-in opportunity and remember
-to bring it back later.
-
-Examples:
-
-- You mention an interview tomorrow. FengMing may check in afterward.
-- You say you are exhausted. FengMing may ask later whether you slept.
-- The agent says it will follow up after something changes. FengMing may track
-  that open loop.
-
-Commitments are not durable facts like `MEMORY.md`, and they are not exact
-reminders. They sit between memory and automation: FengMing remembers a
-conversation-bound obligation, then heartbeat delivers it when it is due.
-
-## Enable commitments
-
-Commitments are off by default. Enable them in config:
-
-```bash
-fengming config set commitments.enabled true
-fengming config set commitments.maxPerDay 3
-```
-
-Equivalent `fengming.json`:
-
-```json
-{
-  "commitments": {
-    "enabled": true,
-    "maxPerDay": 3
-  }
-}
-```
-
-`commitments.maxPerDay` limits how many inferred follow-ups can be delivered
-per agent session in a rolling day. The default is `3`.
-
-## How it works
-
-After an agent reply, FengMing may run a hidden background extraction pass in a
-separate context. That pass looks only for inferred follow-up commitments. It
-does not write into the visible conversation and it does not ask the main agent
-to reason about the extraction.
-
-When it finds a high-confidence candidate, FengMing stores a commitment with:
-
-- the agent id
-- the session key
-- the original channel and delivery target
-- a due window
-- a short suggested check-in
-- non-instructional metadata for heartbeat to decide whether to send it
-
-Delivery happens through heartbeat. When a commitment becomes due, heartbeat
-adds the commitment to the heartbeat turn for the same agent and channel scope.
-The model can send one natural check-in or reply `HEARTBEAT_OK` to dismiss it.
-If heartbeat is configured with `target: "none"`, due commitments remain
-internal and do not send external check-ins. Commitment delivery prompts do not
-replay the original conversation text, and due commitment heartbeat turns run
-without FengMing tools.
-
-FengMing never delivers an inferred commitment immediately after writing it.
-The due time is clamped to at least one heartbeat interval after the commitment
-is created, so the follow-up cannot echo back in the same moment it was
-inferred.
-
-## Scope
-
-Commitments are scoped to the exact agent and channel context where they were
-created. A follow-up inferred while talking to one agent in Discord is not
-delivered by another agent, another channel, or an unrelated session.
-
-This scope is part of the feature. Natural check-ins should feel like the same
-conversation continuing, not like a global reminder system.
-
-## Commitments vs reminders
-
-| Need                                            | Use                                      |
-| ----------------------------------------------- | ---------------------------------------- |
-| "Remind me at 3 PM"                             | [Scheduled tasks](/automation/cron-jobs) |
-| "Ping me in 20 minutes"                         | [Scheduled tasks](/automation/cron-jobs) |
-| "Run this report every weekday"                 | [Scheduled tasks](/automation/cron-jobs) |
-| "I have an interview tomorrow"                  | Commitments                              |
-| "I was up all night"                            | Commitments                              |
-| "Follow up if I do not answer this open thread" | Commitments                              |
-
-Exact user requests already belong to the scheduler path. Commitments are only
-for inferred follow-ups: the moments where the user did not ask for a reminder,
-but the conversation clearly created a useful future check-in.
-
-## Manage commitments
-
-Use the CLI to inspect and clear stored commitments:
-
-```bash
-fengming commitments
-fengming commitments --all
-fengming commitments --agent main
-fengming commitments --status snoozed
-fengming commitments dismiss cm_abc123
-```
-
-See [`fengming commitments`](/cli/commitments) for the command reference.
-
-## Privacy and cost
-
-Commitment extraction uses an LLM pass, so enabling it adds background model
-usage after eligible turns. The pass is hidden from the user-visible
-conversation, but it can read the recent exchange needed to decide whether a
-follow-up exists.
-
-Stored commitments are local FengMing state. They are operational memory, not
-long-term memory. Disable the feature with:
-
-```bash
-fengming config set commitments.enabled false
-```
-
-## Troubleshooting
-
-If expected follow-ups are not appearing:
-
-- Confirm `commitments.enabled` is `true`.
-- Check `fengming commitments --all` for pending, dismissed, snoozed, or expired
-  records.
-- Make sure heartbeat is running for the agent.
-- Check whether `commitments.maxPerDay` has already been reached for that
-  agent session.
-- Remember that exact reminders are skipped by commitment extraction and should
-  appear under [scheduled tasks](/automation/cron-jobs) instead.
-
-## Related
-
-- [Memory overview](/concepts/memory)
-- [Active memory](/concepts/active-memory)
-- [Heartbeat](/gateway/heartbeat)
-- [Scheduled tasks](/automation/cron-jobs)
-- [`fengming commitments`](/cli/commitments)
-- [Configuration reference](/gateway/configuration-reference#commitments)

package/docs/concepts/compaction.md

@@ -1,203 +0,0 @@
----
-summary: "How FengMing summarizes long conversations to stay within model limits"
-read_when:
-  - You want to understand auto-compaction and /compact
-  - You are debugging long sessions hitting context limits
-title: "Compaction"
----
-
-Every model has a context window: the maximum number of tokens it can process. When a conversation approaches that limit, FengMing **compacts** older messages into a summary so the chat can continue.
-
-## How it works
-
-1. Older conversation turns are summarized into a compact entry.
-2. The summary is saved in the session transcript.
-3. Recent messages are kept intact.
-
-When FengMing splits history into compaction chunks, it keeps assistant tool calls paired with their matching `toolResult` entries. If a split point lands inside a tool block, FengMing moves the boundary so the pair stays together and the current unsummarized tail is preserved.
-
-The full conversation history stays on disk. Compaction only changes what the model sees on the next turn.
-
-## Auto-compaction
-
-Auto-compaction is on by default. It runs when the session nears the context limit, or when the model returns a context-overflow error (in which case FengMing compacts and retries).
-
-You will see:
-
-- `embedded run auto-compaction start` / `complete` in normal Gateway logs.
-- `🧹 Auto-compaction complete` in verbose mode.
-- `/status` showing `🧹 Compactions: <count>`.
-
-<Info>
-Before compacting, FengMing automatically reminds the agent to save important notes to [memory](/concepts/memory) files. This prevents context loss.
-</Info>
-
-<AccordionGroup>
-  <Accordion title="Recognized overflow signatures">
-    FengMing detects context overflow from these provider error patterns:
-
-    - `request_too_large`
-    - `context length exceeded`
-    - `input exceeds the maximum number of tokens`
-    - `input token count exceeds the maximum number of input tokens`
-    - `input is too long for the model`
-    - `ollama error: context length exceeded`
-
-  </Accordion>
-</AccordionGroup>
-
-## Manual compaction
-
-Type `/compact` in any chat to force a compaction. Add instructions to guide the summary:
-
-```
-/compact Focus on the API design decisions
-```
-
-When `agents.defaults.compaction.keepRecentTokens` is set, manual compaction honors that FengMing cut-point and keeps the recent tail in rebuilt context. Without an explicit keep budget, manual compaction behaves as a hard checkpoint and continues from the new summary alone.
-
-## Configuration
-
-Configure compaction under `agents.defaults.compaction` in your `fengming.json`. The most common knobs are listed below; for the full reference, see [Session management deep dive](/reference/session-management-compaction).
-
-### Using a different model
-
-By default, compaction uses the agent's primary model. Set `agents.defaults.compaction.model` to delegate summarization to a more capable or specialized model. The override accepts any `provider/model-id` string:
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "compaction": {
-        "model": "openrouter/anthropic/claude-sonnet-4-6"
-      }
-    }
-  }
-}
-```
-
-This works with local models too, for example a second Ollama model dedicated to summarization:
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "compaction": {
-        "model": "ollama/llama3.1:8b"
-      }
-    }
-  }
-}
-```
-
-When unset, compaction starts with the active session model. If summarization fails with a model-fallback-eligible provider error, FengMing retries that compaction attempt through the session's existing model fallback chain. The fallback choice is temporary and is not written back to session state. An explicit `agents.defaults.compaction.model` override remains exact and does not inherit the session fallback chain.
-
-### Identifier preservation
-
-Compaction summarization preserves opaque identifiers by default (`identifierPolicy: "strict"`). Override with `identifierPolicy: "off"` to disable, or `identifierPolicy: "custom"` plus `identifierInstructions` for custom guidance.
-
-### Active transcript byte guard
-
-When `agents.defaults.compaction.maxActiveTranscriptBytes` is set, FengMing triggers normal local compaction before a run if the active JSONL reaches that size. This is useful for long-running sessions where provider-side context management may keep model context healthy while the local transcript keeps growing. It does not split raw JSONL bytes; it asks the normal compaction pipeline to create a semantic summary.
-
-<Warning>
-The byte guard requires `truncateAfterCompaction: true`. Without transcript rotation, the active file would not shrink and the guard remains inactive.
-</Warning>
-
-### Successor transcripts
-
-When `agents.defaults.compaction.truncateAfterCompaction` is enabled, FengMing does not rewrite the existing transcript in place. It creates a new active successor transcript from the compaction summary, preserved state, and unsummarized tail, then records checkpoint metadata that points branch/restore flows at that compacted successor.
-Successor transcripts also drop exact duplicate long user turns that arrive
-inside a short retry window, so channel retry storms are not carried into the
-next active transcript after compaction.
-
-FengMing no longer writes separate `.checkpoint.*.jsonl` copies for new
-compactions. Existing legacy checkpoint files can still be used while referenced
-and are pruned by normal session cleanup.
-
-### Compaction notices
-
-By default, compaction runs silently. Set `notifyUser` to show brief status messages when compaction starts and completes:
-
-```json5
-{
-  agents: {
-    defaults: {
-      compaction: {
-        notifyUser: true,
-      },
-    },
-  },
-}
-```
-
-### Memory flush
-
-Before compaction, FengMing can run a **silent memory flush** turn to store durable notes to disk. Set `agents.defaults.compaction.memoryFlush.model` when this housekeeping turn should use a local model instead of the active conversation model:
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "compaction": {
-        "memoryFlush": {
-          "model": "ollama/qwen3:8b"
-        }
-      }
-    }
-  }
-}
-```
-
-The memory-flush model override is exact and does not inherit the active session fallback chain. See [Memory](/concepts/memory) for details and config.
-
-## Pluggable compaction providers
-
-Plugins can register a custom compaction provider via `registerCompactionProvider()` on the plugin API. When a provider is registered and configured, FengMing delegates summarization to it instead of the built-in LLM pipeline.
-
-To use a registered provider, set its id in your config:
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "compaction": {
-        "provider": "my-provider"
-      }
-    }
-  }
-}
-```
-
-Setting a `provider` automatically forces `mode: "safeguard"`. Providers receive the same compaction instructions and identifier-preservation policy as the built-in path, and FengMing still preserves recent-turn and split-turn suffix context after provider output.
-
-<Note>
-If the provider fails or returns an empty result, FengMing falls back to built-in LLM summarization.
-</Note>
-
-## Compaction vs pruning
-
-|                  | Compaction                    | Pruning                          |
-| ---------------- | ----------------------------- | -------------------------------- |
-| **What it does** | Summarizes older conversation | Trims old tool results           |
-| **Saved?**       | Yes (in session transcript)   | No (in-memory only, per request) |
-| **Scope**        | Entire conversation           | Tool results only                |
-
-[Session pruning](/concepts/session-pruning) is a lighter-weight complement that trims tool output without summarizing.
-
-## Troubleshooting
-
-**Compacting too often?** The model's context window may be small, or tool outputs may be large. Try enabling [session pruning](/concepts/session-pruning).
-
-**Context feels stale after compaction?** Use `/compact Focus on <topic>` to guide the summary, or enable the [memory flush](/concepts/memory) so notes survive.
-
-**Need a clean slate?** `/new` starts a fresh session without compacting.
-
-For advanced configuration (reserve tokens, identifier preservation, custom context engines, OpenAI server-side compaction), see the [Session management deep dive](/reference/session-management-compaction).
-
-## Related
-
-- [Session](/concepts/session): session management and lifecycle.
-- [Session pruning](/concepts/session-pruning): trimming tool results.
-- [Context](/concepts/context): how context is built for agent turns.
-- [Hooks](/automation/hooks): compaction lifecycle hooks (`before_compaction`, `after_compaction`).