agentscope-ai / agentscope-ai/ReMe

[Feature]: Add first-class memory subject scoping

Offen
#506 2 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
enhancement
Vorherrschende Sprache
Python
Sterne
3.4k
Forks
298
Ø Merge
19 Std. 52 Min.
Gemergte PRs (30 T.)
55

Beschreibung

## Problem

ReMe currently has no first-class way to represent and enforce **who a memory is about** within a workspace.

A workspace is the durable data-owner boundary, but a single workspace may contain memories about multiple people, teams, projects, customers, or agents. Markdown frontmatter can already preserve an extra field such as `subject`, and the search backend can already filter exact chunk metadata. However, these capabilities are not connected end to end:

- `FileFrontMatter` preserves unknown keys, but `subject` has no canonical contract.
- `auto_memory` does not accept a stable subject supplied by the host or deterministically write it to daily notes.
- Markdown frontmatter is not copied into chunk metadata by default.
- The public `search` Job exposes date filters, but no subject scope.
- Auto Dream relies on prompt-level actor-scope reasoning and can still extract or integrate memories across different subjects.

This creates a correctness problem in multi-person scenarios. For example, preferences for Alice and Bob can be recalled together or consolidated into one vague personal digest node.

The concepts should remain distinct:

- **workspace owner**: who owns the data space (`workspace_dir`)
- **message actor**: who authored a message (currently closest to `Msg.name`, but not necessarily a stable ID)
- **memory subject**: who or what a memory describes
- **search scope**: which subject-specific memories may be recalled for the current request

Legacy ReMe memory records may use `target` for the memory subject. That is useful prior art, but `target` is overloaded elsewhere for file and operation destinations, so `subject` is clearer as the canonical field.

## Proposed behavior

Introduce a scalar, first-class `subject` contract across memory generation, indexing, retrieval, and Dream consolidation.

### 1. Canonical frontmatter field with legacy compatibility

Use `subject` as the canonical field for new memory files:

```yaml
---
name: invoice-title-preference
description: Alice requires the invoice title to use Volcano Engine.
subject: person:customer-alice
kind: preference
---
```

Define `subject` as “the entity this memory describes.” It is not a destination path, message recipient, workspace owner, or authorization principal.

For compatibility, interpret legacy `target` as `subject` only when `subject` is absent. New writes should emit `subject`. Conflicting `subject` and `target` values must have explicit, tested behavior rather than silently changing scope.

Keep the first version scalar so existing exact-match metadata filters remain sufficient. A future `subjects: [...]` extension can define list-filter semantics separately.

### 2. Deterministic Auto Memory propagation

Add an optional `subject` parameter to `auto_memory` so a host can pass a stable business identity:

```json
{
"session_id": "support-session-1",
"subject": "person:customer-alice",
"messages": []
}
```

When present, ReMe—not the LLM—must ensure the resulting daily note has the exact subject on both create and update paths. The subject should also be available in response metadata. Auto Memory must not infer it from display names or `Msg.name`.

Existing calls without `subject` must remain valid. Updating a note must not silently move it to a different subject; mismatches need deterministic failure or another explicitly documented policy.

### 3. Subject-aware indexing and search

Make canonical subjects available in `FileChunk.metadata` for Markdown memories. The default configuration should include only the required frontmatter keys (for example `subject` and `kind`) rather than exposing arbitrary frontmatter unintentionally.

Expose a top-level `subject` parameter on the public `search` Job and translate it into the internal metadata filter. Direct internal `search_filter` support may remain an implementation detail unless a separate public contract is desired.

Define an explicit shared-memory recall policy. A subject-scoped search should be able to recall both:

- personal memories whose `subject` matches the requested subject; and
- workspace-shared knowledge, procedures, or memories explicitly marked as shared.

This likely requires an OR/union policy rather than a single metadata equality filter. The initial policy and the meaning of missing `subject` must be documented and tested. After enabling the metadata, existing workspaces must be able to rebuild derived state with `reme reindex`; source Markdown remains the source of truth.

