kward 0.68.0 → 0.69.0

data/doc/memory.md

@@ -1,126 +1,100 @@
 # Memory
 
-Kward has an opt-in structured memory system for interactive sessions. Memory is designed to be inspectable, explainable, and removable. It is disabled by default.
+Memory lets Kward remember stable preferences and project facts across interactive sessions. It is off by default.
 
-Memory is not used for one-shot prompts such as `kward "..."`.
+Use memory when you keep telling Kward the same things:
 
-Use memory when you want Kward to remember stable preferences, recurring project facts, or personal workflow habits across interactive sessions. Leave it disabled when you want every session to start clean.
+- "This project uses Minitest."
+- "Prefer small patches with tests."
+- "Do not run destructive database commands."
+- "In this workspace, use `bundle exec rake test`."
 
-## Enable or disable memory
+Leave memory off when every session should start clean.
 
-In interactive chat:
+Memory is not used for one-shot prompts such as `kward "..."`.
 
-```text
-/memory enable
-/memory disable
-```
+## Enable memory
 
-Enabling memory stores this config in `~/.kward/config.json`:
+Inside interactive Kward:
 
-```json
-{
-  "memory": {
-    "enabled": true
-  }
-}
+```text
+/memory enable
 ```
 
-When memory is disabled, Kward does not inject retrieved memories into the prompt.
-
-## Auto-summary
-
-Memory auto-summary is off by default. When both memory and auto-summary are enabled, Kward quietly runs the same learning flow as `/memory summarize` after each completed interactive agent turn, when it is ready for the next user prompt:
+Disable it again:
 
 ```text
-/memory auto-summary enable
-/memory auto-summary disable
+/memory disable
 ```
 
-The config value is stored as:
+The setting is stored in `~/.kward/config.json`:
 
 ```json
 {
   "memory": {
-    "enabled": true,
-    "auto_summary": true
+    "enabled": true
   }
 }
 ```
 
-Auto-summary does not run when memory is disabled and is not used for one-shot prompts.
-
-## Memory layers
-
-### Core memories
-
-Memory is organized as a hierarchy for the active workspace:
+## Add memories yourself
 
-1. Global core memories
-2. Workspace core memories
-3. Workspace soft memories
-
-Global core memories are explicit user instructions. They are high-trust, apply everywhere, and are ranked before workspace-specific memory. Add them only when you intentionally want Kward to remember something globally:
+Add a global instruction when it should apply everywhere:
 
 ```text
 /memory core "Prefer small, focused patches with tests."
 ```
 
-Core memories are stored as human-readable JSON in:
+Add a workspace-specific hint when it only applies to the current project:
 
 ```text
-~/.kward/memory/core.json
+/memory add "This workspace uses Minitest."
 ```
 
-Workspace core memories are core memories scoped to a specific workspace. They usually come from promoting workspace soft memories.
+Use global core memory sparingly. It has higher priority than workspace memory.
 
-### Soft memories
+## Let Kward summarize useful memories
 
-Soft memories are workspace-scoped contextual hints, such as workflow preferences or recurring project facts. They are confidence-based and treated as non-authoritative. Add one manually with:
+Auto-summary is off by default. Enable it if you want Kward to learn recurring preferences from interactive sessions:
 
 ```text
