Skip to content

Commit 2dbd674

Browse files
committed
docs: 更新 README 並新增中文版說明與 Serena 配置
- 更新 README.md:詳列技術棧、核心領域以及與 MCP/libSQL 的差異。 - 新增 README.zh-TW.md:提供正體中文版本的專案說明。 - 新增 CLAUDE.md:定義開發代理(Agent)的指導方針與專案規則。 - 新增 .serena/project.yml:配置 Serena 工具的專案設定,包含 TypeScript 支援。 - 新增 .serena/.gitignore:忽略 Serena 快取與本地設定檔。
1 parent e22753d commit 2dbd674

5 files changed

Lines changed: 593 additions & 147 deletions

File tree

.serena/.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
/cache
2+
/project.local.yml

.serena/project.yml

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# the name by which the project can be referenced within Serena
2+
project_name: "Memoria"
3+
4+
5+
# list of languages for which language servers are started; choose from:
6+
# al angular ansible bash clojure
7+
# cpp cpp_ccls crystal csharp csharp_omnisharp
8+
# dart elixir elm erlang fortran
9+
# fsharp go groovy haskell haxe
10+
# hlsl html java json julia
11+
# kotlin lean4 lua luau markdown
12+
# matlab msl nix ocaml pascal
13+
# perl php php_phpactor powershell python
14+
# python_jedi python_ty r rego ruby
15+
# ruby_solargraph rust scala scss solidity
16+
# svelte swift systemverilog terraform toml
17+
# typescript typescript_vts vue yaml zig
18+
# (This list may be outdated. For the current list, see values of Language enum here:
19+
# https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
20+
# For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
21+
# Note:
22+
# - For C, use cpp
23+
# - For JavaScript, use typescript
24+
# - For Angular projects, use angular (subsumes typescript+html; requires `npm install` in the project root)
25+
# - For Svelte projects, use svelte (subsumes typescript/javascript for .svelte projects; requires npm)
26+
# - For SCSS / Sass / plain CSS, use scss (some-sass-language-server handles all three)
27+
# - For Free Pascal/Lazarus, use pascal
28+
# Special requirements:
29+
# Some languages require additional setup/installations.
30+
# See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
31+
# When using multiple languages, the first language server that supports a given file will be used for that file.
32+
# The first language is the default language and the respective language server will be used as a fallback.
33+
# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
34+
languages:
35+
- typescript
36+
37+
# the encoding used by text files in the project
38+
# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
39+
encoding: "utf-8"
40+
41+
# line ending convention to use when writing source files.
42+
# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
43+
# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
44+
line_ending:
45+
46+
# The language backend to use for this project.
47+
# If not set, the global setting from serena_config.yml is used.
48+
# Valid values: LSP, JetBrains
49+
# Note: the backend is fixed at startup. If a project with a different backend
50+
# is activated post-init, an error will be returned.
51+
language_backend:
52+
53+
# whether to use project's .gitignore files to ignore files
54+
ignore_all_files_in_gitignore: true
55+
56+
# advanced configuration option allowing to configure language server-specific options.
57+
# Maps the language key to the options.
58+
# Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available.
59+
# No documentation on options means no options are available.
60+
ls_specific_settings: {}
61+
62+
# list of additional workspace folder paths for cross-package reference support (e.g. in monorepos).
63+
# Paths can be absolute or relative to the project root.
64+
# Each folder is registered as an LSP workspace folder, enabling language servers to discover
65+
# symbols and references across package boundaries.
66+
# Currently supported for: TypeScript.
67+
# Example:
68+
# additional_workspace_folders:
69+
# - ../sibling-package
70+
# - ../shared-lib
71+
additional_workspace_folders: []
72+
73+
# list of additional paths to ignore in this project.
74+
# Same syntax as gitignore, so you can use * and **.
75+
# Note: global ignored_paths from serena_config.yml are also applied additively.
76+
ignored_paths: []
77+
78+
# whether the project is in read-only mode
79+
# If set to true, all editing tools will be disabled and attempts to use them will result in an error
80+
# Added on 2025-04-18
81+
read_only: false
82+
83+
# list of tool names to exclude.
84+
# This extends the existing exclusions (e.g. from the global configuration)
85+
# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
86+
excluded_tools: []
87+
88+
# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
89+
# This extends the existing inclusions (e.g. from the global configuration).
90+
# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
91+
included_optional_tools: []
92+
93+
# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
94+
# This cannot be combined with non-empty excluded_tools or included_optional_tools.
95+
# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
96+
fixed_tools: []
97+
98+
# list of mode names that are to be activated by default, overriding the setting in the global configuration.
99+
# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
100+
# If the setting is undefined/empty, the default_modes from the global configuration (serena_config.yml) apply.
101+
# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
102+
# Therefore, you can set this to [] if you do not want the default modes defined in the global config to apply
103+
# for this project.
104+
# This setting can, in turn, be overridden by CLI parameters (--mode).
105+
# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
106+
default_modes:
107+
108+
# list of mode names to be activated additionally for this project, e.g. ["query-projects"]
109+
# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
110+
# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
111+
added_modes:
112+
113+
# initial prompt for the project. It will always be given to the LLM upon activating the project
114+
# (contrary to the memories, which are loaded on demand).
115+
initial_prompt: ""
116+
117+
# time budget (seconds) per tool call for the retrieval of additional symbol information
118+
# such as docstrings or parameter information.
119+
# This overrides the corresponding setting in the global configuration; see the documentation there.
120+
# If null or missing, use the setting from the global configuration.
121+
symbol_info_budget:
122+
123+
# list of regex patterns which, when matched, mark a memory entry as read‑only.
124+
# Extends the list from the global configuration, merging the two lists.
125+
read_only_memory_patterns: []
126+
127+
# list of regex patterns for memories to completely ignore.
128+
# Matching memories will not appear in list_memories or activate_project output
129+
# and cannot be accessed via read_memory or write_memory.
130+
# To access ignored memory files, use the read_file tool on the raw file path.
131+
# Extends the list from the global configuration, merging the two lists.
132+
# Example: ["_archive/.*", "_episodes/.*"]
133+
ignored_memory_patterns: []

