Atu Graphology

Name: Atu Graphology
Rating: 3.5 (1 reviews)
Author: rrriiiccckkk

By rrriiiccckkk 👁 43 views ▲ 0 votes

Hook-only evidence-first knowledge graph plugin for OpenClaw.

GitHub

Install

npm install
npm

README

# atu-graphology

[简体中文](README.zh-CN.md) · Current version: **v0.3.0**

An evidence-first local knowledge graph plugin for OpenClaw, with seven tools and two optional automatic hooks.

## Why atu-graphology?

OpenClaw can remember text; atu-graphology adds a structured relationship layer for questions such as “Which companies compete?”, “Who works where?”, and “What evidence supports this edge?” Every stored relationship can retain its source, quote, and confidence.

## Features

- Local SQLite graph storage with entities, relationships, aliases, and evidence observations.
- Exact, alias, FTS5, and Chinese `LIKE` fallback search.
- Evidence-backed traversal and compact context rendering.
- Seven manual tools plus independent, opt-in `autoRecall` and `autoExtract` hooks.
- OpenAI-compatible extraction, including DeepSeek.

## OpenClaw fit

atu-graphology 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: {
    entries: {
      "atu-graphology": {
        enabled: true,
        config: {
          dbPath: "./data/atu-graphology.db",
          extraction: { enabled: false }
        }
      }
    }
  }
}
```

## Configuration

LLM extraction is optional. Set `DEEPSEEK_API_KEY` in the OpenClaw process environment before starting OpenClaw, for example:

```bash
export DEEPSEEK_API_KEY="your-api-key"
```

For an OpenAI-compatible service, configure its base URL and model. The default config below reads the credential from the process environment:

```json5
{
  plugins: {
    entries: {
      "atu-graphology": {
        enabled: true,
        config: {
          llm: {
            baseURL: "https://api.deepseek.com",
            model: "deepseek-chat"
          },
          extraction: { enabled: true, minConfidenceToStore: 0.6 },
          recall: { maxNodes: 5, maxDepth: 1, tokenBudget: 800 }
        }
      }
    }
  }
}
```

Keep secrets out of committed configuration. As an alternative credential path, you may set `llm.apiKey` directly through secret-managed plugin configuration. Manual local recall and graph queries do not require an API key.

## Automatic hooks

Both default off and can be enabled independently. `autoExtract` requires host conversation access. `autoRecall` requires prompt injection not to be disabled:

```json5
{
  plugins: {
    entries: {
      "atu-graphology": {
        enabled: true,
        hooks: {
          allowConversationAccess: true,
          // Do not set allowPromptInjection: false when using autoRecall.
        },
        config: {
          extraction: { enabled: true, autoExtract: true },
          recall: { autoRecall: true }
        }
      }
    }
  }
}
```

Enable only the hook you want. `autoRecall: true` performs local graph lookup before prompt construction. `autoExtract: true` sends only the current user/final-assistant pair—not earlier messages or tool output—to the configured extraction endpoint.

## Tools

| Tool | Purpose |
| --- | --- |
| `kg_ingest` | Extract and store entities, relationships, and evidence from text. |
| `kg_search` | Find entities by name, alias, type, or text match. |
| `kg_related` | Traverse evidence-backed relationships. |
| `kg_stats` | Report graph statistics. |
| `kg_context` | Render compact graph context within a budget. |
| `kg_sources` | List source-level observation and confidence summaries. |
| `kg_forget` | Soft-delete an entity by default, with guarded hard deletion. |

## Data and privacy

The graph and `autoRecall` stay local in SQLite. External extraction occurs only when extraction is enabled and sends input to the configured OpenAI-compatible endpoint. Automatic extraction is limited to the current user/final-assistant pair. Protect the database as user data, review endpoint privacy terms, and supply credentials via environment variables or secret-managed configuration.

## How it works

Ingest normalizes extracted entities and edges, stores evidence observations and confidence, and indexes searchable text. Search resolves entities; traversal follows typed edges; context rendering selects a compact evidence-backed subgraph. The two hooks reuse these operations without claiming the host's `ContextEngine` slot.

## Current limitations

- Extraction quality depends on the configured model and should be verified against stored evidence.
- There are no embeddings, natural-language graph query planner, community detection, or graph insights yet.
- OpenClaw 2026.6.11's official simple-tool CLI validator accepts `defineToolPlugin` entries but rejects this advanced `definePluginEntry` hook plugin. `npm run plugin:official:compat` verifies that known limitation; the project validator and smoke test cover the full plugin.

## Development

```bash
npm install
npm run build
npm test
npm run plugin:validate
```

See [docs/spec.md](docs/spec.md) for the historical v1 MVP specification; it is retained as design history, not current release scope.

## Compatibility

The minimum tested OpenClaw version is **2026.6.11**. The package declares the same minimum for its optional peer dependency and plugin compatibility metadata.

## License

[MIT](LICENSE) © 2026 Rick.

tools