<h1 align="center">🧠 Lemoria</h1> AI를 활용한 개발을 위한 메모리 및 오케스트레이션 운영체제 인공지능 지원 개발을 위한 지속 가능한 기억 장치. <a href="https://img.shields.io/badge/python-3.11%2B-blue" target="_blank"><img src="https://img.shields.io/badge/python-3.11%2B-blue?style=flat-square&logo=python" alt="Python 3.11+" /></a> <a href="https://img.shields.io/github/license/devcristianlopez/lemoria" target="_blank"><img src="https://img.shields.io/github/license/devcristianlopez/lemoria?style=flat-square" alt="MIT License" /></a> <a href="https://img.shields.io/github/last-commit/devcristianlopez/lemoria" target="_blank"><img src="https://img.shields.io/github/last-commit/devcristianlopez/lemoria?style=flat-square" alt="Last Commit" /></a> <a href="https://img.shields.io/github/repo-size/devcristianlopez/lemoria" target="_blank"><img src="https://img.shields.io/github/repo-size/devcristianlopez/lemoria?style=flat-square" alt="Repo Size" /></a> <a href="https://img.shields.io/github/actions/workflow/status/devcristianlopez/lemoria/ci.yml?style=flat-square&logo=githubactions" target="_blank"><img src="https://img.shields.io/github/actions/workflow/status/devcristianlopez/lemoria/ci.yml?style=flat-square&logo=githubactions" alt="CI" /></a> <a href="https://img.shields.io/badge/tests-252-brightgreen?style=flat-square&label=tests" target="_blank"><img src="https://img.shields.io/badge/tests-252-brightgreen?style=flat-square&label=tests" alt="Tests" /></a>

Lemoria는 사용자의 개발 흐름을 AI 에이전트에 의해 오케스트레이션되는 추적 가능한 프로세스로 변환하는 Python 기반의 CLI 도구입니다. 모든 아이디어, 모든 결정, 모든 코드는 초기 명세부터 푸시 및 문서화에 이르기까지 완전한 추적성을 가지고 PostgreSQL에 기록됩니다.

단 한 번 설치하면 모든 프로젝트(깨끗하고, 분리되어 있으며, 아무것도 설정할 필요가 없는)가 에이전트, 데이터베이스 및 영구 메모리를 상속받습니다.

✨ 주요 특징 (Features)

🎯 완벽한 SDD 플로우 — 15단계: discovery → idea → spec → PRD → tasks → architecture → implementation → testing → review → commit → push → documentation → memory update
🤖 8개의 OpenCode 에이전트 — 전문화된 에이전트(implementation, frontend, DB, testing, GitHub, review, documentation)에게 자동으로 작업을 위임하는 오케스트레이터
🧭 에이전트 관리 — 각 서브 에이전트의 .md 파일은 진실의 원천이며 DB는 미러 역할을 합니다. 모델은 에이전트별로 확인하고 변경할 수 있습니다 (lemoria agent sync|model|status)
📊 opencode 텔레메트리 — 세션, 토큰 및 에이전트당 비용을 추적하며, Omarchy 전용 위젯을 통해 Codex/Claude/Fireworks와 분리하여 제공합니다.
🗃️ 완벽한 추적성 (Trazability) — 모든 프로젝트, PRD, 작업, 결정 및 플로우 단계가 관계형 메타데이터와 함께 PostgreSQL에 영구 저장됩니다.
🐘 네이티브 또는 Docker용 PostgreSQL — 이미 실행 중인 서버를 사용하십시오. Docker는 대안일 뿐 필수 요건은 아닙니다.
🔌 글로벌 CLI — 설치 후 모든 터미널에서 lemoria가 사용 가능합니다.
📂 독립적인 프로젝트 — 각 프로젝트는 자체 폴더에 존재하여 교차 오염을 방지합니다.
📚 Obsidian vault — 선택적 양방향 동기화: 마크다운으로 내보내고 vault에서 DB를 복원할 수 있습니다 (개인 메모리, git 저장소 외부에 보관).
📋 기록된 결정 사항 — 중요한 모든 변경 사항은 구현 전에 ADR(Architecture Decision Record)로 문서화됩니다.
🔄 상태 머신 (State machine) — 플로우의 각 단계는 flow_steps에 기록되어 컨텍스트 손실 후에도 세션을 재개할 수 있게 합니다.
🧪 252개의 자동 테스트 — pytest와 SQLite in-memory를 사용하며, GitHub Actions에서 CI(Python 3.11/3.12/3.13)를 지원합니다.
🏷️ 8개의 타입 지정 Enum — 모든 상태는 데이터베이스 수준의 무결성을 위해 CheckConstraint가 적용됩니다.
📡 Context7 MCP — MCP 서버를 통해 라이브러리 및 프레임워크에 대한 실시간 문서를 제공합니다.

