Tools
Atu Mnemos
By Hook-only evidence-first knowledge graph plugin for OpenClaw.
Install
npm install
npmConfiguration Example
{ "subject": "person:alice", "scope": "project:research", "limit": 10 }README
# ATU Mnemos
[简体中文](README.zh-CN.md) · Current release: **v2.1.0**
> Local-first memory trust and knowledge governance for OpenClaw agents.
ATU Mnemos is the canonical product, npm package, OpenClaw plugin ID,
configuration namespace, CLI, and default SQLite path: `atu-mnemos`. v2.1
keeps the former `atu-graphology` plugin ID, CLI command, and environment
variable as compatibility aliases. It never copies or moves an existing graph
database until an operator confirms the local migration.
ATU Mnemos gives an agent persistent, structured memory it can explain:
entities, relationships, observations, and the evidence behind them. It combines
an evidence-backed knowledge graph with scoped memory documents and optional
local semantic retrieval—without taking over OpenClaw conversation storage or
registering a `ContextEngine`.
```text
Conversations / notes / documents
│
▼
explicit or opt-in extraction
│
▼
Evidence-backed graph + local memory documents
│
▼
Scoped retrieval and compact agent context
```
## Why ATU Mnemos?
Ordinary memory stores text. ATU Mnemos preserves the relationships and
provenance that make recalled information useful for research and decisions.
| Need | What it provides |
| --- | --- |
| “What supports this claim?” | Every relationship can retain source, quote, confidence, time, and scoped observations. |
| “What is related to this?” | Evidence-backed traversal, graph queries, timelines, comparisons, and deterministic insights. |
| “Recall this in the right project.” | Stable scopes isolate evidence, retrieval, memory documents, and automatic hooks. |
| “Find the idea even when terminology differs.” | Optional Ollama embeddings support semantic and hybrid graph/memory retrieval. |
| “Can I inspect or undo this?” | Read-only-by-default local Inspector, preview/confirm operations, audit records, and recovery paths. |
## Features
### Core capabilities
- **Evidence-first knowledge graph.** Local SQLite storage for entities, typed relationships, aliases, and immutable evidence observations.
- **Graph and memory retrieval.** Exact, alias, FTS5, Chinese `LIKE`, semantic, and hybrid recall; `kg_context` renders a bounded graph plus matching memory excerpts.
- **Thirty-two tools, three selectable surfaces.** Keep the historical full set, or register only a 10-tool daily `core` surface or 16-tool `research` surface so unused schemas do not consume agent context.
- **User-controlled automation.** `autoRecall` and `autoExtract` are independent, opt-in hooks. Automatic extraction uses only the current user/final-assistant pair.
- **Scoped knowledge.** Keep projects and collections separate while reusing global entity identities only where scoped evidence supports them.
- **Research and quality tools.** Temporal validity, review-only conflict candidates, PPR-aware ranking, communities, insights, bounded query plans, watches, and digests.
- **Bounded Personalized PageRank.** Optional quality ranking is capped and deterministically falls back when graph math, cancellation, or scale limits make PPR unavailable.
- **Local inspection and recovery.** A loopback-only Inspector, redacted views, preview-first maintenance, backups, restore recovery points, and JSONL exchange.
### Local-first, with explicit provider boundaries
The graph, memory documents, chunks, vectors, and recall database are stored in
local SQLite. Embeddings are disabled by default and use the configured local
Ollama endpoint only when enabled. Extraction is also opt-in; when configured,
it sends the documented bounded input to an OpenAI-compatible provider such as
DeepSeek. See [Data and privacy](#data-and-privacy) for the exact boundary.
Library hosts can additionally opt in to the versioned public Provider Adapter
SDK. It keeps calls bounded and cancellable, accepts only public Provider
capabilities, and does not auto-register agent tools or load third-party code
from configuration. See [Provider Adapter SDK](docs/provider-adapter-sdk.md).
For larger graph-entity embedding indexes, a library host may also explicitly
register a versioned optional Vector Backend. SQLite remains the canonical
store; the backend receives only opaque IDs and vectors, and every returned ID
is rechecked locally for type and scope before use. Hosts can seed by cursor,
remove a retired vector with a graph deletion, and reconcile stale opaque IDs
when their backend supports that lifecycle. See [Vector Backend
SDK](docs/vector-backend-sdk.md).
For cooperating agents, the optional local governance layer can require a
host-bound actor, exact-scope human-issued authority, and hash-bound one-use
approval before claim-verification transitions, conflict decisions, or profile
selection writes. It is disabled by default and adds no tool that lets an
agent impersonate another actor. See [Multi-Agent Trust
Governance](docs/multi-agent-governance.md).
### Local Inspector and operations (v1.0)
Start the local Web console only when needed:
```bash
atu-mnemos inspect
```
The command prints a one-time bootstrap URL and binds only to `127.0.0.1` on an
ephemeral port. The default is read-only. It provides Overview, Graph, Entity,
Research, and Trust pages for bounded nodes, relationships, communities, timelines,
redacted evidence summaries, insights, watches, digests, and query history. All
JavaScript and CSS are packaged locally; there is no CDN, remote telemetry, or
remote Web console. Closing the process closes the listener.
To unlock the Operations page for that process only, use:
```bash
atu-mnemos inspect --allow-operations
```
Operations remain preview-first and require a separate explicit confirmation.
They cover audited source trust weights (0–2), verified backup, recovery-point
restore, orphan cleanup, and derived weight recomputation. A source trust change
updates ranking configuration, never immutable evidence confidence. Health
reports distinguish stored confidence from derived freshness/review state;
maintenance suggestions and extraction/recall auditing are report-only until an
operator confirms a supported action. Restore verifies the artifact, creates a
recovery point first, and fails closed on stale revisions or invalid artifacts.
The read-only health response also reports the aggregate availability of backup
and recovery-point artifacts without returning a filesystem path, filename, or
other local location.
### Tool surfaces and operator workflow (v1.9)
`toolSurface` controls which schemas are registered at OpenClaw plugin startup.
It defaults to `"full"` for compatibility with v1.7. `"core"` registers the
ten everyday tools (`kg_search`, `kg_related`, `kg_context`, `kg_recall_explain`,
`kg_ingest`, `kg_sources`, `kg_stats`, `kg_scopes`, `kg_profile`, `kg_memory`);
`"research"` adds query, timeline, compare, insights, watch, and digest. The
reduced `kg_memory` schema exposes only routine store/search operations. No
disabled tool is registered, so it does not occupy the agent's tool context.
The local CLI now has structured JSON operator commands alongside the original
`ingest`, `search`, `related`, `stats`, `forget`, and `inspect` commands:
```bash
atu-mnemos surface core
atu-mnemos trust status --scope project:research
atu-mnemos trust sources --scope project:research
atu-mnemos trust queue --scope project:research --confirm
atu-mnemos profile show person:alice --scope project:research
atu-mnemos profile history person:alice --scope project:research
atu-mnemos recall status --scope project:research
atu-mnemos recall explain "Which supplier should I use?" --scope project:research
atu-mnemos governance status --scope project:research
```
`trust` covers bounded verification queue, retrospective-audit, and redacted source-lifecycle reads and
actions; `profile` provides sourced profile reads, material-change history/diffs, and the existing preview-first
selection flow; `recall` exposes a read-only redacted decision trace, metrics, calibration, canary status,
and rollback. Mutating trust commands require `--confirm`; profile and recall
policy changes retain their existing preview-hash/confirmation protocol. All
new operator output is a stable `{ ok, command, result }` JSON envelope.
`governance` is a local operator-only command family for principals, scoped
grants, one-use approvals, and redacted decision-ledger status. It is not an
OpenClaw agent tool. Its mutations require `--confirm`; a host must still bind
the actual actor before enabled governance can authorize a graph write.
The Inspector Trust page is always read-only, including when Operations is
unlocked. It returns only per-scope aggregate verification, queue, audit,
source-lifecycle, and canary counts—never claim text, evidence snapshots,
provider payloads, credentials, or local paths.
The browser API uses a one-time fragment bootstrap, an HttpOnly session cookie,
in-memory CSRF state, strict same-origin checks, CSP, bounded request bodies, and
no private paths, credentials, quotes, prompts, or raw provider bodies in DOM or
storage. Current browser support is the current Chromium, Firefox, and Safari
families. The production scale gate uses exactly 50,000 nodes and 200,000 edges;
public graph pages remain capped at 5,000 nodes, 20,000 edges, 4 MiB, and 5 s.
Inspector failures are bounded and fail-closed; optional recall, extraction, and
explanation services retain their documented fail-open behavior.
## OpenClaw fit
ATU Mnemos is a full OpenClaw plugin. It complements OpenClaw memory and can coexist with lossless-claw. It does not register a ContextEngine or replace conversation storage. Recall injects selected graph facts through a hook, while the graph remains a separate structured evidence layer.
## Quick start
```bash
npm install
npm run plugin:build
openclaw plugins install --link .
```
Then enable the linked plugin with a minimal manual-tool configuration:
```json5
{
plugins: {
en
... (truncated)
tools
Comments
Sign in to leave a comment