opensource/kilocode
3
0
Fork 0
mirror of https://github.com/Kilo-Org/kilocode.git synced 2026-09-01 15:32:11 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into feat/openai-explicit-prompt-cache-breakpoints

Browse Source
This commit is contained in:
Christiaan Arnoldus
2026-08-10 09:42:57 +02:00
committed by GitHub
parent 71abd522b1 ad9d0adc36
commit 9be130cc81
6 changed files with 309 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/kilo-docs/lib/nav/code-with-ai.ts
+4
View File
@@ -64,6 +64,10 @@ export const CodeWithAiNav: NavSection[] = [
href: "/code-with-ai/agents/chat-interface",
children: "Chat Interface",
},
{
href: "/code-with-ai/agents/session-history",
children: "Session History and Search",
},
{
href: "/code-with-ai/agents/context-mentions",
children: "Context & Mentions",
packages/kilo-docs/pages/code-with-ai/agents/chat-interface.md
+2 -2
View File
@@ -63,7 +63,7 @@ Open your terminal and run `kilo` to launch the interactive terminal interface (
- **Input prompt** - Type your requests and press Enter to send
- **Action buttons** - Approve or reject proposed changes, answer questions
- **Agent dropdown** - Switch between agents (e.g. Code, Ask, Plan) from the sidebar
- **Session management** - Start new sessions or resume previous ones
- **Session management** - Start new sessions or [search and resume previous ones](/docs/code-with-ai/agents/session-history)
**Providing context:**
@@ -89,7 +89,7 @@ You can also rename local sessions from **History** using the edit button or the
- **Input prompt** - Type your requests and press Enter to send
- **Action buttons** - Approve or reject proposed changes, answer questions
- **Agent cycling** - Switch between agents using keybinds or slash commands
- **Session management** - Start new sessions or resume previous ones
- **Session management** - Start new sessions or [search and resume previous ones](/docs/code-with-ai/agents/session-history)
- **New task** - Start a new task, available using the `+` button at the top or `New Task` button above the chat input
- **Worktree** - Continue the current task with it's git state and session history in the Agent Manager in an isolated worktree
- **File changes** - Shows the number of lines changed and opens a diff view
packages/kilo-docs/pages/code-with-ai/agents/context-mentions.md
+6 -4
View File
@@ -25,15 +25,15 @@ Type `@` in the chat input to get autocomplete suggestions. You can mention:
| **File** | Attach a file's contents to your message | `@src/utils.ts` |
| **Terminal** | Include your active VS Code terminal output | `@terminal` |
| **Git Changes** | Attach uncommitted working-tree diffs and new files | `@git-changes` |
| **Past chats** | Attach a previous session's transcript as context | `@` → **Past chats** → pick a session |
| **Past chats** | Add a previous session's chat history as context | `@` → **Past chats** → pick a session |
Selecting a suggestion inserts the mention and highlights it in the input. File contents, terminal output, and git changes are attached as context when you send the message.
### Referencing Past Chats
Choosing **Past chats** from the `@` menu opens a searchable picker of your previous sessions in the current workspace, ordered by recency. Selecting a session inserts a highlighted mention token; when you send the message, that session's current transcript is attached as context so the agent can build on the earlier conversation. Clicking the mention token opens the referenced session.
Choosing **Past chats** from the `@` menu opens a searchable picker of sessions in the current workspace and related Git worktrees, including Agent Manager worktrees, ordered by recency. Search matches session titles and worktree names. Selecting a session inserts a highlighted mention token; when you send the message, that session's current chat history is added as context so the agent can build on the earlier conversation. Clicking the mention token opens the referenced session.
Very long transcripts are truncated, keeping the beginning and end, so a single mention cannot fill the context window.
Very long chat histories are truncated, keeping the beginning and end, so a single mention cannot fill the context window.
### Drag and Drop
@@ -77,7 +77,7 @@ This means the agent can explore your entire project as needed, rather than bein
| **Mention files when helpful** | If you know the exact file, mention its path to save the agent a search step |
| **Keep editor tabs relevant** | Open tabs are passed as context, so keep relevant files open |
| **Trust the agent's tools** | The agent can search, read, and explore your codebase — let it do the discovery work |
| **Reference a past chat** | Type `@` and choose **Past chats** to open a searchable picker of previous sessions in the current workspace. Selecting a session attaches its current transcript as context when you send the message. |
| **Reference a past chat** | Type `@` and choose **Past chats** to search the current workspace and related Git worktrees, including Agent Manager worktrees. Selecting a session adds its current chat history as context when you send the message. |
{% /tab %}
{% tab label="CLI" %}
@@ -93,6 +93,7 @@ When you describe a task, the agent uses its tools — `read`, `grep`, `glob`, a
In the terminal-based TUI, you can provide context in several ways:
- **Type `@` for file autocomplete** — In the TUI, type `@` followed by a filename to get autocomplete suggestions. Selecting a file attaches its contents to your message. You can limit how much is included by appending a line range, e.g. `@src/utils.ts#10-50`.
- **Reference a past chat** — Type `@`, choose **Past chats**, then search for and select a session. Kilo adds that chat history as context when you send the message without switching sessions.
- **Mention file paths in your message** — Simply refer to files by path in your conversation text (e.g., "look at src/utils.ts") and the agent will read them.
- **Use `kilo run -f`** — When using the non-interactive `kilo run` command, pass `-f path/to/file.ts` to explicitly include a file's contents in the context.
- **Let the agent find files itself** — The agent has access to `glob` (find files by pattern), `grep` (search file contents), and `read` (read file contents) tools. Describe what you're looking for and it will locate the relevant code.
@@ -116,6 +117,7 @@ This means the agent can explore your entire project as needed, rather than bein
|---|---|
| **Describe the task clearly** | The agent finds context on its own — focus on _what_ you want done rather than _where_ the code is |
| **Mention files when helpful** | If you know the exact file, mention its path to save the agent a search step |
| **Reference a past chat** | Type `@` and choose **Past chats** to add another session's chat history as context without switching sessions. |
| **Use `kilo run -f`** | Pass key files with `-f` when using `kilo run` for immediate context |
| **Trust the agent's tools** | The agent can search, read, and explore your codebase — let it do the discovery work |
packages/kilo-docs/pages/code-with-ai/agents/session-history.md
+288
View File
@@ -0,0 +1,288 @@
---
title: "Session History and Search"
description: "Find, search, inspect, and resume local Kilo Code sessions"
---
# Session history and search
Kilo Code keeps local session metadata and chat history so you can resume earlier work. You can search session titles in the history UI or CLI, ask the agent to search chat content, or inspect the local SQLite database directly.
{% callout type="info" %}
Local sessions use SQLite, not PostgreSQL. Use `kilo db` or `sqlite3`, not `psql`, to inspect the local database.
{% /callout %}
## Choose a search method
Different search surfaces cover different content and scopes:
| Method | Searches | Scope |
|---|---|---|
| [VS Code History](#search-session-history-in-vs-code) | Session titles | Sessions loaded in the selected Local or Cloud history view |
| [JetBrains History](#search-session-history-in-jetbrains) | Session titles | Sessions loaded in the selected Local or Cloud history view |
| [CLI Past chats](#reference-a-past-chat-in-the-cli-tui) | Session titles | Current workspace |
| [`kilo session list --search`](#filter-session-titles) | Session titles | Current workspace, or every local workspace with `--all` |
| [Ask Kilo to recall past chats](#ask-kilo-to-search-past-chats) | Titles and high-signal chat content | Current workspace and related Git worktrees |
| [VS Code chat search](#search-the-open-chat-session) | Rendered content in the open session | Current chat session |
| [VS Code Past chats](#add-a-past-chat-to-the-current-session) | Session titles and worktree names | Current workspace and related Git worktrees, including Agent Manager worktrees |
| [SQLite query](#query-sqlite-directly) | Any stored field you select | Entire selected local database |
History and CLI list searches do **not** search message content. To find a string inside prompts or replies, ask Kilo to search past chats or use a direct SQLite query.
## Search in the UI
{% tabs %}
{% tab label="VS Code" %}
### Search session history in VS Code
1. Open the Kilo Code sidebar.
2. Select the **History** button in the sidebar title bar. You can also select **Show History** below the recent sessions on a new chat.
3. Select **Local** or **Cloud**.
4. Enter part of a session title in **Search sessions**.
5. Select a result to reopen it.
Local history actions also let you rename, export, or delete a session. Cloud history can be filtered to **Only this repository**.
The History search is a fuzzy title search over the sessions currently loaded into the view. It does not search prompts or agent replies.
### Search the open chat session
Open a session and select the magnifying-glass button in its header. Chat search supports:
- Previous and next match navigation
- Match case
- Whole word
- Regular expressions
Kilo loads older messages while the search is active so the search covers the full local chat session, not only the messages initially visible.
### Add a past chat to the current session
Type `@` in the chat input, select **Past chats**, and search by session title or worktree name. Selecting a result adds that past chat's content as context when you send the message from your current session. It does not switch or reopen sessions. Past chats includes sessions in the current workspace and related Git worktrees, including Agent Manager worktrees.
{% /tab %}
{% tab label="JetBrains" %}
### Search session history in JetBrains
1. Open the Kilo Code tool window.
2. Select **History** in the tool window toolbar.
3. Select **Local** or **Cloud**.
4. Enter part of a session title in **Search sessions**.
5. Select a result to reopen it.
You can rename or delete local sessions. In Cloud history, enable **Only this repository** to narrow the list.
The JetBrains History search matches session titles, not chat content.
{% /tab %}
{% tab label="CLI TUI" %}
### Reference a past chat in the CLI TUI
1. Run `kilo`.
2. Type `@` in the prompt and select **Past chats**.
3. Search for a session by title.
4. Select a session, finish your message, and send it.
Kilo adds the selected chat history as context for your message. This does not switch the TUI to the selected session. Use `/sessions`, `/resume`, or `/continue` when you want to load a different session instead.
{% /tab %}
{% /tabs %}
## Ask Kilo to search past chats
The simplest way to search message content across past local sessions is to ask Kilo directly:
```text
Search my local sessions for "database disk image is malformed" and summarize the matching conversations.
```
Kilo's local recall search covers session titles, user and assistant text, file references, and failed tool errors in the current workspace and related Git worktrees. Every query term must occur somewhere in a matching session; exact phrases and user-authored matches rank higher.
The search includes archived and child sessions. It excludes reasoning, synthetic or ignored text, successful tool output, file contents, and other metadata. Kilo can then read the full chat history for a selected result.
## Search with CLI commands
### Filter session titles
List sessions in the current workspace:
```bash
kilo session list --search "database migration"
```
Search titles across every local workspace and return JSON:
```bash
kilo session list --all --search "database migration" --format json
```
Limit the number of results:
```bash
kilo session list --all --search "migration" --max-count 25
```
`--search` performs a SQLite `LIKE` substring search on the title. It does not inspect messages. Use the returned session ID to resume or export a session:
```bash
kilo --session ses_123
kilo run --session ses_123 "Summarize where we stopped"
kilo export ses_123 > session.json
```
### Find the local database
Print the database selected by the current CLI environment:
```bash
kilo db path
```
Stable installations normally use these paths:
| Environment | Default path |
|---|---|
| Windows | `%USERPROFILE%\.local\share\kilo\kilo.db` |
| macOS | `~/.local/share/kilo/kilo.db` |
| Linux | `~/.local/share/kilo/kilo.db` |
| VS Code Remote SSH | `~/.local/share/kilo/kilo.db` on the remote machine |
The actual path can differ when `KILO_DB`, `XDG_DATA_HOME`, a development channel, or an isolated development environment is active. Prefer `kilo db path` over assuming a path.
## Query SQLite directly
{% callout type="warning" %}
The `kilo db` query command accepts arbitrary SQL, including writes. Use read-only queries, and use `sqlite3 -readonly` for safer interactive inspection. Stop Kilo before copying, replacing, or restoring the database because active transactions may also use `kilo.db-wal` and `kilo.db-shm`.
{% /callout %}
### Use the built-in database command
List recently updated sessions:
```bash
kilo db "
SELECT
id,
title,
directory,
datetime(time_updated / 1000, 'unixepoch') AS updated
FROM session
ORDER BY time_updated DESC
LIMIT 25
" --format json
```
Search non-synthetic text parts for a case-insensitive substring:
```bash
kilo db "
SELECT
s.id AS session_id,
s.title,
json_extract(m.data, '$.role') AS role,
json_extract(p.data, '$.text') AS text
FROM session AS s
JOIN message AS m ON m.session_id = s.id
JOIN part AS p ON p.message_id = m.id
WHERE json_valid(p.data)
AND json_extract(p.data, '$.type') = 'text'
AND coalesce(json_extract(p.data, '$.synthetic'), 0) = 0
AND coalesce(json_extract(p.data, '$.ignored'), 0) = 0
AND instr(
lower(json_extract(p.data, '$.text')),
lower('database disk image is malformed')
) > 0
ORDER BY s.time_updated DESC, m.time_created, p.id
" --format json
```
Replace the search string in the second `lower(...)` expression. This query searches ordinary user and assistant text. It intentionally does not reproduce Kilo's recall ranking, workspace scope, file-reference matching, or tool-error matching.
### Use the SQLite shell
Install the `sqlite3` command-line tool, then open the selected database in read-only mode:
```bash
sqlite3 -readonly "$(kilo db path)"
```
Useful commands inside the shell include:
```sql
.tables
.schema session
.schema message
.schema part
```
Run the SQL examples above without the surrounding `kilo db` command. Exit with `.quit`.
`psql` cannot open this file because `psql` speaks the PostgreSQL client protocol, while local Kilo sessions are stored in an embedded SQLite database.
## Search through the API or SDK
Run a local server with authentication before exposing its API:
```bash
export KILO_SERVER_PASSWORD='replace-with-a-strong-password'
kilo serve --port 4096
```
Search session titles in the current directory:
```bash
curl -u "kilo:$KILO_SERVER_PASSWORD" \
--get "http://127.0.0.1:4096/session" \
--data-urlencode "directory=$PWD" \
--data-urlencode "roots=true" \
--data-urlencode "search=migration" \
--data-urlencode "limit=50"
```
Read the complete chat history for one result:
```bash
curl -u "kilo:$KILO_SERVER_PASSWORD" \
--get "http://127.0.0.1:4096/session/ses_123/message" \
--data-urlencode "directory=$PWD"
```
The list endpoint's `search` parameter searches titles only. To search chat content programmatically, list candidate sessions, read their messages, and inspect text parts in your application.
The JavaScript SDK exposes the same endpoints:
```ts
import { createKiloClient } from "@kilocode/sdk/v2/client"
const auth = Buffer.from(`kilo:${process.env.KILO_SERVER_PASSWORD}`).toString("base64")
const client = createKiloClient({
baseUrl: "http://127.0.0.1:4096",
directory: process.cwd(),
headers: { Authorization: `Basic ${auth}` },
})
const result = await client.session.list(
{ roots: true, search: "migration", limit: 50 },
{ throwOnError: true },
)
for (const session of result.data) {
const history = await client.session.messages(
{ sessionID: session.id, limit: 0 },
{ throwOnError: true },
)
// Inspect history.data[*].parts for the content your application needs.
console.log(session.title, history.data.length)
}
```
`limit: 0` requests the complete chat history from the compatibility API. For large sessions, use a positive `limit` and follow the pagination cursor instead.
## Local and cloud sessions
Local sessions live in the SQLite database on the machine where Kilo runs. With VS Code Remote SSH, that means the remote host. Cloud sessions and shared-session copies are separate and are not available through local SQLite queries unless you import them locally.
For database corruption or reset procedures, see [Troubleshooting IDE Extensions](/docs/getting-started/troubleshooting/troubleshooting-extension). Resetting the database removes local session history, so back it up before recovery work.
packages/kilo-docs/pages/collaborate/sessions-sharing.md
+4 -2
View File
@@ -5,7 +5,7 @@ description: "Share and collaborate on Kilo Code sessions"
# Sessions & Sharing
A session is your platform-agnostic interaction with Kilo. It remembers your repository, your task, and the conversation so you can pause and resume work without losing context. Sessions are private to your account by default; you can optionally share a link with others who can read or fork your session.
A session is your platform-agnostic interaction with Kilo. It remembers your repository, your task, and the conversation so you can pause and resume work without losing context. Local sessions stay on the machine where Kilo runs. Account-backed cloud sessions are private to your account by default. You can optionally share a session link with others who can read or fork it.
## What a session keeps for you
@@ -49,7 +49,9 @@ Forking creates a new session in your account, with its own ID, and copies over
## Where your session data lives
To keep sessions fast and resumable, Kilo stores small JSON blobs associated with your session. These include your conversation history and task metadata. If you share a session, Kilo keeps a public copy used by the share link while your private session remains under your account.
Kilo stores local session history and metadata in an SQLite database on the machine where Kilo runs. Cloud sessions and shared-session copies use Kilo's cloud services and are separate from the local database. If you share a session, Kilo keeps a public copy for the share link while the original session remains private.
See [Session History and Search](/docs/code-with-ai/agents/session-history) to find the local database, search session titles or transcripts, and inspect sessions with the CLI or SQLite.
Good practice:
packages/kilo-docs/pages/getting-started/troubleshooting/troubleshooting-extension.md
+5 -3
View File
@@ -27,12 +27,14 @@ If every prompt fails with `SQLiteError: database disk image is malformed`, Kilo
### Find the database
The database location depends on where Kilo Code is running:
When the kilo CLI uses the same environment as the affected installation, run `kilo db path` to print the selected database. See [Session History and Search](/docs/code-with-ai/agents/session-history) for normal database inspection and search workflows.
The default database location depends on where Kilo Code is running:
| Environment | Database path |
|---|---|
| Windows | `%LOCALAPPDATA%\kilo\kilo.db` |
| macOS | `~/Library/Application Support/kilo/kilo.db` |
| Windows | `%USERPROFILE%\.local\share\kilo\kilo.db` |
| macOS | `~/.local/share/kilo/kilo.db` |
| Linux | `~/.local/share/kilo/kilo.db` |
| VS Code Remote SSH | `~/.local/share/kilo/kilo.db` on the remote machine |