Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
fc48974
feat(config): add openGauss configuration validation
SleepySuke Oct 26, 2026
2baecb2
feat(graph-db): add openGauss AGE node storage
SleepySuke Oct 29, 2026
026bb34
feat(graph-db): add scoped AGE relations and hard deletion
SleepySuke Oct 29, 2026
e37fca5
feat(graph-db): add bounded traversal and tag neighbors
SleepySuke Oct 29, 2026
86ef67b
feat(graph-db): unify openGauss storage and scoped filters
SleepySuke Oct 30, 2026
f4bfdb7
feat(graph-db): add openGauss vector and fulltext retrieval
SleepySuke Nov 2, 2026
2937106
feat(graph-db): add openGauss counts and capacity management
SleepySuke Nov 5, 2026
04d6637
feat: add openGauss structure optimization candidates
SleepySuke Nov 5, 2026
4a52f50
feat: export openGauss graphs from a consistent snapshot
SleepySuke Nov 5, 2026
2d43a57
feat: add atomic openGauss import and scoped clearing
SleepySuke Nov 5, 2026
9b9bec0
feat: add openGauss ownership and deletion records
SleepySuke Nov 5, 2026
2b1a9d7
feat: finalize openGauss context and capability contracts
SleepySuke Nov 5, 2026
c60b10b
test: verify openGauss batch deletion failure recovery
SleepySuke Nov 5, 2026
06112d7
feat: wire openGauss configuration and owned lifecycle
SleepySuke Nov 5, 2026
4515f9c
feat: support optional openGauss dashboard ranges
SleepySuke Nov 5, 2026
88dfa2e
fix: preserve complete openGauss file backups and restore errors
SleepySuke Nov 6, 2026
143e12e
fix: preserve Cube identity and propagate required search failures
SleepySuke Nov 6, 2026
7bfc8a1
feat: add openGauss LIKE and visible Feedback storage failures
SleepySuke Nov 6, 2026
e747c47
fix: simplify shutdown ownership and prevent worker self-close
SleepySuke Nov 6, 2026
cdd17dc
fix: persist distinct Working and graph memory pairs
SleepySuke Nov 6, 2026
e43c9d6
fix: address openGauss PR review regressions
SleepySuke Nov 7, 2026
62ea90c
chore: merge latest dev-v2.0.36 for PR validation
SleepySuke Nov 7, 2026
ad10805
docs: clarify Dashboard default Cube and scope conflicts
SleepySuke Nov 7, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 91 additions & 0 deletions docs/en/open_source/modules/memories/opengauss_graph_db.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
# openGauss graph storage

Select `GRAPH_DB_BACKEND=opengauss` and set `OPENGAUSS_HOST`, `OPENGAUSS_USER`, `OPENGAUSS_PASSWORD`, and `OPENGAUSS_DB`. Install the `tree-mem` extra. The target database must already have the required AGE and DataVec/BM25 capabilities; the adapter does not create a physical database.

Optional settings are `OPENGAUSS_PORT` (5432), `OPENGAUSS_MIN_CONN` (1), `OPENGAUSS_MAX_CONN` (20), `OPENGAUSS_CONNECT_TIMEOUT` (10 seconds), `OPENGAUSS_CONNECTION_WAIT_TIMEOUT` (30 seconds), and `EMBEDDING_DIMENSION` (1024). Explicit request Cube IDs take precedence over the configured default scope. A scope selection is a query filter, not an authorization grant.

## Dashboard ranges

`POST /product/get_memory_dashboard` accepts two optional, nullable fields. Existing clients can omit both.

| Field | Meaning |
| --- | --- |
| `all_cubes: null` or omitted | Select the supplied `mem_cube_id`, or the configured default Cube if omitted. Legacy filter controls below can explicitly select a different range. |
| `all_cubes: true` | Select all Cubes. Cannot be combined with an outer `mem_cube_id` or a `public` single-Cube selection. |
| `all_cubes: false` | Select the supplied Cube, or the configured default if none is supplied. |
| `exclude_cube_id` | Exclude exactly one Cube from an explicitly selected all-Cube range. This field alone does not enable all-Cube selection. Must be a nonblank string; an absent Cube excludes nothing. |

For example, list all scopes except `public`, with pagination:

```json
{
"all_cubes": true,
"exclude_cube_id": "public",
"page": 1,
"page_size": 20
}
```

