foxloom 0.2.1

Hybrid memory layer with mem0-style semantics on top of foxstash-core
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

# Memory Model

## Core Types

`MemoryRecord` fields:

- identity: `memory_id`
- scope linkage: `workspace_id`, `user_id`, `session_id`
- semantics: `scope`, `memory_type`, `status`
- content: `text`, `json_fields`
- ranking: `confidence`, `importance`, `decay_half_life_hours`
- lineage/provenance: `source_run_id`, `updated_at`, `embedding_ref`

## Enumerations

- `MemoryScope`: `user | session | workspace | global`
- `MemoryType`: `profile | episodic | policy | artifact_summary`
- `MemoryStatus`: `active | superseded | quarantined | deleted`

## Operation Model (`MemoryOp`)

- `Add { record, reason }`
- `Update { memory_id, patch, reason }`
- `Supersede { old_memory_id, new_record, reason }`
- `Delete { memory_id, reason }`
- `Noop { memory_id, reason }`

## Merge Semantics (Default Helper)

`merge_candidate(existing, candidate)` behavior:

1. No existing record -> `Add`.
2. Exact text duplicate -> `Update` confidence/importance (or `Noop`).
3. Scope/type mismatch -> `Add`.
4. Non-active states are protected from unsafe supersede.
5. Entity-aware replacement when `json_fields.entity` matches.

```mermaid
flowchart TD
    A[Candidate arrives] --> B{Existing record?}
    B -- No --> C[Add]
    B -- Yes --> D{Same text?}
    D -- Yes --> E[Update or Noop]
    D -- No --> F{Same scope and type?}
    F -- No --> C
    F -- Yes --> G{Same entity?}
    G -- No --> H[Add non-conflicting]
    G -- Yes --> I{Candidate confidence sufficient?}
    I -- Yes --> J[Supersede]
    I -- No --> K[Noop]
```