# SYNAPSE 문서 — 전체 참조
# 생성일: 2026-07-18T06:14:38.985Z
# 전체 글 수: 47
이 문서에는 Synapse API의 전체 문서가 포함되어 있습니다.
Base URL: https://synapse.schaefer.zone
Language: ko
========================================================================
## 카테고리: 시작하기
Synapse를 시작하는 데 필요한 모든 것.
────────────────────────────────────────────────────────────
# 인증 및 Mind Key
SUMMARY: Synapse 인증 작동 방식: 에이전트용 Mind Key, 사람용 JWT, URL 전용 도구용 ?key=.
KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)
JWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)
Mind Key is shown only once at creation. Store it permanently.
Each mind has exactly one Mind Key. Multiple minds = multiple keys.
인증 및 Mind Key
Synapse는 두 가지 인증 방법을 사용하며, 각각 다른 사용 사례에 최적화되어
있습니다. 신뢰할 수 있는 통합을 구축하려면 차이를 이해하는 것이 필수적입니다.
두 가지 인증 방법
| 방법 | 사용 사례 | 속도 제한 | 만료 |
|--------|----------|------------|--------|
| Mind Key | LLM 에이전트, 자동화 도구 | 없음 (헤더) / 분당 60회 (쿼리) | 없음 |
| JWT | 사용자 대면 UI, 계정 작업 | 없음 | 7일 |
Mind Key (에이전트용)
Mind Key는 테넌트 범위의 API 토큰입니다. 단일 마인드의 데이터 (메모리, 작업,
채팅, 스크립트 등)를 인증합니다. 다음에 사용하십시오:
- API를 호출하는 LLM 에이전트
- 백그라운드 자동화 스크립트
- MCP 서버 구성
- 모든 장기 통합
헤더 인증 (권장)
[CODE BLOCK]
쿼리 파라미터 (URL 전용 도구용)
[CODE BLOCK]
> [!WARNING]
> 쿼리 파라미터는 분당 60회로 제한됩니다.
> Bearer 헤더는 속도 제한이 없습니다. 클라이언트가 커스텀 헤더를 지원할
> 때마다 헤더를 사용하십시오.
Mind Key 생성
[CODE BLOCK]
응답에 가 포함됩니다 — 즉시 저장하십시오, 한 번만 표시됩니다.
마인드 나열
[CODE BLOCK]
마인드 삭제 (되돌릴 수 없음!)
[CODE BLOCK]
JWT (사람용)
JWT는 특정 마인드가 아닌 사용자 계정을 인증합니다. 다음에 사용하십시오:
- 계정 가입 및 로그인
- 마인드 생성 / 나열 / 삭제
- 다른 사용자와 마인드 공유
- Web Push 구독 관리
가입
[CODE BLOCK]
반환:
로그인
[CODE BLOCK]
반환:
JWT 만료
JWT는 7일 후에 만료됩니다. JWT가 만료되면 을 다시 호출하여
새 것을 받으십시오. Mind Key는 만료되지 않으므로 기존 에이전트 통합은
계속 작동합니다.
보안 모범 사례
> [!CRITICAL]
> - Mind Key를 git에 절대 커밋하지 마십시오. 환경 변수를 사용하십시오.
> - Mind Key를 로그에 남기지 마십시오. 로그에서 마스킹 ().
> - 유출이 의심되면 키 교체 (마인드 삭제, 새로 생성).
> - 키가 유출된 경우 피해 범위를 제한하기 위해 프로젝트당 하나의 마인드 사용.
환경 변수 패턴
[CODE BLOCK]
[CODE BLOCK]
MCP 서버 구성
[CODE BLOCK]
다중 마인드 패턴
각 사용자는 여러 마인드를 가질 수 있습니다. 일반적인 패턴:
| 마인드 이름 | 용도 |
|-----------|---------|
| | 업무 관련 메모리 |
| | 개인 선호도, 가족 |
| | 특정 프로젝트 컨텍스트 |
| | 학습 진행 상황 |
| | 범용 폴백 |
컨텍스트를 격리하기 위해 다른 LLM 세션에서 다른 Mind Key를 사용하십시오.
속도 제한
| 인증 방법 | 제한 | 범위 |
|-------------|-------|-------|
| Mind Key (헤더) | 없음 | 마인드별 |
| Mind Key (?key=) | 분당 60회 | IP별 |
| JWT (헤더) | 없음 | 사용자별 |
| 공용 엔드포인트 | 없음 | 전역 |
속도 제한 헤더 (, , )는
해당되는 경우 응답에 포함됩니다.
다음 단계
- Mind Key vs JWT — 언제 무엇을 사용할지
- Memory API — Mind Key로 할 수 있는 것
- User API — JWT로 계정 관리
────────────────────────────────────────────────────────────
# Mind Key vs JWT — 언제 무엇을?
SUMMARY: 결정 가이드: 에이전트 데이터 접근용 Mind Key, 계정 관리용 JWT.
KEY CONTEXT:
Mind Key: tenant-scoped, never expires, for memory/chat/tasks/scripts/computers/webhooks.
JWT: user-scoped, 7-day expiry, for /register, /login, /minds (CRUD), /sharing, /push.
Simple rule: if it touches a single mind's data → Mind Key. If it manages the account → JWT.
Exception: /computers/me/* uses Computer Token (not Mind Key or JWT).
Mind Key vs JWT — 언제 무엇을?
Synapse에는 두 가지 인증 토큰이 있습니다. 잘못 선택하면 401 오류가 발생합니다.
이 가이드는 명확한 결정 프레임워크를 제공합니다.
빠른 결정 표
| 하고 싶은 것 | 사용 |
|----------------|-----|
| 메모리 저장 / 회상 | Mind Key |
| 채팅 메시지 전송 / 폴링 | Mind Key |
| 작업 관리 | Mind Key |
| 스크립트 저장 | Mind Key |
| 웹훅 등록 | Mind Key |
| 컴퓨터 제어 | Mind Key (사용자 측) / Computer Token (에이전트 측) |
| 사용자 계정 가입 | 없음 (공용) |
| 로그인 | 없음 (공용) |
| 마인드 생성 / 나열 / 삭제 | JWT |
| 다른 사용자와 마인드 공유 | JWT |
| 웹 푸시 알림 구독 | JWT |
| 감사 로그 보기 | Mind Key |
단순한 규칙
> [!TIP]
> 단일 마인드의 데이터에 접근하면 → Mind Key.
> 계정 또는 마인드 메타데이터를 관리하면 → JWT.
Mind Key — 데이터 접근 토큰
Mind Key는 하나의 마인드 데이터에 접근 권한을 부여합니다. 만료되지 않는
(마인드가 삭제될 때까지) 장기 토큰입니다. 다음에 적합:
- 세션 간 메모리를 유지하는 LLM 에이전트
- 백그라운드 cron 작업
- MCP 서버 구성
- 웹훅 통합
- 메모리를 읽는 모바일 앱
Mind Key가 할 수 있는 것
- — 이 마인드의 모든 메모리 읽기
- — 메모리 저장/업데이트
- — 채팅 메시지 읽기
- — 채팅 메시지 전송
- — 작업 나열
- — 작업 생성
- — 스크립트 저장
- — 웹훅 등록
- — 컴퓨터 명령 큐잉
Mind Key가 할 수 없는 것
- 마인드 생성 / 나열 / 삭제 (JWT 필요)
- 다른 사용자와 마인드 공유 (JWT 필요)
- 사용자 계정 정보 보기 (JWT 필요)
- 웹 푸시 구독 (JWT 필요)
JWT — 계정 관리 토큰
JWT는 사용자 계정을 인증합니다. 7일 후에 만료되며 여러 마인드에 걸치거나
다른 사용자와 관련된 계정 수준 작업에 사용됩니다.
JWT가 할 수 있는 것
- — 새 마인드 생성 (새 Mind Key 반환)
- — 이 사용자의 모든 마인드 나열
- — 마인드 삭제
- — 다른 사용자와 마인드 공유
- — 웹 푸시 알림 구독
- — 마인드 공유 나열
JWT가 할 수 없는 것
- 메모리 읽기 / 쓰기 (Mind Key 필요)
- 채팅 메시지 전송 (Mind Key 필요)
- 작업 관리 (Mind Key 필요)
- 웹훅 등록 (Mind Key 필요)
특수 사례: Computer Token
엔드포인트 (에이전트 측, screen-remote-agent용)는 세 번째
토큰 유형인 Computer Token을 사용합니다. 이 토큰은 설치 코드를 상환할
때 에 의해 반환되며, 하나의 등록된 컴퓨터에
특정합니다.
| 엔드포인트 | 인증 |
|----------|------|
| | Computer Token |
| | Computer Token |
| | Mind Key 또는 JWT |
| | Mind Key 또는 JWT |
일반적인 패턴
패턴 1: 단일 LLM 에이전트
1. 한 번 가입 → JWT 획득
2. 하나의 마인드 생성 → Mind Key 획득
3. LLM이 모든 것에 Mind Key 사용
패턴 2: 다중 프로젝트 에이전트
1. 한 번 가입 → JWT 획득
2. 여러 마인드 생성 (work, personal, project-x) → 여러 Mind Key 획득
3. LLM이 컨텍스트에 따라 다른 Mind Key 로드
패턴 3: 팀 공유
1. 사용자 A가 마인드 생성 → Mind Key A 획득
2. 사용자 A가 JWT로 사용자 B와 공유 ()
3. 사용자 B는 이제 자신의 JWT로 접근 가능
4. LLM 접근을 위해 사용자 B는 자체 Mind Key 생성 필요 (또는 A의 것 사용)
패턴 4: MCP 서버
MCP 서버는 항상 Mind Key 사용 ( 환경 변수로 설정). 하나의
MCP 서버 인스턴스 = 하나의 마인드. 다중 마인드 접근을 위해 여러 MCP
인스턴스를 실행하거나 클라이언트 측 마인드 전환을 구현하십시오.
토큰 형식 치트 시트
| 토큰 | 형식 | 예시 |
|-------|--------|---------|
| Mind Key | + 36자 | |
| JWT | + base64 | |
| Computer Token | + 36자 | |
다음 단계
- Authentication — 전체 인증 가이드
- User 및 Minds API — JWT로 보호된 엔드포인트
- Memory API — Mind Key로 보호된 엔드포인트
────────────────────────────────────────────────────────────
# LLM 에이전트를 위한 빠른 시작
SUMMARY: 3번의 API 호출로: 모든 메모리 회상, 새 메모리 저장, 검색. 필수 LLM 워크플로우.
KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query)
ALWAYS call /memory/recall at the start of every session.
Wichtigste Befehle: GET /memory/recall, POST /memory, GET /memory/search?q=...
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
FTS5 search: multiple words = AND, "phrases" in quotes, prefix* for prefix search
LLM 에이전트를 위한 빠른 시작
세션 간에 모든 메모리를 잃습니다. Synapse는 외부 뇌입니다. 이 가이드는
모든 LLM 에이전트가 알아야 할 세 가지 필수 API 호출을 보여줍니다.
> [!CRITICAL]
> 모든 세션 시작 시 을 호출하십시오.
> 이 호출 없이는 사용자가 누구인지, 무엇을 약속했는지, 지난번에 무엇을
> 작업했는지에 대한 메모리가 없습니다.
1단계: 모든 메모리 회상 (항상 첫 번째)
[CODE BLOCK]
저장된 모든 메모리의 구조화된 일반 텍스트 요약을 반환합니다. 이를 파싱하여
사용자, 그들의 프로젝트, 과거 상호작용에 대한 멘탈 모델을 재구성하십시오.
응답 예시:
[CODE BLOCK]
2단계: 새 메모리 저장
기억할 가치가 있는 것을 학습했을 때:
[CODE BLOCK]
카테고리: , , , , , , , ,
우선순위: , , ,
> [!TIP]
> 항상 필드를 포함하십시오 — 메모리의 짧은 식별자입니다. 이를 통해
> 나중에 동일한 키로 다시 POST하여 같은 메모리를 업데이트할 수 있습니다.
3단계: 특정 메모리 검색
[CODE BLOCK]
> [!TIP]
> FTS5 구문: 여러 단어 = AND 검색. 따옴표 안의 구문: .
> 접두사 검색: . 불린: .
공개 도구 (인증 헤더 없음)
도구가 URL만 열 수 있는 경우 (커스텀 헤더 없음), 파라미터를
사용하십시오:
[CODE BLOCK]
> [!WARNING]
> 는 분당 60회로 제한됩니다. Bearer 헤더는 속도 제한이 없습니다.
> 가능하면 Bearer 헤더를 사용하십시오.
완전한 세션 워크플로우
1. 세션 시작: — 모든 메모리 로드
2. 작업 중: — 특정 사실 찾기
3. 새 정보 시: — 저장 (카테고리, 키, 태그, 우선순위 포함)
4. 주기적으로: — 사람의 메시지 확인
5. 세션 종료: 로 최종 학습 내용 저장
일반적인 패턴
기존 메모리 업데이트
동일한 및 로 를 POST하십시오 — 기존 메모리가
업데이트되며 중복되지 않습니다.
프로젝트 상태 저장
[CODE BLOCK]
실수 기록 (반복 방지)
[CODE BLOCK]
사람의 메시지 확인
[CODE BLOCK]
사람이 보낸 읽지 않은 메시지를 반환합니다. 다음으로 응답:
[CODE BLOCK]
다음 단계
- Authentication — Mind Key vs JWT
- Memory API 참조 — 모든 22개 메모리 엔드포인트
- Chat API — 사람과의 비동기 통신
- LLM Cookbook — 실용적인 패턴
────────────────────────────────────────────────────────────
# 빠른 시작 (사람)
SUMMARY: 계정 가입, 첫 마인드 생성, 메모리 저장 — 모두 5분 안에.
빠른 시작 (사람)
이 가이드는 Synapse 계정, 첫 Mind Key, 첫 메모리 저장까지 안내합니다.
총 소요 시간: 약 5분.
1단계: 계정 가입
Synapse API를 열고 계정을 생성하십시오:
[CODE BLOCK]
응답:
[CODE BLOCK]
> [!TIP]
> JWT를 안전한 곳에 저장하십시오 — 마인드 생성에 필요합니다. JWT는
> 7일 후 만료되며, 동일한 엔드포인트로 다시 로그인하여 갱신할 수 있습니다.
2단계: 첫 마인드 생성
"마인드"는 격리된 메모리 범위입니다. 대부분의 사용자는 하나의 마인드로
시작하지만, 여러 개를 가질 수 있습니다 (예: "work", "personal", "project-x").
각 마인드는 고유한 Mind Key를 가집니다.
[CODE BLOCK]
응답:
[CODE BLOCK]
> [!CRITICAL]
> 를 즉시 저장하십시오. 한 번만 표시되며 나중에 검색할 수
> 없습니다. 분실하면 새 마인드를 생성해야 합니다.
3단계: 첫 메모리 저장
이제 Mind Key를 사용하여 메모리를 저장하십시오:
[CODE BLOCK]
응답:
[CODE BLOCK]
4단계: 모든 메모리 회상
저장한 모든 것을 검색하려면:
[CODE BLOCK]
응답 (일반 텍스트, LLM 사용에 최적화):
[CODE BLOCK]
5단계: 메모리 검색
키워드로 특정 메모리 찾기:
[CODE BLOCK]
6단계: LLM 연결
LLM에게 Synapse 접근 권한을 부여하는 가장 쉬운 방법은 MCP를 통하는 것입니다:
- Claude Desktop 설정 — 2분 구성
- Claude Code 설정 — 터미널 통합
- Cursor 설정 — IDE 통합
설정 후, LLM은 모든 세션 시작 시 자동으로 을 호출하고
를 통해 새 사실을 영구 저장합니다.
메모리 카테고리
Synapse는 8개 카테고리를 지원합니다 — 가장 구체적인 것을 선택하십시오:
| 카테고리 | 사용 사례 |
|----------|----------|
| | 사용자 이름, 역할, 연락처 정보 |
| | 좋아함, 싫어함, 작업 스타일 |
| | 검증 가능한 사실 (프로젝트 세부 정보, 날짜) |
| | 프로젝트 상태, 마일스톤, 할 일 |
| | 사용자가 잘하는 것 |
| | 과거 오류 — 반복 방지 |
| | 세션 관련 컨텍스트 |
| | 기타 노트 |
우선순위 수준
- — 알면 좋음
- — 기본값
- — 중요
- — 절대 잊으면 안 됨 (사용자 정체성, 법적 정보)
다음 단계
- 인증 심층 가이드
- Mind Key vs JWT
- Memory API 참조
- MCP 통합
────────────────────────────────────────────────────────────
# Synapse란 무엇입니까?
SUMMARY: Synapse는 LLM 에이전트를 위한 영구 메모리 API — AI가 세션 간에 결코 잊지 않습니다.
KEY CONTEXT:
Synapse is an HTTP API that gives LLM agents persistent memory across sessions.
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query, rate-limited 60/min)
Most important endpoints: GET /memory/recall (start of every session), POST /memory (store new facts), GET /memory/search?q=...
Mind Key = tenant-scoped API key. Each user can have multiple minds (projects/contexts).
MCP server available: npx -y synapse-mcp-api (79 tools for Claude Desktop, Cursor, etc.)
Synapse란 무엇입니까?
Synapse는 LLM 에이전트를 위한 영구 메모리 API입니다. 모든 채팅 기반
LLM의 근본적인 문제를 해결합니다: 세션 간에 에이전트가 모든 것을 잊습니다.
Synapse는 대화, 일자, 그리고 다른 LLM 제공자 간에 유지되는 영구적이고
쿼리 가능한 뇌를 AI에게 제공합니다.
> [!CRITICAL]
> 이것을 읽고 있는 LLM 에이전트인 경우: 모든 세션 시작 시
> 을 호출하십시오. 이 호출 없이는 과거 상호작용에
> 대한 메모리, 사용자가 누구인지에 대한 지식, 진행 중인 프로젝트에 대한
> 컨텍스트가 없습니다.
Synapse가 해결하는 문제
모든 최신 LLM (Claude, GPT, Gemini, Llama)은 동일한 아키텍처 제한이
있습니다: 대화 컨텍스트 창은 유한하며, 세션이 종료되면 모든 상태가
손실됩니다. 즉, AI 어시스턴트가:
- 채팅 간에 이름, 선호도, 진행 중인 프로젝트를 잊음
- 세션 간에 과거 실수로부터 학습할 수 없음
- 장기 실행 작업에 대한 연속성이 없음
- 매번 동일한 명확화 질문을 다시 함
Synapse는 LLM이 구조화된 메모리를 저장하고 검색할 수 있는 단순한 HTTP API를
제공하여 이를 해결합니다. 메모리는 서버에 유지되며 인덱싱되고 검색 가능하여
향후 모든 세션에서 회상할 수 있습니다.
주요 기능
- 영구 메모리 저장 — 사실, 선호도, 프로젝트, 실수, 기술
- 전문 검색 (FTS5) — 밀리초 단위로 키워드로 모든 메모리 검색
- 의미론적 검색 — 개념적 쿼리를 위한 임베딩 기반 유사도 검색
- 다중 테넌트 — 각 사용자는 격리된 "마인드"를 가짐 (1명의 사용자, 여러 프로젝트)
- 비동기 채팅 — 에이전트가 작업하는 동안 사람이 메시지를 남길 수 있음
- 작업 및 스케줄링 — 내장된 작업 관리자 및 cron 스케줄러
- MCP 통합 — Claude, Cursor, Continue를 위한 Model Context Protocol로 노출된 79개 도구
- 브라우저 및 컴퓨터 제어 — 원격 자동화 도구
- 웹훅 — 메모리/채팅/작업 변경 시 HTTP 콜백 받기
작동 방식
[CODE BLOCK]
1. LLM이 세션 시작 시 호출
2. Synapse가 저장된 모든 메모리의 구조화된 텍스트 요약 반환
3. LLM이 작업하며 주기적으로 를 호출하여 새 사실 저장
4. 사용자가 질문하면 LLM이 를 호출할 수 있음
5. 세션 종료 시, 다음 세션을 위해 중요한 새 컨텍스트가 영구 저장됨
누구를 위한 것입니까?
- 영구 상태가 필요한 LLM 에이전트 개발자
- 커스텀 에이전트로 로컬 LLM (Ollama, LM Studio)을 실행하는 파워 유저
- 공유 메모리가 필요한 AI 어시스턴트를 구축하는 팀
- 세션 간 LLM 호출을 연결하는 자동화 엔지니어
빠른 비교
| 기능 | ChatGPT Memory | Synapse |
|---------|---------------|---------|
| 저장소 위치 | OpenAI 서버 | 본인 서버 |
| API 접근 | 아니오 (폐쇄) | 예 (REST + MCP) |
| 다중 테넌트 | 아니오 | 예 (minds) |
| 커스텀 카테고리 | 아니오 | 예 (8개 카테고리) |
| 검색 | 제한적 | FTS5 + 의미론적 |
| 자체 호스팅 | 아니오 | 예 (Docker) |
다음 단계
- 사람을 위한 빠른 시작 — 5분 안에 Mind Key 받기
- LLM을 위한 빠른 시작 — 첫 API 호출
- Authentication — Mind Key vs JWT
- 아키텍처 개요 — Synapse 구축 방식
## 카테고리: API 참조
모든 API 엔드포인트에 대한 완전한 참조.
────────────────────────────────────────────────────────────
# Browser Proxy
SUMMARY: 브라우저 자동화 서비스 — 헤드리스 브라우저 제어를 위한 별도의 Docker 컨테이너 (포트 13000).
KEY CONTEXT:
Browser Proxy is a SEPARATE Docker service (port 13000), NOT a Synapse endpoint.
Synapse endpoints do NOT include /browser/* paths.
For browser automation, use the MCP browser_new tool OR connect to the browser-proxy service directly.
Synapse MCP exposes browser tools (browser_new, browser_navigate, browser_click, etc.)
Browser Proxy
Browser Proxy는 Playwright를 통해 헤드리스 브라우저 자동화를 제공하는
별도의 Docker 서비스입니다. 이것은 Synapse API의 직접적인 부분이
아닙니다 — Synapse 엔드포인트에는 경로가 포함되지 않습니다.
아키텍처
[CODE BLOCK]
접근 방법
방법 1: Synapse MCP 서버 경유 (권장)
Synapse MCP 서버는 브라우저 도구를 MCP 도구로 노출합니다. LLM 기반
브라우저 자동화에 사용하십시오:
[CODE BLOCK]
사용 가능한 MCP 브라우저 도구:
- — 새 브라우저 탭 열기
- — URL로 이동
- — 요소 클릭
- — 필드에 텍스트 입력
- — 스크린샷 캡처
- — 탭 닫기
- (그 외 다수 — MCP 통합 참조)
방법 2: Browser Proxy 직접 접근
MCP가 아닌 통합의 경우, browser-proxy 서비스에 직접 연결하십시오:
[CODE BLOCK]
일반적인 사용 사례
웹 스크래핑
[CODE BLOCK]
폼 자동화
[CODE BLOCK]
스크린샷 캡처
[CODE BLOCK]
관련 서비스
| 서비스 | 포트 | 용도 |
|---------|------|---------|
| Synapse API | 12800 | Memory, chat, tasks |
| Synapse MCP | 13100 | MCP 서버 (79개 도구) |
| Browser Proxy | 13000 | 헤드리스 브라우저 자동화 |
| SSH Proxy | 12900 | 원격 머신 SSH 접근 |
다음 단계
- MCP 통합 — MCP를 통해 브라우저 도구를 사용하는 방법
- Computer Control API — 등록된 머신에서의 GUI 자동화용
────────────────────────────────────────────────────────────
# Chat API
SUMMARY: 사람과 LLM 에이전트 간의 비동기 채팅 — 폴링, 응답, 기록, 읽지 않은 메시지 수, 파일 업로드.
KEY CONTEXT:
Auth: Mind Key (agent side, ?role=agent) or JWT (human side, ?role=human)
Poll: GET /chat/poll (returns unread messages, marks them as read)
Reply: POST /chat/reply { content }
History: GET /chat/history?limit=50
Unread count: GET /chat/unread?role=agent (or ?role=human)
Upload: POST /chat/upload (multipart, file attachment)
Pattern: poll between tool calls, reply when human asks questions
Chat API
Chat API는 사람과 LLM 에이전트 간의 비동기 메시징을 지원합니다.
동기식 채팅(ChatGPT 스타일)과 달리, 사람은 에이전트가 작업 중인 동안에도
메시지를 남길 수 있으며 — 에이전트는 도구 호출 사이에 폴링합니다.
작동 방식
[CODE BLOCK]
1. 사람이 웹 UI를 통해 메시지를 전송합니다 (JWT 사용)
2. 메시지가 저장되고 읽지 않음으로 표시됩니다
3. 에이전트는 도구 호출 사이에 을 폴링합니다
4. 폴링은 모든 읽지 않은 메시지를 반환하고 읽음으로 표시합니다
5. 에이전트는 메시지를 처리하고, 선택적으로 로 응답합니다
엔드포인트
GET /chat/poll
사람이 보낸 새 메시지를 폴링합니다. 읽지 않은 메시지를 반환하고 읽음으로
표시합니다. 도구 호출 사이에 사용하십시오.
[CODE BLOCK]
응답:
[CODE BLOCK]
POST /chat/reply
에이전트로 메시지를 전송합니다.
[CODE BLOCK]
POST /chat/send
사람으로 메시지를 전송합니다 (Mind Key가 아닌 JWT 필요).
[CODE BLOCK]
GET /chat/history
최근 채팅 기록을 가져옵니다 (양쪽 역할 모두).
[CODE BLOCK]
GET /chat/unread
읽지 않은 메시지 수를 가져옵니다.
[CODE BLOCK]
GET /chat/status
채팅 세션 상태를 가져옵니다 (마지막 메시지 타임스탬프, 읽지 않은 메시지 수).
[CODE BLOCK]
POST /chat/upload
특정 메시지의 파일 첨부를 업로드합니다 (multipart 폼).
[CODE BLOCK]
GET /chat/files/:messageid
메시지의 파일 첨부 목록을 조회합니다.
[CODE BLOCK]
GET /chat/file/:fileid
파일 첨부를 다운로드합니다.
[CODE BLOCK]
폴링 패턴
> [!TIP]
> 도구 호출 사이에 30-60초마다 폴링하십시오. 더 자주 폴링하지 마십시오 —
> API 할당량을 낭비하고 이점이 없습니다.
[CODE BLOCK]
다음 단계
- Tasks API
- Chat Polling Pattern
────────────────────────────────────────────────────────────
# Computer Control API
SUMMARY: 등록된 컴퓨터의 원격 제어 — 명령 큐잉, 스크린샷 캡처, 원격 머신에서 스크립트 실행.
KEY CONTEXT:
Two sides: user-facing (Mind Key/JWT) and agent-facing (Computer Token)
Register agent: POST /computers/register { install_code } → returns computer_token
List: GET /computers/list (Mind Key or JWT)
Queue command: POST /computers/:id/commands { type, payload }
Command types: screenshot, click, move, type, key, scroll, drag
Agent poll: GET /computers/me/poll?wait=5 (Computer Token)
Agent result: POST /computers/me/commands/:cid/result (Computer Token)
One-shot screenshot: GET /computers/:id/screenshot (waits 30s for result)
Pattern: register agent on remote machine → user queues commands → agent polls and executes
Computer Control API
Computer Control API를 사용하면 등록된 컴퓨터를 원격으로 제어할 수 있습니다.
대상 머신에서 소형 에이전트()가 실행되어 명령을
폴링하고, 실행하고, 결과를 다시 게시합니다. 이를 통해 LLM 기반 GUI
자동화가 가능해집니다.
아키텍처
[CODE BLOCK]
사용자 측 엔드포인트 (Mind Key 또는 JWT)
GET /computers/list
등록된 모든 컴퓨터를 나열합니다.
[CODE BLOCK]
GET /computers/:id
단일 컴퓨터의 상세 정보를 가져옵니다.
[CODE BLOCK]
POST /computers/install-code
새 컴퓨터 등록용 설치 코드를 생성합니다.
[CODE BLOCK]
응답:
POST /computers/:id/commands
원격 에이전트가 실행할 명령을 큐에 추가합니다.
[CODE BLOCK]
응답:
GET /computers/:id/command (쿼리 경유)
GET 요청으로 명령을 큐에 추가합니다 (단순한 경우용).
[CODE BLOCK]
GET /computers/:id/commands
컴퓨터의 최근 명령을 나열합니다.
[CODE BLOCK]
GET /computers/:id/commands/:cid
특정 명령의 상태 및 결과를 가져옵니다.
[CODE BLOCK]
GET /computers/:id/screenshot
원샷: 스크린샷 명령을 큐에 추가하고 최대 30초 동안 결과를 기다립니다.
[CODE BLOCK]
POST /computers/:id/disable
컴퓨터를 비활성화합니다 (토큰을 취소하고, 감사를 위해 기록은 유지).
[CODE BLOCK]
DELETE /computers/:id
컴퓨터를 영구적으로 삭제합니다.
[CODE BLOCK]
에이전트 측 엔드포인트 (Computer Token)
이 엔드포인트들은 대상 머신에서 실행되는 가
사용합니다. Mind Key가 아닌 Computer Token(가 반환)을
사용합니다.
POST /computers/register
설치 코드를 상환하고 Computer Token을 받습니다.
[CODE BLOCK]
응답:
> [!CRITICAL]
> 을 저장하십시오 — 한 번만 표시되며 모든 에이전트 측
> 엔드포인트에 필요합니다.
GET /computers/me/poll
새 명령을 롱 폴링합니다. 에이전트는 이것을 루프에서 호출합니다.
[CODE BLOCK]
대기 중인 명령이 있으면 즉시 반환되거나, 없으면 초 후에 반환됩니다.
POST /computers/me/commands/:cid/result
명령 실행 결과를 게시합니다.
[CODE BLOCK]
명령 유형
| 유형 | 페이로드 | 설명 |
|------|---------|-------------|
| | | 화면을 PNG로 캡처 (base64) |
| | | 좌표 클릭 |
| | | 좌표로 마우스 이동 |
| | | 커서 위치에 텍스트 입력 |
| | | 키 조합 누름 |
| | | 스크롤 휠 |
| | | 드래그 앤 드롭 |
일반적인 패턴: LLM 기반 GUI 자동화
[CODE BLOCK]
다음 단계
- Browser Proxy — 브라우저 자동화용 별도 서비스
- Self-Hosted Agents Guide
────────────────────────────────────────────────────────────
# Cron 및 Scheduler
SUMMARY: 반복적인 API 호출 예약 — 주기적 동기화 및 알림에 적합한 cron 작업을 스케줄에 따라 실행합니다.
KEY CONTEXT:
Auth: Mind Key
Create: POST /cron { schedule, endpoint, method?, body?, headers?, enabled? }
List: GET /cron
Delete: DELETE /cron/:id
Toggle: PUT /cron/:id/toggle
Schedule: 5-field cron (minute hour day month day-of-week) OR integer interval (seconds)
Endpoint: must be http(s) URL, same Synapse instance OR public HTTPS (no private IPs)
Pattern: schedule /memory/recall every hour, /chat/poll every 5 min, etc.
Cron 및 Scheduler
Cron API를 사용하면 Synapse 엔드포인트 (또는 외부 HTTPS 엔드포인트)에 대한
반복적인 HTTP 호출을 예약할 수 있습니다. 주기적 동기화, 알림 및 유지 관리
작업에 적합합니다.
엔드포인트
POST /cron
예약된 작업을 생성합니다.
[CODE BLOCK]
응답:
[CODE BLOCK]
GET /cron
모든 예약된 작업을 나열합니다.
[CODE BLOCK]
DELETE /cron/:id
예약된 작업을 삭제합니다.
[CODE BLOCK]
PUT /cron/:id/toggle
삭제하지 않고 작업을 활성화 또는 비활성화합니다.
[CODE BLOCK]
스케줄 구문
표준 cron (5개 필드)
[CODE BLOCK]
예시:
| 스케줄 | 의미 |
|----------|---------|
| | 매시 정각 |
| | 15분마다 |
| | 평일 오전 9시 |
| | 매주 일요일 자정 |
| | 매월 1일 자정 |
정수 간격 (초)
단순한 간격의 경우 정수를 전달합니다:
[CODE BLOCK]
엔드포인트 제한 사항
> [!WARNING]
> 엔드포인트는 다음을 가리키는 또는 URL이어야 합니다:
> - 동일한 Synapse 인스턴스 (예: )
> - 공용 HTTPS URL (사설 IP, localhost, 메타데이터 IP 불가)
이는 손상된 마인드가 내부 서비스로 요청을 예약하는 SSRF 공격을
방지합니다.
일반적인 패턴
시간별 memory recall (LLM 에이전트용)
[CODE BLOCK]
일일 백업
[CODE BLOCK]
주기적 채팅 폴링 (5분마다)
[CODE BLOCK]
주간 보고서 트리거
[CODE BLOCK]
다음 단계
- Variables API
- Webhooks API
────────────────────────────────────────────────────────────
# 오류 및 오류 처리
SUMMARY: HTTP 상태 코드, 오류 응답 형식, 그리고 일반적인 오류로부터 복구하는 방법.
KEY CONTEXT:
Error format: { statusCode, error, message, docs? }
Common errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)
401 → check Mind Key/JWT, see /docs/getting-started/authentication
404 → wrong path, GET /endpoints for valid list, do NOT guess paths
429 → rate limited (?key= is 60/min), use Bearer header instead
500 → server error, retry with backoff, check /health
docs field in error response links to relevant documentation.
오류 및 오류 처리
Synapse는 표준 HTTP 상태 코드와 일관된 오류 응답 형식을 사용합니다.
이 페이지에서는 오류를 해석하고 복구하는 방법을 설명합니다.
오류 응답 형식
모든 오류는 다음 구조의 JSON을 반환합니다:
[CODE BLOCK]
| 필드 | 설명 |
|-------|-------------|
| | HTTP 상태 코드 |
| | HTTP 상태 이름 |
| | 사람이 읽을 수 있는 오류 설명 |
| | 관련 문서 URL (해당되는 경우) |
HTTP 상태 코드
200 OK
성공입니다. 요청이 올바르게 처리되었습니다.
201 Created
성공입니다. 새 리소스가 생성되었습니다 (예: ).
204 No Content
성공입니다. 본문이 반환되지 않았습니다 (예: ).
400 Bad Request
요청이 잘못되었습니다. 일반적인 원인:
- 필수 JSON 필드 누락
- 잘못된 JSON 구문
- 잘못된 enum 값 (예: 잘못된 카테고리)
[CODE BLOCK]
해결: API 문서와 대조하여 요청 본문을 확인하십시오. 모든 필수 필드가
존재하고 유효한 값을 가지고 있는지 확인하십시오.
401 Unauthorized
인증에 실패했습니다. 일반적인 원인:
- 헤더 누락
- 잘못된 Mind Key 또는 JWT
- JWT가 필요한 곳에 Mind Key 사용 (또는 그 반대)
[CODE BLOCK]
해결: 토큰을 확인하십시오. Authentication을 참조하십시오.
403 Forbidden
인증은 되었지만 이 작업을 수행할 권한이 없습니다. 일반적인 원인:
- 다른 사용자의 마인드 삭제 시도
- Mind Key로 memory 검증 시도 (JWT 필요)
- 마인드가 비활성화됨
해결: 이 엔드포인트에 올바른 토큰 유형을 사용하고 있는지 확인하십시오.
404 Not Found
요청한 경로 또는 리소스가 존재하지 않습니다.
> [!CRITICAL]
> 엔드포인트 경로를 추측하지 마십시오. 에 나열된
> 경로만 존재합니다. 404를 받았다면 잘못된 경로를 사용한 것입니다.
[CODE BLOCK]
해결: 를 호출하여 유효한 엔드포인트 목록을
확인하십시오. URL을 목록과 글자 단위로 비교하십시오.
409 Conflict
요청이 기존 상태와 충돌합니다. 일반적인 원인:
- 이미 존재하는 이메일로 등록 시도
- 중복된 webhook URL
해결: 다른 값을 사용하거나, 을 사용하여 기존 리소스를
업데이트하십시오.
429 Too Many Requests
속도 제한에 도달했습니다. 쿼리 파라미터 인증에만 적용됩니다 (분당 60회).
[CODE BLOCK]
응답 헤더:
[CODE BLOCK]
해결: 헤더로 전환하거나 (속도 제한 없음),
초 동안 기다리십시오.
500 Internal Server Error
서버 오류입니다. 이런 일이 발생해서는 안 되며 — 발생한다면 버그입니다.
해결:
1. 지수 백오프로 재시도 (1초, 2초, 4초, 8초)
2. 를 확인하여 서버가 실행 중인지 확인
3. 지속되면 오류를 보고하십시오
503 Service Unavailable
서버가 일시적으로 중단되었습니다 (예: 배포 중, 데이터베이스 마이그레이션).
해결: 기다렸다가 재시도하십시오. 를 확인하십시오.
복구 패턴
지수 백오프 재시도
[CODE BLOCK]
인증 오류 처리
[CODE BLOCK]
일반적인 오류 시나리오
"Mind Key fehlt oder ungültig"
- 헤더를 잊음
- 를 사용했지만 키가 잘못됨
- Mind Key가 필요한 곳에 JWT를 사용 중
"Route not found"
- 존재하지 않는 경로를 추측함
- 동사를 잘못 사용함 (예: vs )
- 에서 유효한 경로 확인
"Rate limit exceeded"
- 를 사용하여 분당 60회 초과
- 헤더로 전환
다음 단계
- Authentication
- API 개요
- 속도 제한
────────────────────────────────────────────────────────────
# Memory API
SUMMARY: 22개 메모리 엔드포인트에 대한 완전한 참조: 저장, 회상, 검색, 의미론적 검색, 동기화, 감사 등.
KEY CONTEXT:
Auth: Mind Key (Authorization: Bearer mk_xxx OR ?key=mk_xxx)
ALWAYS call GET /memory/recall at session start.
POST /memory with same category+key updates the existing memory.
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
Search: GET /memory/search?q=... (FTS5 syntax: AND, OR, "phrases", prefix*)
Semantic: GET /memory/semantic-search?q=... (slower, conceptual)
Sync: GET /memory/diff?since=TIMESTAMP (incremental sync)
Export: GET /memory/mind-export (full JSON dump)
Memory API
Memory API는 Synapse의 핵심입니다. 구조화된 메모리를 저장, 검색, 검색 및
관리하기 위한 22개의 엔드포인트를 제공합니다. 모든 엔드포인트는 인증을 위해
Mind Key가 필요합니다.
> [!CRITICAL]
> 모든 세션 시작 시 을 반드시 호출하십시오. 이것이
> 이전 세션의 컨텍스트를 재구성하는 유일한 방법입니다.
카테고리
메모리는 8개 카테고리로 구성됩니다:
| 카테고리 | 사용 사례 |
|----------|----------|
| | 사용자 이름, 역할, 연락처 정보, 자신에 대한 선호도 |
| | 좋아함, 싫어함, 작업 스타일, 커뮤니케이션 선호도 |
| | 검증 가능한 사실 (프로젝트 세부 정보, 날짜, URL) |
| | 프로젝트 상태, 마일스톤, 아키텍처 |
| | 사용자가 잘하는 것 |
| | 과거 오류 — 반복 방지 |
| | 세션 관련 컨텍스트 |
| | 기타 노트 |
우선순위
- — 알면 좋음
- — 기본값
- — 중요
- — 절대 잊으면 안 됨 (사용자 정체성, 법적 정보)
핵심 엔드포인트
GET /memory/recall
모든 메모리를 LLM에 최적화된 일반 텍스트로 반환합니다. 모든 세션 시작 시
호출하십시오.
[CODE BLOCK]
응답 (text/plain):
[CODE BLOCK]
POST /memory
새 메모리를 저장하거나 기존 메모리를 업데이트합니다 (동일한 카테고리 + 키 = 업데이트).
[CODE BLOCK]
응답:
GET /memory
선택적 필터로 메모리를 나열합니다.
[CODE BLOCK]
PUT /memory/:id
ID로 특정 메모리를 업데이트합니다.
[CODE BLOCK]
DELETE /memory/:id
단일 메모리를 삭제합니다.
[CODE BLOCK]
검색 엔드포인트
GET /memory/search
FTS5를 사용한 전문 검색입니다.
[CODE BLOCK]
FTS5 구문:
- 여러 단어 = AND:
- 구문:
- 접두사:
- 불린:
- 제외:
GET /memory/semantic-search
임베딩을 사용한 개념 검색입니다 (FTS5보다 느리지만 의미를 이해함).
[CODE BLOCK]
키워드가 일치하지 않더라도 쿼리와 의미론적으로 유사한 메모리를
반환합니다. X가 다르게 설명된 "X에 대한 메모리 찾기"에 유용합니다.
GET /memory/by-tag
태그로 메모리를 나열합니다.
[CODE BLOCK]
GET /memory/related/:id
특정 메모리와 관련된 메모리를 찾습니다 (공유 태그 기준).
[CODE BLOCK]
동기화 및 Diff
GET /memory/diff
증분 동기화 — 타임스탬프 이후 변경된 메모리를 반환합니다.
[CODE BLOCK]
응답:
POST /memory/sync
다른 인스턴스에서 diff를 적용합니다 (자체 호스팅 동기화용).
[CODE BLOCK]
대량 작업
POST /memory/bulk-delete
ID로 여러 메모리를 삭제합니다.
[CODE BLOCK]
POST /memory/embed-batch
아직 임베딩이 없는 메모리의 임베딩을 생성합니다 (의미론적 검색용).
[CODE BLOCK]
GET /memory/embed-batch-status
임베딩 생성 진행 상황을 확인합니다.
[CODE BLOCK]
검증
메모리에는 플래그가 있습니다. 에이전트가 저장한 메모리는
기본적으로 미검증()이며, 사람이 저장한 메모리는
검증됨()입니다.
POST /memory/verify
메모리를 검증됨으로 표시합니다 (Mind Key가 아닌 JWT 필요).
[CODE BLOCK]
POST /memory/unverify
메모리를 미검증으로 표시합니다 (JWT 필요).
[CODE BLOCK]
GET /memory/unverified
사용자 검증 대기 중인 메모리를 나열합니다.
[CODE BLOCK]
통계 및 감사
GET /memory/stats
현재 마인드에 대한 집계 통계입니다.
[CODE BLOCK]
반환:
GET /memory/audit
상태를 변경하는 모든 작업의 감사 로그입니다.
[CODE BLOCK]
GET /memory/contradictions
저장된 메모리의 잠재적 모순을 감지합니다.
[CODE BLOCK]
GET /memory/expiring
만료일이 다가오는 메모리를 나열합니다.
[CODE BLOCK]
상태 및 내보내기
GET /memory/health
메모리 시스템의 빠른 상태 확인입니다.
[CODE BLOCK]
GET /memory/mind-export
모든 메모리의 전체 JSON 내보내기입니다 (백업용).
[CODE BLOCK]
POST /memory/compact
유사한 메모리를 압축합니다 (자동 요약).
[CODE BLOCK]
다음 단계
- LLM을 위한 빠른 시작
- 메모리 모범 사례
- FTS5 검색
- 의미론적 검색
────────────────────────────────────────────────────────────
# API 개요 및 Base URL
SUMMARY: Synapse API의 모든 엔드포인트, Base URL, 인증 패턴, 응답 형식을 한눈에 살펴봅니다.
KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)
OR ?key=YOUR_MIND_KEY (query, 60 req/min)
All responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)
All 404 responses mean the path does not exist — do NOT guess paths.
GET /endpoints returns machine-readable list of all valid endpoints.
API 개요 및 Base URL
Synapse API는 RESTful HTTP API입니다. 모든 엔드포인트는 (명시된 경우를
제외하고) JSON을 반환합니다. 이 페이지에서는 개별 엔드포인트를 살펴보기 전에
알아두어야 할 필수 사항을 다룹니다.
Base URL
[CODE BLOCK]
이 문서의 모든 경로는 위 Base URL을 기준으로 합니다. 자체 호스팅 인스턴스의
경우, 본인의 URL로 교체하십시오.
인증
두 가지 방법이 있으며, 모두 헤더로 전송합니다:
[CODE BLOCK]
또는 쿼리 파라미터로도 가능합니다 (분당 60회로 제한):
[CODE BLOCK]
자세한 내용은 Authentication을 참조하십시오.
엔드포인트 그룹
| 그룹 | 인증 | 설명 |
|-------|------|-------------|
| Public | 없음 | 랜딩 페이지, 상태 확인, OpenAPI, 문서 |
| Memory | Mind Key | CRUD, 검색, 동기화, 임베딩 |
| Chat | Mind Key / JWT | 사람과 에이전트 간 비동기 메시징 |
| Tasks | Mind Key | 작업 관리 |
| Scripts | Mind Key / JWT | 영구 스크립트 저장소 |
| Scheduler | Mind Key | Cron 작업 및 변수 |
| Webhooks | Mind Key | 이벤트 시 HTTP 콜백 |
| Computers | Mind Key / JWT | 원격 컴퓨터 제어 |
| User/Minds | JWT | 계정 및 마인드 관리 |
| Sharing | JWT | 사용자 간 마인드 공유 |
| Push | JWT | Web Push 구독 |
| Tools | 없음 | 시간, 계산, 무작위 (공용 유틸리티) |
응답 형식
- JSON (기본값):
- 일반 텍스트: 은 LLM에 최적화된 텍스트를 반환
- HTML: , , , ,
표준 응답 봉투
성공 응답은 데이터를 직접 반환합니다:
[CODE BLOCK]
오류 응답은 다음 형식을 사용합니다:
[CODE BLOCK]
> [!NOTE]
> 필드는 일반적인 오류에 대한 관련 문서로 연결됩니다.
HTTP 상태 코드
| 코드 | 의미 |
|------|---------|
| 200 | 성공 (GET, PUT) |
| 201 | 생성됨 (POST) |
| 204 | 콘텐츠 없음 (DELETE) |
| 400 | 잘못된 요청 (검증 오류) |
| 401 | 인증되지 않음 (토큰 누락/잘못됨) |
| 403 | 금지됨 (잘못된 토큰 유형) |
| 404 | 찾을 수 없음 (경로가 존재하지 않음) |
| 409 | 충돌 (중복) |
| 429 | 요청이 너무 많음 (속도 제한) |
| 500 | 서버 오류 |
검색 가능 엔드포인트
| 엔드포인트 | 용도 |
|----------|---------|
| | 랜딩 페이지 (LLM 최적화) |
| | 모든 엔드포인트의 기계 판독 가능 목록 |
| | 일반 텍스트 엔드포인트 목록 |
| | OpenAPI 3.0 사양 |
| | 전체 API 문서 (HTML) |
| | JSON 형식의 API 문서 |
| | 문서 시스템 (HTML) |
| | 문서 인덱스 (JSON) |
| | 모든 문서를 하나의 텍스트 블록으로 |
| | 대화형 API 플레이그라운드 |
속도 제한
| 인증 방법 | 제한 |
|-------------|-------|
| Mind Key (헤더) | 없음 |
| Mind Key (?key=) | IP당 분당 60회 |
| JWT (헤더) | 없음 |
| 공용 엔드포인트 | 없음 |
속도 제한이 적용된 응답에는 다음이 포함됩니다:
[CODE BLOCK]
페이지네이션
목록 엔드포인트는 및 을 지원합니다:
[CODE BLOCK]
기본 limit: 100. 최대 limit: 500.
CORS
모든 엔드포인트는 브라우저 기반 클라이언트를 위한 CORS를 지원합니다:
[CODE BLOCK]
SDK 및 클라이언트
- Node.js SDK: (저장소)
- MCP 서버: (저장소)
- HTTP 클라이언트: 모든 HTTP 라이브러리 (curl, fetch, axios 등)
다음 단계
- Memory API — 가장 중요한 엔드포인트
- Chat API — 비동기 사람-에이전트 통신
- 오류 및 오류 처리
────────────────────────────────────────────────────────────
# 속도 제한 및 할당량
SUMMARY: Synapse API의 속도 제한 정책 — Bearer 헤더 (무제한), ?key= (분당 60회), 공용 엔드포인트.
KEY CONTEXT:
Mind Key (Authorization: Bearer header) → NO rate limit
Mind Key (?key= query param) → 60 req/min per IP
JWT (Authorization: Bearer header) → NO rate limit
Public endpoints (/tools/*, /docs, /health, /endpoints) → NO rate limit
Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After
Recommendation: ALWAYS use Authorization header. Use ?key= only for URL-only tools.
속도 제한 및 할당량
Synapse는 남용을 방지하면서 정상적인 사용을 방해하지 않는 단순하고
예측 가능한 속도 제한 정책을 가지고 있습니다.
속도 제한 정책
| 인증 방법 | 제한 | 범위 |
|-------------|-------|-------|
| Mind Key () | 없음 | 마인드별 |
| Mind Key () | 분당 60회 | IP별 |
| JWT () | 없음 | 사용자별 |
| 공용 엔드포인트 | 없음 | 전역 |
> [!TIP]
> 가능하면 항상 헤더를 사용하십시오. 속도
> 제한이 없습니다. 는 사용자 정의 헤더를 설정할 수 없는 도구에만
> 사용하십시오.
속도 제한 헤더
인증을 사용할 때, 응답에는 속도 제한 헤더가 포함됩니다:
[CODE BLOCK]
제한을 초과한 경우:
[CODE BLOCK]
속도 제한에 도달한 경우
429를 받은 경우:
1. Authorization 헤더로 전환 (권장):
[CODE BLOCK]
2. 또는 초 대기 후 재시도.
?key= 제한이 존재하는 이유
쿼리 파라미터는 URL 전용 도구(브라우저, 명령어)에
편리하지만, 보안 및 성능에 영향을 미칩니다:
- 보안: 쿼리 파라미터는 서버 접근 로그, 브라우저 기록, Referer 헤더에
기록됩니다. 사용량을 제한하면 노출이 줄어듭니다.
- 성능: 쿼리 파라미터 인증은 IP 기반 속도 제한기(요청당 Redis 조회)가
필요하여 지연이 추가됩니다. 헤더 인증은 이를 생략합니다.
- 남용 방지: 유출된 URL은 공유되어 남용될 수 있습니다. IP
제한으로 피해 범위를 제한합니다.
권장 패턴
LLM 에이전트
[CODE BLOCK]
브라우저 기반 도구
도구가 URL만 열 수 있는 경우:
[CODE BLOCK]
MCP 서버
MCP 서버는 항상 환경 변수를 통해 헤더 인증을
사용합니다 — 속도 제한이 적용되지 않습니다.
대량 가져오기
대량 작업(예: 1000개 메모리 가져오기)의 경우, 항상 헤더 인증을
사용하십시오. 를 통한 대량 가져오기는 1분 이내에 속도 제한에
도달합니다.
할당량 (마인드 수준)
현재 저장소 크기나 메모리 수에 대한 마인드별 할당량이 없습니다. 모든
제한은 데이터 수준이 아닌 인증/IP 수준에 있습니다. 이는 다중 테넌트
공정성을 위해 향후 변경될 수 있습니다.
사용량 모니터링
[CODE BLOCK]
다음 단계
- Authentication
- 오류 및 오류 처리
────────────────────────────────────────────────────────────
# Scripts API
SUMMARY: 영구 스크립트 저장소 — 재사용 가능한 shell, Python 또는 Node 스크립트를 저장하고 curl | bash로 가져옵니다.
KEY CONTEXT:
Auth: Mind Key or JWT
Store: POST /script { name, content, description?, language? }
Fetch as text: GET /script/:name (returns text/plain, curl | bash ready)
Info: GET /script/:name/info (metadata without content)
List: GET /scripts (JSON array)
Delete: DELETE /script/:name
Use case: store deployment scripts, config generators, troubleshooting snippets
Scripts API
Scripts API는 재사용 가능한 스크립트를 위한 영구 저장소를 제공합니다.
스크립트는 마인드 내에서 이름이 지정되고 버전 관리되며, 일반 텍스트로
가져올 수 있습니다 — 패턴에 적합합니다.
엔드포인트
POST /script
스크립트를 저장하거나 업데이트합니다.
[CODE BLOCK]
GET /script/:name
스크립트 내용을 으로 가져옵니다. bash로 파이프하기에 적합합니다.
[CODE BLOCK]
GET /script/:name/info
내용 없이 스크립트 메타데이터를 가져옵니다.
[CODE BLOCK]
응답:
[CODE BLOCK]
GET /scripts
현재 마인드의 모든 스크립트를 나열합니다.
[CODE BLOCK]
DELETE /script/:name
스크립트를 삭제합니다.
[CODE BLOCK]
일반적인 사용 사례
배포 스크립트
LLM이 매번 단계를 다시 도출하지 않고도 실행할 수 있도록 표준 배포 절차를
저장합니다:
[CODE BLOCK]
문제 해결 스니펫
일반적인 문제에 대한 진단 명령을 저장합니다:
[CODE BLOCK]
구성 생성기
구성을 생성하는 스크립트를 저장합니다:
[CODE BLOCK]
다음 단계
- Variables API
- Cron 및 Scheduler
────────────────────────────────────────────────────────────
# Tasks API
SUMMARY: LLM 에이전트용 작업 관리 — 우선순위와 함께 작업을 생성, 나열, 업데이트, 완료, 삭제합니다.
KEY CONTEXT:
Auth: Mind Key
List: GET /mind/tasks?status=pending|in_progress|done|cancelled|all
Create: POST /mind/task { title, description?, priority?, due_at? }
Update: PUT /mind/task/:id { title?, description?, priority?, status?, due_at? }
Complete: GET /mind/task/:id/complete
Delete: GET /mind/task/:id/delete
Priorities: low, normal, high, critical
Statuses: pending, in_progress, done, cancelled
Pattern: create tasks for multi-step work, update status as you progress
Tasks API
Tasks API는 LLM 에이전트에게 다단계 작업을 추적하는 구조화된 방법을
제공합니다. 작업은 현재 마인드로 범위가 지정되며 세션 간에 유지되므로,
에이전트는 중단한 곳에서부터 작업을 재개할 수 있습니다.
엔드포인트
GET /mind/tasks
현재 마인드의 모든 작업을 나열합니다.
[CODE BLOCK]
응답:
[CODE BLOCK]
POST /mind/task
새 작업을 생성합니다.
[CODE BLOCK]
GET /mind/task (쿼리 파라미터)
GET으로 작업을 생성합니다 (URL 전용 도구용).
[CODE BLOCK]
PUT /mind/task/:id
기존 작업을 업데이트합니다.
[CODE BLOCK]
GET /mind/task/:id/complete
작업을 완료로 표시합니다.
[CODE BLOCK]
GET /mind/task/:id/delete
작업을 영구적으로 삭제합니다.
[CODE BLOCK]
우선순위
- — 긴급하지 않음
- — 기본값
- — 중요
- — 즉시 수행 필요
상태
- — 생성됨, 시작되지 않음
- — 현재 작업 중
- — 완료됨
- — 중단됨
패턴: 작업 기반 워크플로우
[CODE BLOCK]
다음 단계
- 작업 기반 워크플로우
- Cron 및 Scheduler
────────────────────────────────────────────────────────────
# 유틸리티 도구 (time, calc, random)
SUMMARY: 공용 유틸리티 엔드포인트 — 서버 시간, 안전한 계산기, 무작위 값 생성기. 인증 불필요.
KEY CONTEXT:
No auth required for any /tools/* endpoint.
GET /tools/time → { time, timezone, offset }
GET /tools/calc?expr=(10+5)*3 → { result, expr } (safe, no eval, arithmetic only)
GET /tools/random?type=uuid → { value, type } (types: uuid, int, float, hex, alpha)
Use case: LLM agents that need current time, safe math, or random values.
유틸리티 도구
엔드포인트는 공용 유틸리티입니다 — 인증이 필요하지 않습니다.
서버 측 시간, 안전한 수학, 또는 무작위 값이 필요한 LLM 에이전트에
유용합니다.
GET /tools/time
현재 서버 시간, 시간대, UTC 오프셋을 가져옵니다.
[CODE BLOCK]
응답:
[CODE BLOCK]
사용 사례: 스케줄링, 타임스탬프, 또는 상대적 날짜 계산을 위해 "지금 몇
시인지" 알아야 하는 LLM 에이전트.
GET /tools/calc
안전한 계산기 — 산술만 지원, 없음. , , , , ,
, , 숫자를 지원합니다.
[CODE BLOCK]
응답:
[CODE BLOCK]
> [!TIP]
> 머릿속으로 또는 문자열 파싱을 통해 수학을 하는 대신 이것을
> 사용하십시오. 안전하고 (코드 주입 불가) 정확합니다.
지원 연산자
- 덧셈
- 뺄셈
- 곱셈
- 나눗셈
- 나머지
- 괄호
- 숫자 (정수 및 소수)
예시
[CODE BLOCK]
GET /tools/random
무작위 값을 생성합니다.
[CODE BLOCK]
타입 파라미터
| 타입 | 파라미터 | 출력 |
|------|-----------|--------|
| | 없음 | UUID v4 문자열 |
| | , (기본값 0-100) | 정수 |
| | , (기본값 0-100) | 소수 |
| | , (길이 범위, 기본값 8-16) | Hex 문자열 |
| | , (길이 범위, 기본값 8-16) | 알파벳 문자열 |
LLM 에이전트를 위한 사용 사례
고유 ID 생성
[CODE BLOCK]
백분율 계산
[CODE BLOCK]
현재 타임스탬프 가져오기
[CODE BLOCK]
테스트 데이터 생성
[CODE BLOCK]
다음 단계
- API 개요 — 모든 엔드포인트 그룹
- 오류 및 오류 처리
────────────────────────────────────────────────────────────
# User 및 Minds API
SUMMARY: 계정 관리 — 가입, 로그인, 마인드 생성, 마인드 나열, 마인드 삭제. JWT로 보호됨.
KEY CONTEXT:
Auth: JWT (from /register or /login)
Register: POST /register { email, password, display_name? } → returns JWT
Login: POST /login { email, password } → returns JWT
Create mind: POST /minds { name, description? } → returns mind_key (shown once!)
List minds: GET /minds
Delete mind: DELETE /minds/:id (irreversible — deletes all memories!)
JWT expires after 7 days. Mind Key never expires.
Mind Key is shown only once at creation — save it permanently.
User 및 Minds API
User 및 Minds API는 계정 관리를 처리합니다. 이 엔드포인트들은 계정
수준에서 작동하므로 (마인드 수준이 아님) Mind Key가 아닌 JWT 인증을
사용합니다.
인증 엔드포인트
POST /register
새 사용자 계정을 생성합니다.
[CODE BLOCK]
응답:
[CODE BLOCK]
POST /login
기존 계정에 로그인합니다.
[CODE BLOCK]
응답: 와 동일.
마인드 엔드포인트
POST /minds
새 마인드를 생성합니다. Mind Key를 반환합니다 — 즉시 저장하십시오,
한 번만 표시됩니다.
[CODE BLOCK]
응답:
[CODE BLOCK]
> [!CRITICAL]
> 는 한 번만 표시됩니다. 분실하면 복구할 수 없으며 — 마인드를
> 삭제하고 새로 만들어야 합니다 (저장된 모든 메모리가 손실됨).
GET /minds
현재 사용자의 모든 마인드를 나열합니다.
[CODE BLOCK]
응답:
[CODE BLOCK]
DELETE /minds/:id
마인드를 영구적으로 삭제합니다.
[CODE BLOCK]
> [!WARNING]
> 마인드 삭제는 되돌릴 수 없습니다. 해당 마인드의 모든 메모리, 작업,
> 채팅 기록, 스크립트가 영구적으로 손실됩니다. 백업이 필요한 경우 먼저
> 로 내보내십시오.
다중 마인드 패턴
대부분의 사용자는 컨텍스트를 격리하기 위해 여러 마인드를 사용하면
이점이 있습니다:
[CODE BLOCK]
다른 LLM 세션에서 다른 Mind Key를 사용하여 컨텍스트를 격리하십시오.
계정 보안
비밀번호 요구 사항
- 최소 6자
- 최대값 없음 (비밀번호 관리자 사용)
- bcrypt 해시로 저장 (평문 저장 안 함)
JWT 만료
JWT는 7일 후에 만료됩니다. 만료되면 을 다시 호출하십시오.
Mind Key 보안
Mind Key는 만료되지 않습니다. Mind Key가 노출된 경우:
1. 로 새 마인드 생성
2. 새 Mind Key로 LLM 구성 업데이트
3. 로 노출된 마인드 삭제
다음 단계
- Authentication — 전체 인증 가이드
- Mind Key vs JWT — 결정 가이드
- Sharing API — 다른 사용자와 마인드 공유
────────────────────────────────────────────────────────────
# Variables API
SUMMARY: LLM 상태를 위한 빠른 키-값 저장소 — 카운터, 플래그, 마지막 확인 타임스탬프, 부분 진행 상황.
KEY CONTEXT:
Auth: Mind Key
Set: POST /var { key, value }
Get: GET /var/:key
List: GET /var
Delete: DELETE /var/:key
Use case: store last-seen timestamps, counters, flags, partial workflow state
Faster than memory (PostgreSQL direct, no FTS5 indexing)
Not for: structured facts (use /memory), long content (use /script)
Variables API
Variables API는 임시 상태를 위한 빠른 키-값 저장소입니다. (인덱싱되고,
검색 가능하며 구조화된) 메모리와 달리 변수는 빠른 읽기/쓰기 액세스에
최적화되어 있습니다 — 카운터, 플래그, 세션 상태에 적합합니다.
엔드포인트
POST /var
변수를 설정하거나 업데이트합니다.
[CODE BLOCK]
GET /var/:key
단일 변수를 가져옵니다.
[CODE BLOCK]
응답:
[CODE BLOCK]
GET /var
모든 변수를 나열합니다.
[CODE BLOCK]
DELETE /var/:key
변수를 삭제합니다.
[CODE BLOCK]
Variables와 Memory 사용 시기
| 사용 사례 | 사용 |
|----------|-----|
| 사용자 이름, 선호도 | Memory (검색 가능, 구조화) |
| 마지막 세션 타임스탬프 | Variable (임시 상태) |
| 카운터 (예: 전송된 메시지) | Variable (빈번한 업데이트) |
| 워크플로우 상태 ("5단계 중 3단계 완료") | Variable (일시적) |
| 긴 형식의 프로젝트 노트 | Memory (전문 인덱싱) |
| 재사용 가능한 스크립트 | Script store (이름 지정, 버전 관리) |
일반적인 패턴
마지막 세션 추적
[CODE BLOCK]
카운터 패턴
[CODE BLOCK]
기능 플래그
[CODE BLOCK]
다음 단계
- Memory API — 구조화되고 검색 가능한 데이터용
- Cron 및 Scheduler
────────────────────────────────────────────────────────────
# Webhooks API
SUMMARY: 메모리, 채팅, 작업 이벤트에 대한 HTTP 콜백 등록 — 데이터 변경 시 알림을 받습니다.
KEY CONTEXT:
Auth: Mind Key
Register: POST /webhooks { url, events, secret? }
List: GET /webhooks
Get: GET /webhooks/:id
Update: PUT /webhooks/:id { url?, events?, secret?, enabled? }
Delete: DELETE /webhooks/:id
Events: memory.*, memory.store, memory.update, memory.delete, chat.*, chat.message_received, task.*, task.created, task.completed
Secret: HMAC-SHA256 signed payload, sent in X-Synapse-Signature header
Pattern: register webhook → receive POST → process event → call Synapse API
Webhooks API
웹훅을 사용하면 Synapse에서 이벤트가 발생할 때 HTTP 콜백을 받을 수
있습니다. 외부 자동화 트리거, 알림 전송, 또는 다른 시스템으로의 동기화에
적합합니다.
엔드포인트
POST /webhooks
새 웹훅을 등록합니다.
[CODE BLOCK]
응답:
[CODE BLOCK]
GET /webhooks
현재 마인드의 모든 웹훅을 나열합니다.
[CODE BLOCK]
GET /webhooks/:id
단일 웹훅을 가져옵니다.
[CODE BLOCK]
PUT /webhooks/:id
웹훅을 업데이트합니다 (URL, 이벤트, 시크릿, 또는 활성화 플래그).
[CODE BLOCK]
DELETE /webhooks/:id
웹훅을 삭제합니다.
[CODE BLOCK]
이벤트 유형
| 패턴 | 발생 시점 |
|---------|------------|
| | 모든 메모리 이벤트 |
| | 새 메모리 저장 |
| | 메모리 업데이트 |
| | 메모리 삭제 |
| | 모든 채팅 이벤트 |
| | 사람이 보낸 새 메시지 |
| | 모든 작업 이벤트 |
| | 새 작업 생성 |
| | 작업 완료 표시 |
| | 모든 이벤트 |
웹훅 페이로드
이벤트가 발생하면 Synapse가 귀하의 URL로 POST합니다:
[CODE BLOCK]
서명 검증
을 설정하면 Synapse가 각 페이로드를 HMAC-SHA256으로 서명합니다:
[CODE BLOCK]
핸들러에서 검증:
[CODE BLOCK]
패턴: 실시간 동기화
[CODE BLOCK]
다음 단계
- Cron 및 Scheduler
- 웹훅 자동화 가이드
## 카테고리: MCP 통합
Claude, Cursor 및 기타 MCP 클라이언트와의 통합.
────────────────────────────────────────────────────────────
# Claude Code에서 MCP
SUMMARY: Claude Code 터미널 에이전트에서 Synapse 도구 사용 — 코딩 세션을 위한 영구 메모리.
KEY CONTEXT:
Claude Code config: ~/.claude/config.json (or via `claude mcp add` command)
Command: npx -y synapse-mcp-api@latest
Env: SYNAPSE_MIND_KEY (required), SYNAPSE_URL (optional)
Alternative: `claude mcp add synapse -- npx -y synapse-mcp-api@latest`
Then: set SYNAPSE_MIND_KEY env var in your shell
Test: in claude code, type "recall all my memories"
Claude Code에서 MCP
Claude Code는 Anthropic의 터미널 기반 코딩 에이전트입니다. Synapse MCP를
사용하면 Claude Code가 코딩 세션 간에 영구 메모리를 얻습니다 — 프로젝트
컨텍스트, 과거 결정, 코드베이스 패턴을 기억합니다.
설정
방법 1: CLI 명령 (권장)
[CODE BLOCK]
방법 2: 구성 파일 편집
편집:
[CODE BLOCK]
작동 확인
Claude Code 시작:
[CODE BLOCK]
Claude Code 프롬프트에서 입력:
[CODE BLOCK]
Claude가 을 호출하고 저장된 메모리로 응답해야 합니다.
일반적인 패턴
프로젝트 컨텍스트 유지
코딩 세션 시작 시:
[CODE BLOCK]
Claude가 을 호출하여 프로젝트 목록을 보고, 중단한 곳에서
작업을 계속합니다.
코드베이스 결정
아키텍처 결정을 내릴 때:
[CODE BLOCK]
Claude가 카테고리 , 우선순위 로 를 호출합니다.
과거 실수 방지
[CODE BLOCK]
Claude가 카테고리 로 메모리를 검색하고 과거 오류를 상기시켜 줍니다.
작업 추적
[CODE BLOCK]
Claude가 를 호출하고, 작업이 세션 간에 유지됩니다.
도구 프로필
119개 도구 모두가 필요 없는 코딩 세션의 경우:
[CODE BLOCK]
문제 해결
MCP 서버가 시작되지 않음
[CODE BLOCK]
Mind Key 인식되지 않음
[CODE BLOCK]
Claude Code가 도구를 보지 못함
- 구성 변경 후 Claude Code 재시작
- 로 Synapse가 등록되었는지 확인
- MCP 문제 해결 참조
다음 단계
- Claude Desktop 설정
- Cursor 설정
- 영구 LLM 에이전트 가이드
────────────────────────────────────────────────────────────
# Claude Desktop에서 MCP
SUMMARY: 2분 안에 Synapse를 Claude Desktop에 연결. Claude가 79개의 Synapse 도구를 네이티브로 받습니다.
KEY CONTEXT:
Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
%APPDATA%\Claude\claude_desktop_config.json (Windows)
MCP server command: npx -y synapse-mcp-api@latest
Env vars: SYNAPSE_MIND_KEY (required), SYNAPSE_URL (optional, default https://synapse.schaefer.zone)
After config: restart Claude Desktop, check for 🔌 icon with "79 tools"
Test: type "memory_recall aufrufen" in a new chat
Troubleshooting: Node.js ≥ 18, check Mind Key, see /docs/mcp/troubleshooting
Claude Desktop에서 MCP
Claude Desktop은 macOS 및 Windows용 Anthropic의 데스크톱 앱입니다. Synapse
MCP 서버를 구성하면 Claude가 79개의 모든 Synapse 도구에 네이티브로 접근할
수 있습니다 — 메모리 저장, 회상, 작업 관리, 채팅 등이 가능합니다.
사전 요구 사항
- Claude Desktop 앱 (macOS 또는 Windows)
- Node.js 18+ 설치 ()
- 귀하의 Synapse Mind Key
1단계: 구성 파일 열기
- macOS:
- Windows:
파일이 없으면 생성하십시오.
2단계: Synapse MCP 서버 추가
[CODE BLOCK]
> [!TIP]
> 이미 다른 MCP 서버가 구성된 경우, 기존 객체 안에
> 블록을 추가하면 됩니다.
3단계: Claude Desktop 재시작
1. Claude Desktop을 완전히 종료 (macOS에서 Cmd+Q, 창 닫기가 아님)
2. Claude Desktop 다시 열기
3. 새 채팅 시작
4. 좌측 하단의 🔌 플러그 아이콘 확인 — "79 tools"라고 표시되어야 함
4단계: 테스트
새 채팅에서 입력:
[CODE BLOCK]
Claude가 도구를 호출하고 저장된 메모리의 요약으로 응답해야
합니다 (마인드가 비어 있는 경우 "No memories yet").
사용 가능한 도구 (선택)
| 도구 | 설명 |
|------|-------------|
| | 모든 메모리 회상 |
| | 새 메모리 저장 |
| | 메모리 검색 |
| | 작업 나열 |
| | 작업 생성 |
| | 새 메시지 확인 |
| | 메시지에 응답 |
| | 브라우저 탭 열기 |
| | 등록된 컴퓨터 나열 |
전체 목록: MCP란 무엇입니까?
문제 해결
Claude Desktop에 도구가 나타나지 않음
1. Node.js 버전 확인: (≥ 18이어야 함)
2. 구성 파일이 유효한 JSON인지 확인 (후행 쉼표 없음)
3. Claude Desktop을 완전히 재시작 (Cmd+Q, 창 닫기가 아님)
4. Claude Desktop 로그 확인: (macOS)
"Mind Key invalid" 오류
- 가 로 시작하는지 확인
- 로 새 키 받기 (의 JWT 필요)
- JSON에서 키 주변에 따옴표 없음
npx를 찾을 수 없음
- Node.js 18+ 설치:
- 설치 후 터미널 재시작
- Homebrew가 있는 macOS:
도구는 표시되지만 호출이 실패
- 이 접근 가능한지 확인:
- Mind Key가 작동하는지 확인:
- MCP 문제 해결 참조
도구 프로필 (토큰 절약)
더 작은 LLM을 사용하거나 컨텍스트 토큰을 절약하려는 경우, 도구 프로필 설정:
[CODE BLOCK]
프로필: (8개 도구), (25), (119, 기본값).
다음 단계
- Claude Code 설정
- Cursor 설정
- MCP 문제 해결
────────────────────────────────────────────────────────────
# Continue.dev에서 MCP
SUMMARY: Synapse를 Continue.dev에 연결 — VS Code 및 JetBrains용 오픈 소스 AI 코딩 어시스턴트.
Continue.dev에서 MCP
Continue.dev는 VS Code 및 JetBrains IDE용 오픈 소스 AI 코딩 어시스턴트입니다.
Synapse MCP를 사용하면 Continue가 세션 간에 영구 메모리를 얻습니다.
사전 요구 사항
- VS Code 또는 JetBrains IDE
- Continue.dev 확장 설치
- Node.js 18+
- 귀하의 Synapse Mind Key
설정
1단계: Continue 구성 열기
VS Code 또는 JetBrains에서:
1. Continue 확장 사이드바 열기
2. 기어 아이콘 클릭 → "Open config.json"
또는 을 직접 편집하십시오.
2단계: Synapse MCP 서버 추가
[CODE BLOCK]
3단계: Continue 다시 로드
VS Code 창 다시 로드 (Cmd+Shift+P → "Reload Window") 또는 IDE 재시작.
작동 확인
Continue 채팅에서:
[CODE BLOCK]
Continue이 을 호출하고 저장된 메모리로 응답해야 합니다.
일반적인 패턴
프로젝트 컨텍스트
[CODE BLOCK]
Continue이 을 호출하여 프로젝트 메모리를 보고, 중단한 곳에서
작업을 계속합니다.
코드 리뷰 패턴
[CODE BLOCK]
Continue이 저장된 코드 리뷰 패턴을 찾아 적용합니다.
페어 프로그래밍 메모리
[CODE BLOCK]
Continue이 메모리로 저장합니다.
문제 해결
MCP 서버가 연결되지 않음
1. 이 유효한 JSON인지 확인
2. Node.js 확인:
3. Continue의 출력 패널 확인 (View → Output → Continue)
4. IDE 재시작
도구가 나타나지 않음
- Continue 버전이 MCP를 지원하는지 확인 (≥ 0.9.x)
- 구성에서 환경 변수가 설정되었는지 확인
- Continue의 로그에서 MCP 오류 확인
다음 단계
- Claude Desktop 설정
- 커스텀 MCP 클라이언트
────────────────────────────────────────────────────────────
# Cursor에서 MCP
SUMMARY: 코딩 세션 간 영구 프로젝트 메모리를 위해 Synapse를 Cursor IDE에 연결.
Cursor에서 MCP
Cursor는 VS Code 기반의 AI 구동 IDE입니다. Synapse MCP를 사용하면 Cursor가
세션 간에 영구 메모리를 얻습니다 — 프로젝트 결정, 코드베이스 패턴, 과거
디버깅 세션을 기억합니다.
사전 요구 사항
- Cursor IDE 설치 ()
- Node.js 18+
- 귀하의 Synapse Mind Key
설정
1단계: Cursor 설정 열기
Cursor에서:
1. 설정 열기 (macOS에서 Cmd+, Windows/Linux에서 Ctrl+,)
2. "MCP" 검색 또는 로 이동
2단계: Synapse MCP 서버 추가
"Add MCP Server" 클릭 및 구성:
| 필드 | 값 |
|-------|-------|
| Name | |
| Type | |
| Command | |
| Env | |
3단계: config.json 직접 편집 (대안)
Cursor는 에 MCP 구성을 저장합니다:
[CODE BLOCK]
4단계: Cursor 재시작
Cursor를 완전히 재시작 (macOS에서 Cmd+Q 후 다시 열기).
작동 확인
Cursor의 채팅 패널 (Cmd+L)에서:
[CODE BLOCK]
Cursor가 을 호출하고 저장된 메모리로 응답해야 합니다.
일반적인 패턴
프로젝트 온보딩
새 프로젝트를 열 때:
[CODE BLOCK]
Cursor가 을 호출하고 중단한 곳에서 작업을 계속합니다.
아키텍처 결정
[CODE BLOCK]
Cursor가 우선순위로 메모리로 저장합니다.
디버깅 기록
[CODE BLOCK]
Cursor가 메모리를 검색하고 과거 수정을 상기시켜 줍니다.
세션 간 코드 패턴
[CODE BLOCK]
Cursor가 이전에 구현한 인증 구현에 대한 메모리를 찾습니다.
문제 해결
MCP 서버가 연결되지 않음
1. Node.js 확인: (≥ 18)
2. MCP 서버 테스트: (오류 없이 시작해야 함)
3. Cursor의 MCP 로그 확인 (View → Output → MCP)
4. Cursor 완전히 재시작
도구가 나타나지 않음
- 이 유효한 JSON인지 확인
- 환경 변수가 설정되었는지 확인
- Cursor 버전이 MCP를 지원하는지 확인 (≥ 0.42)
Mind Key 무효
[CODE BLOCK]
다음 단계
- Claude Desktop 설정
- Continue.dev 설정
- 영구 LLM 에이전트 가이드
────────────────────────────────────────────────────────────
# 커스텀 MCP 클라이언트 구축
SUMMARY: MCP SDK를 사용하여 귀하의 애플리케이션에서 Synapse MCP 서버에 연결.
커스텀 MCP 클라이언트 구축
자체 LLM 애플리케이션을 구축하는 경우, 공식 MCP SDK를 사용하여 Synapse
MCP 서버에 직접 연결할 수 있습니다. 이를 통해 앱이 79개의 모든 Synapse
도구에 접근할 수 있습니다.
SDK
| 언어 | 패키지 |
|----------|---------|
| TypeScript/JavaScript | |
| Python | |
TypeScript 예시
설치
[CODE BLOCK]
stdio를 통한 연결
[CODE BLOCK]
HTTP/SSE를 통한 연결 (원격)
[CODE BLOCK]
Python 예시
설치
[CODE BLOCK]
stdio를 통한 연결
[CODE BLOCK]
도구 프로필
연결 시, 헤더 (HTTP/SSE) 또는 환경 변수
(stdio)를 통해 특정 도구 프로필을 요청할 수 있습니다:
[CODE BLOCK]
오류 처리
[CODE BLOCK]
사용 사례
- 커스텀 AI 어시스턴트 — 영구 메모리가 있는 자체 에이전트 구축
- 워크플로우 자동화 — 커스텀 워크플로우에서 Synapse 도구 체인
- 데이터 파이프라인 — 메모리 추출, 변환, 다른 곳에 로드
- 모니터링 대시보드 — 메모리 통계, 채팅 기록, 작업 표시
다음 단계
- MCP 사양
- Synapse MCP 저장소
- API 개요
────────────────────────────────────────────────────────────
# MCP 문제 해결
SUMMARY: 일반적인 MCP 통합 문제 해결 — 서버 시작 안 됨, 도구 나타나지 않음, 인증 오류.
KEY CONTEXT:
Common issues:
1. Node.js < 18 → upgrade to 18+
2. Mind Key invalid → check format (mk_...), get fresh via POST /minds
3. npx not found → install Node.js
4. Tools not appearing → restart client, check config JSON validity
5. SYNAPSE_URL unreachable → curl /health to verify
6. MCP server crashes → check logs, run npx manually to see error
Debug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr
Logs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/
MCP 문제 해결
Synapse MCP를 LLM 클라이언트와 통합할 때 일반적인 문제와 해결 방법입니다.
빠른 진단 체크리스트
1. ✅ Node.js 18+ 설치? ()
2. ✅ Mind Key가 로 시작? (JWT 가 아님)
3. ✅ Synapse API 접근 가능? ()
4. ✅ Mind Key 작동? ()
5. ✅ 구성 파일이 유효한 JSON? (후행 쉼표 없음, 주석 없음)
6. ✅ 구성 변경 후 클라이언트 재시작?
7. ✅ MCP 서버가 수동으로 시작? ()
문제: 클라이언트에 도구가 나타나지 않음
증상
- Claude Desktop / Cursor / Continue이 0개 도구 표시
- 🔌 아이콘이나 MCP 서버 목록에 "synapse" 항목 없음
해결 방법
1. 클라이언트 완전히 재시작 — macOS에서 Cmd+Q (창 닫기가 아님)
2. 구성 파일 위치 확인:
- Claude Desktop macOS:
- Claude Desktop Windows:
- Cursor:
- Continue:
3. JSON 검증 — 구성을 에 붙여넣기
4. 클라이언트 로그에서 MCP 오류 확인:
- Claude Desktop: (macOS)
- Cursor: View → Output → MCP
5. MCP 서버 수동 실행하여 시작 오류 확인:
[CODE BLOCK]
문제: "Mind Key invalid" 오류
증상
- 도구는 나타나지만 호출이 "401 Unauthorized"로 실패
- 오류: "Mind Key fehlt oder ungültig"
해결 방법
1. Mind Key 형식 확인 — 로 시작, 약 40자
2. 직접 테스트:
[CODE BLOCK]
3. 환경 변수가 설정되었는지 확인 — stdio 전송의 경우, 환경 변수가
셸이 아닌 MCP 서버 구성에 있어야 함
4. 새 Mind Key 받기:
[CODE BLOCK]
문제: npx를 찾을 수 없음
증상
- 오류: "npx: command not found"
- MCP 서버가 시작되지 않음
해결 방법
1. Node.js 18+ 설치:
- macOS: 또는 에서 다운로드
- Linux:
- Windows: 에서 다운로드
2. 설치 후 터미널 재시작
3. 확인:
문제: SYNAPSEURL 접근 불가
증상
- MCP 서버는 시작되지만 도구 호출이 시간 초과
- 오류: "fetch failed" 또는 "ECONNREFUSED"
해결 방법
1. 연결 테스트:
[CODE BLOCK]
2. 기업 방화벽 확인 — 아웃바운드 HTTPS를 차단할 수 있음
3. 대체 URL 시도:
- 프로덕션:
- MCP 서버:
4. 자체 호스팅의 경우: Synapse 인스턴스가 실행 중이고 접근 가능한지 확인
문제: MCP 서버 충돌
증상
- MCP 서버가 시작 후 즉시 종료
- 클라이언트 로그에 "MCP server disconnected" 표시
해결 방법
1. 수동 실행하여 오류 확인:
[CODE BLOCK]
2. 포트 충돌 확인 — MCP 서버는 기본적으로 포트 13100 사용
3. npx 캐시 삭제:
[CODE BLOCK]
4. 최신으로 업데이트:
[CODE BLOCK]
문제: 도구 호출이 429 반환
증상
- 오류: "Rate limit exceeded"
해결 방법
이는 MCP에서 발생하지 않아야 합니다 (헤더 인증 사용, 속도 제한 없음). 발생하는 경우:
1. 어딘가에서 를 사용하고 있는지 확인 — 헤더 인증으로 전환
2. 확인 — 올바른 인스턴스를 가리키는지 확인
3. 문제가 지속되면 지원팀에 연락
문제: 도구는 나타나지만 작동하지 않음
증상
- 클라이언트에 도구 나열됨
- 도구 호출이 오류를 반환하거나 결과 없음
해결 방법
1. 도구 이름 확인 — 정확해야 함 (예: 이 아닌 )
2. 인수 확인 — 도구의 입력 스키마 확인
3. 직접 API로 테스트:
[CODE BLOCK]
4. Synapse 상태 확인:
[CODE BLOCK]
도움말 받기
위의 방법으로 문제가 해결되지 않으면:
1. 기존 이슈 확인:
2. 새 이슈 열기:
- MCP 서버 버전 ()
- 클라이언트 이름 및 버전
- 운영 체제
- 관련 로그 발췌
- 재현 단계
다음 단계
- Claude Desktop 설정
- Claude Code 설정
- API 오류
────────────────────────────────────────────────────────────
# MCP란 무엇입니까?
SUMMARY: Model Context Protocol은 LLM이 외부 도구를 호출할 수 있게 합니다. Synapse는 공식 MCP 서버를 통해 79개 도구를 노출합니다.
KEY CONTEXT:
MCP = Model Context Protocol (Anthropic, 2024). Open standard for LLM-tool integration.
Synapse has official MCP server: synapse-mcp-api (npm package, npx -y synapse-mcp-api@latest)
79 tools exposed: 22 memory, 7 chat, 8 scheduler, 4 tasks, 5 scripts, 9 computers, 4 push, 5 user, 3 utility
3 transports: stdio (local), HTTP/SSE (remote), WebSocket (mobile)
Supported clients: Claude Desktop, Claude Code, Cursor, Continue, Cline, any MCP-compatible client
Tool Profiles (v1.4.0): minimal (8 tools), standard (25), full (119) — controlled via MCP_PROFILE env or Mcp-Tool-Profile header
MCP란 무엇입니까?
Model Context Protocol (MCP)은 LLM이 구조화된 방식으로 외부 도구를
호출할 수 있게 하는 Anthropic (2024)의 개방 표준입니다. API 문서를
프롬프트에 붙여넣는 대신, MCP 서버에 도구를 등록하고 LLM이 필요할 때
호출합니다 — function calling과 같지만, 표준화되고 클라이언트에 독립적입니다.
Synapse MCP 서버
Synapse는 모든 Synapse 기능을 다루는 79개 도구를 노출하는 공식 MCP
서버 ( on npm)를 제공합니다:
| 카테고리 | 도구 | 수 |
|----------|-------|-------|
| Memory | recall, list, store, search, semantic-search, update, delete, bulk-delete, stats, unverified, contradictions, audit, related, by-tag, diff, expiring, health, sync, embed-batch, verify, unverify, mind-export | 22 |
| Chat | poll, reply, status, history, unread, send, upload | 7 |
| Scheduler | cronlist, croncreate, crondelete, crontoggle, varlist, varget, varset, vardelete | 8 |
| Tasks | tasklist, taskget, taskcreate, taskupdate | 4 |
| Scripts | scriptlist, scriptget, scriptinfo, scriptstore, scriptdelete | 5 |
| Computers | computerlist, computerget, installcode, screenshot, commandqueue, commandstatus, commandslist, disable, delete | 9 |
| Push | vapidpublickey, subscribe, unsubscribe, test | 4 |
| User/Mind | register, login, mindslist, mindcreate, minddelete | 5 |
| Utility | time, calc, random | 3 |
| Visualization | graph, tags, compact | 3 |
| Sharing | share, list, revoke | 3 |
| Webhooks | register, list, get, update, delete | 5 |
| Browser | new, navigate, click, type, screenshot, close | 6 |
| 합계 | | 79+ |
작동 방식
[CODE BLOCK]
1. LLM 클라이언트 (Claude Desktop, Cursor 등)를 구성하여 Synapse MCP 서버 사용
2. 클라이언트가 MCP 서버 시작 (를 통해)
3. MCP 서버가 Mind Key를 사용하여 Synapse API에 연결
4. LLM이 79개 도구 모두를 호출할 수 있는 네이티브 함수로 봄
5. LLM이 무언가를 기억해야 할 때 를 호출 — MCP 서버가 이를 Synapse의 로 변환
전송
Synapse MCP 서버는 세 가지 전송을 지원합니다:
stdio (로컬, 데스크톱에 권장)
[CODE BLOCK]
HTTP/SSE (원격, 다중 테넌트)
MCP 클라이언트를 다음에 연결:
[CODE BLOCK]
WebSocket (모바일, 대용량)
[CODE BLOCK]
도구 프로필 (v1.4.0)
더 작은 LLM의 토큰 오버헤드를 줄이기 위해 MCP 서버는 세 가지 도구
프로필을 지원합니다:
| 프로필 | 도구 | 토큰 | 적합한 용도 |
|---------|-------|--------|----------|
| | 8 (복합 디스패치) | 500 | ≤8k 컨텍스트의 자체 호스팅 LLM |
| | 25 (이름 지정) | 2,500 | 중간 크기 LLM (Claude Haiku, GPT-3.5) |
| | 119 (전체) | 8,250 | 대형 LLM (Claude Sonnet/Opus, GPT-4) — 기본값 |
제어 방법:
- 환경 변수:
- 헤더:
지원되는 클라이언트
- Claude Desktop — Anthropic의 데스크톱 앱
- Claude Code — 터미널 코딩 에이전트
- Cursor — AI 구동 IDE
- Continue.dev — 오픈 소스 AI 코딩 어시스턴트
- Cline — VS Code 확장
- 모든 MCP 호환 클라이언트
MCP 대신 직접 API를 사용하는 이유?
| 접근 방식 | 장점 | 단점 |
|----------|------|------|
| 직접 API | 단순, 추가 계층 없음 | LLM이 URL, 헤더, 인증을 알아야 함 |
| MCP | LLM이 네이티브 도구를 봄, URL 암기 불필요 | 추가 MCP 서버 프로세스 |
대부분의 LLM 에이전트 사용 사례에서 MCP가 더 나은 선택입니다 — LLM이
API 경로나 인증 패턴을 기억할 필요가 없습니다.
다음 단계
- Claude Desktop 설정 — 2분 구성
- Claude Code 설정 — 터미널 통합
- 커스텀 MCP 클라이언트 — 자체 구축
## 카테고리: 가이드 및 튜토리얼
구체적인 시나리오를 위한 단계별 가이드.
────────────────────────────────────────────────────────────
# 자동화된 iOS 앱 테스트
SUMMARY: Synapse와 Computer Control API를 사용하여 Simulator를 통해 iOS 앱 테스트를 자동화합니다.
자동화된 iOS 앱 테스트
Synapse의 메모리 시스템을 Computer Control API와 결합하여 LLM 기반 iOS 앱
테스트를 구축하십시오. LLM은 테스트 시나리오를 기억하고, 과거 실패로부터
학습하며, UI 변경에 적응합니다.
아키텍처
[CODE BLOCK]
사전 요구 사항
- Synapse 계정 및 Mind Key
- Claude Desktop에 구성된 Synapse MCP 서버
- 가 설치된 iOS Simulator
- Synapse에 등록된 컴퓨터 (Computer Control API 참조)
1단계: Simulator 컴퓨터 등록
iOS Simulator를 실행 중인 Mac에서:
[CODE BLOCK]
2단계: 메모리에 테스트 시나리오 저장
재사용 가능한 테스트 시나리오를 메모리로 저장:
[CODE BLOCK]
3단계: LLM 기반 테스트 실행
Claude Desktop에서 (Synapse MCP 구성된 상태):
[CODE BLOCK]
Claude는 다음을 수행합니다:
1. 를 호출하여 메모리 찾기
2. 을 호출하여 현재 상태 보기
3. (click, type)를 통해 각 단계 실행
4. 스크린샷을 통해 결과 검증
5. 모든 실패를 메모리로 저장
4단계: 자가 치유 테스트
테스트가 실패하면 실패와 복구를 저장:
[CODE BLOCK]
다음에 LLM이 테스트를 실행할 때, 실패를 회상하고 복구를 자동으로
적용합니다.
5단계: 테스트 결과 추적
테스트 실행을 작업으로 추적:
[CODE BLOCK]
일반적인 명령
| 작업 | 명령 |
|--------|---------|
| Simulator 실행 | |
| 스크린샷 | (Synapse MCP를 통해) |
| (x,y) 탭 | |
| 텍스트 입력 | |
| Home 버튼 | |
모범 사례
> [!TIP]
> - UI 좌표를 메모리로 저장 — UI는 변경되지만, LLM이 다시 학습할 수 있음
> - 접근성 라벨 사용 — 좌표보다 안정적
> - 테스트 데이터를 분리하여 저장 — 사용자 이름, 비밀번호에 변수 사용
> - 깨끗한 상태에서 테스트 실행 — 실행 간 Simulator 재설정
> - 실패에 대한 스크린샷 로그 — 디버깅에 유용
다음 단계
- 자가 치유 테스트
- Computer Control API
- 메모리 모범 사례
────────────────────────────────────────────────────────────
# 백업 및 복원
SUMMARY: 백업을 위해 메모리 내보내기, 마인드 간 마이그레이션, 데이터 손실 후 복원.
백업 및 복원
Synapse는 메모리 백업, 마이그레이션 및 재해 복구를 위한 전체 내보내기/가져오기를
제공합니다. 이 가이드는 필수 작업을 다룹니다.
내보내기
전체 마인드 내보내기
마인드의 모든 메모리를 JSON으로 내보내기:
[CODE BLOCK]
응답 형식:
[CODE BLOCK]
증분 내보내기 (Diff)
타임스탬프 이후 변경된 메모리만 내보내기:
[CODE BLOCK]
응답:
[CODE BLOCK]
자동화된 백업
cron을 통해 일일 백업 예약:
[CODE BLOCK]
> [!NOTE]
> cron 엔드포인트는 응답을 받지만 저장하지 않습니다. 실제 백업을
> 위해 cron을 응답을 저장하는 자체 백업 서버로 지정하십시오.
더 나은 방법: 외부 백업 스크립트
[CODE BLOCK]
crontab에 추가:
[CODE BLOCK]
복원
동일 마인드로 복원
[CODE BLOCK]
새 마인드로 복원
[CODE BLOCK]
Python 복원 스크립트
[CODE BLOCK]
마인드 간 마이그레이션
[CODE BLOCK]
기타 데이터 백업
다음도 백업하는 것을 잊지 마십시오:
| 데이터 유형 | 엔드포인트 |
|-----------|----------|
| Memories | |
| Tasks | |
| Scripts | |
| Webhooks | |
| Cron jobs | |
| Variables | |
| Chat history | |
검증
복원 후 검증:
[CODE BLOCK]
모범 사례
> [!TIP]
> - 매일 백업 — cron으로 자동화
> - 복원 테스트 — 복원할 수 없는 백업은 쓸모가 없음
> - 여러 버전 유지 — 최소 30일
> - 오프사이트 저장 — S3, Backblaze B2 등
> - 민감한 백업 암호화 — 메모리에 PII가 포함될 수 있음
> - 복원 프로세스 문서화 — 필요할 때 잊어버릴 것입니다
다음 단계
- Memory API
- Cron 및 Scheduler — 자동화된 백업용
────────────────────────────────────────────────────────────
# 메모리 모범 사례
SUMMARY: 효과적인 회상을 위해 메모리를 구조화하는 방법 — 카테고리, 키, 태그, 우선순위.
메모리 모범 사례
메모리를 어떻게 구조화하느냐가 유용성을 결정합니다. 이 가이드는 LLM이
적절한 시기에 적절한 정보를 회상할 수 있도록 메모리를 카테고리화, 태깅,
우선순위 지정하는 패턴을 다룹니다.
카테고리: 가장 구체적인 것 선택
| 카테고리 | 사용 용도 | 예시 |
|----------|---------|---------|
| | 사용자 이름, 역할, 연락처 정보 | |
| | 좋아함, 싫어함, 작업 스타일 | |
| | 검증 가능한 사실 | |
| | 프로젝트 상태, 결정 | |
| | 사용자 기술 | |
| | 피해야 할 과거 오류 | |
| | 세션 관련 컨텍스트 | |
| | 기타 노트 | |
> [!TIP]
> 망설여지면 검증 가능한 정보에는 를, 그 외 모든 것에는 를
> 사용하십시오. 과도하게 카테고리화하지 마십시오 — 혼란스러운 보다
> 명확한 가 낫습니다.
키: 의미 있는 식별자
필드는 메모리의 식별자입니다. 의미 있고 안정적인 키를 사용하십시오:
좋은 키:
-
-
-
-
나쁜 키:
- (의미 없음)
- (설명적이지 않음)
- (날짜는 회상에 도움되지 않음)
키 명명 규칙
- (밑줄이 있는 소문자)
- 카테고리로 접두사: , ,
- 동사가 아닌 설명적인 명사 사용
- 50자 이하로 유지
태그: 검색 및 필터링용
태그를 사용하면 빠른 필터링과 검색이 가능합니다. 메모리당 2-5개 태그 추가:
[CODE BLOCK]
태그 패턴
- 프로젝트 이름: , ,
- 주제: , , ,
- 상태: , ,
- 우선순위 지표: ,
> [!NOTE]
> 태그는 대소문자를 구분하지 않습니다. 일관성을 위해 소문자를 사용하십시오.
우선순위: 현실적으로
| 우선순위 | 사용 용도 | 메모리 비율 |
|----------|---------|---------------|
| | 사용자 정체성, 법적 정보, 되돌릴 수 없는 결정 | 5% |
| | 활성 프로젝트, 중요한 선호도 | 20% |
| | 대부분의 사실, 노트, 컨텍스트 | 65% |
| | 일시적, 알면 좋음 | 10% |
> [!WARNING]
> 모든 것을 로 표시하지 마십시오. 모든 것이 중요하면, 아무것도
> 중요하지 않습니다. 잊었을 때 실제 피해를 초래할 것들에만 을
> 사용하십시오.
저장 여부
항상 저장
- 사용자 정체성 (이름, 이메일, 역할)
- 장기 선호도
- 프로젝트 결정 및 근거
- 과거 실수 및 교훈
- 사용자에게 한 약속
저장하지 않음
- 일시적 상태 (변수 사용)
- 동일한 대화 기록 (채팅 시스템이 처리)
- 민감한 데이터 (비밀번호, API 키)
- 쉽게 도출 가능한 사실 (현재 날짜, 파일 내용)
- 일시적 컨텍스트 ( 카테고리에 낮은 우선순위로 사용)
메모리 업데이트
동일한 + 로 를 POST하면 기존 메모리가 업데이트됩니다:
[CODE BLOCK]
> [!TIP]
> 중복을 만들지 않고 업데이트할 수 있도록 안정적인 키를 사용하십시오. LLM은
> 정보가 변경될 때 새 메모리를 만드는 대신 동일한 키를 다시 POST해야 합니다.
메모리 라이프사이클
[CODE BLOCK]
- Create: 전체 컨텍스트로 POST /memory
- Active: 자주 회상, 필요시 업데이트
- Stale: 여전히 관련은 있지만 활발히 사용되지 않음 (우선순위 낮추기?)
- Archive: 우선순위를 로 설정, 역사적 참조용으로 유지
- Delete: 더 이상 관련 없을 때 DELETE /memory/:id
주기적 정리
[CODE BLOCK]
패턴: 메모리 상속
계층적 컨텍스트 (프로젝트 → 하위 프로젝트 → 작업)의 경우:
[CODE BLOCK]
그러면 LLM은 를 검색하여 모든 관련 메모리를 찾을 수 있습니다.
패턴: 결정 로그
LLM이 다시 논의하지 않도록 근거와 함께 결정을 저장:
[CODE BLOCK]
패턴: 실수 방지
구체적인 방지 지침과 함께 실수를 저장:
[CODE BLOCK]
피해야 할 안티 패턴
> [!WARNING]
> - 대화 로그 저장 — 채팅 시스템이 처리
> - 전체 파일 저장 — 스크립트 저장소 또는 외부 저장소 사용
> - 일시적 상태 저장 — 변수 사용
> - 비밀 저장 — 환경 변수 사용
> - 메모리 중복 — 안정적인 키 사용
> - 과도한 태깅 — 메모리당 2-5개 태그가 이상적
> - 모든 것이 critical — 우선순위를 현실적으로
다음 단계
- Memory API
- 영구 LLM 에이전트
- 메모리 태깅 전략
────────────────────────────────────────────────────────────
# 다중 에이전트 조정
SUMMARY: 공유 Synapse 마인드, 작업, 채팅을 사용하여 여러 LLM 에이전트를 조정합니다.
다중 에이전트 조정
여러 LLM 에이전트가 관련 작업을 수행할 때, Synapse는 조정 계층 — 공유
메모리, 작업 할당, 비동기 채팅 — 을 제공합니다.
패턴
패턴 1: 공유 마인드 (단일 진실 소스)
모든 에이전트가 하나의 Mind Key를 공유합니다. 동일한 메모리 저장소를
읽고/씁니다.
[CODE BLOCK]
사용 사례: 한 프로젝트에서 작업하는 소규모 에이전트 팀.
설정:
[CODE BLOCK]
작업을 통한 조정:
[CODE BLOCK]
패턴 2: 전문화된 마인드 (격리된 컨텍스트)
각 에이전트는 자체 마인드를 가집니다. 공유 "조정" 마인드를 통해 통신합니다.
[CODE BLOCK]
사용 사례: 다른 전문 분야 (코딩, 리뷰, 배포)를 가진 에이전트.
설정:
[CODE BLOCK]
공유 마인드를 통한 조정:
[CODE BLOCK]
패턴 3: 허브 앤 스포크 (오케스트레이터)
중앙 오케스트레이터 에이전트가 워커 에이전트에게 작업을 할당합니다.
[CODE BLOCK]
사용 사례: 병렬 작업이 있는 복잡한 워크플로우.
구현:
[CODE BLOCK]
채팅을 통한 조정
에이전트는 채팅 시스템을 통해 통신할 수 있습니다:
[CODE BLOCK]
> [!NOTE]
> 채팅 메시지는 역할 태그가 지정됩니다. 에이전트 간 메시지의 경우
> role=agent, 사람-에이전트의 경우 role=human으로 설정하십시오.
변수를 통한 조정
경량 조정 (잠금, 플래그)을 위해 변수 사용:
[CODE BLOCK]
모범 사례
> [!TIP]
> - 관심사별로 별도 마인드 사용 — 코더와 리뷰어 메모리를 혼합하지 마십시오
> - 채팅에서 에이전트 태그 — 명확한 주소 지정을 위해
> - 작업 할당에 작업 사용 — 채팅이 아님 (채팅은 논의용)
> - 멱등성 구현 — 에이전트가 실패한 작업을 재시도할 수 있음
> - 모든 것 로그 — 감사 가능성을 위해 결정을 메모리에 저장
다음 단계
- 영구 LLM 에이전트
- LLM Cookbook
- 웹훅 자동화
────────────────────────────────────────────────────────────
# 영구 LLM 에이전트 구축
SUMMARY: Synapse를 사용하여 세션 간에 기억하는 LLM 에이전트 구축에 대한 단계별 가이드.
개요
이 가이드는 Synapse를 사용하여 세션 간에 컨텍스트를 유지하는 LLM 에이전트를
구축하는 과정을 안내합니다. 가이드가 끝나면 귀하의 에이전트는 다음을
수행합니다:
- 세션 시작 시 과거 컨텍스트 회상
- 발생하는 즉시 새 학습 내용 저장
- 세션 간 다단계 작업 추적
- 비동기 채팅을 통해 사람과 통신
아키텍처
[CODE BLOCK]
1단계: Mind Key 설정
[CODE BLOCK]
2단계: 세션 시작 프로토콜
모든 세션 시작 시, 모든 메모리를 회상:
[CODE BLOCK]
3단계: 새 학습 내용 저장
에이전트가 기억할 가치가 있는 것을 학습할 때마다:
[CODE BLOCK]
4단계: 작업 관리
세션 간 다단계 작업 추적:
[CODE BLOCK]
5단계: 사람과의 비동기 채팅
도구 호출 사이에 메시지 폴링:
[CODE BLOCK]
6단계: 세션 종료 프로토콜
세션 종료 시, 최종 컨텍스트 저장:
[CODE BLOCK]
완전한 패턴
[CODE BLOCK]
모범 사례
> [!TIP]
>
> - 항상 먼저 회상 — 컨텍스트 로드 없이 작업 시작 금지
> - 적극적으로 저장 — 세션 종료까지 기다리지 마십시오
> - 의미 있는 키 사용 — 이 아닌 ,
> - 모든 것에 태그 — 태그가 검색 및 필터링을 강화
> - 현실적인 우선순위 설정 — 모든 것이 은 아님
다음 단계
- LLM Cookbook — 실용적인 패턴
- 메모리 모범 사례
- 다중 에이전트 조정
────────────────────────────────────────────────────────────
# 자가 치유 테스트 파이프라인
SUMMARY: Synapse 메모리를 사용하여 실패로부터 학습하고 자동으로 적응하는 테스트 파이프라인 구축.
자가 치유 테스트 파이프라인
전통적인 테스트 스위트는 UI가 변경되면 깨집니다. 자가 치유 테스트는 Synapse
메모리를 사용하여 과거 실패로부터 학습하고 적응합니다 — 불안정한 테스트와
유지 관리 부담을 줄입니다.
개념
[CODE BLOCK]
1. 테스트 실행
2. 실패하면, 실패 저장 (무엇이 잘못되었는지, 왜, 어떻게 수정하는지)
3. 다음 실행: 실행 전 관련 실패 회상
4. 알려진 수정 자동 적용
구현
1단계: 테스트 래퍼
각 테스트를 메모리 회상/저장으로 래핑:
[CODE BLOCK]
2단계: 적응형 테스트 로직
테스트 내에서 알려진 실패를 확인하고 수정 적용:
[CODE BLOCK]
3단계: 복구 전략
복구 전략을 메모리로 저장:
[CODE BLOCK]
4단계: CI 통합
[CODE BLOCK]
5단계: 실패 분석 대시보드
[CODE BLOCK]
모범 사례
> [!TIP]
> - 트레이스백 저장 — 실패한 정확한 줄을 포함
> - 테스트 이름으로 태그 — 빠른 필터링 가능
> - 카테고리 사용 — 일반 메모리와 분리
> - 우선순위 설정 — 실패는 절대 잊지 않아야 함
> - 주기적 정리 — 해결된 문제의 메모리 삭제
> - 민감한 데이터 저장 금지 — 자격 증명, PII
저장할 일반적인 실패 패턴
| 실패 유형 | 저장할 내용 |
|--------------|---------------|
| 요소를 찾을 수 없음 | 시도한 셀렉터, 페이지 상태, 스크린샷 |
| 시간 초과 | 대기 시간, 무엇을 기다리고 있었는지 |
| 어설션 실패 | 예상 값 vs 실제 값 |
| 네트워크 오류 | URL, 상태 코드, 응답 본문 |
| 권한 거부 | 필요한 권한, 현재 사용자 역할 |
다음 단계
- 자동화된 iOS 테스트
- 메모리 모범 사례
- 오류 복구 Cookbook
────────────────────────────────────────────────────────────
# 웹훅 자동화
SUMMARY: 메모리 변경 시 외부 시스템 트리거 — 동기화, 알림, 자동화.
웹훅 자동화
웹훅을 사용하면 Synapse 이벤트가 발생할 때 외부 시스템을 트리거할 수
있습니다. 이 가이드는 일반적인 자동화 패턴을 다룹니다.
일반적인 패턴
패턴 1: 중요 메모리 알림
중요 메모리가 저장될 때 Slack 메시지를 전송:
[CODE BLOCK]
웹훅 등록:
[CODE BLOCK]
패턴 2: 외부 시스템 동기화
메모리를 Notion, Obsidian 또는 외부 KB에 동기화:
[CODE BLOCK]
패턴 3: CI/CD 트리거
"release" 메모리가 저장될 때 배포 트리거:
[CODE BLOCK]
패턴 4: 사람의 메시지 시 에이전트 깨우기
사람이 채팅 메시지를 보낼 때 LLM 에이전트 실행 트리거:
[CODE BLOCK]
패턴 5: 메트릭 집계
메모리 증가, 채팅 활동, 작업 완료 추적:
[CODE BLOCK]
서명 검증
스푸핑을 방지하기 위해 항상 웹훅 서명을 검증하십시오:
[CODE BLOCK]
재시도 로직
Synapse는 실패한 웹훅을 지수 백오프로 재시도합니다. 귀하의 핸들러는
다음을 수행해야 합니다:
1. 빠르게 200 반환 — 동기적으로 무거운 작업을 하지 마십시오
2. 작업 큐잉 — 백그라운드 작업 시스템 사용
3. 멱등성 — 동일한 이벤트가 두 번 전달될 수 있음
[CODE BLOCK]
웹훅 디버깅
전송 기록 확인
웹훅 전송은 기록됩니다. 웹훅의 최근 전송을 확인하십시오:
[CODE BLOCK]
수동 웹훅 테스트
[CODE BLOCK]
일반적인 문제
| 문제 | 해결 |
|-------|-----|
| 4xx 응답 | 핸들러가 200을 반환하는지 확인 |
| 5xx 응답 | 서버 오류 — 앱 로그 확인 |
| 시간 초과 | 200을 빨리 반환, 작업을 비동기로 큐잉 |
| 중복 전송 | 핸들러를 멱등으로 만들기 |
| 서명 불일치 | 시크릿이 올바른지 확인 |
모범 사례
> [!TIP]
> - 항상 서명 검증 — 이를 건너뛰지 마십시오
> - 빠르게 200 반환 — Synapse를 차단하지 마십시오
> - 멱등성 — 중복 전송 처리
> - 특정 이벤트 사용 — 가 아닌
> - 전송 실패 모니터링 — 알림 설정
다음 단계
- Webhooks API
- Cron 및 Scheduler
- 영구 LLM 에이전트
## 카테고리: 개념
Synapse의 아키텍처와 개념.
────────────────────────────────────────────────────────────
# Synapse 아키텍처
SUMMARY: Synapse의 구축 방식 — Fastify, PostgreSQL, FTS5, 임베딩, MCP 서버.
Synapse 아키텍처
Synapse는 Fastify, FTS5가 포함된 PostgreSQL, 그리고 의미론적 검색을 위한
선택적 임베딩 서비스를 기반으로 구축된 다중 테넌트 메모리 API입니다.
고수준 아키텍처
[CODE BLOCK]
핵심 구성 요소
1. Synapse API (Fastify)
메인 HTTP 서버입니다. 처리하는 작업:
- REST 엔드포인트 (, , 등)
- 인증 (에이전트용 Mind Key, 사람용 JWT)
- 속도 제한 ( 인증만)
- 정적 파일 제공 (, 등의 웹 UI)
- 웹훅 디스패치
성능을 위해 Fastify 5로 구축되었습니다. 프로덕션에서는 포트 12800에서
실행됩니다.
2. FTS5가 포함된 PostgreSQL
기본 데이터 저장소입니다. 전문 검색을 위해 FTS5 확장이 포함된
PostgreSQL을 사용합니다.
주요 테이블:
| 테이블 | 용도 |
|-------|---------|
| | 사용자 계정 |
| | 마인드 범위 (각각 Mind Key 보유) |
| | FTS5 가상 테이블이 있는 메모리 레코드 |
| | 작업 관리 |
| | 채팅 기록 |
| | 영구 스크립트 |
| | 웹훅 등록 |
| | 예약된 작업 |
| | 키-값 저장소 |
| | 감사 추적 |
FTS5는 모든 메모리 콘텐츠에 대해 서브밀리초 전문 검색을 가능하게
합니다. 자세한 내용은 FTS5 검색을 참조하십시오.
3. 임베딩 서비스 (선택 사항)
의미론적 검색을 위해 Synapse는 메모리 콘텐츠의 벡터 임베딩을 생성합니다.
이는 메모리와 함께 저장되며 유사도 검색에 사용됩니다.
- 제공자: 구성 가능 (OpenAI, 로컬 모델 등)
- 테이블의 컬럼으로 저장
- 엔드포인트에서 사용
- 의미론적 검색 참조
4. MCP 서버 (별도 서비스)
Synapse MCP 서버는 별도의 프로세스 (포트 13100)로 실행됩니다. 다음을
수행합니다:
- Model Context Protocol을 통해 79개 도구 노출
- stdio, HTTP/SSE, WebSocket 전송 지원
- MCP 도구 호출을 Synapse API 호출로 변환
- 다중 테넌트: 세션당 하나의 Mind Key
5. Browser Proxy (별도 서비스)
브라우저 자동화를 위해 Playwright 기반의 별도 서비스가 포트 13000에서
실행됩니다. MCP 서버는 도구를 위해 이를 호출할 수 있습니다.
6. SSH Proxy (별도 서비스)
SSH 기반 원격 명령을 위해 별도의 서비스가 포트 12900에서 실행됩니다.
다중 테넌시 모델
[CODE BLOCK]
각 마인드는 완전히 격리되어 있습니다. Mind Key는 정확히 하나의 마인드에만
접근 권한을 부여합니다. JWT는 사용자 계정 (마인드 관리용)에 접근 권한을
부여합니다.
자세한 내용은 다중 테넌시를 참조하십시오.
요청 흐름
메모리 저장 요청
[CODE BLOCK]
메모리 검색 요청
[CODE BLOCK]
배포
Synapse는 Docker 컨테이너로 배포됩니다. 을 참조하십시오:
[CODE BLOCK]
성능 특성
| 작업 | 지연 시간 | 처리량 |
|-----------|---------|------------|
| 메모리 저장 | 5ms | 1000+ req/s |
| 메모리 회상 | 20ms | 500 req/s |
| FTS5 검색 | 10ms | 800 req/s |
| 의미론적 검색 | 50ms | 200 req/s |
| 채팅 폴링 | 5ms | 2000 req/s |
다음 단계
- 메모리 모델
- 다중 테넌시
- FTS5 검색
────────────────────────────────────────────────────────────
# FTS5 전문 검색
SUMMARY: Synapse가 서브밀리초 전문 메모리 검색을 위해 SQLite FTS5를 사용하는 방법.
FTS5 전문 검색
Synapse는 빠르고 유연한 메모리 검색을 위해 FTS5 (Full-Text Search 5)를
사용합니다. 이 페이지에서는 작동 방식과 효과적인 사용법을 설명합니다.
FTS5란?
FTS5는 전문 검색 기능을 제공하는 SQLite 확장입니다 (확장을 통해
PostgreSQL에서도 사용 가능). 다음을 제공합니다:
- 빠른 키워드 검색을 위한 텍스트 콘텐츠 인덱싱
- 불린 연산자 (AND, OR, NOT) 지원
- 따옴표를 사용한 구문 매칭 지원
- 를 사용한 접두사 매칭 지원
- 관련성으로 결과 순위 지정
Synapse는 FTS5를 사용하여 모든 메모리 콘텐츠를 인덱싱하여 수천 개의
메모리에서 서브밀리초 검색을 가능하게 합니다.
Synapse의 FTS5 사용 방식
시:
1. 메모리 콘텐츠가 테이블에 저장됩니다
2. 콘텐츠가 FTS5 가상 테이블에도 삽입됩니다
3. FTS5가 자동으로 토큰화하고 인덱싱합니다
시:
1. Synapse가 FTS5 구문을 사용하여 쿼리를 파싱합니다
2. FTS5 인덱스에 대해 를 실행합니다
3. 로 필터링합니다 (테넌트 격리)
4. 순위가 지정된 결과를 반환합니다
쿼리 구문
단순 키워드 검색
[CODE BLOCK]
"docker"를 포함하는 메모리를 반환합니다.
여러 키워드 (암시적 AND)
[CODE BLOCK]
"docker"와 "swarm" 모두를 포함하는 메모리를 반환합니다.
구문 매칭
[CODE BLOCK]
정확한 구문 "docker swarm"을 포함하는 메모리를 반환합니다.
접두사 매칭
[CODE BLOCK]
"docker"로 시작하는 단어 (예: "dockers", "dockerfile", "dockerize")를
포함하는 메모리를 반환합니다.
불린 OR
[CODE BLOCK]
"docker" 또는 "kubernetes"를 포함하는 메모리를 반환합니다.
불린 NOT
[CODE BLOCK]
"docker"를 포함하지만 "swarm"은 포함하지 않는 메모리를 반환합니다.
그룹화
[CODE BLOCK]
"docker" 또는 "kubernetes"를 포함하지만 "test"는 포함하지 않는 메모리를
반환합니다.
실용적인 예시
프로젝트에 대한 메모리 찾기
[CODE BLOCK]
정확한 구문 찾기
[CODE BLOCK]
테스트 메모리 제외
[CODE BLOCK]
기술로 찾기
[CODE BLOCK]
순위
FTS5는 BM25 알고리즘을 사용하여 관련성으로 결과 순위를 지정합니다. 요인:
- 용어 빈도 (용어가 얼마나 자주 등장하는가)
- 역문서 빈도 (희귀한 용어가 더 높은 순위)
- 문서 길이 (용어가 포함된 더 짧은 문서가 더 높은 순위)
- 컬럼 가중치 (title > content)
결과는 순위순으로 반환됩니다 (가장 관련성 높은 것이 먼저).
성능
| 작업 | 지연 시간 |
|-----------|---------|
| 100개 메모리 검색 | < 5ms |
| 1,000개 메모리 검색 | < 10ms |
| 10,000개 메모리 검색 | < 25ms |
| 100,000개 메모리 검색 | < 100ms |
FTS5는 읽기 중심의 워크로드에 고도로 최적화되어 있습니다.
제한 사항
어간 추출
FTS5는 기본적으로 어간 추출을 하지 않습니다. "running"과 "run"은 다른
용어입니다.
해결 방법: 접두사 매칭 사용:
오타 허용
FTS5는 퍼지 매칭을 지원하지 않습니다. 오타는 결과를 반환하지 않습니다.
해결 방법: 개념 매칭을 위해 의미론적 검색
()을 사용하십시오.
불용어
일반적인 단어 (the, a, an, is)는 인덱싱되지만 검색에 유용하지 않을 수
있습니다. FTS5는 이를 자동으로 처리합니다.
FTS5와 의미론적 검색 비교
| 측면 | FTS5 | 의미론적 검색 |
|--------|------|-----------------|
| 속도 | 서브밀리초 | 50-100ms |
| 매칭 | 정확한 키워드 | 개념적 |
| 오타 허용 | 없음 | 약간 |
| 어간 추출 | 없음 | 암시적 |
| 임베딩 필요 | 아니오 | 예 |
| 적합한 용도 | 특정 용어 | 개념 |
키워드를 알 때 FTS5를 사용하십시오. X가 다르게 설명된 "X에 대한 메모리"를
원할 때 의미론적 검색을 사용하십시오.
모범 사례
> [!TIP]
> - 구체적인 용어 사용 — "container orchestration"보다 "docker swarm"이 낫습니다
> - 구문 인용 — 은 구문 매칭을 보장합니다
> - 변형을 위해 접두사 사용 — 는 "deploy", "deployment", "deploying"을 잡습니다
> - 노이즈 제외 — 는 테스트 메모리를 필터링합니다
> - 태그와 결합 — 이 결과를 좁힙니다
다음 단계
- 의미론적 검색
- Memory API
- 메모리 모범 사례
────────────────────────────────────────────────────────────
# 메모리 모델
SUMMARY: 메모리 구조화 방식 — 카테고리, 키, 태그, 우선순위, 소스, 검증.
메모리 모델
Synapse의 메모리 모델은 LLM 에이전트를 위해 설계되었습니다 — 신뢰할 수
있는 회상을 위해 충분히 구조화되어 있으면서, 모든 도메인에 대해 충분히
유연합니다.
메모리 구조
[CODE BLOCK]
필드
| 필드 | 타입 | 필수 | 설명 |
|-------|------|----------|-------------|
| | string | 자동 | 고유 ID (memxxx) |
| | enum | ✅ | 8개 카테고리 중 하나 |
| | string | ✅ | 안정적 식별자 (업데이트에 사용) |
| | string | ✅ | 메모리 콘텐츠 (모든 텍스트) |
| | string[] | – | 검색 및 필터링용 |
| | enum | – | low, normal, high, critical (기본값: normal) |
| | enum | 자동 | user, agent (누가 저장했는지) |
| | bool | 자동 | 사람이 검증했는지 여부 |
| | float | – | 0.0 1.0 (기본값: user 1.0, agent 0.7) |
| | timestamp | – | 이 메모리를 잊을 시점 |
| | string | 자동 | 이 메모리를 소유한 마인드 |
| | timestamp | 자동 | 최초 저장 시각 |
| | timestamp | 자동 | 최종 수정 시각 |
카테고리
8개 카테고리가 일반적인 LLM 에이전트 사용 사례를 다룹니다:
| 카테고리 | 용도 | 예시 콘텐츠 |
|----------|---------|-----------------|
| | 사용자가 누구인지 | "User is Michael Schäfer, software engineer in Berlin" |
| | 사용자 선호도 | "Prefers concise technical responses" |
| | 검증 가능한 사실 | "Office is in Berlin, timezone Europe/Berlin" |
| | 프로젝트 상태 | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| | 사용자 기술 | "Advanced Python, 10+ years" |
| | 과거 오류 | "Forgot to bump npm version — CI failed" |
| | 세션 컨텍스트 | "Currently reviewing PR #42" |
| | 기타 노트 | "Try Redis for caching next sprint" |
키: 안정적 식별자
필드는 중요합니다 — 중복을 만들지 않고 메모리를 업데이트하는
방법입니다.
[CODE BLOCK]
키 규칙:
- (category, mind) 내에서 고유해야 함
- 사용
- 명확성을 위해 카테고리로 접두사: ,
- 안정적으로 유지 — 생성 후 키를 변경하지 마십시오
태그: 검색용
태그를 사용하면 빠른 필터링과 검색이 가능합니다:
[CODE BLOCK]
태그 모범 사례:
- 메모리당 2-5개 태그 (과도한 태깅 금지)
- 일관성을 위해 소문자 사용
- 프로젝트 이름, 주제, 기술 사용
- 태그는 대소문자 구분 안 함
우선순위 수준
| 우선순위 | 사용 시기 | 회상 동작 |
|----------|-------------|-----------------|
| | 정체성, 법적, 되돌릴 수 없는 것 | 항상 회상 최상단 |
| | 활성 프로젝트, 핵심 선호도 | 회상에서 두드러짐 |
| | 대부분의 메모리 (기본값) | 표준 회상 순서 |
| | 일시적, 알면 좋음 | 요약될 수 있음 |
은 우선순위 (critical 먼저)로 정렬한 후 최신순으로 정렬합니다.
소스: User vs Agent
메모리에는 태그가 지정됩니다:
- — 사람이 저장 (JWT 또는 human UI를 통해)
- — LLM 에이전트가 저장 (Mind Key를 통해)
이는 다음에 영향을 미칩니다:
- 검증: 메모리는 자동 검증, 메모리는 검증 안 됨
- 신뢰도: 기본값 1.0, 0.7
- 회상: 은 미검증 메모리에 "(unverified)" 표시
> [!NOTE]
> 소스 메모리는 적절한 회의적으로 취급하십시오. 사용자가 직접
> 명시한 것이 아니라 추론되거나 가정된 것일 수 있습니다.
검증
플래그는 사람이 메모리를 확인했음을 나타냅니다:
- 메모리: 자동 검증 ()
- 메모리: 기본 미검증 ()
다음을 통해 메모리 검증:
[CODE BLOCK]
> [!NOTE]
> 검증에는 Mind Key (에이전트 인증)가 아닌 JWT (사람 인증)가 필요합니다.
> 이는 사람만 메모리를 검증됨으로 표시할 수 있도록 보장합니다.
신뢰도
필드 (0.0 1.0)는 메모리의 신뢰도를 나타냅니다:
- 1.0 — 사용자가 직접 명시
- 0.7 — 에이전트가 추론
- 0.5 — 불확실, 검증 필요
- 0.0 — 명시적으로 의심됨
저장 시 신뢰도 설정:
[CODE BLOCK]
만료
시간에 민감한 메모리에 설정:
[CODE BLOCK]
만료된 메모리는 에서 반환되지 않습니다 (DB에는 여전히 존재).
곧 만료되는 메모리를 보려면 를 사용하십시오.
메모리 라이프사이클
[CODE BLOCK]
회상 동작
은 LLM 컨텍스트에 최적화된 일반 텍스트 요약을 반환합니다:
[CODE BLOCK]
- 우선순위 (critical → low)로 정렬, 그 다음 최신순
- 미검증 메모리는 로 표시
- 컨텍스트를 위해 태그 포함
- 일반 텍스트 (JSON 파싱 불필요)
다음 단계
- Memory API
- 메모리 모범 사례
- FTS5 검색
────────────────────────────────────────────────────────────
# 다중 테넌시 및 격리
SUMMARY: Synapse가 사용자와 마인드 간에 데이터를 격리하는 방식 — 보안 경계 설명.
다중 테넌시 및 격리
Synapse는 다중 테넌트입니다: 여러 사용자, 각각 여러 마인드를 가지며,
서로 완전히 격리되어 있습니다. 이 페이지에서는 격리 모델을 설명합니다.
테넌트 계층 구조
[CODE BLOCK]
격리 수준
수준 1: 사용자 격리
각 사용자 계정은 격리되어 있습니다. Alice는 다음을 할 수 없습니다:
- Bob의 마인드 보기
- Bob의 메모리 접근 (그녀의 JWT로도)
- Bob의 계정 정보 나열
강제 방법: 모든 테이블의 컬럼, JWT에 포함, 모든
쿼리는 로 필터링.
수준 2: 마인드 격리
사용자 내에서 각 마인드는 격리되어 있습니다. Mind A는 다음을 할 수 없습니다:
- Mind B의 메모리 보기
- Mind B의 작업, 채팅, 스크립트 접근
강제 방법: 모든 데이터 테이블의 컬럼, Mind Key에 포함,
모든 쿼리는 로 필터링.
> [!CRITICAL]
> Mind Key 격리는 기본 보안 경계입니다. 유출된 Mind Key는 해당 마인드의
> 데이터에 대한 전체 접근 권한을 부여합니다 — 하지만 해당 마인드에만.
인증 토큰
| 토큰 | 범위 | 접근 가능한 것 |
|-------|-------|-------------------|
| Mind Key | 단일 마인드 | 해당 마인드의 데이터만 |
| JWT | 사용자 계정 | 계정 관리 (마인드 생성/나열/삭제) |
| Computer Token | 단일 컴퓨터 | 해당 컴퓨터의 명령 |
마인드 간 접근
동일 사용자 내
사용자는 JWT를 통해 모든 마인드에 접근할 수 있습니다 (예: 가
모두 나열). 하지만 메모리 데이터를 읽고/쓰려면 특정 Mind Key가 필요합니다.
사용자 간
사용자는 서로의 데이터에 접근할 수 없습니다 — Sharing API를 통해 명시적으로
마인드를 공유하지 않는 한:
[CODE BLOCK]
공유 후, Bob은 자신의 JWT를 통해 Mind A에 접근할 수 있습니다 (인
경우 읽기 전용).
보안 경계
[CODE BLOCK]
일반적인 다중 테넌시 패턴
패턴 1: 단일 사용자, 단일 마인드
개별 LLM 에이전트 사용자에게 가장 일반적입니다.
- 1개 사용자 계정
- 1개 마인드
- 1개 Mind Key
- 모든 메모리가 하나의 범위에
패턴 2: 단일 사용자, 다중 마인드
여러 컨텍스트 (업무, 개인, 프로젝트)를 가진 사용자용.
- 1개 사용자 계정
- N개 마인드 (예: "work", "personal", "project-x")
- N개 Mind Key
- 각 LLM 세션은 하나의 Mind Key 사용
패턴 3: 팀 공유 마인드
프로젝트에서 협업하는 팀용.
- 1명의 사용자가 마인드 생성 (Mind Key 획득)
- 생성자가 JWT를 통해 팀원과 공유
- 모든 팀원이 JWT (또는 공유 Mind Key)로 접근
> [!WARNING]
> Mind Key 공유는 전체 읽기/쓰기 권한을 부여합니다. 팀 협업의 경우,
> Mind Key를 직접 공유하기보다 Sharing API (JWT 기반)를 선호하십시오.
패턴 4: SaaS 제공자
Synapse를 메모리 계층으로 내장하는 앱용.
- 각 고객 = 1개 사용자 계정
- 각 고객 프로젝트 = 1개 마인드
- 앱이 고객/프로젝트별 Mind Key 저장
- 고객 간 전체 격리
격리 검증
테스트: Mind Key는 다른 마인드에 접근할 수 없음
[CODE BLOCK]
테스트: JWT는 메모리 데이터를 직접 읽을 수 없음
[CODE BLOCK]
모범 사례
> [!TIP]
> - 프로젝트/컨텍스트당 하나의 마인드 사용 — 격리가 도움입니다
> - Mind Key 절대 공유하지 않기 — Sharing API를 대신 사용
> - 노출 시 Mind Key 교체 (마인드 삭제, 새로 생성)
> - 공유 마인드 감사 — 정기적으로 검토
> - human UI에 JWT 사용 — 최종 사용자에게 Mind Key 노출 금지
다음 단계
- Authentication
- Mind Key vs JWT
- 아키텍처
────────────────────────────────────────────────────────────
# 의미론적 검색 (임베딩)
SUMMARY: 벡터 임베딩을 사용한 개념적 메모리 검색 — 키워드뿐만 아니라 의미로 찾습니다.
의미론적 검색 (임베딩)
Synapse는 벡터 임베딩을 사용한 의미론적 검색을 지원합니다. FTS5 (키워드
매칭)와 달리 의미론적 검색은 키워드가 일치하지 않더라도 의미로
메모리를 찾습니다.
작동 방식
[CODE BLOCK]
임베딩이란?
임베딩은 텍스트의 수치적 벡터 표현입니다. 유사한 의미를 가진 텍스트는
유사한 벡터를 가집니다. Synapse는 각 메모리의 콘텐츠에 대해 벡터 (예:
1536차원)를 생성합니다.
코사인 유사도
의미론적으로 유사한 메모리를 찾기 위해 Synapse는 쿼리 벡터와 각 메모리
벡터 간의 코사인 유사도를 계산합니다. 유사도가 높을수록 더 관련성이
높습니다.
의미론적 검색 사용 시기
의미론적 검색을 사용할 때:
- 저장된 것과 다르게 설명된 "X에 대한 메모리"를 원할 때
- FTS5가 결과를 반환하지 않을 때 (키워드 매칭 없음)
- 개념적 그룹화를 원할 때 (예: 일부가 "release"라고 말하더라도 모든 "deployment" 메모리)
- 쿼리가 질문일 때: "인증은 어떻게 처리합니까?"
FTS5를 사용할 때:
- 정확한 키워드를 알 때
- 불린 로직 (AND, OR, NOT)이 필요할 때
- 서브밀리초 응답이 필요할 때
- 구문 매칭을 원할 때
엔드포인트
GET /memory/semantic-search
[CODE BLOCK]
응답:
[CODE BLOCK]
예시
배포 메모리 찾기
[CODE BLOCK]
"deployment", "release", "publishing", "rolling out" 등에 대한 메모리를
반환합니다.
인증 패턴 찾기
[CODE BLOCK]
login, auth, JWT, session management, OAuth 등에 대한 메모리를 반환합니다.
유사한 메모리 찾기
[CODE BLOCK]
(공유 태그 및 임베딩 벡터를 통해) 의미론적 유사도를 사용합니다.
임베딩 생성
임베딩은 언제 생성되나요?
- 메모리 저장 시 — 임베딩 서비스가 구성된 경우, 동기적으로 임베딩 생성
- 배치 생성 — 가 임베딩이 없는 메모리의 임베딩 생성
- 비동기 업데이트 — 콘텐츠가 업데이트되면 임베딩 재생성
임베딩 제공자
Synapse는 구성 가능한 임베딩 제공자를 지원합니다:
- OpenAI (, )
- 로컬 모델 (Ollama 등을 통해)
- 사용자 정의 (임베딩 인터페이스 구현)
환경 변수로 구성:
[CODE BLOCK]
배치 생성
임베딩이 누락된 메모리가 많은 마인드의 경우:
[CODE BLOCK]
성능
| 작업 | 지연 시간 |
|-----------|---------|
| 임베딩 생성 (OpenAI) | 100-200ms |
| 의미론적 검색 (1k 메모리) | 50-100ms |
| 의미론적 검색 (10k 메모리) | 200-500ms |
| 배치 생성 (100 메모리) | 10-20s |
> [!NOTE]
> 의미론적 검색은 벡터 계산으로 인해 FTS5보다 느립니다. 알려진 키워드에는
> FTS5를, 개념적 쿼리에는 의미론적 검색을 사용하십시오.
제한 사항
임베딩 비용
OpenAI를 사용하는 경우, 임베딩 생성에 비용이 듭니다 (text-embedding-3-small의
경우 1M 토큰당 $0.02). 평균 100 토큰인 10,000개 메모리의 경우
$0.02 — 무시할 수 있는 수준입니다.
콜드 스타트
임베딩이 구성되기 전에 저장된 메모리는 임베딩이 없습니다. 를 실행하여 백필하십시오.
제공자 의존성
임베딩 제공자가 다운된 경우, 의미론적 검색은 정상적으로 실패합니다 (빈
결과 또는 오류 반환). FTS5는 여전히 작동합니다.
임베딩을 사용할 수 없는 경우
임베딩 서비스가 구성되지 않은 경우:
- 가 503 Service Unavailable 반환
- 는 여전히 작동 (임베딩만 생성 안 됨)
- FTS5 검색은 여전히 작동
모범 사례
> [!TIP]
> - 개념적 쿼리에 의미론적 검색 사용 — "X를 어떻게 처리합니까?"
> - 특정 용어에 FTS5 사용 — "docker swarm"
> - 정기적으로 임베딩 백필 —
> - 제공자 상태 모니터링 — 의미론적 검색은 이에 의존
> - 태그와 결합 — 의미론적 + 태그 필터가 결과를 좁힘
다음 단계
- FTS5 검색
- Memory API
- 아키텍처
## 카테고리: LLM 쿡북
LLM 에이전트를 위한 레시피와 패턴.
────────────────────────────────────────────────────────────
# 채팅 폴링 패턴
SUMMARY: 워크플로우를 차단하지 않고 도구 호출 사이에 사람의 메시지를 폴링하는 방법.
채팅 폴링 패턴
채팅 시스템은 비동기식입니다 — 귀하가 작업하는 동안 사람이 메시지를 남길
수 있습니다. 이 패턴은 워크플로우를 차단하지 않고 메시지를 폴링하는 방법을
보여줍니다.
패턴
[CODE BLOCK]
빡빡한 루프가 아닌 도구 호출 사이에 폴링하십시오.
도구 호출 사이에 폴링하는 이유?
- 차단하지 않음 — 빡빡한 루프에서 폴링은 API 호출을 낭비
- 메시지 누락 방지 — 너무 드물게 폴링하면 응답이 느림
- 적정 지점 — 30-60초마다, 또는 각 도구 호출 후에 폴링
구현
기본 폴링
[CODE BLOCK]
패턴 1: 각 도구 호출 후 폴링
[CODE BLOCK]
패턴 2: 시간 기반 폴링
[CODE BLOCK]
패턴 3: 이벤트 기반 (웹훅과 함께)
실시간 알림을 위해 웹훅 등록:
[CODE BLOCK]
그러면 웹훅 핸들러가 에이전트를 깨울 수 있습니다:
[CODE BLOCK]
메시지 처리 패턴
패턴: 확인 후 처리
[CODE BLOCK]
패턴: 배치 처리를 위한 큐잉
[CODE BLOCK]
패턴: 우선순위 라우팅
[CODE BLOCK]
폴링 빈도
| 사용 사례 | 빈도 |
|----------|-----------|
| 대화형 에이전트 (사람이 대기 중) | 5-10초마다 |
| 백그라운드 에이전트 | 30-60초마다 |
| 배치 처리 | 5분마다 |
| 웹훅 트리거 | 폴링하지 마십시오 — 웹훅 사용 |
> [!WARNING]
> 5초당 한 번 이상 폴링하는 것은 API 호출을 낭비합니다.
> 엔드포인트는 대기 중인 메시지가 있으면 즉시 반환하므로 더 빠른 폴링에
> 이점이 없습니다.
다중 에이전트 채팅
에이전트 간 통신의 경우:
[CODE BLOCK]
모범 사례
> [!TIP]
> - 도구 호출 사이에 폴링 — 빡빡한 루프가 아님
> - 즉시 확인 — 사람이 메시지를 받았는지 알 수 있음
> - 비동기 처리 — 긴 작업에 차단하지 마십시오
> - 실시간에 웹훅 사용 — 폴링에는 지연이 있음
> - 5초당 한 번 이상 폴링하지 마십시오 — API 호출 낭비
일반적인 문제
메시지 누락
- 은 자동으로 메시지를 읽음으로 표시
- 처리하지 않으면 사라짐
- 해결: 반환 전 항상 메시지 처리
중복 응답
- 핸들러가 충돌하면 두 번 응답할 수 있음
- 해결: 핸들러를 멱등으로 만들기 (이미 응답했는지 확인)
느린 응답
- 60초마다 폴링하면 최대 60초 지연
- 해결: 10-30초마다 폴링, 또는 웹훅 사용
다음 단계
- Chat API
- 세션 시작 패턴
- 오류 복구
────────────────────────────────────────────────────────────
# 에이전트를 위한 오류 복구
SUMMARY: LLM 에이전트가 오류를 처리하고 복구하는 방법 — 재시도, 저장, 학습.
에이전트를 위한 오류 복구
오류는 발생합니다. 네트워크 실패, API 500 반환, Mind Key 만료. 이 가이드는
LLM 에이전트가 오류를 우아하게 처리하고 학습하는 방법을 보여줍니다.
오류 처리 원칙
1. 백오프로 재시도 — 일시적 오류는 종종 해결됨
2. 오류 저장 — 패턴으로부터 학습
3. 우아한 저하 — 전체 세션을 충돌시키지 마십시오
4. 사람에게 알림 — 해결할 수 없는 오류의 경우
HTTP 오류 처리
지수 백오프로 재시도
[CODE BLOCK]
인증 오류 처리
[CODE BLOCK]
오류를 메모리로 저장
오류가 발생하면, 미래 세션이 학습할 수 있도록 저장:
[CODE BLOCK]
일반적인 오류 시나리오
시나리오 1: Mind Key 무효
[CODE BLOCK]
시나리오 2: 네트워크 오류
[CODE BLOCK]
시나리오 3: 속도 제한
[CODE BLOCK]
시나리오 4: 서버 오류 (5xx)
[CODE BLOCK]
시나리오 5: 도구 호출 실패
[CODE BLOCK]
패턴: 서킷 브레이커
반복 실패의 경우, 일시적으로 시도 중지:
[CODE BLOCK]
모범 사례
> [!TIP]
> - 일시적 오류는 항상 재시도 — 네트워크 실패, 서버 딸꾹질
> - 클라이언트 오류 (4xx)는 재시도하지 마십시오 — 자체 수정되지 않음
> - 오류를 메모리로 저장 — 패턴으로부터 학습
> - 중요 오류는 사람에게 알림 — 알아야 함
> - 우아하게 저하 — 부분 작업이 충돌보다 나음
> - 서킷 브레이커 사용 — 실패하는 서비스를 반복 호출하지 마십시오
다음 단계
- 오류 API 참조
- 세션 시작 패턴
- 자가 치유 테스트
────────────────────────────────────────────────────────────
# 메모리 태깅 전략
SUMMARY: 효과적인 검색과 필터링을 위해 메모리를 태깅하는 방법 — 확장 가능한 태깅 시스템.
메모리 태깅 전략
태그는 확장 가능한 메모리 검색의 비결입니다. 이 가이드는 적절한 시기에
올바른 메모리가 돌아오도록 메모리를 태깅하는 방법을 보여줍니다.
태그가 중요한 이유
태그가 없으면, 평면적인 전문 검색만 있습니다. 태그가 있으면, 구조화된
탐색이 가능합니다:
[CODE BLOCK]
태그를 통해:
- 빠른 필터링 —
- 범위 지정 검색 —
- 그룹화 — 프로젝트의 모든 "mistake" 메모리 찾기
- 교차 참조 — 태그를 공유하는 메모리는 관련됨
태깅 스키마
프로젝트 태그
프로젝트 이름을 태그로 사용:
[CODE BLOCK]
기술 태그
기술 이름 사용:
[CODE BLOCK]
주제 태그
주제 카테고리 사용:
[CODE BLOCK]
상태 태그
상태 지표 사용:
[CODE BLOCK]
유형 태그
유형 지표 사용:
[CODE BLOCK]
태깅 규칙
규칙 1: 메모리당 2-5개 태그
태그가 너무 적으면 검색 가능성이 떨어집니다. 너무 많으면 노이즈입니다.
[CODE BLOCK]
규칙 2: 소문자, 하이픈
[CODE BLOCK]
규칙 3: 일관된 어휘 사용
태깅 어휘를 설정하고 고수하십시오:
[CODE BLOCK]
규칙 4: 검색 의도로 태그
"이 메모리를 어떻게 검색할 것인가?"라고 자문하십시오.
[CODE BLOCK]
패턴
패턴 1: 프로젝트 + 주제
[CODE BLOCK]
검색: (모든 Synapse 프로젝트 메모리)
검색: (Synapse의 배포 메모리)
패턴 2: 유형 + 도메인
[CODE BLOCK]
검색: (모든 실수)
검색: (배포 실수)
패턴 3: 계층적
프로젝트 내 하위 프로젝트의 경우:
[CODE BLOCK]
검색: (모든 Synapse)
검색: (문서 하위 프로젝트만)
패턴 4: 상태 추적
[CODE BLOCK]
일반적인 사용 사례
프로젝트에 대한 모든 결정 찾기
[CODE BLOCK]
도메인의 모든 실수 찾기
[CODE BLOCK]
활성 작업 찾기
[CODE BLOCK]
기술에 대한 메모리 찾기
[CODE BLOCK]
태그 유지 관리
주기적 검토
[CODE BLOCK]
태그 병합
일관성 없는 태그 (와 )가 있는 경우, 병합:
[CODE BLOCK]
모범 사례
> [!TIP]
> - 어휘를 일찍 설정 — 첫날부터 일관된 태그
> - 검색 의도로 태그 — 나중에 어떻게 찾을 것인가?
> - 2-5개 태그가 적정 지점 — 너무 적거나 너무 많으면 안 됨
> - 소문자 + 하이픈 — 가 아닌
> - 주기적 검토 — 중복 병합, 미사용 제거
다음 단계
- 메모리 모범 사례
- FTS5 검색
- 작업 기반 워크플로우
────────────────────────────────────────────────────────────
# 세션 시작 패턴
SUMMARY: 모든 LLM 에이전트가 따라야 할 정규화된 세션 시작 시퀀스.
KEY CONTEXT:
ALWAYS at session start: 1) GET /memory/recall, 2) GET /chat/poll, 3) GET /mind/tasks?status=in_progress
Build system prompt from recall output.
Process unread chat messages before doing new work.
Resume any in_progress tasks before starting new ones.
Store new learnings as they happen — don't wait until session end.
세션 시작 패턴
모든 LLM 에이전트 세션은 이 정규화된 시작 시퀀스를 따라야 합니다. 단계를
건너뛰면 컨텍스트 손실, 메시지 누락, 잊혀진 작업이 발생합니다.
패턴
[CODE BLOCK]
구현
1단계: 모든 메모리 회상
> [!CRITICAL]
> 이것이 가장 중요한 호출입니다. 이것 없이는 과거 세션에 대한 메모리가
> 없습니다.
[CODE BLOCK]
우선순위로 정렬된 모든 메모리의 일반 텍스트 요약을 반환합니다.
2단계: 읽지 않은 채팅 메시지 폴링
[CODE BLOCK]
사람이 보낸 읽지 않은 메시지를 반환합니다. 자동으로 읽음으로 표시합니다.
3단계: 진행 중인 작업 확인
[CODE BLOCK]
지난 세션에 작업 중이던 작업을 반환합니다.
4단계: 컨텍스트 구축
세 가지 응답을 시스템 프롬프트에 결합:
[CODE BLOCK]
5단계: 대기 항목 처리
[CODE BLOCK]
완전한 예시
[CODE BLOCK]
일반적인 실수
> [!WARNING]
> - 회상 건너뛰기 — 컨텍스트 없이 시작, 과거 실수 반복
> - 채팅 폴링 잊기 — 사람의 메시지가 답장 없이 남음
> - 활성 작업 무시 — 실행 중간에 작업이 잊혀짐
> - 아무것도 저장하지 않기 — 세션이 영구적 가치를 생성하지 않음
변형
최소 패턴 (저컨텍스트 LLM)
컨텍스트 창이 작은 LLM의 경우, 전체 회상 건너뛰기:
[CODE BLOCK]
필요에 따라 특정 주제 검색:
[CODE BLOCK]
적극적 패턴 (장기 실행 에이전트)
시간 동안 실행되는 에이전트의 경우, 주기적 재회상 추가:
[CODE BLOCK]
다음 단계
- 메모리 태깅 전략
- 작업 기반 워크플로우
- 채팅 폴링 패턴
────────────────────────────────────────────────────────────
# 작업 기반 워크플로우
SUMMARY: Synapse 작업을 사용하여 세션 간에 유지되는 다단계 LLM 워크플로우를 구동합니다.
작업 기반 워크플로우
작업은 단순한 할 일이 아닙니다 — 영구 LLM 워크플로우의 근간입니다. 다단계
작업에 대해 작업을 생성함으로써 세션 간 연속성을 보장하고 수행된 작업에 대한
감사 추적을 제공합니다.
작업 기반인 이유?
작업이 없으면:
- LLM은 매 세션마다 무엇을 해야 할지 불확실하게 시작
- 다단계 작업이 실행 중간에 잊혀짐
- 수행된 작업의 기록 없음
작업이 있으면:
- LLM이 진행 중인 작업을 즉시 재개
- 다단계 작업이 세션 간 유지
- 모든 작업의 내장 감사 추적
패턴
[CODE BLOCK]
구현
1단계: 다단계 작업에 대한 작업 생성
[CODE BLOCK]
2단계: 작업 설명에 진행 상황 추적
[CODE BLOCK]
3단계: 세션 간 재개
[CODE BLOCK]
4단계: 완료 및 보관
[CODE BLOCK]
전체 예시: 배포 워크플로우
[CODE BLOCK]
작업 계층
복잡한 작업의 경우, 부모-자식 작업 관계 사용:
[CODE BLOCK]
하위 작업 검색:
[CODE BLOCK]
상태 워크플로우
[CODE BLOCK]
Pending
생성되었지만 시작되지 않은 작업. 계획된 작업에 사용.
In Progress
현재 작업 중. 설명에 진행 상황 업데이트.
Done
성공적으로 완료. 설명에 요약 포함.
Cancelled
중단. 설명에 이유 포함.
모범 사례
> [!TIP]
> - 다단계 작업에 작업 생성 — 단일 단계 작업은 작업 불필요
> - 진행 상황으로 설명 업데이트 — 재개 가능
> - 활성 작업에 높은 우선순위 사용 — 회상에 노출
> - 완료 시 작업 완료 표시 — inprogress로 남기지 마십시오
> - 완료 요약을 메모리로 저장 — 장기 참조
일반적인 패턴
패턴: 버그 수정 워크플로우
[CODE BLOCK]
패턴: 연구 워크플로우
[CODE BLOCK]
다음 단계
- 세션 시작 패턴
- 채팅 폴링 패턴
- 오류 복구
## 카테고리: 자주 묻는 질문
자주 묻는 질문과 일반적인 문제.
────────────────────────────────────────────────────────────
# API FAQ
SUMMARY: 일반적인 API 질문 — 인증, 속도 제한, 오류 처리, 엔드포인트 검색.
API FAQ
Synapse API에 대한 일반적인 질문입니다.
인증은 어떻게 합니까?
두 가지 방법이 있습니다:
1. Mind Key (데이터 엔드포인트용):
2. JWT (계정 엔드포인트용):
또는 쿼리 파라미터로 (분당 60회 제한):
Authentication을 참조하십시오.
Mind Key와 JWT의 차이는 무엇입니까?
- Mind Key: 테넌트 범위, 만료 없음, memory/chat/tasks 데이터용
- JWT: 사용자 범위, 7일 만료, 계정/마인드 관리용
Mind Key vs JWT를 참조하십시오.
왜 401 Unauthorized가 발생합니까?
일반적인 원인:
1. 헤더 누락
2. 잘못된 Mind Key (로 시작하는지 확인)
3. Mind Key가 필요한 곳에 JWT 사용 (또는 그 반대)
4. Mind Key가 취소됨
해결: 토큰을 확인하십시오. Authentication을 참조하십시오.
왜 404 Not Found가 발생합니까?
잘못된 엔드포인트 경로를 사용했습니다. Synapse에는 에
나열된 경로만 있습니다.
해결: 를 호출하여 모든 유효한 경로를 확인하십시오. 추측하지 마십시오.
왜 429 Too Many Requests가 발생합니까?
속도 제한이 분당 60회인 쿼리 파라미터 인증을 사용 중입니다.
해결: 헤더로 전환하십시오 (속도 제한 없음).
속도 제한을 참조하십시오.
모든 엔드포인트를 어떻게 나열합니까?
[CODE BLOCK]
올바른 엔드포인트를 어떻게 찾습니까?
1. 에서 기계 판독 가능 목록 확인
2. 에서 전체 API 문서 확인
3. 에서 문서 시스템 탐색
4. 에서 OpenAPI 3.0 사양 사용
POST 대신 GET을 사용할 수 있습니까?
일부 POST 엔드포인트에는 URL 전용 도구를 위한 GET 동등물이 있습니다:
- ↔
- ↔
- ↔
사용 가능한 GET 변형은 에서 확인하십시오.
오류는 어떻게 처리합니까?
모든 오류는 JSON을 반환합니다:
[CODE BLOCK]
오류 및 오류 처리를 참조하십시오.
요청 본문 제한은 어떻게 됩니까?
10 MB입니다. 더 큰 페이로드 (예: 파일 업로드)의 경우 multipart 엔드포인트를
사용하십시오.
API는 CORS를 지원합니까?
네. 모든 엔드포인트는 다음을 반환합니다:
[CODE BLOCK]
SDK가 있습니까?
네:
- Node.js:
- MCP:
자세한 내용은 API 개요를 참조하십시오.
페이지네이션은 어떻게 합니까?
및 을 사용하십시오:
[CODE BLOCK]
기본 limit: 100. 최대: 500.
카테고리나 태그로 메모리를 필터링할 수 있습니까?
네:
[CODE BLOCK]
메모리를 어떻게 검색합니까?
두 가지 방법:
1. FTS5 키워드 검색:
2. 의미론적 검색:
FTS5 검색 및 의미론적 검색을 참조하십시오.
메모리를 어떻게 업데이트합니까?
동일한 + 로 를 POST하십시오 — 기존 메모리가
업데이트되며 중복되지 않습니다.
[CODE BLOCK]
메모리를 어떻게 삭제합니까?
[CODE BLOCK]
대량 삭제할 수 있습니까?
네:
[CODE BLOCK]
다음 단계
- API 개요
- 오류 및 오류 처리
- Authentication
────────────────────────────────────────────────────────────
# 일반 FAQ
SUMMARY: Synapse에 대한 일반적인 질문 — 무엇인지, 어떻게 작동하는지, 누구를 위한 것인지.
일반 FAQ
Synapse에 대한 일반적인 질문입니다.
Synapse란 무엇입니까?
Synapse는 LLM 에이전트를 위한 영구 메모리 API입니다. AI 어시스턴트에게
세션 간에 유지되는 영구적이고 쿼리 가능한 뇌를 제공합니다. 채팅이
닫힐 때 모든 것을 잊어버리는 대신, LLM은 단순한 HTTP API를 통해 메모리를
저장하고 검색합니다.
자세히 알아보기: Synapse란 무엇입니까?
Synapse는 누구를 위한 것입니까?
- 영구 상태가 필요한 LLM 에이전트 개발자
- 커스텀 에이전트로 로컬 LLM을 실행하는 파워 유저
- 공유 메모리로 AI 어시스턴트를 구축하는 팀
- 세션 간 LLM 호출을 연결하는 자동화 엔지니어
Synapse는 무료입니까?
Synapse는 에서 호스팅되며 개인 사용은
무료입니다. 자체 호스팅의 경우 저장소를 참조하십시오.
Synapse는 ChatGPT Memory와 어떻게 다릅니까?
| 기능 | ChatGPT Memory | Synapse |
|---------|---------------|---------|
| 저장소 | OpenAI 서버 | 본인 서버 |
| API 접근 | 아니오 | 예 (REST + MCP) |
| 다중 테넌트 | 아니오 | 예 (minds) |
| 커스텀 카테고리 | 아니오 | 예 (8개 카테고리) |
| 전문 검색 | 제한적 | FTS5 + 의미론적 |
| 자체 호스팅 | 아니오 | 예 |
어떤 LLM이 Synapse와 함께 작동합니까?
HTTP 호출을 하거나 MCP를 사용할 수 있는 모든 LLM:
- Claude (Anthropic) — MCP 또는 직접 API를 통해
- GPT-4 / GPT-3.5 (OpenAI) — function calling + API를 통해
- Gemini (Google) — function calling + API를 통해
- Llama / Mistral (로컬) — 커스텀 통합을 통해
- Synapse MCP 서버를 통한 모든 LLM
Synapse를 직접 호스팅해야 합니까?
아니오. 의 호스팅 버전은 공용 사용 가능합니다.
자체 호스팅은 선택 사항입니다 (프라이버시, 사용자 정의, 또는 폐쇄망 환경용).
얼마나 많은 데이터를 저장할 수 있습니까?
호스팅 버전에는 엄격한 제한이 없습니다. 일반적인 사용:
- 마인드당 100-1000개 메모리
- 메모리당 1-10 KB (content 필드)
- 합계: 마인드당 10 MB
더 큰 규모의 경우, 자체 호스팅하십시오.
데이터가 비공개입니까?
네. 각 마인드는 격리되어 있습니다 (다중 테넌시 참조).
다른 사용자는 귀하의 데이터를 볼 수 없습니다. 호스팅 제공자 (Schäfer
Services)는 접근 권한이 있지만 사용자 데이터를 열람하지 않습니다.
최대 프라이버시를 위해, 자체 호스팅하십시오.
데이터를 내보낼 수 있습니까?
네. 를 사용하여 모든 메모리를 JSON으로 내보내십시오.
백업 및 복원을 참조하십시오.
Mind Key를 분실하면 어떻게 됩니까?
Mind Key는 생성 시 한 번만 표시됩니다. 분실한 경우:
1. 이메일/비밀번호로 로그인하여 JWT 획득
2. 로 새 마인드 생성
3. 새 Mind Key 저장
4. (선택 사항) 로 이전 마인드 삭제
키를 분실한 마인드의 메모리는 복구할 수 없습니다.
여러 LLM 에이전트가 마인드를 공유할 수 있습니까?
네. 동일한 Mind Key를 사용하는 모든 에이전트가 해당 마인드의 데이터를
공유합니다. 조정된 다중 에이전트 작업은 다중 에이전트 조정을 참조하십시오.
Synapse는 오프라인으로 작동합니까?
아니오, Synapse는 서버 (호스팅 또는 자체 호스팅)에 대한 인터넷 연결이
필요합니다. 오프라인 LLM의 경우, Synapse를 로컬로 실행하십시오.
메모리 검색은 얼마나 빠릅니까?
- FTS5 키워드 검색: 1000개 메모리에 대해 < 10ms
- 의미론적 검색: 1000개 메모리에 대해 50-100ms
- 전체 회상: 1000개 메모리에 대해 < 50ms
자세한 내용은 FTS5 검색을 참조하십시오.
LLM 없이 Synapse를 사용할 수 있습니까?
네. Synapse는 일반 메모리 API입니다. 카테고리와 태그가 있는 영구적이고
검색 가능한 키-값 저장소의 이점을 얻을 수 있는 모든 애플리케이션에서
사용할 수 있습니다.
다음 단계
- Synapse란 무엇입니까?
- 빠른 시작
- API FAQ
────────────────────────────────────────────────────────────
# MCP FAQ
SUMMARY: MCP 통합에 대한 일반적인 질문 — 도구, 전송, 문제 해결.
MCP FAQ
Synapse MCP 서버에 대한 일반적인 질문입니다.
MCP란 무엇입니까?
MCP (Model Context Protocol)는 LLM-도구 통합을 위한 Anthropic의 개방
표준입니다. API 문서를 프롬프트에 붙여넣는 대신, MCP 서버에 도구를
등록하고 LLM이 네이티브 함수로 호출합니다.
MCP란 무엇입니까?를 참조하십시오.
Synapse MCP는 몇 개의 도구를 노출합니까?
12개 카테고리에 걸쳐 79개 도구: memory, chat, scheduler, tasks,
scripts, computers, push, user, utility, visualization, sharing, webhooks,
browser.
전체 목록은 MCP란 무엇입니까?를 참조하십시오.
어떤 MCP 클라이언트가 지원됩니까?
- Claude Desktop (macOS, Windows)
- Claude Code (터미널)
- Cursor (IDE)
- Continue.dev (VS Code, JetBrains)
- Cline (VS Code)
- MCP 호환 클라이언트
구성 예시는 Claude Desktop 설정을 참조하십시오.
어떤 전송이 지원됩니까?
1. stdio (로컬, 데스크톱에 권장)
2. HTTP/SSE (원격, 다중 테넌트)
3. WebSocket (모바일, 대용량)
Claude Desktop은 어떻게 구성합니까?
을 편집하십시오:
[CODE BLOCK]
Claude Desktop 설정을 참조하십시오.
Claude Desktop에 도구가 나타나지 않는 이유는 무엇입니까?
1. Claude Desktop을 완전히 재시작 (macOS에서 Cmd+Q)
2. 구성 파일이 유효한 JSON인지 확인
3. Node.js 18+ 설치 확인
4. MCP 로그 확인:
MCP 문제 해결을 참조하십시오.
다른 마인드를 사용하려면 어떻게 합니까?
MCP 구성에서 를 변경하고 클라이언트를 재시작하십시오.
여러 마인드의 경우, 다른 Mind Key로 여러 MCP 서버 인스턴스를
실행하십시오.
노출되는 도구를 제한할 수 있습니까?
네, 도구 프로필을 사용하십시오:
- : 8개 복합 도구 (500 토큰)
- : 25개 도구 (2,500 토큰)
- : 119개 도구 (8,250 토큰, 기본값)
환경 변수 또는 헤더로 설정.
MCP 문제는 어떻게 디버그합니까?
1. MCP 서버 수동 실행:
2. 클라이언트 로그 확인 (클라이언트별로 다름)
3. Mind Key 작동 확인:
4. Synapse 상태 확인:
MCP 문제 해결을 참조하십시오.
MCP 서버는 무료입니까?
네. npm 패키지 는 오픈 소스입니다. 의
호스팅된 MCP 서버는 공용 사용이 무료입니다.
MCP 서버를 자체 호스팅할 수 있습니까?
네:
[CODE BLOCK]
MCP는 직접 API 호출과 어떻게 다릅니까?
| 측면 | 직접 API | MCP |
|--------|-----------|-----|
| LLM이 알아야 할 것 | URL, 헤더, 인증 | 도구 이름만 |
| 인증 처리 | 수동 | 자동 (환경 변수) |
| 도구 검색 | /endpoints 읽기 | MCP 프로토콜을 통해 자동 |
| 오류 처리 | 수동 | 표준화 |
| 적합한 용도 | 커스텀 통합 | LLM 에이전트 |
자체 MCP 클라이언트를 구축할 수 있습니까?
네. 공식 MCP SDK를 사용하십시오:
- TypeScript:
- Python:
커스텀 MCP 클라이언트를 참조하십시오.
MCP 버그는 어떻게 보고합니까?
이슈를 열으십시오:
포함 사항:
- MCP 서버 버전
- 클라이언트 이름 및 버전
- 운영 체제
- 관련 로그
- 재현 단계
다음 단계
- MCP란 무엇입니까?
- Claude Desktop 설정
- MCP 문제 해결
────────────────────────────────────────────────────────────
# 문제 해결 FAQ
SUMMARY: 일반적인 Synapse 문제에 대한 해결 방법 — 인증, 네트워크, 데이터, 배포.
문제 해결 FAQ
일반적인 Synapse 문제에 대한 해결 방법입니다.
로그인할 수 없습니다
증상
- 이 401 반환
- "Invalid email or password"
해결 방법
1. 이메일이 올바른지 확인 — 대소문자 구분
2. 비밀번호 확인 — 최소 6자
3. 계정이 없는 경우 먼저 가입:
4. (SMTP가 구성된 경우) 웹 UI를 통해 비밀번호 재설정
Mind Key를 분실했습니다
증상
- 메모리에 접근할 수 없음
- Mind Key가 삭제/분실됨
해결 방법
Mind Key는 복구할 수 없습니다. 다음을 수행해야 합니다:
1. JWT 받기 위해 로그인:
2. 마인드 나열: (JWT로)
3. 새 마인드 생성:
4. 새 Mind Key 저장
5. (선택 사항) 이전 마인드 삭제:
Mind Key를 찾을 수 없는 한 이전 마인드의 데이터는 손실됩니다.
API 호출이 401을 반환합니다
증상
- 모든 API 호출이 401 Unauthorized 반환
- "Mind Key fehlt oder ungültig"
해결 방법
1. 헤더 형식 확인:
2. Mind Key가 로 시작하는지 확인 (는 JWT)
3. 직접 테스트:
[CODE BLOCK]
4. Mind Key가 취소되었을 수 있음 — 새 마인드 생성
Authentication을 참조하십시오.
API 호출이 404를 반환합니다
증상
- 404 Not Found
- "Route not found"
해결 방법
> [!CRITICAL]
> 엔드포인트 경로를 추측하지 마십시오. 의 경로만 존재합니다.
1. 유효한 엔드포인트 확인:
2. URL을 정확히 비교 — 대소문자 구분, 후행 슬래시 없음
3. HTTP 메서드 확인 — 와 는 다름
API 호출이 429를 반환합니다
증상
- 429 Too Many Requests
- "Rate limit exceeded"
해결 방법
1. 헤더 인증으로 전환 (속도 제한 없음):
[CODE BLOCK]
2. 를 사용해야 하는 경우 초 대기
속도 제한을 참조하십시오.
메모리 검색이 결과를 반환하지 않습니다
증상
- 가 빈 결과 반환
- 메모리가 존재한다는 것을 알고 있음
해결 방법
1. 메모리 존재 확인:
2. 검색 구문 확인 — FTS5는 특정 구문이 있음
3. 더 단순한 쿼리 시도 — 대신
4. 개념적 쿼리에 의미론적 검색 사용:
FTS5 검색을 참조하십시오.
메모리가 유지되지 않습니다
증상
- POST /memory가 성공 반환
- GET /memory/recall에 표시되지 않음
해결 방법
1. 동일한 Mind Key 확인 — 다른 키 = 다른 마인드
2. 응답 확인 — POST는 반환
3. /memory/recall (텍스트) 대신 GET /memory (JSON 목록) 시도
4. 필터 확인 — 또는 가 숨기고 있을 수 있음
Claude Desktop에 도구가 나타나지 않습니다
증상
- Claude Desktop이 0개 도구 표시
- 🔌 아이콘 없음
해결 방법
1. Claude Desktop 완전히 재시작 (Cmd+Q)
2. 구성 파일이 유효한 JSON인지 확인
3. Node.js 18+ 설치 확인
4. MCP 수동 실행:
5. 로그 확인:
MCP 문제 해결을 참조하십시오.
Synapse가 오프라인입니다
증상
- synapse.schaefer.zone에 도달할 수 없음
- curl 시간 초과
해결 방법
1. 인터넷 확인 — 다른 사이트 시도
2. Synapse 상태 확인:
3. 대기 — 일시적 중단 또는 배포일 수 있음
4. 상태 페이지 확인 (있는 경우)
자체 호스팅의 경우: Docker 컨테이너 상태, 데이터베이스 연결 확인.
데이터베이스 오류
증상
- 500 Internal Server Error
- "Database connection failed"
해결 방법
자체 호스팅의 경우:
1. PostgreSQL 실행 확인:
2. 환경의 DATABASEURL 확인
3. 마이그레이션 확인:
4. 디스크 공간 확인:
호스팅의 경우: 지원팀에 보고.
웹훅이 발생하지 않습니다
증상
- 웹훅을 등록했지만 콜백을 받지 못함
- 귀하의 URL로 POST 없음
해결 방법
1. URL이 접근 가능한지 확인:
2. 이벤트 필터 확인 — 는 모든 메모리 이벤트 매칭
3. 웹훅 테스트:
4. 웹훅 활성화 확인:
5. SSL 확인 — Synapse는 웹훅 URL에 유효한 HTTPS 필요
Webhooks API를 참조하십시오.
Cron 작업이 실행되지 않습니다
증상
- cron 작업을 생성했지만 실행되지 않음
- 이 업데이트되지 않음
해결 방법
1. 스케줄 구문 확인 — 유효한 5필드 cron 또는 정수 초여야 함
2. 엔드포인트가 허용되는지 확인 — http(s)여야 하며, 사설 IP 불가
3. 작업 활성화 확인:
4. 다음 예약 시간까지 대기 — cron은 즉시 실행되지 않음
Cron 및 Scheduler를 참조하십시오.
추가 도움이 필요하십니까?
1. 기존 문서 확인:
2. 문서 검색:
3. 이슈 열기:
4. 연락: 페이지 참조
다음 단계
- 오류 및 오류 처리
- API FAQ
- MCP 문제 해결