Kilo Code memory: what persists and what to add

What Kilo Code remembers between sessions

Custom instructions personalize how Kilo Code behaves, shaping responses, coding style and decision-making (Kilo Code docs). Per-agent prompts apply across all sessions using that agent, and project-level instructions apply to every session, so the guidance you set is there next time (Kilo Code docs).

Both the VSCode extension and the CLI support custom instructions, though the mechanisms differ (Kilo Code docs). The extension layers them: per-agent prompts in the Settings UI, instruction files auto-discovered in your project, and global config (Kilo Code docs).

Set a per-agent prompt

Each agent can have its own custom prompt, configured in the settings UI. The prompt is injected into the agent's system prompt and applies across all sessions that use that agent (Kilo Code docs).

This suits stable preferences, such as coding conventions or how you want answers formatted. For a wider look at steering agents with written context, see give your AI context.

Use AGENTS.md at the project root

Kilo Code automatically discovers instruction files at your project root and in parent directories (Kilo Code docs). AGENTS.md is the primary instruction file, CLAUDE.md is supported for compatibility, and CONTEXT.md provides additional project context. Any of these files at the project root gives project-wide instructions (Kilo Code docs).

Project-level instructions load before global instructions and apply to every session (Kilo Code docs). AGENTS.md files also work in subdirectories: one loads dynamically when the agent's Read tool accesses a file in that directory, and its contents are injected into the conversation. A subdirectory file supplements root instructions for tasks in that directory, so it does not need to repeat them (Kilo Code docs).

Global instructions for all projects

For instructions that apply across all projects, place an AGENTS.md file in the global config directory. In Kilo Code this is ~/.config/kilo/AGENTS.md (Kilo Code docs).

There is also a Claude-compatible global fallback at ~/.claude/CLAUDE.md, used until Claude Code Migration has been attempted. Attempting migration ends that fallback, while project-level CLAUDE.md files keep working (Kilo Code docs).

Add rule sources in kilo.jsonc

The instructions key in kilo.jsonc accepts an array of paths, globs or URLs pointing to extra instruction files. You manage these in Settings → Agent Behaviour → Rules (Kilo Code docs).

URL-based sources are fetched at session start with a 5-second timeout. If a URL is unreachable, the source is silently skipped (Kilo Code docs). Legacy .kilocoderules files from the VSCode extension are still loaded via auto-migration, and AGENTS.md is recommended for new projects (Kilo Code docs).

The limits to plan around

These features inject text into prompts. Per-agent prompts go into the system prompt, and instruction files load per session or on directory access (Kilo Code docs). The documented edges are concrete: URL rules have a 5-second timeout and are silently skipped when unreachable (Kilo Code docs), the ~/.claude/CLAUDE.md global fallback ends once Claude Code Migration is attempted (Kilo Code docs), and subdirectory files load only when the Read tool touches that directory (Kilo Code docs).

For material that accumulates, such as saved reading, decisions and playbooks, a separate library the agent can query is one way to handle it. KnowMan saves articles and links, reads and tags them, and keeps memories such as claims, decisions and playbooks (KnowMan). The broader pattern is covered in persistent memory for AI agents.

Where KnowMan fits

KnowMan saves articles and links, reads and tags them, answers questions with citations, and keeps memories such as claims, decisions and playbooks (KnowMan). Its MCP server is a local stdio server, package @knowman/mcp, started with npx -y @knowman/mcp on Node 22 or newer (KnowMan).

Through the server an agent gets tools including kb_search to search saved items by keyword or meaning, kb_ask to answer questions with citations, and kb_memories to read saved claims, decisions and playbooks (KnowMan). A practical split is to keep AGENTS.md for rules and preferences, and let KnowMan hold the growing library. KnowMan runs locally with npx -y @knowman/mcp and also as a hosted server at https://api.knowman.io/mcp, where you sign in with OAuth or send an API key (KnowMan). The general pattern is covered in an MCP server knowledge base, and the same idea applies to Claude Code.

Use the hosted KnowMan server in Kilo Code

KnowMan runs as a hosted server at https://api.knowman.io/mcp in addition to the local stdio server. In clients that support remote MCP servers you add the server URL and sign in with OAuth: the client opens the KnowMan consent page, you approve the requested scopes, and access tokens refresh automatically.

The alternative is an API key, created in your KnowMan settings, sent with each request as an Authorization: Bearer <key> header. Both paths expose the same six tools, from kb_search and kb_ask to kb_save, so the split between AGENTS.md rules and the KnowMan library stays the same.

The general remote-server pattern is described in an MCP server knowledge base. For the local server instead, run npx -y @knowman/mcp; the open-source client lives at knowman-mcp on GitHub.