Kward

Memory

Memory lets Kward remember stable preferences and project facts across interactive sessions. It is off by default.

Use memory when you keep telling Kward the same things:

  • "This project uses Minitest."
  • "Prefer small patches with tests."
  • "Do not run destructive database commands."
  • "In this workspace, use bundle exec rake test."

Leave memory off when every session should start clean.

Memory is not used for one-shot prompts such as kward "...".

Enable memory

Inside interactive Kward:

/memory enable

Disable it again:

/memory disable

The setting is stored in ~/.kward/config.json:

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

Add memories yourself

Add a global instruction when it should apply everywhere:

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

Add a workspace-specific hint when it only applies to the current project:

/memory add "This workspace uses Minitest."

Use global core memory sparingly. It has higher priority than workspace memory.

Let Kward summarize useful memories

Auto-summary is off by default. Enable it if you want Kward to learn recurring preferences from interactive sessions:

/memory auto-summary enable

This only runs when memory is enabled. It does not run for one-shot prompts.

You can also ask Kward to summarize the current session manually:

/memory summarize

Kward is conservative about inferred memories and refuses to automatically persist emotional, intimate, romantic, or dependency-forming memories.

Inspect what Kward remembers

List active memories for the current workspace:

/memory list

Show memory files and state:

/memory inspect

Explain why memories were used for the most recent turn:

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

/memory forget core_001
/memory forget soft_001

Promote a workspace hint when it should become a stronger rule:

/memory promote soft_001

Relax a global memory back to the current workspace:

/memory relax core_001

How memory is organized

Kward uses three layers:

  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.

Core memories override soft memories. Soft memories are treated as hints, not facts.

Kward does not inject every stored memory into every prompt. It retrieves a bounded set that appears relevant to the current turn.

Where memory is stored

Default files:

~/.kward/memory/core.json
~/.kward/memory/soft.jsonl
~/.kward/memory/events.jsonl

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 support

The experimental RPC backend exposes memory methods such as memory/list, memory/add, memory/forget, memory/why, and memory/summarize. See RPC protocol if you are building a client.