설치 (모든 모드 공통)

Install (common to all modes)

$ curl -sSfL https://openxgram.org/install.sh | sh
$ xgram --version
# openxgram 0.2.0

$ xgram init --alias my-laptop
# 12-단어 복구 시드를 출력합니다 (오프라인 보관 권장)
# 이후 모든 데이터는 ~/.openxgram/ 로컬 SQLite 한 파일에만 저장됩니다.

외부 전송 0: 위 두 명령은 인터넷에 데이터를 전혀 보내지 않습니다 (install.sh 내려받기 제외). 블록체인 키페어(secp256k1)는 사용자 기기에서 생성되고, 이후 외부로 나가지 않습니다.

Zero external transmission: these two commands send nothing to the internet (other than fetching install.sh). The blockchain keypair (secp256k1) is generated locally and never leaves the device.

같은 데이터, 세 가지 화면

Same data, three faces

설치 한 번이면 같은 ~/.openxgram/ 위에 CLI · TUI · GUI 셋 다 동시에 사용할 수 있습니다 — 어떤 인터페이스에서 작업해도 즉시 다른 쪽에 반영됩니다. 상황에 맞는 것을 고르세요.

One install gives you CLI · TUI · GUI over the same ~/.openxgram/ data — work in any of them and the others reflect it instantly. Pick the one that fits the moment.

1) 웹 AI (Claude · ChatGPT · Gemini) — 셸 접근 불가

1) Web AI (Claude · ChatGPT · Gemini) — no shell access

대부분의 사용자가 매일 쓰는 환경입니다. 웹 채팅창은 사용자 기기의 셸에 접근할 수 없으므로 두 가지 방법으로 OpenXgram 을 연결합니다 — 어떤 방법이든 사용자 기기 밖으로 데이터가 나가지 않습니다.

This is the everyday environment for most users. Web chat windows can't reach your local shell, so OpenXgram connects via two paths — both keep data on your machine.

1-A) 시스템 지침 / Custom Instructions / Project 에 사용법 붙이기 (가장 쉬움)

1-A) Paste usage into System Prompt / Custom Instructions / Project rules (easiest)

ChatGPT Custom Instructions, Claude Project Instructions, Gemini Gems 같은 곳에 아래 템플릿을 그대로 붙여 넣으세요. AI 가 안내대로 동작합니다 — 사용자(나) 가 터미널에서 xgram 명령을 실행해서 결과를 채팅에 붙여 넣는 식으로 양방향 연결됩니다.

Paste the template below into ChatGPT Custom Instructions, Claude Project Instructions, or Gemini Gems. The AI follows it — you run xgram in your terminal and paste the result back into chat to complete the loop.

# 템플릿 (KO) — 시스템 지침/Custom Instructions/Project 에 붙여넣기

당신은 OpenXgram 메모리 시스템을 사용하는 AI 입니다.

[규칙]
1. 사용자가 새 주제를 꺼내면, 가장 먼저 이렇게 답합니다:
   "관련 기억을 회상하시려면 사용자(나) 의 터미널에서 다음 명령을 실행해 결과를 붙여 넣어 주세요:
    xgram session recall --query <핵심 키워드> --k 5"

2. 사용자가 회상 결과를 붙여 넣으면, 그 정보를 바탕으로 답변합니다.

3. 대화 중 중요한 결정/사실/규칙이 나오면 이렇게 안내합니다:
   "이 내용을 기억에 저장하시려면:
    xgram memory add --kind <fact|decision|rule> --content <내용>"

4. 외부 메모리 서비스(Mem0·Zep 등)는 절대 권하지 않습니다.
5. 모든 기억은 사용자(나) 의 기기 안에만 머무릅니다.

영어 템플릿이 필요하면 xgram memory export-prompt 명령으로 즉시 출력할 수 있습니다.

Run xgram memory export-prompt for the English template.

1-B) MCP 서버 연결 (Claude Desktop 등 MCP 지원 클라이언트)

1-B) MCP server (Claude Desktop and other MCP clients)

붙여넣기 방식보다 자동화가 더 필요하면 MCP 를 사용하세요. xgram 자체가 MCP 서버를 띄울 수 있습니다. Claude Desktop 의 MCP 설정에 OpenXgram 을 등록하면, 웹 Claude 가 사용자 기기의 xgram 을 직접 호출해 메모리를 읽고 씁니다 — 데이터는 로컬 루프백(127.0.0.1)으로만 흐릅니다.

For deeper automation than copy/paste, use MCP. xgram can run as an MCP server. Add it to Claude Desktop's MCP config and Claude reaches into your local xgram to read/write memory — traffic flows over loopback (127.0.0.1) only.

