AI Chat and Actions

AI Chat & Agent

The chat panel is a real agent, not a one-shot question box: it searches, reads, cross-checks and only then answers — and when you ask for something to be changed on disk, it proposes a plan you approve. Nothing is ever written without your click.

The turn, end to end

your message
   │
   ├─ 1. pre-RAG      hybrid search (top 6, current scope) → excerpts
   ├─ 2. system prompt built: agent rules + your overrides
   │                   + durable memory + excerpts + folder structure
   ├─ 3. ReAct loop (max 5 rounds)
   │        model → tool calls? ──yes──▶ execute, feed observations back ──┐
   │            │                                                          │
   │            no                                                         │
   │            ▼                                                          │
   │        final text ◀─────────────────────────────────────────────────┘
   │        (or: a plan was proposed → hand back to you immediately)
   ▼
answer + clickable sources    │    or    │    Before → After action card

1. Pre-RAG seeding

Before the model is called at all, your last message is run through hybrid search + reranking (top 6, restricted to the open folder if one is scoped). The excerpts go into the system prompt.

This matters twice: it saves a round-trip in the common case, and it means a model that cannot call tools still answers from your files instead of hallucinating. Graceful degradation, not a fallback path.

2. What the model is told

The system prompt is assembled fresh each turn:

Block	Content
Agent rules	Built-in: which tools exist, use them before answering, cite files by name, call propose_actions to act (nothing executes without validation), call remember for durable facts, answer concisely.
Your overrides	prompts.chat_system, appended as "additional instructions" — it adds to the agent rules rather than replacing them.
Durable memory	Up to 50 notes the agent has saved across past conversations.
Seeded excerpts	The pre-RAG results, numbered, with path and snippet.
Folder structure	If a scope is set: a [D]/[F] listing of the folder, 2 levels deep, 200 entries max, exact absolute paths. This is what lets it reason structurally about a reorganisation, not just semantically.

Then your conversation history is appended as ordinary user/assistant messages.

3. The ReAct loop

The model is called with the full tool schema (tool_choice: auto). If it returns tool calls, each one is executed, its observation appended as a tool message, and the model is called again. Up to 5 rounds, then it must answer.

The loop stops early when the model returns plain content, or as soon as a plan is proposed — at that point control belongs to you.

Every tool call is announced to the UI before it runs (an agent-step event), which is the live trace you see in the chat: 🔍 Searching: invoices 2024, 📄 Reading: report.pdf, 🛠️ Preparing an action plan.

The built-in tools

Tool	What it does	Bounds
search_files	Hybrid semantic + keyword search. Args: query, optional scope.	Top 8 per call. Results are added to the response's clickable sources.
read_file	Reads a file's text. Arg: path.	~4000 characters, lossy-UTF-8 so binaries degrade instead of failing.
list_directory	Lists a folder's exact paths. Arg: path.	200 entries.
read_semantics	Reads the extracted sense of files under a folder. Args: path, recursive.	60 files. Prerequisite for fixing wrong qualifications — you can't correct what you can't see.
propose_actions	Builds a Dry-Run plan. Args: summary, operations[].	Executes nothing. Validated, persisted as a draft, handed to you.
remember	Saves a durable fact or preference. Arg: note.	Deduplicated; injected into every future conversation; manageable in Settings.

Plus every tool exposed by your MCP servers, namespaced mcp__<server>__<tool>.

Security bounds

read_file, list_directory, read_semantics and every path in propose_actions are restricted to your indexed roots, with segment-boundary matching: a root of …\Docs does not authorise …\DocsEvil\secret. Out-of-bounds calls return a refusal string to the model, not data.

With no roots configured there is no restriction — there is nothing to protect yet.

Actions: the Dry-Run model

When the assistant wants to change something, it calls propose_actions, and you get an Action Plan card: a Before → After diff, one line per operation, each with the model's stated reason.

{
  "summary": "Group 2024 invoices by quarter",
  "operations": [
    { "kind": "mkdir",  "new_path": "C:\\...\\Invoices\\2024-Q1", "reason": "..." },
    { "kind": "move",   "old_path": "C:\\...\\edf-jan.pdf",
                        "new_path": "C:\\...\\Invoices\\2024-Q1\\edf-jan.pdf", "reason": "..." }
  ]
}

Five operation kinds:

Kind	Effect
move / rename	Renames on disk (parent directories created as needed).
mkdir	Creates a folder.
delete	Moves the target to SenseTree's local trash (<data dir>\trash\<uuid>__<name>) — reversible, never a hard delete.
requalify	Rewrites a file's extracted sense. The file itself is untouched.

You can uncheck operations before approving. Only operations that were in the original plan are accepted — an edited list is verified against the stored draft, so nothing can be injected between proposal and approval.

Applying, transactionally

Approve runs three phases in order:

1. Disk. Operations execute one by one, each success journaled. On the first failure, everything already done is rolled back in reverse (rename back, restore from trash, remove created directory) and nothing is kept. You get the error and the rollback report.
2. Index. With disk consistent: renames update the LanceDB path without re-embedding, deletions remove vectors and catalog rows.
3. Semantics. requalify operations are written last, and are themselves atomic — if one fails, the previously rewritten ones are restored.

Then the transaction is marked committed. Discard just marks the draft discarded; nothing was ever written.

Why requalify is special

The extracted sense isn't only displayed — it is embedded (chunk #0 carries it, and every other chunk's vector is prefixed with it). Rewriting it in the database alone would leave search matching the old, wrong description.

So a requalification: pins the new sense (so re-indexing never regenerates over your correction), clears the stored hash, and re-queues the file at high priority. It is re-extracted and re-embedded with the pinned sense, which is what makes the fix real in search and not just on screen.

The other planner

Besides the agent, plan_reorganization is a direct one-shot planner: an instruction plus a scope, answered in strict JSON (response_format: json_object), with the folder listing and known summaries as context. It produces the same ActionPlan and goes through the same approval, rollback and validation path. Model output is tolerant-parsed — code fences and surrounding prose are stripped before the JSON object is read.

Durable memory

remember writes a one-line note to a local SQLite table. Every later conversation gets those notes in its system prompt under "what you already know". Use it for lasting things — "my invoices live in D:\Admin\Factures", "answer in short bullet points" — not for the current task.

Notes are listed and deletable in Settings → Agent memory, and they never leave your machine except as part of the system prompt sent to your configured reasoning endpoint.

Requirements and tips

• Needs the reasoning slot enabled. Without it there is no chat.
• Tool-calling support is what separates a good experience from a passable one. Models advertising tools (most modern instruct models, and the Ollama catalog flags them) will search and read; those without still answer from the pre-RAG context.
• Scope the chat. Open the folder you want it to reason about — that is what fills the structural listing, and what bounds search_files by default.
• Read the reasons on each operation before approving. That line is the whole point of the Dry-Run.
• Malformed plans or invented paths usually mean the reasoning model is too weak for strict-format output. Try a stronger one, raise reasoning_effort for the reasoning slot, or tighten prompts.chat_system — see Prompts.

Related IPC commands

Command	Role
chat_with_assistant	One agent turn: pre-RAG, ReAct loop, tools, plan or answer.
plan_reorganization	One-shot planner over a scope. Draft only.
apply_action_plan	Approve — transactional apply with rollback and index sync.
discard_action_plan	Discard a draft.
agent_memory_list / _delete / _clear	Manage durable memory.
qualify_file / qualify_folder	Re-run qualification on demand, outside the chat.