CLAUDE.md

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Snapshot
6+
7+
Memoria is a TypeScript CLI + HTTP service that gives AI agents cross-session persistent memory. Runtime is Node.js (≥18, CI uses Node 22) with `better-sqlite3` and `zod`. Package manager is **pnpm** (lockfile is authoritative). ESM-only (`"type": "module"`), TS strict mode.
8+
9+
`AGENTS.md` is the long-form agent guide — read it for HTTP API, bootstrap flow, and code-style detail. `package.json` scripts and `.github/workflows/ci.yml` are the source of truth for commands; if local docs disagree with CI, follow CI.
10+
11+
## Common Commands
12+
13+
```bash
14+
pnpm install # install deps (use pnpm, not npm/yarn)
15+
pnpm run check # tsc --noEmit (primary static check)
16+
pnpm run build # esbuild bundle -> dist/cli.mjs
17+
pnpm run memoria -- --help # run CLI in dev via tsx
18+
./cli <command> # same entrypoint, shorter
19+
node dist/cli.mjs --help # smoke-check the production bundle
20+
bash -n install.sh # syntax-check the installer
21+
```
22+
23+
## Tests
24+
25+
There is **no unit-test framework** (no Jest/Vitest). All tests are bash scripts under `scripts/` that exercise the CLI end-to-end. To run a single flow, invoke its script directly:
26+
27+
```bash
28+
bash scripts/test-smoke.sh # CLI full flow (most common)
29+
bash scripts/test-bootstrap.sh # ./cli setup self-install
30+
bash scripts/test-adapter-runtime.sh # adapter ESM runtime
31+
bash scripts/test-no-clone-install.sh # install.sh from release tarball
32+
bash scripts/test-mcp-e2e.sh # MCP/libSQL hybrid + incremental
33+
bash scripts/test-wiki-ingest.sh # raw source ingest
34+
bash scripts/test-wiki-build.sh # compiled wiki special pages
35+
bash scripts/test-wiki-query-fileback.sh # query file-back
36+
bash scripts/test-wiki-lint.sh # wiki governance lint
37+
```
38+
39+
CI runs these in the order listed in `.github/workflows/ci.yml`. Mirror that order locally before opening a PR.
40+
41+
For ad-hoc verification of a CLI flow without running full smoke:
42+
43+
```bash
44+
TMP=$(mktemp -d); MEMORIA_HOME="$TMP" ./cli init
45+
MEMORIA_HOME="$TMP" ./cli sync examples/session.sample.json
46+
```
47+
48+
## Architecture
49+
50+
The CLI (`src/cli.ts`, ~350 lines) is a thin Commander shell. **All business logic lives in `src/core/`**, accessible to CLI, HTTP server, and SDK alike:
51+
52+
- `core/memoria.ts``MemoriaCore` class, the public API surface
53+
- `core/db.ts` — all SQLite operations (open/close lifecycle in `try/finally`)
54+
- `core/types.ts``MemoriaResult<T>` envelope, `RecallFilter`, etc.
55+
- `core/paths.ts``resolveMemoriaPaths()`, `getMemoriaHome()`
56+
- `core/source-import.ts` — raw markdown/text ingestion
57+
- `core/wiki.ts` / `wiki-build.ts` / `wiki-query.ts` / `wiki-lint.ts` — compiled wiki pipeline (`index`/`log`/`overview` special pages, `synthesis`/`comparison` file-back, durable lint findings)
58+
- `core/index.ts` — unified re-export (import from here, not deep paths, when adding callers)
59+
60+
Three entrypoints consume `core/`:
61+
62+
- `src/cli.ts` — Commander CLI (`./cli`)
63+
- `src/server.ts` — HTTP API on `node:http` (zero extra deps), default port 3917, env `MEMORIA_PORT`
64+
- `src/sdk.ts``MemoriaClient` Node SDK
65+
66+
Adapters (`src/adapter/`) extend `BaseAdapter` to wire Memoria into specific agent runtimes (Gemini, OpenCode).
67+
68+
**Every public API returns `MemoriaResult<T>`** with `evidence[]`, `confidence`, `latency_ms`. Preserve this envelope when adding new endpoints/methods.
69+
70+
### Persistence Layout
71+
72+
`MEMORIA_HOME` (defaults to repo root, overridable; `MEMORIA_DB_PATH` / `MEMORIA_SESSIONS_PATH` / `MEMORIA_CONFIG_PATH` override individual paths). SQLite is the source of truth; markdown files under `<home>/memoria/` are derived/synced views. `initDatabase()` patches older DBs in place — keep schema changes backward-compatible.
73+
74+
### Recall
75+
76+
`recall()` supports `keyword | tree | hybrid` modes with an adaptive gate that skips trivial queries. Hits are ranked by relevance × time-decay (halfLife = 90 days). Telemetry rows are exposed via `recallTelemetry({ window, limit })` and `GET /v1/telemetry/recall`.
77+
78+
## Conventions That Are Easy to Get Wrong
79+
80+
- **Don't rename CLI commands** (`init`, `sync`, `stats`, `doctor`, `verify`, `index`, `source`, `wiki`, `govern`, `prune`, `export`, `serve`, `preflight`, `setup`) without an explicit request — they are part of the agent contract.
81+
- **`prune --all`** includes consolidate (90d) + stale (180d) by default. Use `--consolidate-days` / `--stale-days` for custom thresholds; don't change defaults silently.
82+
- **Schema changes** must keep older DBs readable (see existing patch pattern in `initDatabase()`); add migrations rather than breaking columns.
83+
- **Validate at boundaries** with Zod (`unknown` → parse), not deep inside core logic.
84+
- **DB lifecycle**: every code path that opens the DB must close it in `try/finally`.
85+
- **Don't add tooling** (linters, formatters, test frameworks, runtime deps) unless asked — this repo deliberately stays lean. Current deps: `better-sqlite3`, `commander`, `zod`.
86+
- **MCP/libSQL is optional**, gated by `LIBSQL_URL`. Memoria-only must remain a fully functional mode.
87+
- **ESM imports only**. Use `node:fs/promises` for async fs and `path.join/resolve` for paths.
88+
- **Sample files** (e.g. `examples/session.sample.json`) are consumed by both docs and tests — update all readers if the schema changes.
89+
90+
## Definition of Done
91+
92+
1. `pnpm run check` passes.
93+
2. `pnpm run build` succeeds and `node dist/cli.mjs --help` runs.
94+
3. For flow changes: relevant `scripts/test-*.sh` passes.
95+
4. Touched shell scripts pass `bash -n`.
96+
5. CLI flags/output remain consistent with existing UX.

0 commit comments

Comments
 (0)