데이터 → 가이드

데이터 레이어 — read / write 사용 가이드

어디서 어떻게 데이터가 들어오고 누가 어떻게 꺼내쓰는지. 로컬 클로드 세션에 hook/MCP 셋업하는 법까지.

전체 흐름 (한눈에)

              WRITE (5)                                READ (3)
              ─────────                                ────────

  사람: /app/data/contribute  ──┐                ┌──  UI: /app/data, /app/data/collections/*
                                │                │
  사람: stamp-decisions.mjs    ──┤                ├──  API: /api/data/{stats,recent,search,
                                │                │       collections/*,items/*,walk}
  자동: claude-hook            ──┤    Qdrant     │
   (UserPromptSubmit)          ──┼──► 20 col ───┼──  MCP: seeso-knowledge.{search,store,
                                │                │       list_collections,get_recent,
  자동: systemd timer (3)      ──┤                │       related_to,walk,record_decision,
   (slack/git/docs)            ──┤                │       record_claim,link}
                                │                │
  MCP store / record_*         ──┘                └──  (Cmd+K 글로벌 팔레트는 search API 활용)

✍️ WRITE — 5가지 진입로

1

사람이 직접 — /app/data/contribute

정상
사람검증완료

가장 단순한 인풋. paste / file / url 3 모드. 4W 자동 추정 + 사용자 확정. layer/domain 자동 라우팅.

# 또는 curl 직접 (cookie 인증 필요)
curl -X POST https://ax.careerly.co.kr/api/data/contribute \
  -H "Cookie: ax_session=careerly1!" \
  -H "Content-Type: application/json" \
  -d '{"content":"...", "project":"careerly", "tags":["..."], "layer":"L1", "domain":"careerly"}'
2

API 박제 — POST /api/data/decision · /claim

정상
API프로그램

의사결정·주장처럼 명시 ID + status 가 필요한 데이터. 사람-issued decision_id (예: D-V2-REORG) + status (proposed/accepted/superseded).

POST /api/data/decision
{
  "project": "careerly",
  "domain": "careerly",
  "decision_id": "D-PRICING-2026Q2",
  "decision_status": "accepted",
  "title": "...",
  "content": "...",
  "rationale": "...",
  "tags": ["pricing"]
}
3

자동 hook — 클로드 세션 프롬프트

정상
자동claude-hook

클로드 코드 세션의 모든 사용자 프롬프트가 자동으로 Qdrant에 저장됨 (서버 한정 — 로컬 머신은 별도 셋업 필요).

cwd 기반 라우팅: /home/ubuntu/ax-poc 같은 ax 워크스페이스 → ax__L0_episode, 그 외 → seeso__L0_episode

# 로컬 머신에 설치하려면 (서버 외):
# 1) ~/.claude/settings.json 의 hooks.UserPromptSubmit 에 추가
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": "node /path/to/seeso-ax/collectors/claude-hook/hook.js"
        }]
      }
    ]
  }
}
# 2) ~/projects/seeso/seeso-ax/.env 에 QDRANT/OPENAI 키 셋업
#    (보안: 키 노출 위험 — 가급적 서버 hook만 쓰기 권장)
4

자동 timer — slack / git / docs 수집기

부분 동작
자동systemd

서버에서 systemd user timer 가 슬랙(15m) / git(30m) / docs(60m) 주기로 데이터 push. 현재는 v1 컬렉션(seeso-slack) 에 들어감 — v2 네이티브 리팩토링은 별도 task.

# 서버에서 상태 보기
systemctl --user list-timers seeso-collect-*
journalctl --user -u seeso-collect-slack -f
# 첫 트리거 결과: slack 108 + git 170 messages collected
5

MCP 툴 — store · record_decision · record_claim · link

정상
MCPClaude 세션

클로드 코드 세션에서 직접 Qdrant 에 점 추가. 다음 클로드 세션에서 /mcp seeso-knowledge.store(...).

# 셋업: ~/.claude.json 에 추가 (서버 외 머신)
{
  "mcpServers": {
    "seeso-knowledge": {
      "command": "uv",
      "args": [
        "run", "--project", "/path/to/data-ontology/mcp-server",
        "python", "-m", "seeso_knowledge_mcp.server"
      ],
      "env": {"PYTHONUNBUFFERED": "1"}
    }
  }
}

# 또는 서버 HTTP 변형 (port 18790, 추후 인증 추가)

👁️ READ — 3가지 surface

A

UI (사람)

정상
대시보드
  • /app/data — 인덱스 (24K 매트릭스)
  • /app/data/collections/[id] — 컬렉션 raw 데이터 + 의미 검색
  • /app/data/[uxCat]/[id] — catch-all (Cmd+K, recent row 클릭에서 자동)
  • /app/teams/data-ontology — 팀 페이지 “검색 가능 데이터” 탭
  • Cmd+K — 글로벌 팔레트, “데이터” 그룹
B

API (server-side, cookie 인증)

정상
API
# 모두 cookie 필요: ax_session=careerly1!
GET /api/data/stats                      # 20 컬렉션 카운트
GET /api/data/recent?limit=10            # 최근 (4 휴먼 컬렉션 머지)
GET /api/data/search?q=AI팀&limit=5      # fan-out 의미 검색 + reweight
GET /api/data/collections/{id}?limit=50  # 단일 컬렉션 scroll
GET /api/data/collections/{id}?q=...     # 단일 컬렉션 의미 검색
GET /api/data/items/{id}                 # fan-out 으로 점 1개 찾기
GET /api/data/walk?from={id}&depth=2     # refs[] 그래프 traversal
C

MCP — Claude 세션이 호출

정상
MCP

등록된 클로드 코드 세션에서 /mcp 입력하면seeso-knowledge 9 툴 list. 이미 메인 세션에 등록됨.

# read tools
seeso-knowledge.search(query, project?, source?, layer?, top_k=10)
seeso-knowledge.list_collections()
seeso-knowledge.get_recent(collection, limit=20)
seeso-knowledge.related_to(point_id, top_k=5)
seeso-knowledge.walk(from_id, max_depth=3, rel?)

# write tools
seeso-knowledge.store(collection, content, metadata)
seeso-knowledge.record_decision(domain, decision_id, status, ...)
seeso-knowledge.record_claim(domain, content, source_uri, confidence)
seeso-knowledge.link(from_id, to_id, rel)

❓ 자주 묻는 것

ax 대시보드를 쓰면 자동으로 데이터가 모이나?›
부분적. 사이트 자체는 단순 뷰어/인풋. 자동 적재는:
  • 서버 클로드 세션의 프롬프트 (claude-hook)
  • 슬랙/깃/문서 (systemd timer, 서버 한정)
로컬 머신에서 자동 적재하려면 위 셋업 가이드 (Write #3, #5) 따라야 함.
MCP 가 내 로컬 클로드에 연결되어있나?›
아니오. 서버의 ~/.claude.json 만 등록됨. 로컬에서 쓰려면 (a) mcp-server 코드 clone + 로컬 등록, 또는 (b) 서버 HTTP 변형 (port 18790, 인증 미완) 활용.
검색이 안 나오면?›
(1) cookie 인증 확인, (2) 컬렉션이 비어있는지 확인 (/app/data), (3) 의미 검색이라 키워드보다 자연어 쿼리가 더 잘 hit. 영어/한국어 다 OK.
데이터 잘못 들어갔으면 지울 수 있나?›
현재 UI 미지원. policies/access.md 따라 슬찬만 삭제 가능 (script 또는 Qdrant 직접). decisions 컬렉션은 영구 (audit).
legacy 컬렉션 (seeso-docs 등) 은 어떻게?›
v1 → v2 마이그레이션 1회 실행됨 (21K → seeso__L1_note). v1은 그대로 남아있음 (지우지 X — 백업). 새 데이터는 v2 컬렉션에만.
데이터 인덱스기여하기