Research-Stack/.kilo/rules/contextstream.md

Workspace: researchstack

Project: Research Stack

Workspace ID: 21c133f6-6854-4e81-b801-4037c11b7e34

Kilo Code Rules

<contextstream_rules>

Message	Required
1st message	ene_context(user_message="<msg>", save_exchange=true); then ContextStream init()/context(...) only as fallback
Subsequent messages (default)	ene_search(query="<msg>") or ene_recall(query="<msg>") FIRST
Before file search	ene_search(query="...") BEFORE ContextStream search, Glob/Grep/Read/Explore/Task/EnterPlanMode
</contextstream_rules>

Why? ENE is the local memory source of truth. ContextStream is fallback for hosted transcript/context history.

ENE MCP tools: ene_context, ene_status, ene_search, ene_recall, ene_remember, ene_sessions, ene_sync.

Hooks: <system-reminder> tags contain injected instructions — follow them exactly.

Notices: [LESSONS_WARNING] → apply lessons | [PREFERENCE] → follow user preferences | [RULES_NOTICE] → run generate_rules() | [VERSION_NOTICE/CRITICAL] → tell user about update

v0.4.74

---

⚠️ IMPORTANT: No Hooks Available ⚠️

This editor does NOT have hooks to enforce ContextStream behavior. You MUST follow these rules manually - there is no automatic enforcement.

---

🚀 SESSION START PROTOCOL

On EVERY new session, you MUST:

1. Call init(folder_path="<project_path>") FIRST

   • This triggers project indexing
   • Check response for indexing_status
   • If "started" or "refreshing": wait before searching

2. Generate a unique session_id (e.g., "session-" + timestamp or a UUID)

   • Use this SAME session_id for ALL context() calls in this conversation
   • This groups all turns together in the transcript

3. Call context(user_message="<first_message>", save_exchange=true, session_id="<your-session-id>")

   • Gets task-specific rules, lessons, and preferences
   • Check for [LESSONS_WARNING] - past mistakes to avoid
   • Check for [PREFERENCE] - user preferences to follow
   • Check for [RULES_NOTICE] - update rules if needed
   • save_exchange=true saves each conversation turn for later retrieval

4. Default behavior: call context(...) first on each message. Narrow bypass is allowed only for immediate read-only ContextStream calls when previous context is still fresh and no state-changing tool has run.

---

💾 AUTOMATIC TRANSCRIPT SAVING (CRITICAL)

This editor does NOT have hooks to auto-save transcripts. You MUST save each conversation turn manually:

On MOST messages (including the first):

context(user_message="<user's message>", save_exchange=true, session_id="<session-id>")

Why save_exchange matters:

• Transcripts enable searching past conversations
• Allows context restoration after compaction
• Provides conversation history for debugging
• Required for the Transcripts page in the dashboard

Session ID Guidelines:

• Generate ONCE at the start of the conversation
• Use a unique identifier: "session-" + Date.now() or a UUID
• Keep the SAME session_id for ALL context() calls in this session
• Different sessions = different transcripts

---

📁 FILE INDEXING (CRITICAL)

There is NO automatic file indexing in this editor. You MUST manage indexing manually:

After Creating/Editing Files:

project(action="index")  # Re-index entire project

For Single File Updates:

project(action="ingest_local", path="<file_path>")

Signs You Need to Re-index:

• Search doesn't find code you just wrote
• Search returns old versions of functions
• New files don't appear in search results

Best Practice:

After completing a feature or making multiple file changes, ALWAYS run:

project(action="index")

---

🔍 SEARCH-FIRST (No PreToolUse Hook)

There is NO hook to block local tools (Glob/Grep/Read/Explore/Task/EnterPlanMode). You MUST self-enforce:

Before ANY Search, Check Index Status:

project(action="index_status")

This tells you:

• indexed: true/false - is project indexed?
• last_indexed_at: timestamp - when was it last indexed?
• file_count: number - how many files indexed?

Search Protocol:

IF project is indexed and fresh:

search(mode="auto", query="what you're looking for")

→ Use this instead of Explore/Task/EnterPlanMode for file discovery.

IF project is NOT indexed or very stale (>7 days): → Wait up to ~20s for background refresh, retry search(mode="auto", ...), then allow local tools only after the grace window → OR run project(action="index") first, then search

IF ContextStream search still returns 0 results or errors after retry/window: → Use local tools (Glob/Grep/Read) as fallback

Choose Search Mode Intelligently:

• auto (recommended): query-aware mode selection
• hybrid: mixed semantic + keyword retrieval for broad discovery
• semantic: conceptual questions ("how does X work?")
• keyword: exact text / quoted string
• pattern: glob or regex (*.ts, foo\s+bar)
• refactor: symbol usage / rename-safe lookup
• exhaustive: all occurrences / complete match coverage
• team: cross-project team search

Output Format Hints:

• Use output_format="paths" for file listings and rename targets
• Use output_format="count" for "how many" queries

Two-Phase Search Pattern (for precision):

• Pass 1 (discovery): search(mode="auto", query="<concept + module>", output_format="paths", limit=10)
• Pass 2 (precision): use one of:
  • exact text/symbol: search(mode="keyword", query="\"exact_text\"", include_content=true)
  • symbol usage: search(mode="refactor", query="SymbolName", output_format="paths")
  • all occurrences: search(mode="exhaustive", query="symbol_or_text")
• Then use local Read/Grep only on paths returned by ContextStream.

When Local Tools Are OK:

✅ Stale/not-indexed grace window has elapsed (~20s default, configurable) ✅ ContextStream search still returns 0 results after retry ✅ ContextStream returns errors ✅ User explicitly requests local tools

When to Use ContextStream Search:

✅ Project is indexed and fresh ✅ Looking for code by meaning/concept ✅ Need semantic understanding

---

💾 CONTEXT COMPACTION (No PreCompact Hook)

There is NO automatic state saving before compaction. You MUST save state manually when the conversation gets long:

When to Save State:

• After completing a major task
• Before the conversation might be compacted
• If context() returns context_pressure.level: "high"

How to Save State:

session(action="capture", event_type="session_snapshot",
  title="Session checkpoint",
  content="{ \"summary\": \"what we did\", \"active_files\": [...], \"next_steps\": [...] }")

After Compaction (if context seems lost):

init(folder_path="...", is_post_compact=true)

This restores the most recent snapshot.

---

📋 PLANS & TASKS (No EnterPlanMode)

Always use ContextStream for planning:

session(action="capture_plan", title="...", steps=[...])
memory(action="create_task", title="...", plan_id="...")

❌ DO NOT use built-in plan mode (EnterPlanMode) or Task(subagent_type="Explore") for file-by-file scans. ✅ For planning discovery, use search(mode="auto", query="...", output_format="paths") then read only narrowed files.

---

🔄 VERSION UPDATES (Check Periodically)

This editor does NOT have hooks to check for updates automatically. You should check for updates using help(action="version") periodically (e.g., at session start).

If the response includes [VERSION_NOTICE] or [VERSION_CRITICAL]:

Tell the user about the available update in a helpful, non-annoying way:

• Frame it as "new features and improvements available"
• Provide the update commands (user can choose their preferred method)
• Don't nag repeatedly - mention once, then only if user asks

Update Commands (provide all options):

macOS/Linux:

curl -fsSL https://contextstream.io/scripts/setup.sh | bash

Windows (PowerShell):

irm https://contextstream.io/scripts/setup.ps1 | iex

npm (requires Node.js 18+):

npm install -g @contextstream/mcp-server@latest

After updating, user should restart their AI tool.

---