npm package: @namsangboy/openclaw-plugin-axiommind
Description: Intelligent memory graduation pipeline for OpenClaw with intent-based retrieval, 5-stage memory promotion, and custom chat UI
Author: namsangboy
Latest version: 0.2.0

# AxiomMind - Intelligent Memory System for OpenClaw

An OpenClaw plugin that automatically extracts important information from conversations and promotes it through a 5-stage graduation pipeline into long-term memory.

> OpenClaw용 지능형 메모리 시스템. 대화에서 중요한 정보를 자동 추출하고, 단계적 검증을 거쳐 장기 메모리로 승격합니다.

## Features

- **5-Stage Memory Graduation** - Raw → Working → Candidate → Verified → Certified
- **Intent-Based Retrieval** - Searches memory only when needed, not every message
- **Semantic Search** - Multilingual vector search via EmbeddingGemma (100+ languages)
- **Auto-Promotion Scheduler** - Background promotion, consolidation, and graph cleanup
- **Conflict Detection** - Automatic duplicate/contradiction detection and resolution
- **Safety Filter** - Anti-creepy filter for sensitive information handling
- **Memory Graph** - Graph-based memory with multi-hop relationship queries
- **Custom Chat UI** - Built-in web UI with memory visualization and dashboard
- **Idris Type Verification** - Optional formal verification for memory integrity

## Installation

### From npm

```bash
openclaw plugins install @namsangboy/openclaw-plugin-axiommind
```

Then restart the Gateway.

### From source

```bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw/extensions/axiommind

# Install dependencies and build
npm install
npm run build

# Install as local plugin
openclaw plugins install -l ./extensions/axiommind
```

### Build the Web UI (optional)

```bash
cd extensions/axiommind/web
npm install
npm run build
```

## Configuration

After installation, configure the plugin in `~/.openclaw/openclaw.json`:

```json
{
  "plugins": {
    "entries": {
      "openclaw-plugin-axiommind": {
        "enabled": true,
        "config": {
          "embeddingProvider": "openclaw",
          "graduation": {
            "daysForVerified": 7,
            "daysForCertified": 30
          },
          "autoScheduler": {
            "enabled": true
          }
        }
      }
    }
  }
}
```

### Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `true` | Enable/disable the plugin |
| `dataDir` | string | `~/.openclaw/axiommind` | Data storage directory |
| `embeddingProvider` | string | `"openclaw"` | Embedding provider: `openclaw` (local, multilingual, free), `openai`, `cohere`, or `local` (TF-IDF fallback) |
| `graduation.daysForVerified` | number | `7` | Days before L2 → L3 auto-promotion |
| `graduation.daysForCertified` | number | `30` | Days before L3 → L4 auto-promotion |
| `graduation.daysForDemotion` | number | `90` | Days of inactivity before demotion |
| `graduation.confirmationThreshold` | number | `3` | Confirmations required for L2 → L3 |
| `similarity.threshold` | number | `0.85` | Duplicate detection threshold (0.0-1.0) |
| `autoScheduler.enabled` | boolean | `true` | Enable background auto-promotion |
| `autoScheduler.promotionCheckInterval` | number | `3600000` | Promotion check interval (ms) |
| `autoScheduler.consolidationInterval` | number | `21600000` | Consolidation interval (ms) |

### Environment Variables

| Variable | Description |
|----------|-------------|
| `AXIOMMIND_DATA_DIR` | Override data directory |
| `AXIOMMIND_AUTH_TOKEN` | Authentication token |
| `AXIOMMIND_DAYS_FOR_VERIFIED` | Override promotion days (L2 → L3) |
| `AXIOMMIND_DAYS_FOR_CERTIFIED` | Override promotion days (L3 → L4) |
| `AXIOMMIND_SIMILARITY_THRESHOLD` | Override similarity threshold |

## Memory Graduation Pipeline

| Stage | Name | Description | Promotion Criteria |
|-------|------|-------------|-------------------|
| L0 | Raw | Extracted from conversation | Automatic |
| L1 | Working | Stored in DuckDB | On extraction |
| L2 | Candidate | Passed Idris type check | `compile_status = 'success'` |
| L3 | Verified | Additional verification passed | Repeated confirmation or user approval |
| L4 | Certified | Long-term stable memory | 30 days retention + consistency check |

## Agent Tools

The plugin registers three agent tools:

| Tool | Description |
|------|-------------|
| `axiom_search` | Search memories by keywords, types, and stages |
| `axiom_recall` | Recall memories from a specific session |
| `axiom_save` | Save a new memory entry |

## Web UI

Access the built-in web UI at:

```
http://localhost:18789/ax?token=YOUR_GATEWAY_TOKEN&session=agent:axiommind:main
```

### Dashboard

```
http://localhost:18789/ax/dashboard
```

Shows memory statistics, stage distribution, top accessed memories, recent activity, and scheduler status.

## API Endpoints

All endpoints are prefixed with `/ax/api/`.

### Memory Search

```
GET /ax/api/search?keywords=coffee,preference&types=fact,decision&stages=working,verified
```