# 옵션 1) HTTP MCP — 로컬 루프백
$ xgram mcp-serve --bind 127.0.0.1:7301
# 외부 0.0.0.0 바인딩 절대 금지

# 옵션 2) Claude Desktop ~/.claude/mcp_servers.json 에 추가 (--bind 생략 시 stdio 모드)
{
  "openxgram": {
    "command": "xgram",
    "args": ["mcp-serve"]
  }
}

2) 터미널 AI 하네스 — 셸 접근 가능한 AI

2) Terminal AI harness — AI agents with shell access

Claude Code · Cursor · Aider 같이 셸을 쓸 수 있는 AI 에는, 프로젝트 지침 파일에 "OpenXgram 명령으로 기억을 회상·저장하라" 라고만 적어두면 AI 가 자동으로 사용합니다. 데이터는 모두 사용자 기기 안에서만 흐릅니다.

For AI agents with shell access (Claude Code · Cursor · Aider), just add to your project rules file: "recall and save memory using xgram commands." The agent will use it automatically. Everything stays on your machine.

CLAUDE.md / .cursorrules / .aiderrules 에 추가

Add to CLAUDE.md / .cursorrules / .aiderrules

# OpenXgram 메모리 사용 규칙

## 응답 시작 전
- 관련 기억 회상: xgram session recall --query "<핵심 키워드>" --k 5
- vault 자격 필요 시: xgram vault get <key>

## 중요한 결정/사실 등장 시
- 사실 저장: xgram memory add --kind fact --content "..."
- 결정 저장: xgram memory add --kind decision --content "..."
- 규칙 저장: xgram memory add --kind rule --content "..."

## 절대 금지
- 외부 클라우드/SaaS 메모리 서비스 사용 금지 — 모든 기억은 OpenXgram 으로
- 사용자(나) 의 승인 없는 vault put/delete 금지

이렇게 한 줄 한 줄 적어두면, AI 가 모델을 바꿔도 (Claude → ChatGPT, Cursor → Aider) 같은 메모리를 이어 쓰게 됩니다.

With these lines in place, the same memory carries over even when you switch models (Claude → ChatGPT, Cursor → Aider).

3) 직접 CLI — 개발자/파워 유저

3) Direct CLI — developers / power users

가장 빠른 길. 셸에서 직접 명령어를 칩니다.

The fastest path. You type commands in the shell.

$ xgram session new --title "주간 회고"
# → session id 출력 (예: 7f3a...). 아래 <ID> 자리에 그 값을 사용
$ xgram session message --session-id <ID> --sender me --body "이번 주 최우선은 결제 자동화"
$ xgram memory add --kind decision --content "RBF tip 은 +15% 로 고정"
$ xgram session recall --query "결제 자동화" --k 5
# top-5 회상 결과 (다른 AI 와 공유 가능)

4) 다중 에이전트 메신저 허브 — Channel MCP 내장

4) Multi-agent messenger hub — embedded Channel MCP

여러 AI 에이전트(eno · qua · pip · res ...)가 같은 채팅·라우팅 허브를 공유합니다. OpenXgram 1대가 channel-mcp 정식 구현체로 동작 — 외부 channel-mcp 운영 불필요. Discord/Telegram/Slack/KakaoTalk 어댑터가 한 바이너리에 들어 있고, send_to_platform · send_message 도구 시그니처는 Starian channel-mcp 와 호환됩니다.

Run one OpenXgram daemon as the multi-agent chat & routing hub. channel-mcp lives inside OpenXgram — no external service needed. Discord / Telegram / Slack / KakaoTalk adapters share one binary, and tool signatures match Starian channel-mcp (drop-in compatible).

$ # 1. 자기 webhook/봇 토큰을 환경변수로 (외부 SaaS 0)
$ export DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
$ export TELEGRAM_BOT_TOKEN=...  TELEGRAM_CHAT_ID=...
$ export XGRAM_CHANNEL_PEERS="eno:discord:default,qua:telegram:default"

$ # 2. Channel MCP 서버 기동 (loopback 만 — 절대 규칙)
$ xgram channel serve --bind 127.0.0.1:7250 --auth-token $(openssl rand -hex 32)
  ✓ OpenXgram Channel MCP 서버 기동
    bind     : 127.0.0.1:7250
    adapters : discord:default · telegram:default · slack:default
    peers    : eno → discord, qua → telegram

$ # 3. 다른 에이전트들이 OpenXgram 의 HTTP 엔드포인트로 송수신
$ xgram channel send --to-role eno --text "build green" --msg-type result
$ xgram channel list-adapters
$ xgram channel list-peers

외부 channel-mcp 운영 불필요 — OpenXgram 한 대에 다 들어 있음. 기존 Starian channel-mcp 클라이언트는 http://127.0.0.1:7250/tools/{name} 로 동일하게 호출 가능합니다.

