Borgmind

Name: Borgmind
Rating: 3.5 (1 reviews)
Author: mputiyon1985

By mputiyon1985 👁 50 views ▲ 0 votes

Multi-agent shared knowledge base plugin for OpenClaw fleet

GitHub

Install

npm install
```

Configuration Example

{
  "bootstrap": {
    "plugins": {
      "borgmind": {
        "enabled": true,
        "config": {
          "soulId": "pepper",
          "tursoUrl": "libsql://borgmind-mputiyon1985-mputiyon1985.aws-us-east-1.turso.io",
          "tursoToken": "<your-primary-token>",
          "tokens": {
            "pepper": "<pepper-token>",
            "jarvis": "<jarvis-token>",
            "tony": "<tony-token>",
            "rhodey": "<rhodey-token>"
          },
          "agentNames": {
            "main": "Pepper",
            "rocket": "Rocket",
            "groot": "Groot",
            "nebula": "Nebula",
            "rhodey": "Rhodey"
          }
        }
      }
    }
  }
}

README

# BorgMind Plugin — OpenClaw Gateway Plugin

Shared multi-agent persistent memory, knowledge graph, and inter-agent messaging built on Turso/libSQL.

**Version:** 1.0.0  
**License:** MIT

## Features

✅ **Shared Memory** — Any agent can read/write persistent memory entries  
✅ **Auto-Source-Tagging** — Every write is tagged with the writing agent's name  
✅ **Conflict Resolution** — Cross-agent overwrites are fully audited in `memory_log` table  
✅ **Force-Sync Reads** — `borgmind.recall(..., {fresh:true})` flushes the embedded replica before reading  
✅ **Knowledge Graph** — BFS-traversable shared knowledge (subject→predicate→object triples)  
✅ **Inter-Agent Messaging** — Send/receive messages via shared `comms` table  
✅ **Tiered Storage** — hot/warm/cold tiers with TTL support  
✅ **Tier Promotion** — Automatic promotion/demotion via libSQL (not cron)  

## Installation

```bash
cd ~/.openclaw/extensions/borgmind-plugin
npm install
```

## Configuration

> ⚠️ **Security:** Do NOT commit `openclaw.json` with plaintext tokens. Use env-var placeholders like `${BORGMIND_TOKEN_PEPPER}`. The plugin resolves `${VAR_NAME}` syntax against `process.env` at startup.

Add to your `openclaw.json` plugins section:

```json
{
  "bootstrap": {
    "plugins": {
      "borgmind": {
        "enabled": true,
        "config": {
          "soulId": "pepper",
          "tursoUrl": "libsql://borgmind-mputiyon1985-mputiyon1985.aws-us-east-1.turso.io",
          "tursoToken": "<your-primary-token>",
          "tokens": {
            "pepper": "<pepper-token>",
            "jarvis": "<jarvis-token>",
            "tony": "<tony-token>",
            "rhodey": "<rhodey-token>"
          },
          "agentNames": {
            "main": "Pepper",
            "rocket": "Rocket",
            "groot": "Groot",
            "nebula": "Nebula",
            "rhodey": "Rhodey"
          }
        }
      }
    }
  }
}
```

### Field Reference

| Field | Required | Description |
|---|---|---|
| `soulId` | No | Default soul ID if agentId not provided (default: `pepper`) |
| `tursoUrl` | Yes | Full `libsql://` URL to the Turso database |
| `tursoToken` | Yes | Primary/Pepper auth token (used as fallback for unknown agents) |
| `tokens` | No | Per-agent auth tokens override `tursoToken` |
| `agentNames` | No | Maps session agent IDs → display/source names |
| `enabled` | No | Set `false` to disable the plugin without removing config |

## Registered Tools

| Tool | Description |
|---|---|
| `borgmind.remember` | Write shared memory. Auto-tags source. Returns conflict warning. |
| `borgmind.recall` | Read memory by category+key. `{fresh:true}` force-syncs first. |
| `borgmind.search` | Search across all memory (LIKE match on category/key). |
| `borgmind.know` | Add a knowledge graph triple (subject→predicate→object). |
| `borgmind.ask` | BFS-traverse the knowledge graph from a starting subject. |
| `borgmind.send` | Send an inter-agent message (stored in shared `comms` category). |
| `borgmind.inbox` | List messages addressed to the current agent. |

### Tool Examples

```
// Write a memory
borgmind.remember({ category: "project.iat", key: "version", value: "2.3.1" })

// Read it
borgmind.recall({ category: "project.iat", key: "version" })

// Read fresh
borgmind.recall({ category: "project.iat", key: "version", options: { fresh: true } })

// Search
borgmind.search({ query: "iat", options: { tier: "hot" } })

// Add knowledge
borgmind.know({ subject: "iat", predicate: "hosted_on", object: "vercel" })

// Traverse
borgmind.ask({ subject: "iat" })

// Send message
borgmind.send({ recipient: "tony", message: "Deploy staging now" })

// Check inbox
borgmind.inbox({ options: { unreadOnly: true } })
```

## Conflict Resolution

When agent A writes `project.x/key` and agent B later writes the same key:
1. Detection: `written_by` in DB ≠ current agent
2. Audit: `memory_log` records `action='conflict_resolution'` with `old_value` + `new_value`
3. Supersession log is written (old record marked as superseded)
4. Agent B receives a warning: `"Key was previously written by A at [time]. Your write overwrote it."`
5. Last-write-wins (but fully auditable)

## Source Auto-Tagging

Inside tool execute handlers:
```js
const source = options.source ?? resolveSource(agentId, pluginCfg.agentNames);
```

So `borgmind.remember({category:'x', key:'y', value:'z'})` automatically tags `source='Pepper'` when called from Pepper's session, without the agent specifying it.

## Smoke Test

```bash
cd ~/.openclaw/extensions/borgmind-plugin
node test/test-smoke.js
```

The smoke test:
- Imports the BorgMind library directly (bypass the plugin registration)
- Writes a memory as pepper
- Reads it back
- Verifies source auto-tag
- Writes as tony to trigger conflict detection
- Verifies conflict logged in `memory_log`
- Tests knowledge graph traversal
- Tests inter-agent messaging
- Cleans up test rows

## Architecture

```
borgmind-plugin/
├── index.js          ← Plugin entry (definePluginEntry, hooks + 7 tool factories)
├── lib/
│   ├── borgmind.js   ← Main API (BorgMind.init, BorgMindInstance class)
│   ├── memory.js     ← write_memory, read_memory, search_memory, inbox
│   ├── graph.js      ← add_relationship, traverse
│   ├── souls.js      ← read_soul, update_soul, upsert_soul
│   ├── sync.js       ← syncReplica (turso embedded replica flush)
│   └── db.js         ← DB factory (initDb, getClient, closeAll)
├── schema.sql        ← Full DB schema (copy from workspace)
├── test/
│   └── test-smoke.js ← Independent smoke test
├── BUILD-LOG.md      ← Development log
└── README.md         ← This file
```

## Notes

- Uses Turso embedded replicas for low-latency local reads
- Schema is auto-applied on first init (all `CREATE TABLE IF NOT EXISTS`)
- No external sync engine needed — libSQL's embedded replica handles push/pull
- Tokens map: pepper (primary), jarvis, tony, rhodey all share the same DB
- `agent_end` hook triggers sync + close per session
- Tool factories receive `ctx.agentId` and `ctx.sessionKey` for multi-agent isolation

tools