@ngo-a/native-memory-citations 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +84 -11
- package/openclaw.plugin.json +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -3,6 +3,8 @@
|
|
|
3
3
|
Native OpenClaw plugin for cited local memory search and retrieval.
|
|
4
4
|
Native means OpenClaw-native plugin, not native system memory.
|
|
5
5
|
|
|
6
|
+
|
|
7
|
+
|
|
6
8
|
## Tools
|
|
7
9
|
|
|
8
10
|
- `native_memory_search`: search approved memory roots and return snippets with source paths, line numbers, and file SHA-256 hashes.
|
|
@@ -48,22 +50,93 @@ npm run plugin:validate
|
|
|
48
50
|
npm test
|
|
49
51
|
```
|
|
50
52
|
|
|
51
|
-
##
|
|
53
|
+
## Configuration
|
|
54
|
+
|
|
55
|
+
Plugin configuration is supplied in the plugin's entry within the OpenClaw Gateway
|
|
56
|
+
configuration. It governs which files the plugin is permitted to read and cite. The
|
|
57
|
+
plugin reads existing memory files only; it does not create, modify, or delete them.
|
|
58
|
+
All keys are optional.
|
|
59
|
+
|
|
60
|
+
| Key | Type | Default | Description |
|
|
61
|
+
|-----|------|---------|-------------|
|
|
62
|
+
| `workspace` | string | `$OPENCLAW_WORKSPACE`, then `~/.openclaw/workspace` | Absolute path against which roots are resolved. |
|
|
63
|
+
| `allowedRoots` | string[] | Built-in default set (see Default Scope) | Workspace-relative files or directories to search. When set to a non-empty array, it replaces the default set in full. |
|
|
64
|
+
| `sharedMode` | boolean | `false` | When `true`, excludes the private `MEMORY.md` from the default set. Has no effect when `allowedRoots` is set. |
|
|
65
|
+
| `maxFileBytes` | number | `1048576` (1 MiB) | Per-file size limit. Files exceeding this limit are skipped rather than reported as errors. |
|
|
66
|
+
|
|
67
|
+
### Default search scope
|
|
68
|
+
|
|
69
|
+
The default roots are defined in the Default Scope section above: `memory/`,
|
|
70
|
+
`MEMORY.md`, `USER.md`, `IDENTITY.md`, and `TOOLS.md`. With `sharedMode: true`,
|
|
71
|
+
`MEMORY.md` is excluded.
|
|
72
|
+
|
|
73
|
+
### Defining custom roots
|
|
74
|
+
|
|
75
|
+
Set `allowedRoots` to the exact set of workspace-relative files or directories that
|
|
76
|
+
should be searchable. This value replaces the default set in full and takes
|
|
77
|
+
precedence over `sharedMode`. Any default entries that should remain searchable must
|
|
78
|
+
be listed explicitly.
|
|
52
79
|
|
|
53
|
-
|
|
54
|
-
|
|
80
|
+
Each entry must be a workspace-relative, visible path. An entry is rejected, with an
|
|
81
|
+
`Invalid allowedRoots entry` error, if it is empty, `.`, `..`, an absolute path,
|
|
82
|
+
contains a `..` segment, or contains a hidden segment (a segment beginning with `.`,
|
|
83
|
+
for example `memory/.dreams`). These restrictions are part of the access boundary
|
|
84
|
+
and are enforced intentionally.
|
|
85
|
+
|
|
86
|
+
### Examples
|
|
87
|
+
|
|
88
|
+
Shared or team deployment, retaining the defaults while excluding the private
|
|
89
|
+
journal:
|
|
55
90
|
|
|
56
91
|
```json
|
|
57
|
-
{
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
92
|
+
{ "sharedMode": true }
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Restricting the plugin to a specific, minimal set:
|
|
96
|
+
|
|
97
|
+
```json
|
|
98
|
+
{ "allowedRoots": ["memory", "USER.md"] }
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Adding custom directories. Because `allowedRoots` replaces the default set, any
|
|
102
|
+
defaults that should remain searchable are listed again:
|
|
103
|
+
|
|
104
|
+
```json
|
|
105
|
+
{ "allowedRoots": ["memory", "USER.md", "IDENTITY.md", "TOOLS.md", "notes", "decisions"] }
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Permitting larger files (4 MiB) and specifying a non-default workspace:
|
|
109
|
+
|
|
110
|
+
```json
|
|
111
|
+
{ "workspace": "/srv/openclaw/workspace", "maxFileBytes": 4194304 }
|
|
63
112
|
```
|
|
64
113
|
|
|
65
|
-
|
|
66
|
-
|
|
114
|
+
### Operational notes
|
|
115
|
+
|
|
116
|
+
- `allowedRoots` replaces the default set; it does not extend it. A value of
|
|
117
|
+
`["notes"]` makes `MEMORY.md`, `USER.md`, and the remaining defaults unreachable.
|
|
118
|
+
List every path that should remain searchable.
|
|
119
|
+
- `sharedMode` has no effect once `allowedRoots` is set; the explicit list takes
|
|
120
|
+
precedence.
|
|
121
|
+
- Files exceeding `maxFileBytes` are skipped and logged rather than reported as
|
|
122
|
+
errors. Set the limit to accommodate the largest memory files in use.
|
|
123
|
+
- Hidden directories, `..` segments, and absolute paths cannot be included. This is
|
|
124
|
+
enforced by the access boundary.
|
|
125
|
+
|
|
126
|
+
### Settings not exposed through configuration
|
|
127
|
+
|
|
128
|
+
Redaction is implemented in code and is not configurable through plugin
|
|
129
|
+
configuration; the schema rejects unrecognized keys. The named secret patterns and
|
|
130
|
+
the high-entropy backstop are defined in `src/core.ts`. Modifying redaction behavior
|
|
131
|
+
requires editing that file and re-running the test suite (`npm test`) to confirm
|
|
132
|
+
that the redaction invariants continue to hold. It is not a configuration setting in
|
|
133
|
+
this version.
|
|
134
|
+
|
|
135
|
+
### Per-request limit
|
|
136
|
+
|
|
137
|
+
`native_memory_fetch` accepts a `maxChars` argument (default `8000`, constrained to
|
|
138
|
+
the range 256 to 20000) that bounds the amount of cited content returned by a single
|
|
139
|
+
fetch. This is a per-call tool argument and is independent of plugin configuration.
|
|
67
140
|
|
|
68
141
|
## Notes
|
|
69
142
|
|
package/openclaw.plugin.json
CHANGED