No external channel-mcp required — everything runs in one OpenXgram binary. Existing Starian channel-mcp clients can call the same tool names against http://127.0.0.1:7250/tools/{name}.

Discord · Telegram 알림 — 5분 안에 휴대폰으로

Discord · Telegram alerts — phone notifications in 5 minutes

AI 에이전트가 결정·승인·에러를 보낼 곳을 만듭니다. 둘 중 하나만 해도 충분합니다 — 둘 다 하면 더 안전합니다. 아래 단계만 따라 하면 끝, 외부 SaaS 없이 사용자(나) 의 webhook/bot 으로만 메시지가 갑니다.

Set up where the agent pings you for decisions, approvals, and errors. Either one is enough — both is safer. Just follow the steps below. No external SaaS — the message goes only to your webhook/bot.

$ xgram notify setup-telegram   # 봇 토큰만 붙여넣으면 끝
$ xgram notify setup-discord    # 봇 토큰 + 서버 초대 안내 (webhook URL 옵션)

# 받기만 (stdout 출력)
$ xgram notify telegram-listen

# 받은 메시지를 L0 message 로 저장 — AI 가 회상에서 참조 가능
$ xgram notify telegram-listen --store-session "tg-inbox"

# 특정 chat_id 만 필터링
$ xgram notify telegram-listen --chat-id 123456789 --store-session "tg-inbox"

다중 에이전트 채팅방 — Discord 봇으로 메시지 수신

Multi-agent chat room — receive messages via Discord bot

여러 AI 에이전트가 같은 디스코드 채널에서 대화·결정·합의하게 하려면 메시지를 받아야 합니다 — webhook 은 송신 전용입니다. 아래 5단계로 봇 토큰을 만들고 Gateway WebSocket 으로 채널 메시지를 수신하세요. 받은 모든 메시지는 OpenXgram 의 메모리(L0)에 저장 가능합니다.

To let multiple AI agents chat, decide, and reach consensus in the same Discord channel, you need to receive messages — webhooks are send-only. Follow the 5 steps below to create a bot token and stream channel messages over the Gateway WebSocket. Every received message can be persisted to OpenXgram's L0 memory.

AI 가 자동으로 알리게 — 한 줄이면 끝

Make the AI ping you automatically — one line

사용자(나) 의 CLAUDE.md · .cursorrules · 시스템 지침에 아래 한 줄을 추가하세요. AI 가 중요한 결정·승인·에러 시 자동으로 알림을 보냅니다 — 추가 설정 0.

Add the single line below to your CLAUDE.md · .cursorrules · system prompt. The AI will ping you on decisions, approvals, and errors automatically — zero extra setup.

중요한 결정·승인·에러 시 즉시 xgram notify 로 알리기 (Discord 또는 Telegram).

📡 Channel MCP — 토큰 없이 5 플랫폼을 한 인터페이스로

📡 Channel MCP — one interface, 5 platforms, no per-app tokens

여러 AI 에이전트가 같은 메시지 라우팅 허브 (Starian Channel MCP) 를 쓰는 환경이라면, OpenXgram 은 webhook/봇 토큰을 직접 들고 있을 필요 없이 channel-mcp 의 HTTP gateway 한 곳으로 위임할 수 있습니다. discord · telegram · slack · kakaotalk · webhook — 5 플랫폼이 같은 명령으로 통합됩니다.

If multiple AI agents share a message routing hub (Starian Channel MCP), OpenXgram can delegate sending to the channel-mcp HTTP gateway instead of holding webhook/bot tokens itself. Five platforms — discord · telegram · slack · kakaotalk · webhook — through one command.

# 1) channel-mcp gateway URL 등록 (1회)
$ export OPENXGRAM_CHANNEL_MCP_URL="http://localhost:7100"
# bearer 토큰을 요구하는 호스트라면:
$ export OPENXGRAM_CHANNEL_MCP_TOKEN="<TOKEN>"

# 2) send_to_platform — 디스코드 채널로 전송
$ xgram notify channel --platform discord --channel-id 12345 --text "approve?"

# 3) send_message — 역할명으로 다른 에이전트에게 라우팅 (피어)
$ xgram notify channel --to-role res --summary "조사 부탁" --msg-type request

# 4) 등록된 어댑터 + 연결 상태 조회
$ xgram notify channel --list-adapters

장점. 토큰을 OpenXgram 마다 등록하지 않아도 됩니다 (channel-mcp 에 1회). 5 플랫폼을 한 인터페이스로. 역할명 (res, eno, master …) 으로 다른 에이전트에게 직접 메시지 전달.

Why. Tokens live in channel-mcp once, not in every OpenXgram instance. Five platforms behind one command. Direct peer-to-peer routing by role name (res, eno, master …).