The existing filter controls `{"object_type":"public","mem_cube_id":"P"}` select P, while `{"object_type":"user","mem_cube_id":"P"}` explicitly select all other Cubes. Controls can appear at the root or under `and` and apply globally. Scope controls anywhere beneath `or` are rejected because extracting them would change the Boolean meaning; ordinary business `or` filters are preserved. Repeated identical controls are accepted. An outer `mem_cube_id` must agree with a `public` selection and cannot accompany a `user` selection. Incomplete or conflicting controls, unknown object types, empty Boolean nodes, single-Cube exclusion, and conflicting exclusion IDs return parameter errors. Explicit `all_cubes=false` conflicts with a `user` selection.

`user_id`, memory type, status and business filters still constrain the selected range. Supply both positive `page` and `page_size`, or omit both to return all matching records. Pagination and totals apply independently to each of the four memory categories. A bucket's `total_nodes` counts its records on the current page; `statistics` counts all matching records before pagination.

All backends now return empty category lists when the page has no records, including explicitly selected Cubes. No empty Cube bucket is manufactured. An empty page can still have a positive total. A genuinely empty response has this shape:

```json
{
"code": 200,
"message": "Memories retrieved successfully",
"data": {
"text_mem": [], "tool_mem": [], "skill_mem": [], "pref_mem": [],
"statistics": {
"total_text_nodes": 0, "total_tool_nodes": 0,
"total_skill_nodes": 0, "total_preference_nodes": 0
}
}
}
```

Only openGauss currently accepts non-null new range fields. Other adapters preserve their existing range rules for omitted/null fields and reject explicit new selections. `all_cubes` accepts JSON booleans, not `0`, `1`, or strings. Java clients adopting the fields should use nullable `Boolean`/`String`; do not replace an omitted choice with a primitive Boolean's default `false`.

Expect HTTP 422 for request-model type/shape errors, 400 for invalid range/filter combinations, and 500 for storage execution failures. An error response has `data: null`; callers must not interpret it as an empty successful query. The ordinary `/get_memory` request still requires `mem_cube_id` and does not gain these range fields.

## Resource ownership and current boundaries

Direct `TreeTextMemory` and `GeneralMemCube` instances close their own resources through `close()`. Injected graphs and memories remain borrowed. The API closes its shared graph after its Scheduler has finished using it; independently initialized Schedulers close their own graph. `Scheduler.stop()` stops work, while `close()` ends the lifecycle. Final close rejects new work and lazy initialization, waits for running tasks and recovery, reports cleanup failures, and can retry incomplete cleanup. Successful repeated close is a no-op.

Graph adapters without an explicit `close` are skipped for compatibility; that does not establish that their resources were released. This change does not add complete Scheduler restart support. The combined Tree `drop` workflow, non-default Feedback TFIDF, actual Java integration, full service HTTP E2E, and production-scale performance require separate validation.

TreeTextMemory.dump exports every state from one Cube. Its default omits vectors;
pass `include_embedding=True` for a full logical backup. GeneralMemCube.dump
requests vectors for openGauss Tree memory automatically. Files are published
with a same-directory atomic replacement only after writing, flushing, syncing,
and closing succeeds. A failed export or write preserves the previous file.
This guarantee covers one memory file, not the Cube's entire directory.

An explicit load fails on missing, unreadable, or invalid JSON files with
`memos.exceptions.MemoryError`. Database errors retain their cause. Restoration
is an atomic merge into the same Cube: it preserves nodes and edges absent from
the file. Importing a node without an embedding clears its existing embedding.

Search results retain their original Cube identity, including equal memory IDs
in different Cubes. Parallel Cube searches merge in request order. The existing
no/sim/MMR selection and scoring rules remain in use. Required storage and input
errors propagate through keyword search, API handlers and scheduled Feedback;
these errors are distinct from a successful query with no matches.

Default Feedback (`DB_IDX_READY=False`) supports SQL LIKE keyword replacement.
`search_by_keywords_like` accepts the caller's exact pattern: `%` matches any
sequence, `_` matches one character, and backslash escapes those characters.
It binds the pattern, defaults to activated memories, applies the usual Cube/KB
scope and filters, and returns all matches in Cube/ID order. Empty patterns only
match empty text; invalid types, NUL and an unpaired trailing escape are rejected.
The default projection contains `id`; multi-Cube projections also contain
`user_name`. Explicit fields can include memory, embedding and metadata fields.

Feedback preserves the existing version behavior: with versioning off, working
memory updates in place and long-term memory creates a new node then archives
the old one. These multiple writes are not one transaction. Storage errors are
reported and are not retried by the Feedback wrapper, since a failed connection
can leave a write's commit outcome unknown. Successful earlier updates may remain.
The TFIDF branch (`DB_IDX_READY=True`) remains unsupported.
Loading
Loading