アーキテクチャ

公開面と実行面

利用者が触るPortal、Gateway、CLIを公開面の入口に置き、推論・GPU・共有Knowledge DBを内部側へ分離します。 Gatewayは認証とRelayが責務で、内部daemonや認証DBを直接公開しません。Knowledge SocietyもCLIではなくdaemon上で動きます。

CLI / TUI

利用者の端末

VPS Gateway

Token検証・WebSocket Relay

murasamed

Brain・Society・Tool・Evaluation・Knowledge

Portalは導入、公式Docs、管理面を配信する。
Gatewayは公開面のRelay/Auth。外部LLMの秘密キーや共有DBを持たない。
CLIは society.op などの操作要求を送るクライアントであり、SocietyのDB・Player・Schedulerを保持しない。
daemonはCodex worker、local Qwen、pooler、GLM、Card、Memory、Verified Knowledge、Society Jobへ接続する。
Project KGとDistillerのGlobal KG PoCは、既存Card PostgreSQLスキーマとは分離したSQLiteを使う。

コンポーネント

コンポーネント	主な責務	状態
`murasame`	TUI、ask、exec、User Brain、KG CLI	運用中 / PoC
`murasamed`	セッション、Brain、Tool、Routing、Autopilot	運用中
`murasame-pooler`	外部LLM APIのキー管理・接続プール	実装済み
`Knowledge Society Runtime`	Persona、Council、Claim、Candidate、Job、Simulation Clock、Player実行	実装済み / 明示有効化
PostgreSQL + pgvector	共有Card、Memory、Evaluation、Verification資産	運用中
Project / Global KG	意図・関係・Proposal・Snapshot	SQLite PoC
RunPod Distiller	LLM-jp候補採掘とGraph Bridge	PoC / 日次Window

通常ターン

CLI
  → WebSocket / local daemon
  → Brain: Card / Verification / Memory / User Brain retrieval
  → Codex gpt-5.6-luna:low
       ├─ success → result
       ├─ eval fail → medium → high → xhigh → max
       └─ unavailable → local Qwen / configured pooler
  → tool loop / evaluation / task log

Codex-firstでは、変更を残した失敗を別effortで重複実行しない安全境界があります。 Card検索は既定で有効、Memory検索は設定とユーザー境界に従います。

Knowledge Societyの実行境界

murasame CLI
    │  society.op
    ▼
local WebSocket / Gateway Relay
    ▼
murasamed
    ├─ Society Scheduler
    ├─ Simulation Job Queue (lease / heartbeat / retry)
    ├─ Persona Context Pack
    ├─ Council → Claim / Question / Candidate
    ├─ Evidence / Verification / Promotion Gate
    └─ Player Runtime
         └─ OpenCode → GLM-5.3

MURASAME_SOCIETY=1 をdaemonの設定へ明示すると、永続JobのSimulation Loopが起動します。 Personaは常駐プロセスではなく、Jobの実行時だけContext Packとしてロードされます。Playerを増やしても、共有Queue・Lease・Society全体の予算境界は変わりません。

OpenCode Playerの運用境界

現行のSociety Playerはdaemon内からOpenCodeを起動し、Coding PlanのGLM-5.3へ構造化されたCouncil turnを渡します。 Society PlayerにはTool、Shell、File、Network、MCP権限を与えず、資料取得と実地Verificationを別の許可された処理へ分離します。

MURASAME_SOCIETY=1
MURASAME_SOCIETY_PLAYERS=opencode
MURASAME_OPENCODE_MODEL=zai-coding-plan/glm-5.3
MURASAME_SOCIETY_MAX_PLAYERS=1
# Societyとカード評価Workerで共有する開始間隔
MURASAME_OPENCODE_MIN_INTERVAL_MS=60000
# Society全体の日次予算
MURASAME_SOCIETY_DAILY_MODEL_CALLS=200
MURASAME_SOCIETY_DAILY_TOKENS=500000
MURASAME_SOCIETY_DAILY_VERIFICATIONS=20

OpenCode呼び出し開始前にホスト共有のファイルロックと状態ファイルで最小間隔を予約します。呼び出しが失敗しても間隔は維持され、リトライによる短時間の連続送信を抑えます。

Knowledgeの境界

Personal

User Brain

CLIの ~/.murasame/userbrain.db に保存。本人確認後、必要な関連Contextだけを送る。

Per user

Memory

MURASAMEdの memories でユーザー別に分離。全件を毎回注入せず検索結果を使う。

Shared

Knowledge Card

PostgreSQL + pgvector。candidateは隔離し、verified/referenceだけを検索する。

Executable evidence

Verified Knowledge

Claim / Spec / Run / Evidence / ExperienceをCardと別ライフサイクルで管理する。

意味Graphの位置

Human Intent + Global Knowledge + Card + Evidence
                    ↓
              Project KG(SQLite)
              ├─ Specification View
              ├─ Next.js Skeleton
              └─ Traceability
                    ↑
       CodeGraph / Understand-Anything / AST
                    ↓
             Update Candidate

Graphはコード検索のIndexではありません。Requirement、Decision、Constraint、Rationale、Evidenceを上位概念として保持し、コードを出力または実装対応として扱います。ただしPoC段階では、Graphがすべてのコードを生成・維持することを目指していません。

Global Knowledgeの自動進化

DistillerはRunPod 48GB級GPUでLLM-jp 4 33B Thinkingを動かし、Raw / Parsed / Provenanceを保存します。 Parsed JSONLはGlobal KGへの未承認Proposalへ自動接続しますが、proposed / unverified のままです。 Evidence、評価、人の承認なしに既存Cardや通常ターンへ昇格しません。

常駐運転と回復(MVP運用面)

daemonとgatewayは HTTP の /health(liveness)と /ready(readiness)を持ちます。 daemonのreadyはDB migrate完了∧シャットダウン中でないこと、gatewayのreadyは認証ソースが有効∧シャットダウン中でないことです。どちらのエンドポイントも認証不要ですが、トークンやユーザー名などの秘密情報は返しません。

Societyの常駐ループは既定停止です。開始後は murasame society runtime status でSimulation Clockを、murasame society jobs list でJobのqueued / running / failedを確認し、必要なら runtime pause で社会時間を止められます。

# daemon / gateway の状態と理由を確認(全ready=0 / 問題あり=1)
murasame status
murasame status --json

SIGTERM / SIGINTでgraceful shutdown。背景タスクはkillのうえfailed(中断)としてDBへ確定し、正常終了は exit 0。
再起動時には前回プロセスが残した status='running' の背景タスクをfailedへ確定する回復処理が走る(冪等)。
systemd等への常駐登録は Restart=on-failure を推奨。停止・再起動を上記の回復機構に任せられます。
daemonの長時間TaskはDBの状態とログを持ち、再起動後も参照できます。

Distiller側の継続処理(queue / lease / retry / resume、systemd timer)はDistiller / RunPodに、障害時の切り分け手順はリポジトリの docs/18-mvp-ops-runbook.md が正本です。

障害と再開

Graph Proposalはstable IDと状態を持ち、同じCandidateを無制限に重複適用しません。
DistillerはTopic Queue、lease、Checkpointを持ち、3時間Windowを日次で再開できます。
Source CodeとGraphが矛盾した場合、コードを即時正本にせず、意図・実装事実・Evidenceの差分としてレビューします。