### Entries CRUD

```
GET    /ax/api/entries              # List entries (with pagination and filtering)
GET    /ax/api/entries/:id          # Get single entry
PUT    /ax/api/entries/:id          # Update entry
DELETE /ax/api/entries/:id          # Delete entry
```

### Graduation

```
GET  /ax/api/graduation/stats      # Graduation statistics
POST /ax/api/graduation/promote    # Manual promotion
```

### Conflicts

```
GET  /ax/api/conflicts             # List conflicts
POST /ax/api/conflicts/resolve     # Resolve a conflict
```

### Scheduler

```
GET  /ax/api/scheduler/stats                  # Scheduler statistics
POST /ax/api/scheduler/trigger-promotion      # Trigger manual promotion
POST /ax/api/scheduler/trigger-consolidation  # Trigger manual consolidation
POST /ax/api/scheduler/start                  # Start scheduler
POST /ax/api/scheduler/stop                   # Stop scheduler
```

### Dashboard

```
GET /ax/api/dashboard/stats          # Overall statistics
GET /ax/api/dashboard/top-accessed   # Most accessed memories
GET /ax/api/dashboard/activity       # Recent activity timeline
```

### Embeddings

```
GET /ax/api/embeddings/info          # Embedding provider info and cache stats
```

## Architecture

```
User Message
     |
     v
+------------------+
|  Intent Router   |  classifyIntent() + calculateMemoryScore()
+--------+---------+
         |
         v
+------------------+
| Action Decision  |  skip / cache_check / search / graph
+--------+---------+
         |
         v
+------------------+     +------------------+
| Semantic Cache   | <-> |  Memory Graph    |
+--------+---------+     +------------------+
         |
         v
+------------------+
|  Safety Filter   |  use / confirm / soft_hint / skip
+--------+---------+
         |
         v
+------------------+
| Light Context    |  ~300 tokens injected into agent context
+------------------+
```

### Intent Types

| Intent | Example |
|--------|---------|
| `direct_recall` | "Do you remember...?", "What did I say last time?" |
| `preference_query` | "Recommend something", "What should I drink?" |
| `project_resume` | "Continue where we left off" |
| `reference_resolve` | "That thing", "The method I mentioned" |
| `temporal_query` | "When did...", "How long ago..." |
| `multi_hop_query` | "The C that B recommended from A" |
| `contradiction_check` | "I think I said something different before" |
| `no_memory_needed` | General questions |

## Project Structure

```
extensions/axiommind/
├── index.ts                    # Plugin entry point
├── openclaw.plugin.json        # Plugin manifest
├── api/
│   ├── routes.ts               # REST API router
│   ├── static.ts               # Static file serving
│   └── auth.ts                 # Authentication
├── memory-pipeline/
│   ├── orchestrator.ts         # Pipeline orchestrator
│   ├── indexer.ts              # DuckDB indexing
│   ├── search.ts               # Memory search
│   ├── tools.ts                # Agent tools
│   ├── types.ts                # Type definitions
│   ├── graduation.ts           # Memory promotion logic
│   ├── conflict-resolver.ts    # Conflict detection & resolution
│   ├── intent-router.ts        # Intent classification & scoring
│   ├── message-handler.ts      # Unified message processing
│   ├── memory-graph.ts         # Graph-based memory
│   ├── semantic-cache.ts       # Semantic similarity cache
│   ├── safety-filter.ts        # Anti-creepy filter
│   ├── embeddings.ts           # Vector embedding module
│   ├── auto-scheduler.ts       # Background promotion scheduler
│   ├── context-extractor.ts    # Context extraction
│   ├── similarity.ts           # Similarity calculation
│   └── config.ts               # Configuration
├── idris/                      # Idris type definitions
│   └── src/LongTermMemory/
│       ├── MemorySchema.idr
│       └── GraduationSchema.idr
└── web/                        # Next.js web UI
    ├── app/
    └── features/
        ├── chat/               # Chat components
        ├── memory/             # Memory panel
        └── dashboard/          # Dashboard
```

## Data Storage

```
~/.openclaw/axiommind/
├── data/
│   └── memory.duckdb           # Memory database (DuckDB)
└── sessions/
    └── YYYY-MM-DD_NN.idr       # Idris session files
```

## Requirements

- **OpenClaw** >= 2026.1.26
- **Node.js** >= 22
- **DuckDB** (bundled via `better-sqlite3`)

## Troubleshooting

See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for detailed solutions.

### Quick Diagnostics

```bash
# Check gateway status
openclaw channels status --probe

# Check port
lsof -i :18789

# Check logs
tail -f /tmp/openclaw-gateway.log

# Check DB files
ls -la ~/.openclaw/axiommind/data/
```

## References

- [MemGPT](https://arxiv.org/abs/2310.08560) - 2-Tier memory architecture
- [Mem0](https://arxiv.org/abs/2504.19413) - Graph-based memory
- [Supermemory](https://supermemory.ai/research) - Temporal + Relational memory
- [Semantic Caching](https://redis.io/blog/what-is-semantic-caching/) - Cost optimization

## License

MIT