# Cyrene-Agent
**English** | [δΈζ](./README.md)
**Primary repo**: [GitHub](https://github.com/Playa-Cyrene/Cyrene-Agent) γ» **Mirror for China**: [Gitee](https://gitee.com/playa0/cyrene-agent)
# Cyrene-Agent
**English** | [δΈζ](./README.md)
**Primary repo**: [GitHub](https://github.com/Playa-Cyrene/Cyrene-Agent) γ» **Mirror for China**: [Gitee](https://gitee.com/playa0/cyrene-agent)
 |
 |
 |
 |
- **Driven by CyreneHarness** β Each message enters the while loop in [CyreneHarness](./src/main/orchestrator/harness/cyrene-harness.ts): every round calls the LLM β writes back the assistant message β dispatches tools β writes back tool results β checks uncertain effects β continues or ends. Pre-processors (CITA context understanding) run before the Harness entry; inside the loop, each round carries a compact execution persona ([`prompts/cyrene_harness.md`](./prompts/cyrene_harness.md)) that only governs expression style and never leaks into tool arguments β on conflict, "task correctness > clarity > Cyrene's style"; the full Soul persona layer generates the reply text after the Harness exit.
- **Free tool chaining** β Web search, webpage reading, file R/W, document generation, and lifestyle tools can be combined on demand; the model picks the next tool without pre-orchestrated flows.
- **Persona and workflow coexist** β Cyrene's character-driven reply is preserved alongside tool calls.
#### π» Code Collaboration (Code)
> [!WARNING]
>
> Code mode **does not yet include a built-in review / diff preview**. Once the Agent finishes editing a file, the change is written to disk immediately. It is recommended to open the bound directory in your preferred IDE or diff tool (VS Code, Cursor, JetBrains, SourceGit, etc.) so you can inspect and roll back any change at any time.
>
> Initializing Git is the safest fallback: after `git init && git add -A`, any change can be inspected with `git diff` and reverted with `git checkout -- .`
- **Code-specific tools on top of Work** β Reuses the [CyreneHarness](./src/main/orchestrator/harness/cyrene-harness.ts) main loop and registers extra code-focused tools (read/write/edit, command execution, LSP queries, etc.); permission approval (checkPermission) filters unsafe calls before tool execution, and Execution Policy decides whether to require a second user confirmation.
- **Trusted workspace binding** β All read/write, command execution, and LSP queries must stay inside the user-bound directory; the model cannot pick or change the workspace, and out-of-scope access (including `..` and symlink escapes) is rejected outright.
- **Semantic code queries (LSP)** β Code mode can query definitions, references, hover details, symbols, and diagnostics inside the bound workspace without modifying files.
- **User-managed servers** β Cyrene provides an LSP client only. It never bundles, downloads, upgrades, or silently installs language servers; install the services you need yourself, or explicitly ask Cyrene to assist through existing permission-controlled tools.
- **Security boundary** β Language server processes are spawned with `stdio: "pipe"`, `shell: false`, and `cwd` forced to the bound workspace. The model cannot specify a command, server ID, or workspace root.
- **Obsidian Vault Workspace** β Binds a Vault as the learning workspace, using the `materials/`, `notes/`, `exercises/`, `templates/`, and `learn/progress.md` structure. See the [Learn mode guide](docs/user-guide/learn-mode.md).
- **Built on RAG and personalized memory** β Learning materials are indexed through the [RAG knowledge base](#-rag-document-knowledge-base) for retrieval, while progress and preferences flow into the L2 long-term memory to stay continuous across sessions.
- **Accompanied Understanding** β Helps users understand materials through questions, breakdowns, analogies, and discussion rather than doing the learning for them.
- **Notes and Exercises** β Organizes concepts, generates exercises, and records reviews inside the Vault, automatically maintaining a learning-progress overview.
- **Respects the User's Pace** β Re-explains when the user is stuck, advances when the user is ready, and never scolds the user for wrong answers.
#### π Rich Text and Code Rendering
- **Markdown Rendering** β Supports headings, lists, blockquotes, tables, links, code blocks, and other common Markdown elements.
- **Syntax Highlighting** β Supports syntax highlighting and copy actions for multiple common programming languages.
- **Mathematical Formulas** β Supports inline and block-level formula rendering.
- **Streaming Compatibility** β Keeps output stable during generation and renders complete rich text after a message finishes.
#### π΅ Music Companion
- **Cyrene Music Window** β A dedicated built-in "Cyrene Music" player supporting playlist tabs, local caching, and playlist management.
- **NetEase Cloud Music Source** β Powered by the self-developed `NeteaseOpenapiProvider` calling the NetEase OpenAPI for song / artist / album search, daily recommendations, playlists, and favorites.
- **Bundled mpv Playback** β Controlled by `MpvController` driving the bundled mpv process for load, play, pause, seek, volume, and stop, without launching any external client.
- **Tool Chaining** β In `Work / Learn` modes, music tools can combine with others (web search, files, documents) to complete flows like "search β add to playlist β play".
- **Lazy Start with Graceful Degradation** β The music backend only establishes a network session on the first real music operation; a missing mpv never affects chat or other core features.
#### π§ Personalized Memory
- **L0 / L1 / L2 Layered Memory** β Separately manages core user profiles, recent state, and long-term experiences.
- **Memory Evidence Chain** β Memory entries retain their source and context to reduce unsupported profile inference.
- **Conflict Detection and Resolution** β Retrieves, scores, and semantically evaluates old and new memories to distinguish contextual differences, preference evolution, and direct conflict.
- **Self-Developed DMAE Worldbook** β Manages character knowledge and long-term interaction content through triggers, priority, intrinsic value, linked activation, and Active / Dormant / Archived states.
- **Relationship and Style Continuity** β Gradually develops user preferences, communication habits, and relationship context through long-term interaction.
#### π Voice Interaction
- **Multiple TTS Engines** β Supports Mossland, MiniMax, MiMo, GPT-SoVITS, and custom cloud-based speech services.
- **ASR** β Supports Alibaba Cloud real-time speech recognition and Mossland or MiniMax full-turn audio transcription after each utterance.
- **Complete Voice Calls** β Continuous voice interaction through the `LISTENING β THINKING β SPEAKING` state flow.
- **VAD Silence Detection** β Automatically detects when the user has stopped speaking and triggers a response.
#### π§° Tool Ecosystem
Cyrene includes many built-in and extensible tools, primarily covering the following categories:
- **Documents and Office Work** β Generate Word, Excel, PDF, and Markdown documents.
- **Web Capabilities** β Web search, webpage reading, content extraction, and information organization.
- **File Processing** β Read, write, and browse local files, as well as interpret images.
- **Everyday Services** β Weather, maps, translation, currency conversion, bookkeeping, trip planning, and more.
- **Music** β Search for songs, retrieve recommendations, and play through the bundled player.
- **Task Collaboration** β Task lists, user-choice cards, task delegation, and subtask handling.
- **MCP Extensions** β Connect additional external tools and services through the Model Context Protocol.