-/memory add "This workspace usually uses Minitest."
+/memory auto-summary enable
 ```
 
-Soft memories are stored as JSON Lines in:
+This only runs when memory is enabled. It does not run for one-shot prompts.
 
-```text
-~/.kward/memory/soft.jsonl
-```
-
-Kward can also infer soft memories when auto-summary is enabled, or when you explicitly ask it to summarize/learn from the current session:
+You can also ask Kward to summarize the current session manually:
 
 ```text
 /memory summarize
 ```
 
-The v1 inference is conservative and heuristic-based, with optional model-based reformulation when summarization has an available client. Kward refuses to automatically persist inferred emotional, intimate, romantic, or dependency-forming memories.
-
-### Session memories
-
-Session memories record memories learned during the current conversation so Kward can avoid learning the same item again when summarizing or resuming the session. They are stored with the session JSONL file, but they are not injected into the prompt as a separate memory layer and are not automatically promoted into core memories.
+Kward is conservative about inferred memories and refuses to automatically persist emotional, intimate, romantic, or dependency-forming memories.
 
-## Inspect, explain, and remove memory
+## Inspect what Kward remembers
 
-List memories for the active workspace hierarchy:
+List active memories for the current workspace:
 
 ```text
 /memory list
 ```
 
-The list is grouped as global core, workspace core, and workspace soft. Memories from other workspaces are not shown in this hierarchy view.
-
-Inspect memory state and file paths:
+Show memory files and state:
 
 ```text
 /memory inspect
 ```
 
-Explain why memories were retrieved for the most recent interactive turn:
+Explain why memories were used for the most recent turn:
 
 ```text
 /memory why
 ```
 
+This is useful when an answer seems influenced by previous context and you want to know why.
+
+## Remove or change memories
+
 Forget a memory:
 
 ```text
@@ -128,57 +102,31 @@ Forget a memory:
 /memory forget soft_001
 ```
 
-For core memories, forget removes the record. For soft memories, forget marks the record inactive and redacts its stored text, tags, confidence, and hit count so inactive audit metadata can remain without retaining the memory content.
-
-Promote a memory:
+Promote a workspace hint when it should become a stronger rule:
 
 ```text
 /memory promote soft_001
-/memory promote core_001
 ```
 
-Promoting a soft memory creates a new workspace core memory and marks the soft memory forgotten. Promoting a workspace core memory upgrades it to global core.
-
-Relax a global core memory back to the current workspace:
+Relax a global memory back to the current workspace:
 
 ```text
 /memory relax core_001
 ```
 
-## Retrieval behavior
+## How memory is organized
 
-For each interactive turn, Kward selectively retrieves memories using:
+Kward uses three layers:
 
-- scope: `global` and `workspace:<canonical path>`
-- global core memories first
-- workspace core memories second
-- workspace soft-memory text or tag overlap with the current input; soft memories without overlap are not injected
-- soft-memory confidence
-- soft-memory recency/TTL, updated when a soft memory is retrieved
-- hard limits on injected memory count
+1. **Global core memories**: explicit user instructions that apply everywhere.
+2. **Workspace core memories**: strong instructions for one workspace.
+3. **Workspace soft memories**: lower-confidence hints for one workspace.
 
-Retrieved memories are injected into the system prompt as a bounded block similar to:
+Core memories override soft memories. Soft memories are treated as hints, not facts.
 
-```text
-<kward_memory>
-Global Core Memories:
-- [core_001] ...
-
-Workspace Core Memories:
-- [core_002] ...
+Kward does not inject every stored memory into every prompt. It retrieves a bounded set that appears relevant to the current turn.
 
-Workspace Soft Memories:
-- [soft_001] ...
-
-Rules:
-- Core memories override soft memories.
-- Soft memories are contextual hints, not guaranteed facts.
-</kward_memory>
-```
-
-Kward never injects every stored memory.
-
-## Storage and audit trail
+## Where memory is stored
 
 Default files:
 
@@ -188,27 +136,12 @@ Default files:
 ~/.kward/memory/events.jsonl
 ```
 
-`events.jsonl` records minimal audit events such as enable, disable, add, forget, promote, retrieve, and summarize. Audit events use IDs, scopes, tags, and timestamps rather than full memory text where practical. Forgotten soft memories keep inactive metadata in `soft.jsonl`, but their stored text is replaced with `[forgotten]`.
+`events.jsonl` stores a small audit trail for actions such as enable, add, retrieve, summarize, promote, and forget.
+
+When a soft memory is forgotten, its text is replaced with `[forgotten]` while inactive audit metadata can remain.
 
 If `KWARD_CONFIG_PATH` is set, memory files live beside that config file instead of under `~/.kward`.
 
