How Do Enkaidu Sessions Work

Enkaidu is an agentic assistant that works with your choice of local AI models and providers. When launched, Enkaidu presents the user with an initial primary chat session connected to an AI model and system prompt based on your configuration.

Queries to the model accumulates history, gathering up queries, responses, and tool calls. When using small models with modest context windows running on systems with limited memory, the history can soon overwhelm the context window’s size. Depending on the LLM provider’s configuration, the context will get “clipped”, often by just dropping the oldest messages in the history and sometimes by shedding content in the middle. This in effect can lead to the model losing its “memory” of requests in the conversation.

Enkaidu offers two ways to work with sessions to better manage the context window as well as coordinate with different AI models:

1. Nested working sessions, and
2. multiple active root sessions.

Nested sessions#

When using AI models to perform lengthy tasks, all the back and forth that was necessary to complete the task is no longer needed when moving on to another task. While sometimes we need none of it, often we need to retain some of the context so we can build on the knowledge from the previous task in a way lets us control what we retain.

Branching#

Enkaidu’s /session push command enables branching the current session into a nested sub-session. The input focus (represented by the blue session container in the illustration) moves to the branched “sub-session” and all subeqeuent requests and responses accumulate in the nested chat history.

Note Using /session push preserves history by default when branching the session. However you can use various keep_* parameters to control if some or none of the outer session’s history and state are included in the nested session.

You can use /session push to repeatedly branch a session, each time creating a nested sub-session that isolates the subsequent conversation history.

Returning#

When a task in a nested session has been completed, Enkaidu’s /session pop command can be used to exit the nested session and return to the outer session. When invoked without additional parameters, /session pop will throw away the nested chat history and return the input focus to where the session was branched using /session push.

Retaining#

When using a branched session to do some work, it is often more useful to “bring back” some (or all) of the information in the nested session context. Retaining salient information from the otherwise lengthy and noisy context can be helpful when the task involves lots of tool calling and reading and changing files.

Note Use /session usage to get a sense of the tokens in the session history.

The /session pop command supports an optional retain= parameter lets you specify how much (full or outline) of which scope (session or last conversation) to “capture and return” to the outer session.

The following table clarifies the use of the retain= parameter, including a mapping to the numbered markers in the illustration’s example conversation.

While the entire nested session can be retained, the other options provide selective ways to bring back just enough to let us remember and continue on to our next task.

Replacing#

When retaining and returning information from a branched session, /session pop supports the parameter replace=. When replace=true is used with /session pop Enkaidu will replace the outer / parent session’s history with the retained information.

This capability was conceived to support session history compaction. Consider the following example of inputs to Enkaidu after you’ve spent some time doing some work:

> /session push
> Perform a CONTEXT CHECKPOINT COMPACTION and create a hand-off summary for another LLM that will resume the task. 
> /session pop retain=session replace=true

After executing the above steps the current (outer) session will have its history replaced by the retained content from the branched session, in effect compacting it.

Multiple root sessions#

Branching and nesting happens within a single rooted session, and all interactions are with the same LLM that was configured at the start of the session.

Enkaidu supports the /session new <NAME> ... command that can be used to create separate and independent rooted sessions, where each (if you wish) can be used with a different AI model.

The command /session goto <NAME> is available to enable switching back and forth between any named rooted session.

Enkaidu supports the use of branching and nesting within each rooted session.

Next steps#

The use of nested sessions is well defined, with a focus on efficiently and effectively using the limited context windows of small and local AI models.

At this time the purpose for named rooted sessions is less clear. Each named session is entirely un-related the others, and is somewhat like running Enkaidu multiple times in different terminals (but without the true concurrency of separate processes).

Switch between named sessions is merely the first step towards being able to delegate tasks from one to another. We can also imagine these rooted sessions operating concurrently, maybe with tasks running autonomously and even feeding each other.

More to come.