### 4. Prevent cross-subject Dream consolidation

Carry subject scope through Dream extraction and integration:

- units from different subjects must not be merged during extraction;
- a digest candidate may be treated as `same_abstraction` only when its subject scope is compatible;
- `CREATE`, `CORROBORATE`, `REFINE`, and `CORRECT` must never update a digest node owned by a different subject;
- newly created personal digest nodes inherit the canonical subject deterministically;
- subjectless shared knowledge remains governed by the documented shared-memory policy.

These constraints should be enforced in code before or around model calls, not only described in prompts.

## Acceptance criteria

- [ ] `subject` has a documented canonical meaning in Markdown frontmatter.
- [ ] Legacy `target` is read as an alias when `subject` is absent, with tested conflict behavior.
- [ ] `auto_memory` accepts an optional stable `subject` and deterministically preserves it on create and update.
- [ ] The model cannot invent or change the supplied subject.
- [ ] Markdown chunks expose the normalized subject in metadata using a minimal allowlist.
- [ ] `search` exposes a subject scope and applies a documented subject-specific plus shared-memory recall policy to both keyword and vector results.
- [ ] Auto Dream does not merge or update across incompatible subject scopes, and created personal digest nodes inherit the subject.
- [ ] Existing unscoped workspaces and `auto_memory` callers remain backward compatible.
- [ ] Reindex/migration behavior is documented; indexes remain rebuildable from workspace files.
- [ ] Focused unit tests cover aliases, create/update propagation, scoped search, shared recall, and Dream cross-subject rejection.
- [ ] English and Chinese user documentation describe the terminology and examples.

## Area

Memory or workspace files (cross-cutting into Jobs/Steps and Search/Index).

## Local-first and compatibility considerations

`subject` lives in user-owned Markdown and is therefore transparent and portable. Chunk metadata, catalogs, and indexes remain derived and rebuildable. Existing unscoped files continue to work, and legacy `target` records remain readable.

Enabling frontmatter metadata must use an explicit key allowlist to avoid unintentionally indexing unrelated or sensitive fields. Changing the default requires documenting that users should run `reme reindex`.

Subject filtering is a **retrieval-correctness boundary, not a security boundary**. Files still share a workspace, and read/list/traverse operations may access other subjects. Callers that control the subject can also switch scopes. Strong isolation should continue to use separate workspaces; a future multi-tenant authorization design must enforce trusted scope across search, read, list, traversal, and writes.

## Alternatives considered

- **Keep using free-form `target` only:** compatible with legacy records, but the name is overloaded throughout ReMe and remains attribution metadata unless it participates in generation, retrieval, and Dream.
- **Use one directory per subject:** makes scope visible but complicates daily/digest layouts and still does not define cross-cutting API or Dream behavior.
- **Only enable frontmatter metadata filters:** improves manual search filtering but does not make Auto Memory write the identity or stop Dream from combining subjects.
- **Use `Msg.name` as the subject:** display names are not guaranteed to be stable or unique, and the message actor is conceptually different from the memory subject.
- **Treat subject filtering as authorization:** insufficient because other workspace operations remain accessible and caller-supplied filters are not trusted identity.

## Example usage

```shell
reme auto_memory \
session_id=support-session-1 \
subject=person:customer-alice \
messages='[...]'

reme search \
query='invoice preferences' \
subject=person:customer-alice

# After upgrading an existing workspace so subject metadata is indexed:
reme reindex
```

## Out of scope

- Multi-tenant authentication or authorization
- A plural `subjects` schema and list matching semantics
- Inferring stable identities from display names or message content
- Changing the workspace-as-owner isolation boundary

Beitragsleitfaden

Für dieses Repository ist kein Beitragsleitfaden indexiert

Bewertung

Dieses Issue wurde noch nicht bewertet.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.