understanding_aico_history.md

Understanding aico history: Managing the AI's Focus

The aico history commands are a powerful feature for controlling the context sent to the AI. Every time you run aico ask or aico edit, your entire active conversation history is sent along with your new prompt. This is how the AI "remembers" what you've discussed, such as a plan you created in a previous step.

However, as a conversation gets longer, the context can become very large. This has two main effects:

1. It increases cost and token usage. More history means a larger payload for the API call.
2. It can distract the AI. Early brainstorming or corrected mistakes might not be relevant to the current task, but the AI will still see them.

The aico history subgroup lets you solve this by telling aico: "For the next prompt, only use the conversation starting from this specific point." The older messages are not deleted; they are simply ignored for future API calls until you decide otherwise.

A Practical Workflow

Let's walk through a common scenario: planning a feature and then implementing it.

1. The Planning Phase

You start a new session and have a conversation with the AI to create a plan.

# Start a new session
> aico init --model "claude-3-5-sonnet-20240620"

# Add a relevant file
> aico add my_app/core.py

# Brainstorm and create a plan
> aico ask "I want to add a caching layer. What are some options?"
> aico ask "Let's go with an in-memory dictionary. Propose a 3-step plan to implement it in core.py."

At this point, you've had two interactions, resulting in four total messages in your session log (two from you, two from the AI).

2. Checking the History Status

Before you start implementing, you can check what context aico is prepared to send next.

> aico history view
History contains 4 total messages. The next prompt will use 4 of these, starting from message 0.

The output is clear: the session has 4 messages stored, and all 4 will be used in the next command.

3. Focusing the AI on Execution

Your first interaction was just brainstorming. The actual, actionable plan begins with your second prompt (message index 2). To save tokens and focus the AI purely on the plan, you can set the "active" history to start from there.

> aico history set 2

Now, check the status again:

> aico history view
History contains 4 total messages. The next prompt will use 2 of these, starting from message 2.

This confirms exactly what you intended. The full history is preserved, but the AI's focus for the next command is now narrowed to just the plan itself (messages 2 and 3).

4. Resetting the Context

If you later decide you want the AI to consider the entire conversation again, you can easily reset the view to include everything from the beginning.

> aico history reset

Running aico history view again would now show that the next prompt will use all 4 messages, starting from message 0.

history set vs. undo: Focus vs. Correction

It's helpful to know when to use history set and when to use undo:

• aico history set: Use this for focusing. It's a strategic move when you're transitioning from one phase of work to another (e.g., from planning to implementation). You're telling the AI, "Let's work on this part of the conversation now."
• aico undo: Use this for correction. It's a tactical fix for when the last command produced a bad result or you made a mistake in your prompt. It "soft-deletes" the last interaction so it doesn't influence the next one.