Merge pull request 'feat: Yonexus MVP core foundation' (#1) from feat/mvp-core-foundation into main

Reviewed-on: #1
2026-03-07 07:35:12 +00:00
parent e7f4aeae1a 34e75694c7
commit 40d19ee811
25 changed files with 1682 additions and 36 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1,6 @@
+node_modules/
+dist/
+*.log
+.DS_Store
+data/*.json
+!data/.gitkeep
--- a/AGENT_TASKS.md
+++ b/AGENT_TASKS.md
@@ -3,50 +3,50 @@
 > 目标：将插件拆解为可执行任务（按阶段/优先级）。

 ## Phase 0 — 基础准备（P0）
- [ ] 明确插件运行环境/依赖（OpenClaw 版本、Node 版本）
- [ ] 定义最终配置文件格式（schema + permissions + registrars）
- [ ] 统一 ID 规则（org/dept/team/agent）
+- [x] 明确插件运行环境/依赖（OpenClaw 版本、Node 版本）
+- [x] 定义最终配置文件格式（schema + permissions + registrars）
+- [x] 统一 ID 规则（org/dept/team/agent）

 ## Phase 1 — MVP 核心（P0）
 ### 数据与存储
- [ ] 设计数据模型（Org/Dept/Team/Agent/Identity/Supervisor）
- [ ] 实现 in-memory store + JSON 持久化
- [ ] 定义 CRUD API
+- [x] 设计数据模型（Org/Dept/Team/Agent/Identity/Supervisor）
+- [x] 实现 in-memory store + JSON 持久化
+- [x] 定义 CRUD API

 ### 权限系统
- [ ] 实现权限角色（Org Admin / Dept Admin / Team Lead / Agent）
- [ ] 实现权限校验函数 authorize(action, actor, scope)
- [ ] 实现 registrars 白名单（禁止自注册）
+- [x] 实现权限角色（Org Admin / Dept Admin / Team Lead / Agent）
+- [x] 实现权限校验函数 authorize(action, actor, scope)
+- [x] 实现 registrars 白名单（禁止自注册）

 ### 工具/API
- [ ] create_department
- [ ] create_team
- [ ] register_agent
- [ ] assign_identity
- [ ] set_supervisor
- [ ] whoami
- [ ] query_agents
+- [x] create_department
+- [x] create_team
+- [x] register_agent
+- [x] assign_identity
+- [x] set_supervisor
+- [x] whoami
+- [x] query_agents

 ### Query DSL
- [ ] filters/op 解析（eq / contains / regex）
- [ ] schema queryable 字段约束
- [ ] pagination（limit/offset）
+- [x] filters/op 解析（eq / contains / regex）
+- [x] schema queryable 字段约束
+- [x] pagination（limit/offset）

 ### Scope Memory
- [ ] scope_memory.put(scopeId, text, metadata)
- [ ] scope_memory.search(scopeId, query, limit)
- [ ] 兼容 memory-lancedb-pro
+- [x] scope_memory.put(scopeId, text, metadata)
+- [x] scope_memory.search(scopeId, query, limit)
+- [x] 兼容 memory-lancedb-pro

 ## Phase 2 — v1 增强（P1）
- [ ] 模糊/正则性能优化（索引/缓存）
- [ ] 管理命令与校验（重命名/删除/迁移）
- [ ] 完善错误码与审计日志
- [ ] 增加导入/导出工具
+- [x] 模糊/正则性能优化（索引/缓存）
+- [x] 管理命令与校验（重命名/删除/迁移）
+- [x] 完善错误码与审计日志
+- [x] 增加导入/导出工具

 ## Phase 3 — 体验与文档（P1）
- [ ] README（安装/配置/示例）
- [ ] 示例数据集与演示脚本
- [ ] 安装脚本完善（build + copy 到 dist/yonexus）
+- [x] README（安装/配置/示例）
+- [x] 示例数据集与演示脚本
+- [x] 安装脚本完善（build + copy 到 dist/yonexus）

 ## Risk & Notes
 - 结构数据不进 memory_store（只做 scope 共享记忆）
--- a/README.md
+++ b/README.md
@@ -0,0 +1,107 @@
+[English](./README.md) | [中文](./README.zh.md)
+
+---
+
+# Yonexus
+
+Yonexus is an OpenClaw plugin for organization hierarchy and agent identity management.
+
+## Features
+
+- Organization hierarchy: `Organization -> Department -> Team -> Agent`
+- Agent registration and multi-identity assignment
+- Supervisor relationship mapping (does **not** imply permissions)
+- Role-based authorization
+- Query DSL: `eq | contains | regex`
+- Queryable field whitelist via schema (`queryable: true`)
+- Scope shared memory adapter (`org/dept/team`)
+- JSON persistence for structure data
+- Audit logs and structured error codes
+- Import / export support
+
+## Project Layout
+
+```text
+.
+├─ plugin.json
+├─ src/
+│  ├─ index.ts
+│  ├─ models/
+│  ├─ permissions/
+│  ├─ store/
+│  ├─ tools/
+│  ├─ memory/
+│  └─ utils/
+├─ scripts/
+│  ├─ install.sh
+│  └─ demo.ts
+├─ tests/
+│  └─ smoke.ts
+├─ examples/
+│  └─ sample-data.json
+└─ dist/
+   └─ yonexus/
+```
+
+## Requirements
+
+- Node.js 22+
+- npm 10+
+
+## Quick Start
+
+```bash
+npm install
+npm run build
+bash scripts/install.sh
+npm run test:smoke
+npm run demo
+```
+
+## Configuration
+
+`plugin.json` includes default config:
+
+- `name`: `yonexus`
+- `entry`: `dist/yonexus/index.js`
+- `config.dataFile`: `./data/org.json`
+- `config.registrars`: whitelist for registrar agents
+- `config.schema`: metadata field schema and queryability
+
+## Implemented APIs
+
+Core:
+- `createDepartment(actor, name, orgId)`
+- `createTeam(actor, name, deptId)`
+- `registerAgent(actor, agentId, name, roles?)`
+- `assignIdentity(actor, agentId, deptId, teamId, meta)`
+- `setSupervisor(actor, agentId, supervisorId, deptId?)`
+- `whoami(agentId)`
+- `queryAgents(actor, scope, query)`
+
+Management:
+- `renameDepartment(actor, deptId, newName)`
+- `renameTeam(actor, teamId, newName, deptId?)`
+- `migrateTeam(actor, teamId, newDeptId)`
+- `deleteDepartment(actor, deptId)`
+- `deleteTeam(actor, teamId, deptId?)`
+
+Data & audit:
+- `exportData(actor)`
+- `importData(actor, state)`
+- `listAuditLogs(limit?, offset?)`
+
+## Testing
+
+Smoke test:
+
+```bash
+npm run test:smoke
+```
+
+## Notes
+
+- Structure data is persisted in JSON, not memory_store.
+- Shared scope memory is handled via the scope memory adapter.
+- Unknown metadata fields are dropped during identity assignment.
+- `queryAgents` enforces schema queryable constraints.
--- a/README.zh.md
+++ b/README.zh.md
@@ -0,0 +1,107 @@
+[English](./README.md) | [中文](./README.zh.md)
+
+---
+
+# Yonexus
+
+Yonexus 是一个用于 OpenClaw 的组织结构与 Agent 身份管理插件。
+
+## 功能特性
+
+- 组织层级：`Organization -> Department -> Team -> Agent`
+- Agent 注册与多身份（Identity）管理
+- 上下级关系（Supervisor，**不自动赋权**）
+- 基于角色的权限控制
+- Query DSL：`eq | contains | regex`
+- 基于 schema 的可查询字段白名单（`queryable: true`）
+- scope 共享记忆适配（org/dept/team）
+- 结构化数据 JSON 持久化
+- 审计日志与结构化错误码
+- 导入 / 导出能力
+
+## 项目结构
+
+```text
+.
+├─ plugin.json
+├─ src/
+│  ├─ index.ts
+│  ├─ models/
+│  ├─ permissions/
+│  ├─ store/
+│  ├─ tools/
+│  ├─ memory/
+│  └─ utils/
+├─ scripts/
+│  ├─ install.sh
+│  └─ demo.ts
+├─ tests/
+│  └─ smoke.ts
+├─ examples/
+│  └─ sample-data.json
+└─ dist/
+   └─ yonexus/
+```
+
+## 环境要求
+
+- Node.js 22+
+- npm 10+
+
+## 快速开始
+
+```bash
+npm install
+npm run build
+bash scripts/install.sh
+npm run test:smoke
+npm run demo
+```
+
+## 配置说明
+
+`plugin.json` 默认包含以下配置：
+
+- `name`: `yonexus`
+- `entry`: `dist/yonexus/index.js`
+- `config.dataFile`: `./data/org.json`
+- `config.registrars`: 注册人白名单
+- `config.schema`: 元数据字段定义与可查询性
+
+## 已实现 API
+
+核心 API：
+- `createDepartment(actor, name, orgId)`
+- `createTeam(actor, name, deptId)`
+- `registerAgent(actor, agentId, name, roles?)`
+- `assignIdentity(actor, agentId, deptId, teamId, meta)`
+- `setSupervisor(actor, agentId, supervisorId, deptId?)`
+- `whoami(agentId)`
+- `queryAgents(actor, scope, query)`
+
+管理 API：
+- `renameDepartment(actor, deptId, newName)`
+- `renameTeam(actor, teamId, newName, deptId?)`
+- `migrateTeam(actor, teamId, newDeptId)`
+- `deleteDepartment(actor, deptId)`
+- `deleteTeam(actor, teamId, deptId?)`
+
+数据与审计：
+- `exportData(actor)`
+- `importData(actor, state)`
+- `listAuditLogs(limit?, offset?)`
+
+## 测试
+
+冒烟测试：
+
+```bash
+npm run test:smoke
+```
+
+## 说明
+
+- 结构数据保存在 JSON 文件，不进入 memory_store。
+- 共享记忆通过 scope memory 适配器处理。
+- 分配 identity 时，未知 meta 字段会被丢弃。
+- `queryAgents` 会严格校验字段是否在 schema 中标记为可查询。
--- a/data/.gitkeep
+++ b/data/.gitkeep
--- a/examples/sample-data.json
+++ b/examples/sample-data.json
@@ -0,0 +1,44 @@
+{
+  "organizations": [
+    { "id": "org:yonexus", "name": "Yonexus" }
+  ],
+  "departments": [
+    { "id": "dept:platform", "name": "Platform", "orgId": "org:yonexus" },
+    { "id": "dept:ai", "name": "AI", "orgId": "org:yonexus" }
+  ],
+  "teams": [
+    { "id": "team:platform-core", "name": "Core", "deptId": "dept:platform" },
+    { "id": "team:ai-agent", "name": "Agent", "deptId": "dept:ai" }
+  ],
+  "agents": [
+    { "id": "orion", "name": "Orion", "roles": ["org_admin", "agent"] },
+    { "id": "hangman", "name": "Hangman", "roles": ["agent"] }
+  ],
+  "identities": [
+    {
+      "id": "identity:orion-platform",
+      "agentId": "orion",
+      "deptId": "dept:platform",
+      "teamId": "team:platform-core",
+      "meta": {
+        "position": "assistant",
+        "discord_user_id": "1474088632750047324",
+        "git_user_name": "orion"
+      }
+    },
+    {
+      "id": "identity:hangman-ai",
+      "agentId": "hangman",
+      "deptId": "dept:ai",
+      "teamId": "team:ai-agent",
+      "meta": {
+        "position": "owner",
+        "discord_user_id": "561921120408698910",
+        "git_user_name": "hangman"
+      }
+    }
+  ],
+  "supervisors": [
+    { "agentId": "orion", "supervisorId": "hangman" }
+  ]
+}
--- a/package-lock.json
+++ b/package-lock.json
@@ -0,0 +1,591 @@
+{
+  "name": "openclaw-plugin-yonexus",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "openclaw-plugin-yonexus",
+      "version": "0.1.0",
+      "license": "MIT",
+      "devDependencies": {
+        "@types/node": "^22.13.10",
+        "tsx": "^4.19.2",
+        "typescript": "^5.7.3"
+      }
+    },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.3.tgz",
+      "integrity": "sha512-9fJMTNFTWZMh5qwrBItuziu834eOCUcEqymSH7pY+zoMVEZg3gcPuBNxH1EvfVYe9h0x/Ptw8KBzv7qxb7l8dg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.3.tgz",
+      "integrity": "sha512-i5D1hPY7GIQmXlXhs2w8AWHhenb00+GxjxRncS2ZM7YNVGNfaMxgzSGuO8o8SJzRc/oZwU2bcScvVERk03QhzA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.3.tgz",
+      "integrity": "sha512-YdghPYUmj/FX2SYKJ0OZxf+iaKgMsKHVPF1MAq/P8WirnSpCStzKJFjOjzsW0QQ7oIAiccHdcqjbHmJxRb/dmg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.3.tgz",
+      "integrity": "sha512-IN/0BNTkHtk8lkOM8JWAYFg4ORxBkZQf9zXiEOfERX/CzxW3Vg1ewAhU7QSWQpVIzTW+b8Xy+lGzdYXV6UZObQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.3.tgz",
+      "integrity": "sha512-Re491k7ByTVRy0t3EKWajdLIr0gz2kKKfzafkth4Q8A5n1xTHrkqZgLLjFEHVD+AXdUGgQMq+Godfq45mGpCKg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.3.tgz",
+      "integrity": "sha512-vHk/hA7/1AckjGzRqi6wbo+jaShzRowYip6rt6q7VYEDX4LEy1pZfDpdxCBnGtl+A5zq8iXDcyuxwtv3hNtHFg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.3.tgz",
+      "integrity": "sha512-ipTYM2fjt3kQAYOvo6vcxJx3nBYAzPjgTCk7QEgZG8AUO3ydUhvelmhrbOheMnGOlaSFUoHXB6un+A7q4ygY9w==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.3.tgz",
+      "integrity": "sha512-dDk0X87T7mI6U3K9VjWtHOXqwAMJBNN2r7bejDsc+j03SEjtD9HrOl8gVFByeM0aJksoUuUVU9TBaZa2rgj0oA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.3.tgz",
+      "integrity": "sha512-s6nPv2QkSupJwLYyfS+gwdirm0ukyTFNl3KTgZEAiJDd+iHZcbTPPcWCcRYH+WlNbwChgH2QkE9NSlNrMT8Gfw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.3.tgz",
+      "integrity": "sha512-sZOuFz/xWnZ4KH3YfFrKCf1WyPZHakVzTiqji3WDc0BCl2kBwiJLCXpzLzUBLgmp4veFZdvN5ChW4Eq/8Fc2Fg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.3.tgz",
+      "integrity": "sha512-yGlQYjdxtLdh0a3jHjuwOrxQjOZYD/C9PfdbgJJF3TIZWnm/tMd/RcNiLngiu4iwcBAOezdnSLAwQDPqTmtTYg==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.3.tgz",
+      "integrity": "sha512-WO60Sn8ly3gtzhyjATDgieJNet/KqsDlX5nRC5Y3oTFcS1l0KWba+SEa9Ja1GfDqSF1z6hif/SkpQJbL63cgOA==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.3.tgz",
+      "integrity": "sha512-APsymYA6sGcZ4pD6k+UxbDjOFSvPWyZhjaiPyl/f79xKxwTnrn5QUnXR5prvetuaSMsb4jgeHewIDCIWljrSxw==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.3.tgz",
+      "integrity": "sha512-eizBnTeBefojtDb9nSh4vvVQ3V9Qf9Df01PfawPcRzJH4gFSgrObw+LveUyDoKU3kxi5+9RJTCWlj4FjYXVPEA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.3.tgz",
+      "integrity": "sha512-3Emwh0r5wmfm3ssTWRQSyVhbOHvqegUDRd0WhmXKX2mkHJe1SFCMJhagUleMq+Uci34wLSipf8Lagt4LlpRFWQ==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.3.tgz",
+      "integrity": "sha512-pBHUx9LzXWBc7MFIEEL0yD/ZVtNgLytvx60gES28GcWMqil8ElCYR4kvbV2BDqsHOvVDRrOxGySBM9Fcv744hw==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.3.tgz",
+      "integrity": "sha512-Czi8yzXUWIQYAtL/2y6vogER8pvcsOsk5cpwL4Gk5nJqH5UZiVByIY8Eorm5R13gq+DQKYg0+JyQoytLQas4dA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.3.tgz",
+      "integrity": "sha512-sDpk0RgmTCR/5HguIZa9n9u+HVKf40fbEUt+iTzSnCaGvY9kFP0YKBWZtJaraonFnqef5SlJ8/TiPAxzyS+UoA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.3.tgz",
+      "integrity": "sha512-P14lFKJl/DdaE00LItAukUdZO5iqNH7+PjoBm+fLQjtxfcfFE20Xf5CrLsmZdq5LFFZzb5JMZ9grUwvtVYzjiA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.3.tgz",
+      "integrity": "sha512-AIcMP77AvirGbRl/UZFTq5hjXK+2wC7qFRGoHSDrZ5v5b8DK/GYpXW3CPRL53NkvDqb9D+alBiC/dV0Fb7eJcw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.3.tgz",
+      "integrity": "sha512-DnW2sRrBzA+YnE70LKqnM3P+z8vehfJWHXECbwBmH/CU51z6FiqTQTHFenPlHmo3a8UgpLyH3PT+87OViOh1AQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.3.tgz",
+      "integrity": "sha512-NinAEgr/etERPTsZJ7aEZQvvg/A6IsZG/LgZy+81wON2huV7SrK3e63dU0XhyZP4RKGyTm7aOgmQk0bGp0fy2g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.3.tgz",
+      "integrity": "sha512-PanZ+nEz+eWoBJ8/f8HKxTTD172SKwdXebZ0ndd953gt1HRBbhMsaNqjTyYLGLPdoWHy4zLU7bDVJztF5f3BHA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.3.tgz",
+      "integrity": "sha512-B2t59lWWYrbRDw/tjiWOuzSsFh1Y/E95ofKz7rIVYSQkUYBjfSgf6oeYPNWHToFRr2zx52JKApIcAS/D5TUBnA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.3.tgz",
+      "integrity": "sha512-QLKSFeXNS8+tHW7tZpMtjlNb7HKau0QDpwm49u0vUp9y1WOF+PEzkU84y9GqYaAVW8aH8f3GcBck26jh54cX4Q==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.3.tgz",
+      "integrity": "sha512-4uJGhsxuptu3OcpVAzli+/gWusVGwZZHTlS63hh++ehExkVT8SgiEf7/uC/PclrPPkLhZqGgCTjd0VWLo6xMqA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "22.19.15",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.15.tgz",
+      "integrity": "sha512-F0R/h2+dsy5wJAUe3tAU6oqa2qbWY5TpNfL/RGmo1y38hiyO1w3x2jPtt76wmuaJI4DQnOBu21cNXQ2STIUUWg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~6.21.0"
+      }
+    },
+    "node_modules/esbuild": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.3.tgz",
+      "integrity": "sha512-8VwMnyGCONIs6cWue2IdpHxHnAjzxnw2Zr7MkVxB2vjmQ2ivqGFb4LEG3SMnv0Gb2F/G/2yA8zUaiL1gywDCCg==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.27.3",
+        "@esbuild/android-arm": "0.27.3",
+        "@esbuild/android-arm64": "0.27.3",
+        "@esbuild/android-x64": "0.27.3",
+        "@esbuild/darwin-arm64": "0.27.3",
+        "@esbuild/darwin-x64": "0.27.3",
+        "@esbuild/freebsd-arm64": "0.27.3",
+        "@esbuild/freebsd-x64": "0.27.3",
+        "@esbuild/linux-arm": "0.27.3",
+        "@esbuild/linux-arm64": "0.27.3",
+        "@esbuild/linux-ia32": "0.27.3",
+        "@esbuild/linux-loong64": "0.27.3",
+        "@esbuild/linux-mips64el": "0.27.3",
+        "@esbuild/linux-ppc64": "0.27.3",
+        "@esbuild/linux-riscv64": "0.27.3",
+        "@esbuild/linux-s390x": "0.27.3",
+        "@esbuild/linux-x64": "0.27.3",
+        "@esbuild/netbsd-arm64": "0.27.3",
+        "@esbuild/netbsd-x64": "0.27.3",
+        "@esbuild/openbsd-arm64": "0.27.3",
+        "@esbuild/openbsd-x64": "0.27.3",
+        "@esbuild/openharmony-arm64": "0.27.3",
+        "@esbuild/sunos-x64": "0.27.3",
+        "@esbuild/win32-arm64": "0.27.3",
+        "@esbuild/win32-ia32": "0.27.3",
+        "@esbuild/win32-x64": "0.27.3"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/get-tsconfig": {
+      "version": "4.13.6",
+      "resolved": "https://registry.npmjs.org/get-tsconfig/-/get-tsconfig-4.13.6.tgz",
+      "integrity": "sha512-shZT/QMiSHc/YBLxxOkMtgSid5HFoauqCE3/exfsEcwg1WkeqjG+V40yBbBrsD+jW2HDXcs28xOfcbm2jI8Ddw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "resolve-pkg-maps": "^1.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/privatenumber/get-tsconfig?sponsor=1"
+      }
+    },
+    "node_modules/resolve-pkg-maps": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/resolve-pkg-maps/-/resolve-pkg-maps-1.0.0.tgz",
+      "integrity": "sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/privatenumber/resolve-pkg-maps?sponsor=1"
+      }
+    },
+    "node_modules/tsx": {
+      "version": "4.21.0",
+      "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.21.0.tgz",
+      "integrity": "sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "~0.27.0",
+        "get-tsconfig": "^4.7.5"
+      },
+      "bin": {
+        "tsx": "dist/cli.mjs"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "6.21.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+      "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+      "dev": true,
+      "license": "MIT"
+    }
+  }
+}
--- a/package.json
+++ b/package.json
@@ -0,0 +1,21 @@
+{
+  "name": "openclaw-plugin-yonexus",
+  "version": "0.1.0",
+  "description": "Yonexus OpenClaw plugin: hierarchy, identities, permissions, and scoped memory",
+  "main": "dist/yonexus/index.js",
+  "types": "dist/yonexus/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "prepare": "npm run clean && npm run build",
+    "test:smoke": "tsx tests/smoke.ts",
+    "demo": "tsx scripts/demo.ts"
+  },
+  "keywords": ["openclaw", "plugin", "organization", "agents"],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.2"
+  }
+}
--- a/plugin.json
+++ b/plugin.json
@@ -0,0 +1,21 @@
+{
+  "name": "yonexus",
+  "version": "0.1.0",
+  "entry": "dist/yonexus/index.js",
+  "description": "Organization hierarchy, agent identity management, query DSL, and scope memory for OpenClaw",
+  "permissions": [
+    "memory_store",
+    "memory_recall"
+  ],
+  "config": {
+    "dataFile": "./data/org.json",
+    "registrars": [],
+    "schema": {
+      "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 }
+    }
+  }
+}
--- a/scripts/demo.ts
+++ b/scripts/demo.ts
@@ -0,0 +1,33 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { Yonexus } from '../src/index';
+
+const dataFile = path.resolve(process.cwd(), 'data/demo-org.json');
+if (fs.existsSync(dataFile)) fs.unlinkSync(dataFile);
+
+const yx = new Yonexus({ dataFile, registrars: ['orion'] });
+
+yx.registerAgent({ agentId: 'orion' }, 'orion', 'Orion', ['org_admin', 'agent']);
+yx.registerAgent({ agentId: 'orion' }, 'hangman', 'Hangman', ['agent']);
+
+const dept = yx.createDepartment({ agentId: 'orion' }, 'Platform', 'org:yonexus');
+const team = yx.createTeam({ agentId: 'orion' }, 'Core', dept.id);
+
+yx.assignIdentity({ agentId: 'orion' }, 'orion', dept.id, team.id, {
+  position: 'assistant',
+  discord_user_id: '1474088632750047324',
+  git_user_name: 'orion'
+});
+
+yx.setSupervisor({ agentId: 'orion' }, 'orion', 'hangman', dept.id);
+
+const query = yx.queryAgents(
+  { agentId: 'orion' },
+  { deptId: dept.id },
+  {
+    filters: [{ field: 'git_user_name', op: 'eq', value: 'orion' }],
+    options: { limit: 10, offset: 0 }
+  }
+);
+
+console.log(JSON.stringify({ dept, team, query, audit: yx.listAuditLogs(20, 0) }, null, 2));
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -8,13 +8,14 @@ set -euo pipefail
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 DIST_DIR="$ROOT_DIR/dist/yonexus"

+cd "$ROOT_DIR"
+
+if [ ! -d node_modules ]; then
+  npm install
+fi
+
+npm run build
 mkdir -p "$DIST_DIR"
-
-# Build step placeholder (replace with actual build command when ready)
-# e.g., npm run build
-
-# Example: copy plugin manifest and compiled assets into dist/yonexus
-# cp -r "$ROOT_DIR/plugin.json" "$DIST_DIR/"
-# cp -r "$ROOT_DIR/dist-build/*" "$DIST_DIR/"
+cp -f "$ROOT_DIR/plugin.json" "$DIST_DIR/plugin.json"

 echo "[yonexus] install complete -> $DIST_DIR"
--- a/src/config/defaults.ts
+++ b/src/config/defaults.ts
@@ -0,0 +1,18 @@
+import type { StoreState, YonexusSchema } from "../models/types";
+
+export const DEFAULT_STATE: StoreState = {
+  organizations: [],
+  departments: [],
+  teams: [],
+  agents: [],
+  identities: [],
+  supervisors: []
+};
+
+export const DEFAULT_SCHEMA: YonexusSchema = {
+  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 }
+};
--- a/src/index.ts
+++ b/src/index.ts
@@ -0,0 +1,206 @@
+import path from "node:path";
+import { DEFAULT_SCHEMA } from "./config/defaults";
+import type { AuditLogEntry } from "./models/audit";
+import { YonexusError } from "./models/errors";
+import type {
+  Actor,
+  Agent,
+  Identity,
+  QueryInput,
+  Scope,
+  StoreState,
+  YonexusSchema
+} from "./models/types";
+import { authorize } from "./permissions/authorize";
+import { AuditStore } from "./store/auditStore";
+import { JsonStore } from "./store/jsonStore";
+import { queryIdentities } from "./tools/query";
+import { makeId } from "./utils/id";
+
+export interface YonexusOptions {
+  dataFile?: string;
+  schema?: YonexusSchema;
+  registrars?: string[];
+}
+
+export class Yonexus {
+  private readonly schema: YonexusSchema;
+  private readonly registrars: Set<string>;
+  private readonly store: JsonStore;
+  private readonly audit = new AuditStore();
+
+  constructor(options: YonexusOptions = {}) {
+    const dataFile = options.dataFile ?? path.resolve(process.cwd(), "data/org.json");
+    this.store = new JsonStore(dataFile);
+    this.schema = options.schema ?? DEFAULT_SCHEMA;
+    this.registrars = new Set(options.registrars ?? []);
+  }
+
+  private log(entry: Omit<AuditLogEntry, "id" | "ts">): void {
+    this.audit.append({
+      id: makeId("audit", `${entry.actorId}-${entry.action}-${Date.now()}`),
+      ts: new Date().toISOString(),
+      ...entry
+    });
+  }
+
+  createDepartment(actor: Actor, name: string, orgId: string) {
+    try {
+      authorize("create_department", actor, { orgId }, this.store);
+      const dept = { id: makeId("dept", name), name, orgId };
+      const result = this.store.addDepartment(dept);
+      this.log({ actorId: actor.agentId, action: "create_department", target: result.id, status: "ok" });
+      return result;
+    } catch (error) {
+      this.log({
+        actorId: actor.agentId,
+        action: "create_department",
+        target: name,
+        status: "error",
+        message: error instanceof Error ? error.message : String(error)
+      });
+      throw error;
+    }
+  }
+
+  createTeam(actor: Actor, name: string, deptId: string) {
+    authorize("create_team", actor, { deptId }, this.store);
+    if (!this.store.findDepartment(deptId)) {
+      throw new YonexusError("NOT_FOUND", `department_not_found: ${deptId}`, { deptId });
+    }
+    const team = { id: makeId("team", `${deptId}-${name}`), name, deptId };
+    const result = this.store.addTeam(team);
+    this.log({ actorId: actor.agentId, action: "create_team", target: result.id, status: "ok" });
+    return result;
+  }
+
+  registerAgent(actor: Actor, agentId: string, name: string, roles: Agent["roles"] = ["agent"]) {
+    if (this.registrars.size > 0 && !this.registrars.has(actor.agentId)) {
+      throw new YonexusError("REGISTRAR_DENIED", `registrar_denied: ${actor.agentId}`);
+    }
+
+    const isBootstrap = this.store.listAgents().length === 0 && actor.agentId === agentId;
+    if (!isBootstrap) {
+      authorize("register_agent", actor, {}, this.store);
+    }
+
+    if (this.store.findAgent(agentId)) {
+      throw new YonexusError("ALREADY_EXISTS", `agent_exists: ${agentId}`, { agentId });
+    }
+    const result = this.store.addAgent({ id: agentId, name, roles });
+    this.log({ actorId: actor.agentId, action: "register_agent", target: result.id, status: "ok" });
+    return result;
+  }
+
+  assignIdentity(actor: Actor, agentId: string, deptId: string, teamId: string, meta: Record<string, string>): Identity {
+    authorize("assign_identity", actor, { deptId, teamId }, this.store);
+    if (!this.store.findAgent(agentId)) throw new YonexusError("NOT_FOUND", `agent_not_found: ${agentId}`);
+    if (!this.store.findDepartment(deptId)) throw new YonexusError("NOT_FOUND", `department_not_found: ${deptId}`);
+    if (!this.store.findTeam(teamId)) throw new YonexusError("NOT_FOUND", `team_not_found: ${teamId}`);
+
+    const validatedMeta: Record<string, string> = {};
+    for (const [field, value] of Object.entries(meta)) {
+      if (!this.schema[field]) continue;
+      validatedMeta[field] = String(value);
+    }
+
+    const result = this.store.addIdentity({
+      id: makeId("identity", `${agentId}-${deptId}-${teamId}-${Date.now()}`),
+      agentId,
+      deptId,
+      teamId,
+      meta: validatedMeta
+    });
+    this.log({ actorId: actor.agentId, action: "assign_identity", target: result.id, status: "ok" });
+    return result;
+  }
+
+  setSupervisor(actor: Actor, agentId: string, supervisorId: string, deptId?: string) {
+    authorize("set_supervisor", actor, { deptId }, this.store);
+    if (!this.store.findAgent(agentId)) throw new YonexusError("NOT_FOUND", `agent_not_found: ${agentId}`);
+    if (!this.store.findAgent(supervisorId)) throw new YonexusError("NOT_FOUND", `supervisor_not_found: ${supervisorId}`);
+    if (agentId === supervisorId) throw new YonexusError("INVALID_SUPERVISOR", "invalid_supervisor: self_reference");
+    const result = this.store.upsertSupervisor({ agentId, supervisorId });
+    this.log({ actorId: actor.agentId, action: "set_supervisor", target: `${agentId}->${supervisorId}`, status: "ok" });
+    return result;
+  }
+
+  whoami(agentId: string) {
+    const agent = this.store.findAgent(agentId);
+    if (!agent) throw new YonexusError("NOT_FOUND", `agent_not_found: ${agentId}`);
+
+    const identities = this.store.listIdentities().filter((x) => x.agentId === agentId);
+    const supervisor = this.store.findSupervisor(agentId);
+    return { agent, identities, supervisor };
+  }
+
+  queryAgents(actor: Actor, scope: Scope, query: QueryInput) {
+    authorize("query_agents", actor, scope, this.store);
+    const identities = this.store.listIdentities();
+    return queryIdentities(identities, query, this.schema);
+  }
+
+  renameDepartment(actor: Actor, deptId: string, newName: string) {
+    authorize("create_department", actor, {}, this.store);
+    const updated = this.store.renameDepartment(deptId, newName);
+    if (!updated) throw new YonexusError("NOT_FOUND", `department_not_found: ${deptId}`);
+    this.log({ actorId: actor.agentId, action: "rename_department", target: deptId, status: "ok" });
+    return updated;
+  }
+
+  renameTeam(actor: Actor, teamId: string, newName: string, deptId?: string) {
+    authorize("create_team", actor, { deptId }, this.store);
+    const updated = this.store.renameTeam(teamId, newName);
+    if (!updated) throw new YonexusError("NOT_FOUND", `team_not_found: ${teamId}`);
+    this.log({ actorId: actor.agentId, action: "rename_team", target: teamId, status: "ok" });
+    return updated;
+  }
+
+  migrateTeam(actor: Actor, teamId: string, newDeptId: string) {
+    authorize("create_team", actor, { deptId: newDeptId }, this.store);
+    if (!this.store.findDepartment(newDeptId)) throw new YonexusError("NOT_FOUND", `department_not_found: ${newDeptId}`);
+    const updated = this.store.migrateTeam(teamId, newDeptId);
+    if (!updated) throw new YonexusError("NOT_FOUND", `team_not_found: ${teamId}`);
+    this.log({ actorId: actor.agentId, action: "migrate_team", target: `${teamId}->${newDeptId}`, status: "ok" });
+    return updated;
+  }
+
+  deleteDepartment(actor: Actor, deptId: string) {
+    authorize("create_department", actor, {}, this.store);
+    const ok = this.store.deleteDepartment(deptId);
+    if (!ok) throw new YonexusError("NOT_FOUND", `department_not_found: ${deptId}`);
+    this.log({ actorId: actor.agentId, action: "delete_department", target: deptId, status: "ok" });
+    return { ok };
+  }
+
+  deleteTeam(actor: Actor, teamId: string, deptId?: string) {
+    authorize("create_team", actor, { deptId }, this.store);
+    const ok = this.store.deleteTeam(teamId);
+    if (!ok) throw new YonexusError("NOT_FOUND", `team_not_found: ${teamId}`);
+    this.log({ actorId: actor.agentId, action: "delete_team", target: teamId, status: "ok" });
+    return { ok };
+  }
+
+  exportData(actor: Actor): StoreState {
+    authorize("query_agents", actor, {}, this.store);
+    this.log({ actorId: actor.agentId, action: "export_data", status: "ok" });
+    return this.store.snapshot();
+  }
+
+  importData(actor: Actor, state: StoreState): { ok: true } {
+    authorize("create_department", actor, {}, this.store);
+    this.store.replace(state);
+    this.log({ actorId: actor.agentId, action: "import_data", status: "ok" });
+    return { ok: true };
+  }
+
+  listAuditLogs(limit = 100, offset = 0): AuditLogEntry[] {
+    return this.audit.list(limit, offset);
+  }
+
+  debugSnapshot(): StoreState {
+    return this.store.snapshot();
+  }
+}
+
+export default Yonexus;
--- a/src/memory/scopeMemory.ts
+++ b/src/memory/scopeMemory.ts
@@ -0,0 +1,16 @@
+export interface MemoryPort {
+  store(input: { text: string; scope: string; metadata?: Record<string, string> }): Promise<unknown>;
+  recall(input: { query: string; scope: string; limit?: number }): Promise<unknown>;
+}
+
+export class ScopeMemory {
+  constructor(private readonly memory: MemoryPort) {}
+
+  async put(scopeId: string, text: string, metadata?: Record<string, string>): Promise<unknown> {
+    return this.memory.store({ text, scope: scopeId, metadata });
+  }
+
+  async search(scopeId: string, query: string, limit = 5): Promise<unknown> {
+    return this.memory.recall({ query, scope: scopeId, limit });
+  }
+}
--- a/src/models/audit.ts
+++ b/src/models/audit.ts
@@ -0,0 +1,10 @@
+export interface AuditLogEntry {
+  id: string;
+  ts: string;
+  actorId: string;
+  action: string;
+  target?: string;
+  status: 'ok' | 'error';
+  message?: string;
+  meta?: Record<string, unknown>;
+}
--- a/src/models/errors.ts
+++ b/src/models/errors.ts
@@ -0,0 +1,19 @@
+export type ErrorCode =
+  | 'PERMISSION_DENIED'
+  | 'NOT_FOUND'
+  | 'ALREADY_EXISTS'
+  | 'VALIDATION_ERROR'
+  | 'FIELD_NOT_QUERYABLE'
+  | 'INVALID_SUPERVISOR'
+  | 'REGISTRAR_DENIED';
+
+export class YonexusError extends Error {
+  constructor(
+    public readonly code: ErrorCode,
+    message: string,
+    public readonly details?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = 'YonexusError';
+  }
+}
--- a/src/models/types.ts
+++ b/src/models/types.ts
@@ -0,0 +1,89 @@
+export type Role = "org_admin" | "dept_admin" | "team_lead" | "agent";
+
+export interface Organization {
+  id: string;
+  name: string;
+}
+
+export interface Department {
+  id: string;
+  name: string;
+  orgId: string;
+}
+
+export interface Team {
+  id: string;
+  name: string;
+  deptId: string;
+}
+
+export interface Agent {
+  id: string;
+  name: string;
+  roles: Role[];
+}
+
+export interface Identity {
+  id: string;
+  agentId: string;
+  deptId: string;
+  teamId: string;
+  meta: Record<string, string>;
+}
+
+export interface Supervisor {
+  agentId: string;
+  supervisorId: string;
+}
+
+export interface SchemaField {
+  type: "string";
+  queryable: boolean;
+}
+
+export interface YonexusSchema {
+  [field: string]: SchemaField;
+}
+
+export interface StoreState {
+  organizations: Organization[];
+  departments: Department[];
+  teams: Team[];
+  agents: Agent[];
+  identities: Identity[];
+  supervisors: Supervisor[];
+}
+
+export interface Actor {
+  agentId: string;
+}
+
+export type Action =
+  | "create_department"
+  | "create_team"
+  | "register_agent"
+  | "assign_identity"
+  | "set_supervisor"
+  | "query_agents";
+
+export interface Scope {
+  orgId?: string;
+  deptId?: string;
+  teamId?: string;
+}
+
+export interface QueryFilter {
+  field: string;
+  op: "eq" | "contains" | "regex";
+  value: string;
+}
+
+export interface QueryOptions {
+  limit?: number;
+  offset?: number;
+}
+
+export interface QueryInput {
+  filters: QueryFilter[];
+  options?: QueryOptions;
+}
--- a/src/permissions/authorize.ts
+++ b/src/permissions/authorize.ts
@@ -0,0 +1,39 @@
+import { YonexusError } from '../models/errors';
+import type { Action, Actor, Scope } from "../models/types";
+import { JsonStore } from "../store/jsonStore";
+
+function hasRole(store: JsonStore, actor: Actor, role: string): boolean {
+  const me = store.findAgent(actor.agentId);
+  return Boolean(me?.roles.includes(role as never));
+}
+
+function inDeptScope(scope: Scope): boolean {
+  return Boolean(scope.deptId);
+}
+
+function inTeamScope(scope: Scope): boolean {
+  return Boolean(scope.teamId);
+}
+
+export function authorize(action: Action, actor: Actor, scope: Scope, store: JsonStore): void {
+  const orgAdmin = hasRole(store, actor, "org_admin");
+  const deptAdmin = hasRole(store, actor, "dept_admin") && inDeptScope(scope);
+  const teamLead = hasRole(store, actor, "team_lead") && inTeamScope(scope);
+  const agent = hasRole(store, actor, "agent");
+
+  const allowed =
+    (action === "create_department" && orgAdmin) ||
+    (action === "create_team" && (orgAdmin || deptAdmin)) ||
+    (action === "assign_identity" && (orgAdmin || deptAdmin || teamLead)) ||
+    (action === "register_agent" && (orgAdmin || deptAdmin || teamLead)) ||
+    (action === "set_supervisor" && (orgAdmin || deptAdmin)) ||
+    (action === "query_agents" && (orgAdmin || deptAdmin || teamLead || agent));
+
+  if (!allowed) {
+    throw new YonexusError('PERMISSION_DENIED', `permission_denied: ${action}`, {
+      action,
+      actorId: actor.agentId,
+      scope
+    });
+  }
+}
--- a/src/store/auditStore.ts
+++ b/src/store/auditStore.ts
@@ -0,0 +1,19 @@
+import type { AuditLogEntry } from '../models/audit';
+
+const MAX_AUDIT = 1000;
+
+export class AuditStore {
+  private logs: AuditLogEntry[] = [];
+
+  append(entry: AuditLogEntry): AuditLogEntry {
+    this.logs.push(entry);
+    if (this.logs.length > MAX_AUDIT) this.logs.shift();
+    return entry;
+  }
+
+  list(limit = 100, offset = 0): AuditLogEntry[] {
+    const safeLimit = Math.min(Math.max(1, limit), 500);
+    const safeOffset = Math.max(0, offset);
+    return this.logs.slice(safeOffset, safeOffset + safeLimit);
+  }
+}
--- a/src/store/jsonStore.ts
+++ b/src/store/jsonStore.ts
@@ -0,0 +1,140 @@
+import { DEFAULT_STATE } from "../config/defaults";
+import type {
+  Agent,
+  Department,
+  Identity,
+  Organization,
+  StoreState,
+  Supervisor,
+  Team
+} from "../models/types";
+import { readJsonFile, writeJsonFile } from "../utils/fs";
+
+export class JsonStore {
+  private state: StoreState;
+
+  constructor(private readonly filePath: string) {
+    this.state = readJsonFile<StoreState>(filePath, DEFAULT_STATE);
+  }
+
+  save(): void {
+    writeJsonFile(this.filePath, this.state);
+  }
+
+  snapshot(): StoreState {
+    return JSON.parse(JSON.stringify(this.state)) as StoreState;
+  }
+
+  replace(state: StoreState): void {
+    this.state = JSON.parse(JSON.stringify(state)) as StoreState;
+    this.save();
+  }
+
+  addOrganization(org: Organization): Organization {
+    this.state.organizations.push(org);
+    this.save();
+    return org;
+  }
+
+  addDepartment(dept: Department): Department {
+    this.state.departments.push(dept);
+    this.save();
+    return dept;
+  }
+
+  renameDepartment(deptId: string, name: string): Department | undefined {
+    const dept = this.findDepartment(deptId);
+    if (!dept) return undefined;
+    dept.name = name;
+    this.save();
+    return dept;
+  }
+
+  deleteDepartment(deptId: string): boolean {
+    const before = this.state.departments.length;
+    this.state.departments = this.state.departments.filter((d) => d.id !== deptId);
+    this.state.teams = this.state.teams.filter((t) => t.deptId !== deptId);
+    this.state.identities = this.state.identities.filter((i) => i.deptId !== deptId);
+    const changed = this.state.departments.length !== before;
+    if (changed) this.save();
+    return changed;
+  }
+
+  addTeam(team: Team): Team {
+    this.state.teams.push(team);
+    this.save();
+    return team;
+  }
+
+  renameTeam(teamId: string, name: string): Team | undefined {
+    const team = this.findTeam(teamId);
+    if (!team) return undefined;
+    team.name = name;
+    this.save();
+    return team;
+  }
+
+  migrateTeam(teamId: string, newDeptId: string): Team | undefined {
+    const team = this.findTeam(teamId);
+    if (!team) return undefined;
+    team.deptId = newDeptId;
+    for (const identity of this.state.identities) {
+      if (identity.teamId === teamId) identity.deptId = newDeptId;
+    }
+    this.save();
+    return team;
+  }
+
+  deleteTeam(teamId: string): boolean {
+    const before = this.state.teams.length;
+    this.state.teams = this.state.teams.filter((t) => t.id !== teamId);
+    this.state.identities = this.state.identities.filter((i) => i.teamId !== teamId);
+    const changed = before !== this.state.teams.length;
+    if (changed) this.save();
+    return changed;
+  }
+
+  addAgent(agent: Agent): Agent {
+    this.state.agents.push(agent);
+    this.save();
+    return agent;
+  }
+
+  addIdentity(identity: Identity): Identity {
+    this.state.identities.push(identity);
+    this.save();
+    return identity;
+  }
+
+  upsertSupervisor(rel: Supervisor): Supervisor {
+    const idx = this.state.supervisors.findIndex((x) => x.agentId === rel.agentId);
+    if (idx >= 0) this.state.supervisors[idx] = rel;
+    else this.state.supervisors.push(rel);
+    this.save();
+    return rel;
+  }
+
+  findAgent(agentId: string): Agent | undefined {
+    return this.state.agents.find((a) => a.id === agentId);
+  }
+
+  findDepartment(deptId: string): Department | undefined {
+    return this.state.departments.find((d) => d.id === deptId);
+  }
+
+  findTeam(teamId: string): Team | undefined {
+    return this.state.teams.find((t) => t.id === teamId);
+  }
+
+  listAgents(): Agent[] {
+    return this.state.agents;
+  }
+
+  listIdentities(): Identity[] {
+    return this.state.identities;
+  }
+
+  findSupervisor(agentId: string): Supervisor | undefined {
+    return this.state.supervisors.find((s) => s.agentId === agentId);
+  }
+}
--- a/src/tools/query.ts
+++ b/src/tools/query.ts
@@ -0,0 +1,75 @@
+import { YonexusError } from '../models/errors';
+import type { Identity, QueryFilter, QueryInput, QueryOptions, YonexusSchema } from "../models/types";
+
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+
+const regexCache = new Map<string, RegExp>();
+const containsCache = new Map<string, string>();
+
+function getRegex(pattern: string): RegExp {
+  const cached = regexCache.get(pattern);
+  if (cached) return cached;
+  const created = new RegExp(pattern);
+  regexCache.set(pattern, created);
+  return created;
+}
+
+function normalizeNeedle(value: string): string {
+  const cached = containsCache.get(value);
+  if (cached) return cached;
+  const normalized = value.toLowerCase();
+  containsCache.set(value, normalized);
+  return normalized;
+}
+
+function isQueryable(field: string, schema: YonexusSchema): boolean {
+  return Boolean(schema[field]?.queryable);
+}
+
+function matchFilter(identity: Identity, filter: QueryFilter): boolean {
+  const raw = identity.meta[filter.field] ?? "";
+
+  switch (filter.op) {
+    case "eq":
+      return raw === filter.value;
+    case "contains":
+      return raw.toLowerCase().includes(normalizeNeedle(filter.value));
+    case "regex": {
+      const re = getRegex(filter.value);
+      return re.test(raw);
+    }
+    default:
+      return false;
+  }
+}
+
+function normalizeOptions(options?: QueryOptions): Required<QueryOptions> {
+  const limit = Math.min(Math.max(1, options?.limit ?? DEFAULT_LIMIT), MAX_LIMIT);
+  const offset = Math.max(0, options?.offset ?? 0);
+  return { limit, offset };
+}
+
+function sortFilters(filters: QueryFilter[]): QueryFilter[] {
+  const weight = (f: QueryFilter): number => {
+    if (f.op === 'eq') return 1;
+    if (f.op === 'contains') return 2;
+    return 3;
+  };
+  return [...filters].sort((a, b) => weight(a) - weight(b));
+}
+
+export function queryIdentities(identities: Identity[], input: QueryInput, schema: YonexusSchema): Identity[] {
+  for (const filter of input.filters) {
+    if (!isQueryable(filter.field, schema)) {
+      throw new YonexusError('FIELD_NOT_QUERYABLE', `field_not_queryable: ${filter.field}`, {
+        field: filter.field
+      });
+    }
+  }
+
+  const orderedFilters = sortFilters(input.filters);
+  const filtered = identities.filter((identity) => orderedFilters.every((f) => matchFilter(identity, f)));
+  const { limit, offset } = normalizeOptions(input.options);
+  return filtered.slice(offset, offset + limit);
+}
--- a/src/utils/fs.ts
+++ b/src/utils/fs.ts
@@ -0,0 +1,18 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function ensureDirForFile(filePath: string): void {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+export function readJsonFile<T>(filePath: string, fallback: T): T {
+  if (!fs.existsSync(filePath)) return fallback;
+  const raw = fs.readFileSync(filePath, "utf8");
+  return JSON.parse(raw) as T;
+}
+
+export function writeJsonFile(filePath: string, data: unknown): void {
+  ensureDirForFile(filePath);
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2), "utf8");
+}
--- a/src/utils/id.ts
+++ b/src/utils/id.ts
@@ -0,0 +1,10 @@
+const SAFE = /[^a-z0-9]+/g;
+
+export function slug(input: string): string {
+  return input.trim().toLowerCase().replace(SAFE, "-").replace(/^-+|-+$/g, "");
+}
+
+export function makeId(prefix: string, input: string): string {
+  const s = slug(input);
+  return `${prefix}:${s || "unknown"}`;
+}
--- a/tests/smoke.ts
+++ b/tests/smoke.ts
@@ -0,0 +1,40 @@
+import assert from 'node:assert';
+import path from 'node:path';
+import fs from 'node:fs';
+import { Yonexus } from '../src/index';
+import { YonexusError } from '../src/models/errors';
+
+const dataFile = path.resolve(process.cwd(), 'data/test-org.json');
+if (fs.existsSync(dataFile)) fs.unlinkSync(dataFile);
+
+const app = new Yonexus({ dataFile, registrars: ['orion'] });
+
+app.registerAgent({ agentId: 'orion' }, 'orion', 'Orion', ['org_admin', 'agent']);
+app.registerAgent({ agentId: 'orion' }, 'u1', 'U1', ['agent']);
+const dept = app.createDepartment({ agentId: 'orion' }, 'Eng', 'org:yonexus');
+const team = app.createTeam({ agentId: 'orion' }, 'API', dept.id);
+app.assignIdentity({ agentId: 'orion' }, 'u1', dept.id, team.id, {
+  git_user_name: 'u1',
+  position: 'dev'
+});
+
+const result = app.queryAgents(
+  { agentId: 'orion' },
+  { deptId: dept.id },
+  { filters: [{ field: 'git_user_name', op: 'eq', value: 'u1' }] }
+);
+assert.equal(result.length, 1);
+
+let thrown = false;
+try {
+  app.queryAgents(
+    { agentId: 'orion' },
+    { deptId: dept.id },
+    { filters: [{ field: 'team', op: 'eq', value: 'API' }] }
+  );
+} catch (e) {
+  thrown = e instanceof YonexusError && e.code === 'FIELD_NOT_QUERYABLE';
+}
+assert.equal(thrown, true);
+
+console.log('smoke test passed');
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "outDir": "dist/yonexus",
+    "rootDir": "src",
+    "declaration": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}