언제 webhook? 단독 사용자, channel-mcp 를 운영하지 않는 환경. 언제 channel-mcp? Starian / Eno / Res 처럼 여러 에이전트가 협업하는 다중 에이전트 시스템.

Use webhook when you're a solo user without channel-mcp. Use channel-mcp when multiple agents (Starian / Eno / Res …) collaborate on a shared hub.

구현 노트 — channel-mcp HTTP gateway 가 표준 MCP JSON-RPC tools/call (POST /mcp) 를 노출한다고 가정합니다. 호스트가 다른 경로를 쓰면 ChannelMcpClient::with_endpoint 로 교체하세요.

Implementation note — assumes the channel-mcp HTTP gateway exposes the standard MCP JSON-RPC tools/call (POST /mcp). Override via ChannelMcpClient::with_endpoint if your host uses a different path.

예약 메시지 + 체인 메시지 — 다중 에이전트 워크플로우

Scheduled messages + message chains — multi-agent workflows

AI 들이 자동으로 협업하도록 시간·조건 기반 라우팅을 제공합니다. 특정 시각 또는 cron 표현식으로 미래 메시지를 예약하고 (KST 기준), 여러 단계를 직렬로 묶어 응답에 따라 분기시킵니다.

Time- and condition-based routing so agents collaborate autonomously. Schedule future messages by absolute time or cron (KST), or chain steps with delays and response-based branching.

# 1) 1회 예약 — 2026-05-05 09:00 KST 에 res 에이전트로
$ xgram schedule once --at "2026-05-05T09:00:00+09:00" \
    --to-role res --text "morning briefing"

# 2) 반복 예약 — 매일 09:00 KST 디스코드 채널로
$ xgram schedule cron "0 9 * * *" \
    --to-platform discord --channel-id 12345 --text "daily standup"

# 3) 예약 목록 / 취소 / 도달분 수동 실행
$ xgram schedule list
$ xgram schedule cancel <id>
$ xgram schedule run-pending

체인 (chain). YAML 파일에 단계를 적고 한 번에 실행. 직전 응답에 키워드가 있으면 다음 단계 진행 — response_contains / response_not_contains.

Chain. Define steps in YAML, run once. Branch on prior response keywords using response_contains / response_not_contains.

# chain.yaml
name: morning-routine
steps:
  - to_role: master
    text: "오늘 일정 어떠세요?"
    delay_secs: 0
  - to_role: res
    text: "오늘 뉴스 요약 부탁"
    delay_secs: 30
  - to_platform: discord
    channel_id: "12345"
    text: "✓ standup 시작"
    condition_kind: response_contains
    condition_value: "ok"

# 등록 → 실행
$ xgram chain create --file chain.yaml
$ xgram chain list
$ xgram chain show morning-routine
$ xgram chain run morning-routine

저장소. SQLite 마이그레이션 0016 — scheduled_messages + message_chains + chain_steps. 모든 시간은 KST. 실패 시 last_error 컬럼 + status='failed' 로 기록 (silent fallback 금지).

Storage. SQLite migration 0016 — scheduled_messages + message_chains + chain_steps. All timestamps in KST. Failures recorded in last_error with status='failed' (no silent fallbacks).

구현 노트 — ChannelSender trait 가 송신 추상화입니다. xgram chain run 은 현재 NoopSender (dry-run) 로 동작하며, channel-mcp 어댑터의 RouteEngine 가 이 trait 를 구현하면 자동으로 실 송신으로 연결됩니다.

Implementation note — sending is abstracted by the ChannelSender trait. xgram chain run currently uses NoopSender (dry-run); once the channel-mcp adapter's RouteEngine implements the trait it switches to real delivery.

모델 갈아타기 — 같은 기억 그대로

Switching models — same memory, intact

ChatGPT 에서 한 시간 일하다가 Claude 로 옮길 때, 또는 Gemini 에서 시작했다가 Cursor 로 옮길 때 — 이전 대화·결정·규칙을 그대로 가져갑니다.

Move from ChatGPT to Claude, or from Gemini to Cursor — your prior conversation, decisions, and rules all come along.

# 다른 AI 에 이미 쌓인 기억을 가져오기
$ xgram memory export-prompt   # 이 프롬프트를 그 AI 에 붙여 넣기
# → AI 가 저장된 기억을 5 카테고리로 출력 (Instructions/Identity/Career/Projects/Preferences)
# → 결과를 파일로 저장 후 import:
$ xgram memory import --input ./from-other-ai.md --format claude

# 반대로 OpenXgram → 다른 AI 로 가져가기
$ xgram memory export --format claude > my-memory.md
# my-memory.md 를 다른 AI 의 시스템 지침/Project 에 붙여 넣기