mirror of
https://github.com/tiennm99/serena.git
synced 2026-10-15 04:18:56 +00:00
Merge remote-tracking branch 'origin/main' into query-project-tool
Conflicts: src/serena/agent.py src/serena/project.py
This commit is contained in:
Dominik Jain authored and Dominik Jain committed
commit
8f3a31768e
66 files changed
+3090
-1351
No files matched your search
@@ -30,7 +30,7 @@ Some languages require additional installations or setup steps, as noted.
|
||||
* **AL**
|
||||
* **Bash**
|
||||
* **C#**
|
||||
(by default, uses the Roslyn language server (language `csharp`), requires `pwsh` ([PowerShell 7+](https://learn.microsoft.com/en-us/powershell/scripting/install/install-powershell-on-windows?view=powershell-7.5)) on Windows;
|
||||
(by default, uses the Roslyn language server (language `csharp`), requiring [.NET v10+](https://dotnet.microsoft.com/en-us/download/dotnet) and, on Windows, `pwsh` ([PowerShell 7+](https://learn.microsoft.com/en-us/powershell/scripting/install/install-powershell-on-windows?view=powershell-7.5));
|
||||
set language to `csharp_omnisharp` to use OmiSharp instead)
|
||||
* **C/C++**
|
||||
(by default, uses the clangd language server (language `cpp`) but we also support ccls (language `cpp_ccls`);
|
||||
@@ -45,15 +45,19 @@ Some languages require additional installations or setup steps, as noted.
|
||||
* **Erlang**
|
||||
(requires installation of beam and [erlang_ls](https://github.com/erlang-ls/erlang_ls); experimental, might be slow or hang)
|
||||
* **F#**
|
||||
(requires .NET SDK 8.0+; uses FsAutoComplete/Ionide, which is auto-installed; for Homebrew .NET on macOS, set DOTNET_ROOT in your environment)
|
||||
(requires [.NET v8.0+](https://dotnet.microsoft.com/en-us/download/dotnet); uses FsAutoComplete/Ionide, which is auto-installed; for Homebrew .NET on macOS, set DOTNET_ROOT in your environment)
|
||||
* **Fortran**
|
||||
(requires installation of fortls: `pip install fortls`)
|
||||
* **Go**
|
||||
(requires installation of `gopls`)
|
||||
* **Groovy**
|
||||
(requires local groovy-language-server.jar setup via `GROOVY_LS_JAR_PATH` or configuration)
|
||||
* **Haskell**
|
||||
* **Haskell**
|
||||
(automatically locates HLS via ghcup, stack, or system PATH; supports Stack and Cabal projects)
|
||||
* **HLSL / GLSL / WGSL**
|
||||
(uses [shader-language-server](https://github.com/antaalt/shader-sense) (language `hlsl`); automatically downloaded;
|
||||
on macOS, requires Rust toolchain for building from source;
|
||||
note: reference search is not supported by this language server)
|
||||
* **Java**
|
||||
* **JavaScript**
|
||||
* **Julia**
|
||||
@@ -64,6 +68,8 @@ Some languages require additional installations or setup steps, as noted.
|
||||
(must explicitly enable language `markdown`, primarily useful for documentation-heavy projects)
|
||||
* **Nix**
|
||||
(requires nixd installation)
|
||||
* **OCaml**
|
||||
(requires opam and ocaml-lsp-server to be installed manually; see the [OCaml Setup Guide](../03-special-guides/ocaml_setup_guide_for_serena.md))
|
||||
* **Pascal**
|
||||
(uses Pascal/Lazarus, which is automatically downloaded; set `PP` and `FPCDIR` environment variables for source navigation)
|
||||
* **Perl**
|
||||
@@ -96,7 +102,8 @@ see Serena's [memory on that](https://github.com/oraios/serena/blob/main/.serena
|
||||
As an alternative to language servers, the [Serena JetBrains Plugin](https://plugins.jetbrains.com/plugin/28946-serena/)
|
||||
leverages the powerful code analysis capabilities of JetBrains IDEs.
|
||||
The plugin naturally supports all programming languages and frameworks that are supported by JetBrains IDEs,
|
||||
including IntelliJ IDEA, PyCharm, Android Studio, AppCode, WebStorm, PhpStorm, RubyMine, GoLand, AppCode, CLion, and others.
|
||||
including IntelliJ IDEA, PyCharm, Android Studio, WebStorm, PhpStorm, RubyMine, GoLand, and potentially others
|
||||
(Rider and CLion are unsupported though).
|
||||
|
||||
When using the plugin, Serena connects to an instance of your JetBrains IDE via the plugin. For users who already
|
||||
work in a JetBrains IDE, this means Serena seamlessly integrates with the IDE instance you typically have open anyway,
|
||||
|
||||
@@ -103,22 +103,12 @@ By default, Serena will perform an **onboarding process** when
|
||||
it is started for the first time for a project.
|
||||
The goal of the onboarding is for Serena to get familiar with the project
|
||||
and to store memories, which it can then draw upon in future interactions.
|
||||
If an LLM should fail to complete the onboarding and does not actually write the
|
||||
respective memories to disk, you may need to ask it to do so explicitly.
|
||||
|
||||
The onboarding will usually read a lot of content from the project, thus filling
|
||||
up the context. It can therefore be advisable to switch to another conversation
|
||||
once the onboarding is complete.
|
||||
After the onboarding, we recommend that you have a quick look at the memories and,
|
||||
if necessary, edit them or add additional ones.
|
||||
In general, **memories** provide a way for Serena to store and retrieve
|
||||
information about the project, relevant conventions, and other relevant aspects.
|
||||
|
||||
**Memories** are files stored in `.serena/memories/` in the project directory,
|
||||
which the agent can choose to read in subsequent interactions.
|
||||
Feel free to read and adjust them as needed; you can also add new ones manually.
|
||||
Every file in the `.serena/memories/` directory is a memory file.
|
||||
Whenever Serena starts working on a project, the list of memories is
|
||||
provided, and the agent can decide to read them.
|
||||
We found that memories can significantly improve the user experience with Serena.
|
||||
For more information on this, including how to manage
|
||||
or disable these features, see [Memories & Onboarding](045_memories).
|
||||
|
||||
|
||||
## Preparing Your Project
|
||||
|
||||
@@ -0,0 +1,84 @@
|
||||
# Memories & Onboarding
|
||||
|
||||
Serena provides the functionality of a fully featured agent, and a useful aspect of this is Serena's memory system.
|
||||
Despite its simplicity, we received positive feedback from many users who tend to combine it with their
|
||||
agent's internal memory management (e.g., `AGENTS.md` files).
|
||||
|
||||
## Memories
|
||||
|
||||
Memories are simple, human-readable Markdown files that both you and
|
||||
your agent can create, read, and edit.
|
||||
|
||||
Serena differentiates between
|
||||
* **project-specific memories**, which are stored in the `.serena/memories/` directory within your project folder, and
|
||||
* **global memories**, which are shared across all projects and, by default, are stored in `~/.serena/memories/global/`
|
||||
|
||||
The LLM is informed about the existence of memories and instructed to read them when appropriate,
|
||||
inferring appropriateness from the file name.
|
||||
When the agent starts working on a project, it receives the list of available memories.
|
||||
The agent should be instructed to update memories by the user when appropriate.
|
||||
|
||||
### Organizing Memories
|
||||
|
||||
Memories can be organized into **topics** by using `/` in the memory name (e.g. `modules/frontend`).
|
||||
The structure is mapped to the file system, where topics correspond to subdirectories.
|
||||
The `list_memories` tool can filter by topic, allowing the agent to explore even large numbers of memories in a structured way.
|
||||
|
||||
(global-memories)=
|
||||
### Global Memories
|
||||
|
||||
Global memories use the top-level topic `global`, i.e. whenever a memory name starts with `global/`,
|
||||
it is stored in the global memories directory and is shared across all projects.
|
||||
|
||||
By default, deletion and editing of global memories is allowed.
|
||||
If you want to primarily manage such memories yourself and protect them from accidental modification by the agent,
|
||||
set `edit_global_memories: False` in Serena's [global configuration](050_configuration).
|
||||
|
||||
Since global memories are not versioned alongside your project files,
|
||||
it can be helpful to track global memories with git (i.e. to make `~/.serena/memories/` a git repository)
|
||||
in order to have a history of changes and the possibility to revert them if needed.
|
||||
|
||||
### Manually Editing Memories
|
||||
|
||||
You may edit memories directly in the file system, using your preferred text editor or IDE.
|
||||
Alternatively, access them via the [Serena Dashboard](060_dashboard), which provides a graphical interface for
|
||||
viewing, creating, editing, and deleting memories while Serena is running.
|
||||
|
||||
(onboarding)=
|
||||
## Onboarding
|
||||
|
||||
By default, Serena performs an **onboarding process** when it encounters a project
|
||||
for the first time (i.e., when no project memories exist yet).
|
||||
The goal of the onboarding is for Serena to get familiar with the project —
|
||||
its structure, build system, testing setup, and other essential aspects —
|
||||
and to store this knowledge as memories for future interactions.
|
||||
|
||||
In further project activations, Serena will check whether onboarding was already
|
||||
performed by looking for existing project memories and will skip the onboarding
|
||||
process if memories are found.
|
||||
|
||||
### How Onboarding Works
|
||||
|
||||
1. When a project is activated, Serena checks whether onboarding was already
|
||||
performed (by checking if any memories exist).
|
||||
2. If no memories are found, Serena triggers the onboarding process, which
|
||||
reads key files and directories to understand the project.
|
||||
3. The gathered information is written into project-specific memory files (see above).
|
||||
|
||||
### Tips for Onboarding
|
||||
|
||||
- **Context usage**: The onboarding process will read a lot of content from the project,
|
||||
filling up the context window. It is therefore advisable to **switch to a new conversation**
|
||||
once the onboarding is complete.
|
||||
- **LLM failures**: If an LLM fails to complete the onboarding and does not actually
|
||||
write the respective memories to disk, you may need to ask it to do so explicitly.
|
||||
- **Review the results**: After onboarding, we recommend having a quick look at the
|
||||
generated memories and editing them or adding new ones as needed.
|
||||
|
||||
## Disabling Memories and Onboarding
|
||||
|
||||
If you do not require the functionality described in this section, you can selectively disable it.
|
||||
|
||||
* To disable all memory related tools (including onboarding), adding `no-memories` to the `base_modes`
|
||||
in Serena's [global configuration](050_configuration).
|
||||
* Similarly, to disable only onboarding, add `no-onboarding` to the `base_modes`.
|
||||
@@ -0,0 +1,88 @@
|
||||
# OCaml Setup Guide for Serena
|
||||
|
||||
This guide explains how to set up an OCaml project so that Serena can provide code intelligence via ocaml-lsp-server (ocamllsp).
|
||||
|
||||
Unlike some other languages, Serena does not download the OCaml language server automatically. You must install it yourself via opam, as OCaml tooling is compiled from source against your specific environment.
|
||||
|
||||
---
|
||||
## Prerequisites
|
||||
|
||||
Install the following on your system and ensure they are available on `PATH`:
|
||||
|
||||
- **opam** (OCaml package manager)
|
||||
- macOS: `brew install opam`
|
||||
- Ubuntu/Debian: `sudo apt install opam`
|
||||
- Fedora: `sudo dnf install opam`
|
||||
- Other: https://opam.ocaml.org/doc/Install.html
|
||||
- **OCaml compiler** (via opam)
|
||||
- OCaml < 5.1 or >= 5.1.1 (OCaml 5.1.0 is **not supported** by ocaml-lsp-server)
|
||||
- Recommended: OCaml 4.14.x (stable) or 5.2+ (for cross-file references)
|
||||
- **ocaml-lsp-server** (via opam)
|
||||
- **dune** (build system, via opam)
|
||||
|
||||
---
|
||||
## Installation
|
||||
|
||||
1. Initialize opam if you haven't already:
|
||||
```bash
|
||||
opam init
|
||||
eval $(opam env)
|
||||
```
|
||||
|
||||
2. Create an opam switch with a compatible OCaml version:
|
||||
```bash
|
||||
# For cross-file reference support (recommended)
|
||||
opam switch create serena-ocaml ocaml-base-compiler.5.2.1
|
||||
eval $(opam env)
|
||||
|
||||
# Or for stable OCaml 4.14.x
|
||||
opam switch create serena-ocaml ocaml-base-compiler.4.14.2
|
||||
eval $(opam env)
|
||||
```
|
||||
|
||||
3. Install the language server and build tools:
|
||||
```bash
|
||||
opam install ocaml-lsp-server dune
|
||||
```
|
||||
|
||||
4. Verify the installation:
|
||||
```bash
|
||||
opam exec -- ocamllsp --version
|
||||
opam exec -- ocaml -version
|
||||
```
|
||||
|
||||
---
|
||||
## Cross-File References
|
||||
|
||||
Cross-file reference support (finding all usages of a symbol across your project) requires:
|
||||
|
||||
- OCaml >= 5.2
|
||||
- ocaml-lsp-server >= 1.23.0
|
||||
- dune >= 3.16.0
|
||||
|
||||
When these requirements are met, Serena automatically builds the cross-file index during startup via `dune build @ocaml-index`. Without these versions, references are limited to the current file.
|
||||
|
||||
---
|
||||
## Using Serena with OCaml
|
||||
|
||||
- Serena automatically detects OCaml files (`*.ml`, `*.mli`) and Reason files (`*.re`, `*.rei`).
|
||||
- The language server is started via `opam exec -- ocamllsp`, so your opam environment must be configured.
|
||||
- Ensure your project builds successfully with `dune build` before using Serena for best results.
|
||||
|
||||
---
|
||||
## Troubleshooting
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| "opam not found" | Install opam and add it to PATH |
|
||||
| "OCaml 5.1.0 is incompatible" | Create a new switch: `opam switch create <name> ocaml-base-compiler.5.2.1` |
|
||||
| "ocaml-lsp-server not found" | `opam install ocaml-lsp-server` |
|
||||
| Cross-file refs not working | Ensure OCaml >= 5.2 and ocaml-lsp-server >= 1.23.0; run `dune build` first |
|
||||
| Stale index | Rebuild with `dune build @ocaml-index` |
|
||||
|
||||
---
|
||||
## Reference
|
||||
|
||||
- opam: https://opam.ocaml.org
|
||||
- ocaml-lsp-server: https://github.com/ocaml/ocaml-lsp
|
||||
- Project-wide occurrences: https://discuss.ocaml.org/t/ann-project-wide-occurrences-in-merlin-and-lsp/14847
|
||||
Reference in new issue
Block a user