Feature Request: Memory System - Persistent context across sessions

What feature would you like to see?

Implement a comprehensive Memory System that allows Kimi Code CLI to remember useful context, project patterns, and user preferences across sessions. This includes both automatic memory (AI-managed notes) and manual memory (user-defined instructions via configuration files).

Additional information

Motivation

Currently, each Kimi Code CLI session starts fresh with no knowledge of:

• Project-specific patterns and conventions
• User preferences for coding style and workflow
• Previous debugging insights or solutions
• Common commands and project structure

A memory system would significantly improve productivity by:

• Reducing repetitive explanations of project context
• Maintaining consistency across sessions
• Preserving learned insights about the codebase
• Personalizing the experience to individual users

Proposed Memory Hierarchy

Memory Type	Location	Purpose	Use Case Examples	Shared With
Managed policy	System-wide (/etc/kimi/AGENTS.md or equivalent)	Organization-wide instructions	Company coding standards, security policies	All users in organization
Project memory	./AGENTS.md or ./.kimi/AGENTS.md	Team-shared project instructions	Project architecture, coding standards, workflows	Team members via source control
Project rules	./.kimi/rules/*.md	Modular, topic-specific instructions	Language-specific guidelines, testing conventions	Team members via source control
User memory	~/.kimi/AGENTS.md	Personal preferences for all projects	Code styling preferences, personal shortcuts	Just you (all projects)
Local project memory	./AGENTS.local.md	Personal project-specific preferences	Sandbox URLs, preferred test data	Just you (current project)
Auto memory	~/.kimi/projects/<project>/memory/	AI's automatic notes and learnings	Project patterns, debugging insights	Just you (per project)

Detailed Design

1. Manual Memory (AGENTS.md files)

Users create and maintain markdown files with instructions, rules, and preferences.

File Locations (in order of precedence, most specific first)

./AGENTS.local.md                    # Personal, project-specific (gitignored)
./AGENTS.md or ./.kimi/AGENTS.md     # Project-level, shared
~/.kimi/AGENTS.md                     # User-level, all projects
/etc/kimi/AGENTS.md                   # Organization-level (Linux)
/Library/Application Support/Kimi/AGENTS.md  # Organization-level (macOS)

Example AGENTS.md

# Project Guidelines

## Build Commands
- Use `make build` for production builds
- Use `make dev` for development with hot reload
- Always run `make check` before committing

## Code Style
- 2-space indentation
- Max line length: 100 characters
- Use type hints for all function parameters

## Testing
- Run `pytest` before submitting PRs
- Target 80%+ code coverage
- Use pytest-asyncio for async tests

Modular Rules Directory (.kimi/rules/)

For larger projects, organize instructions into multiple files:

.kimi/
├── AGENTS.md
└── rules/
    ├── python.md          # Python-specific guidelines
    ├── testing.md         # Testing conventions
    ├── api.md             # API standards
    └── frontend.md        # Frontend guidelines

Rules can be path-specific using YAML frontmatter:

---
paths: ["**/*.py"]
---
# Python Rules
- Use type hints
- Follow PEP 8

2. Auto Memory (AI-Managed)

Kimi automatically saves notes and learnings as it works with a project.

Storage Location

~/.kimi/projects/<project-hash>/memory/
├── MEMORY.md           # Entry point and index
├── patterns.md         # Project patterns
├── debugging.md        # Debugging insights
└── preferences.md      # User preferences learned

The <project> path is derived from the git repository root. Git worktrees get separate memory directories.

What Kimi Remembers

• Project patterns: Build commands, test conventions, code style preferences
• Debugging insights: Solutions to tricky problems, common error causes
• Architecture notes: Key files, module relationships, important abstractions
• User preferences: Communication style, workflow habits, tool choices

MEMORY.md Structure

# Memory Index

## Patterns
- We use `uv` for Python package management
- Tests are in `tests/` directory with `test_*.py` naming
- See [patterns.md](patterns.md) for more

## Debugging
- Import errors often mean you need to run `make prepare` first
- See [debugging.md](debugging.md) for more

## Preferences
- User prefers concise responses
- User uses `ruff` for linting

Loading Behavior

• First 200 lines of MEMORY.md are loaded into system prompt at session start
• Topic files (e.g., debugging.md) are not loaded automatically; Kimi reads them on demand
• Kimi reads and writes memory files during the session

3. Commands

# Open memory file selector to view/edit any memory
/memory

# Ask Kimi to remember something specific
"Remember that we use pnpm, not npm"
"Save to memory that the API tests require a local Redis instance"

4. File Import Syntax

AGENTS.md files can import additional files using @path/to/import syntax:

# Project Guidelines

@../shared/company-standards.md
@.kimi/rules/python.md

Configuration

Enable/Disable Auto Memory

# Toggle via command
/memory

# Or in config.toml
[memory]
auto_memory_enabled = true

Environment Variable

# Disable auto memory (useful for CI)
export KIMI_DISABLE_AUTO_MEMORY=1

Best Practices

1. Be specific: "Use 2-space indentation" is better than "Format code properly"
2. Use structure: Format as bullet points under descriptive headings
3. Review periodically: Update memories as projects evolve
4. Keep MEMORY.md concise: Move detailed notes to topic files

Implementation Notes

Discovery Order

Kimi Code CLI reads memories recursively from current working directory up to (but not including) root:

1. Start at cwd, recurse upward
2. Read any AGENTS.md or AGENTS.local.md files found
3. Also discover AGENTS.md in subtrees under cwd (loaded on demand when accessing those files)

Precedence

More specific instructions take precedence over broader ones:
./AGENTS.local.md > ./AGENTS.md > ~/.kimi/AGENTS.md > Organization policy

Git Integration

• AGENTS.local.md should be automatically added to .gitignore
• Project-level AGENTS.md and .kimi/rules/ should be committed to source control

Future Enhancements

• Memory search: Search across all memory files
• Memory sharing: Share memory snippets with team members
• Memory versioning: Track changes to memory over time
• AI-suggested memories: Proactively suggest things to remember

Related Features

• AGENTS.md injection: Currently AGENTS.md is injected via KIMI_AGENTS_MD variable
• Agent specs: YAML specs under src/kimi_cli/agents/ could reference memory files

Additional Context

Reference implementation: Claude Code Memory

Start by reading the existing AGENTS.md injection via KIMI_AGENTS_MD and the agent specifications under src/kimi_cli/agents/. The proposal covers manual and automatic memory, discovery, precedence, commands, configuration, and persistence, so scope and implementation boundaries need maintainer clarification. Done would require the agreed memory behavior to work across sessions and its configuration and commands to be supported.