Tools
Native Memory Citations
By OpenClaw plugin for bounded, cited local memory retrieval with redaction and opt-in enhanced memory sidecars.
Install
openclaw plugins install @ngo-a/native-memory-citationsConfiguration Example
{ "sharedMode": true }README
# Native Memory Citations
[](https://github.com/NGO-A/native-memory-citations/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@ngo-a/native-memory-citations)
[](LICENSE)
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.)
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.
## Operating modes
The plugin runs in one of two modes, selected by the `mode` configuration key.
- **`bounded` (default).** The behavior described throughout this README: read-only
retrieval, keyword/substring search, extractive cited answers, no network calls, no
model calls, and no changes to host configuration. This is what a default install
does, and what every guarantee in this document refers to.
- **`enhanced` (opt-in, experimental).** Bounded mode is the stable production core;
enhanced mode layers additional agentic-memory capabilities on top of it, reusing the
same access boundary, redaction, and citation guarantees. This release adds a
functional zero-LLM knowledge-graph sidecar plus experimental lifecycle scaffolding
(snapshot injection, observation tagging, dreaming integration); richer semantic and
reranked recall and a memory-wiki bridge are forthcoming. Every enhanced capability is
disabled by default even in enhanced mode and is turned on explicitly, per feature.
Leaving configuration at its defaults keeps the plugin in bounded mode; an upgrade
changes nothing until you opt in. Enhanced-mode capabilities are introduced
incrementally beginning with the 2026.6.9 release - see
[Enhanced mode](#enhanced-mode-opt-in).
## 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 by default: bounded mode never creates, modifies, or deletes any file, and
in every mode the plugin never modifies your source memory files (`MEMORY.md`, daily
notes, `DREAMS.md`). Enhanced mode, when explicitly enabled, writes only its own
size-bounded derived sidecars (e.g. `memory/graph.jsonl`, `memory/observations.jsonl`),
which are excluded from retrieval and citation - so generated content never feeds back
into what the plugin returns.
## Install
From npm (recommended):
```sh
openclaw plugins install @ngo-a/native-memory-citations
```
From a local checkout (development):
```sh
openclaw plugins install ./native-memory-citations
```
Reload the Gateway after installing so the plugin host exposes the tools.
## Requirements
- Node.js 22.19.0 or newer.
- OpenClaw 2026.6.8 or newer (declared as a peer dependency).
- A local OpenClaw workspace containing text memory files.
Supported memory file types are `.md`, `.txt`, `.json`, `.jsonl`, `.yaml`, and
`.yml`. Files with other extensions are not scanned.
## 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 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
By default the plugin searches:
- `memory/`
- `MEMORY.md`
- `USER.md`
- `IDENTITY.md`
- `TOOLS.md`
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`.
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
Plugin configuration is supplied in the plugin's entry within the OpenClaw Gateway
configuration. It governs which files the plugin is permitted to read and cite. The
bounded-mode plugin reads existing memory files only; it does not create, modify, or
delete them. Enhanced mode can write only its own derived sidecars when explicitly
enabled.
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. |
| `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 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
Set `allowedRoots` to the exact set of workspace-relative files or directories that
should be searchable. This value replaces the default set in full and takes
precedence over `sharedMode`. Any default entries that should remain searchable must
be listed explicitly.
Each entry must be a workspace-relative, visible path. An entry is rejected, with an
`Invalid allowedRoots entry` error, if it is empty, `.`, `..`, an absolute path,
contains a `..` segment, or contains a hidden segment (a segment beginning with `.`,
for example `memory/.dreams`). These restrictions are part of the access boundary
and are enforced intentionally.
### Examples
Shared or team deployment, retaining the defaults while excluding the private
journal:
```json
{ "sharedMode": true }
```
Restricting the plugin to a specific, minimal set:
```json
{ "allowedRoots": ["memory", "USER.md"] }
```
Adding custom directories. Because `allowedRoots` replaces the default set, any
defaults that should remain searchable are listed again:
```json
{ "allowedRoots": ["memory", "USER.md", "IDENTITY.md", "TOOLS.md", "notes", "decisions"] }
```
Permitting larger files (4 MiB) and specifying a non-default workspace:
```json
{ "workspace": "/srv/openclaw/workspace", "maxFileBytes": 4194304 }
```
### 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.
- `sharedMode` has no effect once `allowedRoots` is set; the explicit list takes
precedence.
- Files exceeding `maxFileBytes` are skipped and logged rather than reported as
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.
### Settings not exposed through configuration
Redaction is implemented in code and is not configurable through plugin
configuration; the schema rejects unrecognized keys. The named secret patterns and
the high-entropy backstop are defined in `src/core.ts`. Modifying redaction behavior
requires editing that file and re-running the test suite (`npm test`) to confirm
that the redaction invariants continue to hold. It is not a configuration setting in
this version.
### Per-request limit
`native_memory_fetch` accepts a `maxChars` argument (default `8000`, constrained to
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.
## Citation integrity
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:
```json
{
"sourceId": "memory/2026-06-17.md",
"lineStart": 12,
"lineEnd": 14,
"expectedSha256": "..."
}
```
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.
## Enhanced mode (opt-in)
Enhanced mode layers the three pillars of agentic memory - storage, injection, and
recall - on top of the bounded core, while reusing the same
... (truncated)
tools
Comments
Sign in to leave a comment