@ngo-a/native-memory-citations 0.1.3 → 2026.6.0

package/README.md

@@ -1,19 +1,44 @@
 # Native Memory Citations
 
-Native OpenClaw plugin for cited local memory search and retrieval.
-Native means OpenClaw-native plugin, not native system memory.
+Native Memory Citations is an OpenClaw plugin for controlled, cited retrieval from
+local workspace memory files. ("Native" denotes an OpenClaw-native plugin, not
+native system memory.)
 
-![Architecture](https://raw.githubusercontent.com/NGO-A/native-memory-citations/v0.1.3/docs/architecture.svg)
+The plugin is built for environments where memory access must be explicit, bounded,
+and auditable. An operator defines which workspace files or directories may be
+searched. The plugin enforces that access boundary before reading any content,
+redacts secret-shaped material from what it returns, and attaches citation metadata
+so every answer can be traced back to its source. The objective is not broad memory
+access; it is operator-controlled retrieval with an audit trail.
+
+![Architecture](https://raw.githubusercontent.com/NGO-A/native-memory-citations/v0.1.4/docs/architecture.svg)
+
+## Key capabilities
+
+- Operator-defined search scope, limited to workspace-relative roots.
+- Optional shared mode that excludes private memory from the default set.
+- Per-file size limits, with oversized files skipped rather than read.
+- Redaction of secret-shaped content in all returned text (search, fetch, and answers).
+- Citations on every result, with full-file SHA-256 hashes for staleness detection.
+- Per-request output limits on fetched content.
+- Read-only operation: the plugin never creates, modifies, or deletes memory files.
+
+## Intended use
+
+Native Memory Citations is intended for OpenClaw deployments where an agent needs
+access to selected memory files without broad filesystem visibility. It suits
+single-user, team, and shared environments in which private memory, project notes,
+identity files, and tool references must be handled within clear boundaries.
 
 ## Tools
 
-- `native_memory_search`: search approved memory roots and return snippets with source paths, line numbers, and file SHA-256 hashes.
-- `native_memory_fetch`: fetch a cited source by `sourceId` or safe path, optionally checking an expected citation hash.
-- `native_memory_answer`: build an extractive answer from cited memory snippets; says when no cited memory is found.
+- `native_memory_search` — search the approved roots and return snippets with source paths, line numbers, and file SHA-256 hashes.
+- `native_memory_fetch` — fetch a cited source by `sourceId` or a safe path, optionally checking an expected citation hash.
+- `native_memory_answer` — build an extractive answer from cited snippets, and state plainly when no cited memory is found.
 
-## Default Scope
+## Default scope
 
-By default, the plugin searches:
+By default the plugin searches:
 
 - `memory/`
 - `MEMORY.md`
@@ -21,34 +46,13 @@ By default, the plugin searches:
 - `IDENTITY.md`
 - `TOOLS.md`
 
-Set `sharedMode: true` in plugin config to exclude the private `MEMORY.md` from
-the default root set. Setting `allowedRoots` explicitly overrides the default
-set entirely and supersedes `sharedMode`.
-
-Custom `allowedRoots` entries must be workspace-relative visible paths. Empty
-entries, `.`, `..`, paths containing `..`, absolute paths, and hidden path
-segments such as `memory/.dreams` are rejected.
+Set `sharedMode: true` to exclude the private `MEMORY.md` from this default set.
+Setting `allowedRoots` explicitly overrides the default set entirely and takes
+precedence over `sharedMode`.
 
-## Build, Generate, Validate
-
-The manifest (`openclaw.plugin.json`) is generated from the `defineToolPlugin`
-metadata in `src/index.ts`. Do not hand-edit it; regenerate after changing the
-plugin id, name, description, `configSchema`, or any tool name:
-
-```bash
-npm install
-npm test
-npm run plugin:build
-npm run plugin:validate
-```
-
-In CI, fail on stale generated metadata without rewriting files:
-
-```bash
-npm run plugin:build:check
-npm run plugin:validate
-npm test
-```
+Custom `allowedRoots` entries must be workspace-relative, visible paths. Empty
+entries, `.`, `..`, paths containing `..`, absolute paths, and hidden segments such
+as `memory/.dreams` are rejected.
 
 ## Configuration
 
@@ -60,15 +64,15 @@ All keys are optional.
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
 | `workspace` | string | `$OPENCLAW_WORKSPACE`, then `~/.openclaw/workspace` | Absolute path against which roots are resolved. |
-| `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. |
+| `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. |
 | `sharedMode` | boolean | `false` | When `true`, excludes the private `MEMORY.md` from the default set. Has no effect when `allowedRoots` is set. |
 | `maxFileBytes` | number | `1048576` (1 MiB) | Per-file size limit. Files exceeding this limit are skipped rather than reported as errors. |
 
 ### Default search scope
 
-The default roots are defined in the Default Scope section above: `memory/`,
-`MEMORY.md`, `USER.md`, `IDENTITY.md`, and `TOOLS.md`. With `sharedMode: true`,
-`MEMORY.md` is excluded.
+The default roots are listed in Default scope above: `memory/`, `MEMORY.md`,
+`USER.md`, `IDENTITY.md`, and `TOOLS.md`. With `sharedMode: true`, `MEMORY.md` is
+excluded.
 
 ### Defining custom roots
 
@@ -114,14 +118,14 @@ Permitting larger files (4 MiB) and specifying a non-default workspace:
 ### Operational notes
 
 - `allowedRoots` replaces the default set; it does not extend it. A value of
- `["notes"]` makes `MEMORY.md`, `USER.md`, and the remaining defaults unreachable.
- List every path that should remain searchable.
+  `["notes"]` makes `MEMORY.md`, `USER.md`, and the remaining defaults unreachable.
+  List every path that should remain searchable.
 - `sharedMode` has no effect once `allowedRoots` is set; the explicit list takes
- precedence.
+  precedence.
 - Files exceeding `maxFileBytes` are skipped and logged rather than reported as
- errors. Set the limit to accommodate the largest memory files in use.
+  errors. Set the limit to accommodate the largest memory files in use.
 - Hidden directories, `..` segments, and absolute paths cannot be included. This is
- enforced by the access boundary.
+  enforced by the access boundary.
 
 ### Settings not exposed through configuration
 
@@ -138,28 +142,10 @@ this version.
 the range 256 to 20000) that bounds the amount of cited content returned by a single
 fetch. This is a per-call tool argument and is independent of plugin configuration.
 
-## Notes
+## Citation integrity
 
-This v1 is intentionally local-file based. It is portable and dependency-light.
-A future version can add vector search while keeping the same public tool names.
-Search is keyword/substring based with an mtime/size line cache, bounded scan
-concurrency, and `AbortSignal` checks during scan.
-
-Returned snippets, fetched content, match lines, and extractive answers are
-redacted for common secret patterns such as bearer tokens, API keys, GitHub
-tokens, password/secret/token assignment lines, credential URLs, JWTs, cloud
-keys, and private key blocks. The named pattern list is best-effort labeling,
-not the security boundary; returned text also masks sufficiently long
-high-entropy tokens when no named pattern matches. Redaction is defense-in-depth,
-not the access boundary; the access boundary is allowed roots, hidden-path
-rejection, symlink/realpath checks, file-type filtering, and size limits.
-Redaction does not mutate source files and does not affect citation hashes,
-which are computed from original file text.
-
-## Citation Integrity
-
-Search hits include `sha256`, computed from the full text file used for line
-splitting and citation line numbers. Fetch results include the current `sha256`
+Search hits include a `sha256`, computed from the full text of the file used for
+line splitting and citation line numbers. Fetch results include the current `sha256`
 for the same full-file content.
 
 To detect stale citations, pass the hash from a prior search hit:
@@ -173,53 +159,57 @@ To detect stale citations, pass the hash from a prior search hit:
 }
 ```
 
-If the file changed, fetch still returns the current content for inspection, but
+If the file has changed, fetch still returns the current content for inspection but
 marks the result with `stale: true` and a `staleMessage` explaining the hash
 mismatch. Because hashes cover the full file, appending to a daily journal marks
 earlier citations stale even when the cited lines themselves are unchanged.
 
+## Security model
+
+The plugin enforces a two-layer model.
+
+The access boundary determines what may be read. `allowedRoots` is trusted operator
+configuration. Any caller-supplied fetch path, and any symlink that would escape a
+root, is treated as untrusted and re-checked with `realpath`. Symlinks encountered
+while walking directories during search are skipped. Fetch additionally rejects
+hidden path segments, non-text files, and files larger than `maxFileBytes`.
+
+Redaction is applied to all returned text as defense-in-depth. Named secret patterns
+provide readable labels for common formats; a high-entropy backstop masks unknown
+long tokens. Redaction is not an authorization or access-control boundary. It does
+not modify source files, and it does not affect citation hashes, which are computed
+from the original file text.
+
+To report a vulnerability, see [SECURITY.md](SECURITY.md).
+
 ## Install
 
 From npm (recommended):
 
- openclaw plugins install @ngo-a/native-memory-citations
+    openclaw plugins install @ngo-a/native-memory-citations
 
 From a local checkout (development):
 
- openclaw plugins install ./native-memory-citations
+    openclaw plugins install ./native-memory-citations
 
 Reload the Gateway after installing so the plugin host exposes the tools.
 
-## Security Model
-
-See [SECURITY.md](./SECURITY.md): `allowedRoots` is trusted operator config;
-a symlink that escapes a root, and any caller-supplied fetch path, is untrusted
-and re-checked with `realpath`; symlinks found while walking directories during
-search are skipped. Fetch also rejects hidden path segments, non-text files, and
-files larger than `maxFileBytes`. Citation hashes let callers detect when a
-previous path-and-line citation may now point at changed content. Returned text
-is redacted before it leaves the plugin; named secret patterns provide nicer
-labels, while the high-entropy backstop handles unknown token formats. Redaction
-is not an authorization or access-control boundary.
-
-## Releasing
-
-Published to npm as `@ngo-a/native-memory-citations`.
+## Implementation notes
 
-To cut a new release:
+This v1 is intentionally local-file based. It is portable and dependency-light. A
+future version can add vector search while keeping the same public tool names.
+Search is keyword and substring based, with an mtime/size line cache, bounded scan
+concurrency, and `AbortSignal` checks during the scan.
 
-1. Make changes and confirm the suite is green: `npm test`
-2. Bump `version` in `package.json` (e.g. `0.1.0` -> `0.1.1`) per semver.
-3. `npm publish`
+## Contributing
 
-The `prepublishOnly` script rebuilds `dist/` first, and `publishConfig.access`
-is `public`, so no extra flags are needed. A published version number cannot be
-overwritten; fixes ship as a new version.
+Development setup, manifest generation, and the release process are documented in
+[CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 
-[MIT](./LICENSE)
+MIT. See [LICENSE](LICENSE).
 
 ## Changelog
 
-See [CHANGELOG.md](./CHANGELOG.md).
+See [CHANGELOG.md](CHANGELOG.md).

package/openclaw.plugin.json

@@ -30,7 +30,7 @@
     },
     "additionalProperties": false
   },
-  "version": "0.1.3",
+  "version": "2026.6.0",
   "contracts": {
     "tools": [
       "native_memory_search",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngo-a/native-memory-citations",
-  "version": "0.1.3",
+  "version": "2026.6.0",
   "type": "module",
   "description": "Native OpenClaw plugin for cited local memory search and retrieval.",
   "license": "MIT",