🚀 빠른 시작 (Quick Start)

1. 저장소 복제

git clone https://github.com/devcristianlopez/lemoria.git && cd lemoria

참고: 설치 후에는 lemoria/ 저장소는 필요하지 않습니다. 에이전트는 ~/.config/opencode/agents/에 남아 있으며, lemoria 명령어는 전역적으로 사용 가능합니다.

요구 사항: Python >= 3.11, uv 및 PostgreSQL >= 14 (시스템 기본 또는 Docker — 어느 것이든 상관없습니다). Docker는 필수 사항이 아니며 pip도 마찬가지입니다. 설치 프로그램은 먼저 uv를 사용하므로, PEP 668과 충돌 없이 Python 3.14가 설치된 Arch에서도 작동합니다. 다른 배포판에서 오셨고 자세한 내용을 원하시면, INSTALL.md에서 왜 그곳에서 pip install이 실패하는지 그리고 시스템을 손상시키지 않고 어떻게 해제할 수 있는지 설명합니다.

필수 명령어 (오케스트레이터가 실행하며, 진단 및 자동화에 사용됩니다):

lemoria project list               # 모든 프로젝트 목록 표시
lemoria flow list <project-id>     # 프로젝트의 PRD(Product Requirements Documents)
lemoria flow status <flow-id>      # 상태 머신(state machine)의 상태 (완료/누락된 단계)
...

커밋은 메시지 규칙을 통해 작업(Task)과 연결됩니다:

Task: <task-id>

lemoria commit sync는 GitPython을 사용하여 해당 트레일러를 읽어 역사적 추적성(trazabilidad)을 재구성합니다. lemoria commit add <sha> --task <id>는 특정 SHA를 기록해야 할 때 사용됩니다. vault는 이 링크들을 commits.md에 내보내므로, Obsidian에서 PRD → Task → Commit 순으로 탐색할 수 있습니다.

🔒 vault는 절대 git에 업로드되지 않습니다

vault에는 개인 메모리: 모든 프로젝트의 대화, ADR(Architecture Decision Records), PRD 및 커밋이 포함됩니다. 이것이 어떤 저장소 외부에서 존재하는 이유입니다:

~/.lemoria/vault/          ← 기본값 (모든 repo 외부)

만약 누군가 저장소 내부에 LEMORIA_VAULT_PATH를 설정하면, Lemoria는 자체 보호 기능을 수행합니다: VaultService.protect_from_git()은 가장 가까운 .git을 감지하고, 쓰기 전에 해당 레포의 .gitignore에 vault를 추가하며, 이는 idempontent(멱등적)하게 작동합니다. 실패하는 경우는 없습니다: 만약 .gitignore를 쓸 수 없다면 stderr로 알림을 보내고 계속 작업을 수행합니다.

$ lemoria vault sync <project-id>
  ! Vault is inside a git repo — added 'vault/obsidian/' to /ruta/al/repo/.gitignore

📋 SDD Flow — Spec Driven Development (명세 주도 개발)

Lemoria는 SDD 흐름을 12단계에 걸쳐 구현하며, 각 단계는 다음 단계를 구동하는 아티팩트를 생성합니다:

💡 User Request
   │
   ↓
...

State Machine (상태 기계)

SDD 흐름의 모든 실행은 flow_steps 테이블에 **흐름(flow)**으로 기록됩니다. 오케스트레이터는 시작 시 현재 상태를 조회하여, 컨텍스트 손실 없이 중단된 흐름을 재개할 수 있게 합니다:

flow step <flow-id> <step> --status completed|running|failed
flow status <flow-id>        # 모든 단계 + 전체 상태 표시

각 단계는 id, flow_id, step, status, started_at, completed_at, output을 가집니다.

SDD 원칙

#	원칙
1	모든 구현은 PRD로 시작합니다
...

🤖 OpenCode Agents (오픈코드 에이전트)