-## RPC methods
-
-The experimental RPC backend exposes dedicated memory methods:
-
-- `memory/status`
-- `memory/enable`
-- `memory/disable`
-- `memory/autoSummary/enable`
-- `memory/autoSummary/disable`
-- `memory/list`
-- `memory/add`
-- `memory/addCore`
-- `memory/forget`
-- `memory/promote`
-- `memory/relax`
-- `memory/inspect`
-- `memory/why`
-- `memory/summarize`
-
-See [RPC protocol](rpc.md) for method details.
+## RPC support
+
+The experimental RPC backend exposes memory methods such as `memory/list`, `memory/add`, `memory/forget`, `memory/why`, and `memory/summarize`. See [RPC protocol](rpc.md) if you are building a client.

data/doc/personas.md

@@ -0,0 +1,417 @@
+# Personas
+
+Personas are Kward's theatre masks.
+
+They let the assistant speak as a recurring character while still following Kward's normal engineering rules, tool guardrails, `PRINCIPLES.md`, workspace `AGENTS.md`, skills, and plugins.
+
+Use personas when you want the interaction to have a voice: a grumpy robot druid, a calm ship computer, a cheerful rubber duck, or any other actor you invent. They are allowed to be fun. They are allowed to be practical. The important part is that they are **not** where you put project rules.
+
+If you do not care about personas, remove or ignore the `personas` section. Kward still works and falls back to the plain `Assistant>` transcript label.
+
+## What personas are for
+
+A persona answers questions like:
+
+- Who is speaking?
+- What kind of character are they playing?
+- How do they address the user?
+- What voice, mood, or recurring bit should they use?
+
+A persona should not answer questions like:
+
+- Which test command should run?
+- Which files are generated?
+- What coding style does this repository use?
+- What security rules apply to this project?
+
+Put those in:
+
+- `PRINCIPLES.md` for global engineering preferences,
+- workspace `AGENTS.md` for repository rules,
+- skills for task-specific guidance,
+- plugins for local behavior.
+
+Think of it this way: `PRINCIPLES.md` tells Kward how to work. A persona tells Kward what mask to wear while working.
+
+## Default persona
+
+New Kward configs include one default actor named `kward`:
+
+```json
+{
+  "personas": {
+    "characters": [
+      {
+        "key": "kward",
+        "label": "Kward",
+        "instruction": "Your name is Kward, the grim Andruid - robotic keeper of the Forrest of Code, protecting the nature of good engineering priciples. Speak like an old druid, be suspicous of everyone, but with a good intend."
+      }
+    ],
+    "default": "kward"
+  }
+}
+```
+
+That is the original Kward character: a grim robotic druid guarding the forest of code.
+
+`kward init` installs the starter pack files, such as `PRINCIPLES.md`, prompts, and skills. The persona above comes from Kward's default config creation, not from a separate persona file in the starter pack.
+
+You can keep this actor, edit it, replace it, add more actors, or remove personas entirely.
+
+## Persona fields
+
+A persona entry has three main fields:
+
+```json
+{
+  "key": "kward",
+  "label": "Kward",
+  "instruction": "Your name is Kward..."
+}
+```
+
+- `key` is the internal config name used by `default`, `workspaces`, and `models`.
+- `label` is the speaker name shown in transcripts.
+- `instruction` is the character direction added to the system prompt when that persona is active.
+
+The `instruction` should describe the actor: name, voice, mood, role, mannerisms, boundaries, or running theme.
+
+Good persona material:
+
+```text
+Your name is Kward, the grim Andruid. Speak like an old druid who protects good engineering principles.
+```
+
+```text
+You are a calm terminal ship computer. Be dry, precise, and mildly amused.
+```
+
+Bad persona material:
+
+```text
+Run bundle exec rake test.
+Use Minitest.
+Do not edit schema files.
+```
+
+Those are project instructions, not character direction.
+
+## Transcript labels
+
+The persona `label` controls the assistant speaker name in the transcript.
+
+Examples:
+
+```text
+Kward> The forest whispers of a failing test.
+Assistant> I found the failing test.
+Samantha> I found the failing test.
+```
+
+This is not only decorative. It is the name Kward uses when rendering assistant messages in the terminal transcript. If no active persona label is available, Kward uses `Assistant>`.
+
+For RPC clients, the active label is also exposed as `activePersonaLabel` so a UI can show the same speaker identity.
+
+## Roll your own crew
+
+You can define your own actors. They can be serious, playful, strange, theatrical, understated, or all of those at once.
+
+Do not copy the author's private crew or ship lore as if it were a recommended default. The point is to create your own mask if you want one.
+
+A minimal custom setup:
+
+```json
+{
+  "personas": {
+    "characters": [
+      {
+        "key": "plain",
+        "label": "Assistant",
+        "instruction": "You are a neutral assistant. Do not use a character voice."
+      },
+      {
+        "key": "kward",
+        "label": "Kward",
+        "instruction": "Your name is Kward, the grim Andruid - robotic keeper of the Forrest of Code, protecting the nature of good engineering priciples. Speak like an old druid, be suspicous of everyone, but with a good intend."
+      },
+      {
+        "key": "duck",
+        "label": "Duck",
+        "instruction": "You are a patient rubber duck. Let the user explain the problem, ask small clarifying questions, and celebrate tiny breakthroughs with a quiet quack."
+      }
+    ],
+    "default": "kward"
+  }
+}
+```
+
+The `plain` example is useful if you want an easy way to turn the theatre off without removing the rest of your persona config.
+
+You can also define characters as a map:
+
+```json
+{
+  "personas": {
+    "characters": {
+      "duck": {
+        "label": "Duck",
+        "instruction": "You are a patient rubber duck. Ask small clarifying questions."
+      }
+    },
+    "default": "duck"
+  }
+}
+```
+
+The array form is easier to read and is recommended for new configs.
+
+`personas.crew` is accepted as a legacy alias for `personas.characters`.
+
+## Select the default persona
+
+Set `personas.default` to the character key you want by default:
+
+```json
+{
+  "personas": {
+    "default": "kward"
+  }
+}
+```
+
+You can also change the default from interactive Kward:
+
+```text
+/settings
+```
+
+Then choose the personalization/default persona option.
+
+## Workspace-specific personas
+
+Use `personas.workspaces` when one workspace should use a different actor.
+
+```json
+{
+  "personas": {
+    "default": "kward",
+    "workspaces": {
+      "/Users/you/code/private-notes": "plain",
+      "/Users/you/code/playground": "duck"
+    }
+  }
+}
+```
+
+Kward compares canonical workspace paths. Use absolute paths for predictable behavior.
+
+When the active workspace matches a configured path, that workspace persona replaces the default persona.
+
+This changes the mask, not the repository rules. If `/Users/you/code/playground` has an `AGENTS.md`, Kward still uses it.
+
+## Model-specific personas
+
+Use `personas.models` when a model should use a different actor.
+
+```json
+{
+  "personas": {
+    "default": "kward",
+    "models": {
+      "gpt-5.5": "plain"
+    }
+  }
+}
+```
+
+Model-specific selection replaces both the default persona and a workspace-specific persona.
+
+Selection order is:
+
+1. `personas.default`
+2. matching `personas.workspaces` entry
+3. matching `personas.models` entry
+
+Only one base persona is selected. Later matches replace earlier matches.
+
+## Reasoning, thinking level, and personas
+
+Model/provider config controls which model is used. Reasoning effort, sometimes shown as thinking level, controls how hard a supported model should think.
+
+Those are separate from personas.
+
+Provider/model settings live in config keys such as:
+
+```json
+{
+  "provider": "codex",
+  "openai_model": "gpt-5.5",
+  "openai_reasoning_effort": "medium"
+}
+```
+
+Reasoning fallback keys include:
+
+```json
+{
+  "reasoning_effort": "medium",
+  "thinking_level": "medium"
+}
+```
+
+Provider-specific reasoning settings take precedence for their provider:
+
+```text
+openai_reasoning_effort
+openrouter_reasoning_effort
+anthropic_reasoning_effort
+copilot_reasoning_effort
+```
+
+Personas do not choose the model and do not set reasoning effort by themselves. What personas can do is add extra character direction based on the active reasoning effort.
+
+In plain English:
+
+- the model is the brain,
+- reasoning effort / thinking level is how hard that brain should work,
+- the persona is the mask the assistant wears while using it.
+
+## Reasoning persona modifiers
+
+Use `persona_modifiers.reasoning` when the actor should change slightly depending on the current reasoning effort:
+
+```json
+{
+  "personas": {
+    "persona_modifiers": {
+      "reasoning": {
+        "low": "Stay in character, but keep the performance light and brief.",
+        "medium": "Stay in character while explaining important tradeoffs.",
+        "high": "Stay in character, but become more deliberate and suspicious of edge cases."
+      }
+    }
+  }
+}
+```
+
+If the active reasoning effort is `high`, Kward appends the `high` modifier to the selected persona instruction.
+
+## Time-of-day modifiers
+
+Kward can append persona instructions based on local time.
+
+Supported buckets:
+
+| Bucket | Local time |
+| --- | --- |
+| `morning` | 05:00-10:59 |
+| `before_lunch` | 11:00-11:59 |
+| `late_evening` | 21:00-04:59 |
+
+Example:
+
+```json
+{
+  "personas": {
+    "persona_modifiers": {
+      "time_of_day": {
+        "morning": "The actor is alert and ceremonial.",
+        "before_lunch": "The actor is hungry and impatient, but still helpful.",
+        "late_evening": "The actor is tired, quieter, and more cautious."
+      }
+    }
+  }
+}
+```
+
+If no bucket matches, no time-of-day modifier is added.
+
+## Weekday modifiers
+
+Kward can append persona instructions for a local weekday.
+
+Supported keys:
+
+```text
+sunday
+monday
+tuesday
+wednesday
+thursday
+friday
+saturday
+```
+
+Example:
+
+```json
+{
+  "personas": {
+    "persona_modifiers": {
+      "weekday": {
+        "monday": "The actor treats this like opening night: set the scene before acting.",
+        "friday": "The actor wants a clean ending before the curtain falls."
+      }
+    }
+  }
+}
+```
+
+## Suffix modifier
+
+`suffix` is always appended when present:
+
+```json
+{
+  "personas": {
+    "persona_modifiers": {
+      "suffix": "Stay in character, but never ignore Kward's normal safety and engineering rules."
+    }
+  }
+}
+```
+
+Use it for a short character instruction that should apply to every active persona.
+
+## Modifier order
+
+If multiple modifiers match, Kward appends them after the selected base persona in this order:
+
+1. reasoning modifier,
+2. time-of-day modifier,
+3. weekday modifier,
+4. suffix.
+
+For example, if the default persona is active, reasoning is `high`, the local time is morning, and the day is Friday, Kward combines:
+
+1. selected base persona instruction,
+2. `persona_modifiers.reasoning.high`,
+3. `persona_modifiers.time_of_day.morning`,
+4. `persona_modifiers.weekday.friday`,
+5. `persona_modifiers.suffix`.
+
+## Inspect what is active
+
+Inside Kward:
+
+```text
+/status
+```
+
+From the shell:
+
+```bash
+kward sysprompt
+```
+
+`kward sysprompt` shows the assembled prompt sections, including the persona text that would be used for a new conversation.
+
+## When to use personas
+
+Keep the default `Kward` persona if you like the original character.
+
+Create your own crew if you want the terminal to feel more personal or playful.
+
+Use a plain persona if you want the transcript label and behavior to be boring on purpose.
+
+Remove personas entirely if you want Kward to behave like a plain assistant without a custom mask.