무료 Git‑Native 메모리 레이어를 AI 에이전트를 위해 만들었습니다 — 이유와 방법

Source: Dev.to

내가 계속 생각하게 된 문제

나는 AI 에이전트를 끊임없이 사용한다 — Windows에서는 Claude, macOS에서는 Codex를 통한 Claude, 두 번째 의견을 위해 GPT‑4o 등. 매 세션마다 에이전트는 낯선 존재다. 내 선호도, 내 프로젝트, 아무것도 모른다.

기존의 “메모리” 솔루션들은 모두 같은 문제를 가지고 있었다: 유료 API, 서버에 저장되는 데이터, 단일 모델에 종속. 어느 것도 만족스럽지 않았다.

해결책: agent‑soul

agent‑soul은 Git‑기반 메모리 프레임워크로, 다음과 같은 특징을 갖는다:

• 무료 – 유료 API나 월 요금이 없음
• 프라이빗 – 모든 데이터가 내 GitHub 저장소에 존재
• 모델‑중립 – 어떤 LLM에도 동작

각 메모리는 개인 GitHub 저장소에 저장되는 append‑only JSON 이벤트이다. Python 컴파일러가 GitHub Actions를 통해 매 푸시마다 실행되어 이벤트를 처리하고 깔끔한 Markdown 파일을 출력한다. 에이전트 세션이 시작될 때, 에이전트는 시스템 프롬프트를 통해 해당 파일들을 읽는다. 이것이 전체 시스템이다.

┌─────────────────────────────────────────────────────────┐
│                    agent-soul repo                      │
│                                                         │
│  sources//YYYY-MM-DD.ndjson   ← append‑only   │
│      event stream (what happened)                       │
│                                                         │
│  canonical/                            ← compiled by CI│
│    profile.md          ← who the user is               │
│    stable-memory.md   ← durable facts                  │
└─────────────────────────────────────────────────────────┘

이벤트 추가하기

python scripts/add_event.py \
  --source windows-claude \
  --kind preference \
  --scope stable \
  --summary "User prefers explicit TypeScript types over inferred generics."

변경을 푸시하면 GitHub Actions가 자동으로 컴파일한다.

유료 메모리 API와의 비교

핵심 개념

• Append‑only 이벤트 소싱 – 모든 메모리 변경은 Git 커밋으로 기록되어 완전한 감사 로그를 제공한다. 언제든 되돌리기, diff, grep이 가능하다.
• Supersedes 필드 – 사실이 바뀔 때는 기존 이벤트를 참조하는 새로운 이벤트를 작성한다. 컴파일러는 superseded된 이벤트를 제외하고, 히스토리는 보존한다.
• 충돌 감지 – 컴파일러는 Jaccard 유사도를 이용해 모순되는 이벤트를 표시한다. 결과는 canonical/conflicts.md에 기록된다.
• 멀티‑에이전트 동기화 – Windows의 Claude와 macOS의 Claude가 동일한 컴파일된 메모리를 공유한다. git pull 할 수 있는 모든 에이전트가 동기화된다.

시작하기

1. 저장소를 포크한다.
2. 네 개의 페르소나 파일(SOUL.md, IDENTITY.md, USER.md, VOICE.md)을 채운다.
3. 포크에서 GitHub Actions를 활성화한다.
4. JOIN.md에 있는 세션 프로토콜을 에이전트 설정 파일에 붙여넣는다.
5. 한 번 푸시하면 — Actions가 메모리를 컴파일한다. 다음 세션부터 에이전트가 당신을 기억한다.

설정 시간은 약 10분 정도이다.

기여하기

이슈와 풀 리퀘스트를 환영한다. AI 에이전트가 실제로 당신을 기억하도록 만들고 싶지만, 비용을 내거나 타인의 서버를 신뢰하고 싶지 않다면 agent‑soul을 한 번 사용해 보라.