Context Management

In long-running sessions or complex development tasks, the model’s context window has a limited capacity. As context continues to grow, inference efficiency may decrease, and key information may get buried. Hawa Code provides two context management tools: Message Archiving and Memo, for proactively controlling context size while preserving reusable analysis conclusions.

Both tools are disabled by default and must be manually enabled via environment variables.

1. Enabling the Tools

Tool Environment Variable Purpose
Message Archiving HAWA_CODE_MESSAGE_ARCHIVING=true Archive historical tool results
Memo HAWA_CODE_MEMO=true Persist analysis conclusions to disk and read them on demand

Add the following configuration to the project’s .env file to enable them:

HAWA_CODE_MESSAGE_ARCHIVING=true
HAWA_CODE_MEMO=true

The two tools complement each other: Message Archiving reduces the size of the immediate context, while Memo preserves structured information across multiple session stages. It is recommended to enable both when handling complex tasks.

2. Message Archiving

2.1 Overview

The Message Archiving tool archives tool execution results in the current context that have already been produced but are no longer directly used. Archived results no longer occupy the model context, but remain in the session state and can be restored when necessary.

Content suitable for archiving includes:

  • Tool outputs that have been completed and are unrelated to the current task step
  • Results that are long but whose key information has already been extracted as summaries
  • Files or logs queried temporarily that are unlikely to be reused later

Content that will not be archived includes:

  • Results with content no longer than 100 characters
  • Tool outputs on which the current reasoning still depends

2.2 UI Feedback

When a batch of tool results is archived, the interface will display:

⎿ Archived 3 tool result(s)
  Key summary: confirmed the return value formats of three APIs

When archived results are restored, the interface will display:

⎿ Unarchived 2 tool result(s)

2.3 Benefits

  • Reduces context consumption: Prevents large blocks of file content and log output from lingering in the conversation context.
  • Automated decisions: When context size increases, Hawa Code proactively identifies and archives low-relevance results.
  • Reversible operation: Archived results can be automatically restored later when needed.

3. Memo

3.1 Overview

The Memo tool saves key information needed across multiple conversation turns to disk, such as analysis conclusions, execution plans, error records, or core findings. After writing, the full content is removed from the current context, leaving only a short summary; the full content can be read at any time when needed.

3.2 Operation Types

The Memo tool supports the following operations:

Operation Purpose
write Write or overwrite a memo. Requires key, summary, and content
list List all memos in the current session, sorted by most recently updated
read Read the full content of the memo with the specified key
delete Delete the memo with the specified key

3.3 Memo Structure

Each memo consists of the following fields:

  • key: The unique identifier for the memo, e.g., auth-flow-analysis
  • summary: A summary of no more than 300 characters, retained in the context to quickly determine whether to read it
  • content: The full content of the memo, which can contain analysis results of any length

3.4 Storage Path

Memo content is persisted as Markdown files. The default path is:

~/.hcode/projects/{project-dir}/notes/{session-id}/{key}.md

Where:

  • {project-dir}: The project directory name converted from the current working directory
  • {session-id}: The unique identifier of the current session
  • {key}: The unique identifier of the memo

All memos under the same project and session also maintain an index file:

~/.hcode/projects/{project-dir}/notes/{session-id}/index.json

Memo files remain on the local disk for a long time; as long as the cache is not cleared or files are manually deleted, the content can continue to be used in subsequent sessions.

3.5 Benefits

  • Reusable across turns: Even after many turns, previously saved conclusions can be precisely retrieved.
  • Frees up context space: Long analyses retain only summaries, reducing context burden during ongoing reasoning.
  • Automatic deduplication: Repeated writes with the same key will overwrite old content without being counted as additional memos.
  • Capacity management: Each session can save up to 50 memos; when the limit is reached, outdated content must be manually deleted.

4. Using Together

Message Archiving and Memo can be used together in complex tasks as follows:

  1. Analysis phase: Use Memo to save structured conclusions such as code structure, call relationships, and key findings.
  2. Execution phase: Use Message Archiving to archive memo lists or memo content that has already been read.
  3. Reuse phase: When needed, reload relevant memos via the read operation, and archive them again after use.

The positioning of the two tools can be summarized as:

  • Message Archiving: Archives temporarily unused conversation content to keep the current context tidy.
  • Memo: Persists important conclusions to disk and reads them on demand.

5. Summary

Message Archiving and Memo together form Hawa Code’s context management mechanism. The former controls the volume of the current session’s context, while the latter preserves and reuses key knowledge within the session lifecycle. When handling long conversations, code analysis, and multi-step development scenarios, enabling both tools can significantly improve session clarity and continuity.