Lemoria는 언어/프레임워크에 의존하지 않는 영어 기반의 8개 에이전트를 포함하고 있습니다. orchestrator가 기본 에이전트이며, 나머지 에이전트들은 SDD 흐름 단계에 따라 작업을 위임받는 서브 에이전트입니다.

에이전트(Agente)	모드(Modo)	역할(Rol)
🧠 Orchestrator	`primary` (기본값)	SDD 흐름 결정, 작업 위임, 종료 체크리스트 실행
...

에이전트와 스킬은 프로젝트 레벨(.opencode/)과 글로벌 레벨(~/.config/opencode/) 모두에 복사되며, 추가 설정 없이 모든 프로젝트에서 사용할 수 있습니다. 설치 프로그램은 전역 설정에 default_agent: orchestrator를 추가합니다. 만약 해당 값이 없다면 추가하고; 이미 다른 값이 있다면 그 값을 존중하며 알림을 줍니다. 오케스트레이터를 기본값으로 사용하면, 어떤 프로젝트에서든 OpenCode를 열 때 오케스트레이터가 시작됩니다: 자연어로 기능을 설명하기만 하면 나머지는 오케스트레이터가 처리합니다.

You: "JWT를 이용한 인증을 구현하고 싶어요"
→ Orchestrator가 프로젝트, 대화 및 PRD(제품 요구사항 문서) 등록
→ implementation-agent, testing-agent, review-agent 등에 위임...
...```

배울 슬래시 명령어(slash command)나 메뉴는 없습니다: 흐름은 **100% 에이전트 주도형(agent-driven)**입니다. 오케스트레이터가 Lemoria의 명령을 대신 실행합니다. 유일한 인간 설정 영역은 서브에이전트들의 모델과 노력이며, 이는 CLI를 통해 이루어집니다 (서브에이전트 설정 보기 [Configurar subagentes](#configurar-subagentes) 참조).

### 설정: `opencode.json` 대 `opencode.jsonc`

Lemoria는 서로 다른 목적을 가진 두 가지 OpenCode 설정 파일을 사용합니다:

| 파일 | 위치 | 기능 | 비고 |
| :--- | :--- | :--- | :--- |
| `opencode.jsonc` | `~/Projects/lemoria/` (레포지토리 내) | Lemoria 프로젝트 설정: 기본 에이전트 및 스킬 | ✅ `//`와 `/* */` 지원 |
| `opencode.json` | `~/.config/opencode/` (글로벌) | 사용자 전역 설정: **기본 에이전트**, AI 페르소나, 상호작용 언어, MCP 서버 |

**차이점은 무엇인가요?**

- **`opencode.jsonc`**는 레포지토리에 위치하며 Lemoria 프로젝트 관련 사항(기본으로 로드할 에이전트, 스킬 검색 위치 등)을 정의합니다. 이 파일은 주석을 남길 수 있도록 `.jsonc` 확장자를 사용합니다.
- **`opencode.json`**은 전역 설정에 있으며 사용자 전체의 기본값과 설정을 관리합니다.

- **`opencode.json`**: 이 파일은 각 사용자의 홈 디렉터리에 위치하며, AI의 언어와 톤을 정의하는 곳입니다. 설치 프로그램이 해당 파일이 없으면 생성합니다 (기본값 에이전트: `orchestrator`, 스킬 경로 포함). 이미 존재하는 경우, `default_agent`가 누락된 경우에만 추가하고 나머지 키는 유지합니다. 기본 에이전트를 오케스트레이터로 설정하면 모든 프로젝트가 이와 함께 시작됩니다. AI가 사용자에게 스페인어, 영어 또는 다른 스타일로 대화하기를 원한다면 이곳에서 설정할 수 있습니다.

**왜 중요한가요?**

Lemoria의 에이전트와 스킬은 모두 **영어**로 되어 있습니다 (범용적입니다). 하지만 AI는 사용자가 `~/.config/opencode/opencode.json`에 정의한 언어로 사용자에게 소통합니다. 예를 들면:

