Yonexus — Project Plan

1) Goal

Build an OpenClaw plugin that models organization hierarchy and agent identities, supports supervisor relationships, provides query tools for agents, and uses shared memory per scope (org/department/team).

2) Core Concepts

Hierarchy: Organization → Department → Team → Agent
Supervisor: each agent may have exactly one supervisor
Identity: an agent can hold multiple identities across teams/departments
Schema-driven metadata: configurable fields with per-field queryability
Scope memory: shared memory for org/department/team (using memory_store, compatible with memory-lancedb-pro)

3) Storage Strategy

Structure & identity data: in-memory + JSON persistence (no memory_store)
Shared memory: memory_store keyed by scope (org:{id}, dept:{id}, team:{id})
Filesystem resources (OpenClaw install dir ${openclaw dir}):
- Create a data-only folder at ${openclaw dir}/yonexus (no plugin code here)
- yonexus/organizations/<org-name>/ contains: teams/, docs/, notes/, knowledge/, rules/, lessons/, workflows/
- On create_organization: create <org-name> folder and its subfolders
- On create_team: create organizations/<org-name>/teams/<team-name>/ with agents/, docs/, notes/, knowledge/, rules/, lessons/, workflows/
- On assign_identity: create organizations/<org-name>/teams/<team-name>/agents/<agent-id>/ with docs/, notes/, knowledge/, rules/, lessons/, workflows/

4) Permissions Model (B)

Roles:

Org Admin
Dept Admin
Team Lead
Agent

Rules:

Supervisor is not a role (no inherent permissions)
Registration not self-service
- only configured agent list or human via slash command

Permission matrix (recommended):

create_department → Org Admin
create_team → Org Admin, Dept Admin (same dept)
assign_identity → Org Admin, Dept Admin (same dept), Team Lead (same team)
register_agent → Org Admin, Dept Admin, Team Lead (scope-limited)
set_supervisor → Org Admin, Dept Admin (same dept)
query → all roles, but only schema fields with queryable: true

5) Schema Configuration (example)

{
  "position": { "type": "string", "queryable": true },
  "discord_user_id": { "type": "string", "queryable": true },
  "git_user_name": { "type": "string", "queryable": true },
  "department": { "type": "string", "queryable": false },
  "team": { "type": "string", "queryable": false }
}

6) Tool/API Surface (MVP)

create_organization(name)
create_department(name, orgId)
create_team(name, deptId)
register_agent(agentId, name)
assign_identity(agentId, deptId, teamId, meta)
set_supervisor(actor, agentId, supervisorId)
whoami(agentId) → identities + supervisor + roles
query_agents(filters, options) → list; supports eq | contains | regex

Query example:

{
  "filters": [
    {"field":"discord_user_id","op":"eq","value":"123"},
    {"field":"git_user_name","op":"regex","value":"^hang"}
  ],
  "options": {"limit": 20, "offset": 0}
}

7) Data Model (MVP)

Organization { id, name }
Department { id, name, orgId }
Team { id, name, deptId }
Agent { id, name, roles[] }
Identity { id, agentId, deptId, teamId, meta }
Supervisor { agentId, supervisorId }

8) Milestones

Phase 0 (Design)

finalize schema
confirm permission rules

Phase 1 (MVP)

storage + JSON persistence
core models + tools
query DSL
scope memory adapter

Phase 2 (v1)

policy refinements
better query pagination & filtering
management commands & validation

9) Project Structure (recommended)

openclaw-plugin-yonexus/
├─ plugin.json
├─ src/
│  ├─ index.ts
│  ├─ store/        # in-memory + JSON persistence
│  ├─ models/
│  ├─ permissions/
│  ├─ tools/
│  ├─ memory/
│  └─ utils/
├─ scripts/
│  └─ install.sh
├─ dist/
│  └─ yonexus/      # build output target
└─ data/
   └─ org.json

10) Install Script Requirement

Provide scripts/install.sh
It should register the OpenClaw plugin name as yonexus
Build artifacts must be placed into dist/yonexus

11) Notes & Decisions

Structure data is not stored in memory_store.
Shared memory uses memory_store (compatible with memory-lancedb-pro).
Queryable fields are whitelisted via schema.

4.3 KiB Raw Blame History