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 is not used for one-shot prompts such as kward "...".

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.

Enable or disable memory

In interactive chat:

/memory enable
/memory disable

Enabling memory stores this config in ~/.kward/config.json:

{
  "memory": {
    "enabled": true
  }
}

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:

/memory auto-summary enable
/memory auto-summary disable

The config value is stored as:

{
  "memory": {
    "enabled": true,
    "auto_summary": 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:

  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:

/memory core "Prefer small, focused patches with tests."

Core memories are stored as human-readable JSON in:

~/.kward/memory/core.json

Workspace core memories are core memories scoped to a specific workspace. They usually come from promoting workspace soft memories.

Soft 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:

/memory add "This workspace usually uses Minitest."

Soft memories are stored as JSON Lines in:

~/.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:

/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.

Inspect, explain, and remove memory

List memories for the active workspace hierarchy:

/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:

/memory inspect

Explain why memories were retrieved for the most recent interactive turn:

/memory why

Forget a memory:

/memory forget core_001
/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:

/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:

/memory relax core_001

Retrieval behavior

For each interactive turn, Kward selectively retrieves memories using:

  • 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

Retrieved memories are injected into the system prompt as a bounded block similar to:

<kward_memory>
Global Core Memories:
- [core_001] ...

Workspace Core Memories:
- [core_002] ...

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

Default files:

~/.kward/memory/core.json
~/.kward/memory/soft.jsonl
~/.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].

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 for method details.