```json
// ~/.config/opencode/opencode.json
{
  "agents": {
...

이는 에이전트가 영어로 작동한다 (코드, 커밋, 문서)는 의미이며, 하지만 사용자는 원하는 언어로 상호작용할 수 있다는 뜻입니다.

🧭 에이전트 및 원격 측정(Telemetry) 관리

Lemoria는 단순히 위임하는 것 이상을 합니다. 하위 에이전트를 등록하고, 각 에이전트의 모델을 변경할 수 있게 하며, Omarchy 자체 위젯에 **사용량 소비(consumption)**를 게시합니다.

핵심 개념: 모델 상속(Inheritance)

OpenCode는 모든 에이전트의 프론트매터(frontmatter)에서 model 키를 읽습니다. 만약 에이전트가 이 키를 선언하지 않으면, 호출한 주체의 모델을 상속받습니다.

Lemoria의 7개 하위 에이전트는 모델을 선언하지 않기 때문에, 7개 모두 오케스트레이터의 모델을 사용합니다. 따라서 agents.model 열은 비어 있습니다:

버그가 아닙니다. 이것은 OpenCode의 동작 방식입니다. 모델을 고정하는 것은 선택 사항이며 에이전트별로 적용되며, 빈 열은 정확히 그 의미를 나타냅니다: "이 에이전트는 모델을 고정하지 않음."

모델을 고정하려면 프론트매터에 한 줄을 추가해야 하며, 다음 명령어로 수행합니다:

lemoria agent model review-agent anthropic/claude-sonnet-4-5   # 모델 고정
lemoria agent model review-agent anthropic/claude-sonnet-4-5 --effort high
lemoria agent model review-agent          # 인자 없음: 현재 상태 표시

명령어는 .md 파일을 편집하며, 데이터베이스(DB)를 편집하지 않습니다. 마크다운이 진실의 원천이며, 베이스는 이를 단순히 반영할 뿐입니다. lemoria agent status는 세 가지 상황을 구별합니다:

`source`	의미
`inherits`	frontmatter에 `model` 없음 → 호출한 주체의 모델 사용
...

명령어

명령어	기능
`lemoria agent sync [--dry-run] [--dir PATH]`	`.opencode/agents/*.md`를 `agents` 테이블에 반영합니다.
...
`--dry-run`은 아무것도 쓰지 않고 무엇이 변경될지 알려줍니다. `.md` 파일의 경로는 `LEMORIA_OPENCODE_AGENTS_DIR` (기본값 `./.opencode/agents`)에서 나옵니다.

서브 에이전트 설정

오케스트레이터는 Lemoria에서 설정되지 않습니다. 모델과 노력(effort)은 세션 기반이며 OpenCode의 /models 및 /variants를 통해 선택됩니다. 서브 에이전트는 CLI를 통해 고정(pin)할 수 있으며, lemoria agent model은 해당 .md 파일에 model: provider/model#variant를 작성합니다:

lemoria agent status
lemoria agent model implementation-agent openai/gpt-5.6-sol --effort high
lemoria agent model review-agent openai/gpt-5.6-luna --effort high
...

--clear는 고정(pin)을 제거하고 에이전트를 상속(inheritance) 상태로 되돌립니다. 즉, 오케스트레이터의 세션 모델을 다시 사용합니다. frontmatter에 model이 없는 모든 에이전트도 마찬가지입니다. — 고정되지 않은 에이전트는 오케스트레이터의 모델을 상속받습니다.

실행 중인 에이전트 및 소비량 확인

lemoria agent status는 패널에서 제공하지 않는 서브 에이전트별 상세 내역입니다. 출력 예시 (모델은 세션에 따라 다름):

AI 개발을 위한 메모리 및 오케스트레이션 운영체제: Lemoria

요약

핵심 포인트

✨ 주요 특징 (Features)

🚀 빠른 시작 (Quick Start)

1. 저장소 복제

🔒 vault는 절대 git에 업로드되지 않습니다

📋 SDD Flow — Spec Driven Development (명세 주도 개발)

State Machine (상태 기계)

SDD 원칙

🤖 OpenCode Agents (오픈코드 에이전트)

🧭 에이전트 및 원격 측정(Telemetry) 관리

핵심 개념: 모델 상속(Inheritance)

명령어

서브 에이전트 설정

실행 중인 에이전트 및 소비량 확인

댓글

✨ 주요 특징 (Features)

🚀 빠른 시작 (Quick Start)

1. 저장소 복제

🔒 vault는 절대 git에 업로드되지 않습니다

📋 SDD Flow — Spec Driven Development (명세 주도 개발)

State Machine (상태 기계)

SDD 원칙

🤖 OpenCode Agents (오픈코드 에이전트)

🧭 에이전트 및 원격 측정(Telemetry) 관리

핵심 개념: 모델 상속(Inheritance)

명령어

서브 에이전트 설정

실행 중인 에이전트 및 소비량 확인