AI 세션 검색 (aise)
Claude Code, Claude Desktop local agent, Codex, Cursor, Antigravity, Pi coding agent, Prime Agent, Google AI Studio, 그리고 Gemini CLI 등에서 로컬 AI 코딩 에이전트의 세션 기록을 검색하고 복구합니다. macOS, Linux, Windows 환경에서 CLI, MCP 서버, Python 또는 Rust를 사용하여 하나의 인덱스를 활용할 수 있습니다.
PyPI
crates.io
CI
License
<img width="1561" height="1098" alt="aise searching indexed AI coding sessions from the terminal" src="https://github.com/user-attachments/assets/757950b2-0523-4b59-b617-96d94ccf5ab1" />
하나의 인덱스로 9개 제공업체 검색
aise는 로컬 트랜스크립트를 인덱싱하여 이전 메시지를 찾고, 파일 버전을 복구하며, 실패한 실행 주변의 컨텍스트를 읽을 수 있게 합니다. 쿼리를 실행할 때 필요에 따라 인덱스가 새로 고쳐지며, --index-refresh existing-only를 사용하면 인덱스를 새로 고치지 않고도 내용을 읽을 수 있습니다.
설치하기
uv로 전역 aise 명령어를 설치하는 것이 권장됩니다:
uv tool install ai-session-search && aise integrations install
또는 Rust의 cargo를 사용합니다:
cargo install ai-session-search --locked && aise integrations install
두 명령어 모두 최신 안정화 버전을 설치합니다. 두 번째 명령어는 MCP 서버를 등록하고 감지된 각 하네스(harness)에 대한 가이드를 작성하며, --dry-run을 사용하면 모든 쓰기 작업을 미리 볼 수 있습니다.
일반적인 작업
| 할 일 | 명령어 |
|---|
| 무언가가 발생한 세션 찾기 | aise search "auth refactor" |
| ... | |
사용자 입력에는 에이전트가 바쁜 동안 타이핑된 프롬프트와 도구를 통해 기록된 답변이 포함됩니다. --role user는 저장된 역할을 가로질러 해당 기록된 입력 영역을 검색하며, 반환되는 컨텍스트에는 생성된 텍스트가 포함될 수 있습니다. 상위 에이전트가 하위 에이전트에게 보낸 알려진 프롬프트는 이 선택자 밖에 남아 있습니다. --role을 생략하면 전체 내용을 검색합니다.
Claude Code 대화 및 첨부 파일 기록이 검색 가능한 텍스트를 제공합니다. 저장된 API 요청 사본은 반복되는 턴이나 파일 편집을 추가하지 않습니다. 큐에 제출된 Claude 제출물은 큐 명령 첨부 파일을 통해 전달되거나 이전 항목이 취소/삭제된 후 직접 나타나며, 이 경우에도 한 번만 표시됩니다. 독립적인 동일 텍스트 제출물은 별개로 유지됩니다. 언급된 파일, 첨부 파일 스니펫, 메모 및 계획 텍스트, 그리고 호출된 스킬 내용은 기본적으로 검색 가능합니다.
주입된 지침(Injected instructions), 세션 컨텍스트(session context), 후크 메시지(hook messages), 그리고 인터럽트 알림(interrupt notices)은 harness notice입니다. --kinds harness-notice를 사용하여 찾을 수 있습니다. aise doctor는 인식되지 않은 기록 및 첨부 파일 유형을 보고하며, 형식이 잘못된 첨부 파일과 건너뛴 바이너리 페이로드(binary payloads)는 구문 분석 경고(parse warnings)로 나타납니다.
수정 및 반복(Corrections and repeats)은 큐에 제출된 입력을 포함하여 인간 발신자 증거가 있는 입력을 사용합니다. 오래된 Claude Code 기록은 발신자를 생략할 수 있습니다. 보고서는 해당 행들을 unattributed_input_count로 계산하고 기본적으로 제외합니다. --include-unattributed-input을 전달하여 포함시킬 수 있으며, 이는 프로그램이 보냈을 수도 있습니다. aise repeats --format json --report는 이 개수를 그룹과 함께 포함합니다.
배포된 수정 카테고리(correction categories)는 고정 구문(fixed phrasings)의 작은 시작 세트입니다. 이들은 상황에 맞게 작성된 수정 사항을 놓칠 수 있습니다. 세션이 어디서 잘못되었는지 찾으려면, 기록된 입력을 나열하고 컨텍스트와 함께 읽어보십시오. 카테고리를 빠른 첫 번째 필터로 사용하십시오:
aise list --path ~/source/project --when 7d --limit 10
aise messages search "" --session-id SESSION_ID --role user --all-results --format json
aise messages get SESSION_ID --seq 42 --context 3
MCP를 사용하려면 list_sessions(path_prefix="/path/to/project", when="7d", limit=10), search_messages(session_id="SESSION_ID", role="user", all_results=true)를 사용한 다음, get_session(session_id="SESSION_ID", seq=42, context=3)을 사용합니다. 발신자 귀속에 불확실성이 있을 때는 출처(provenance)를 확인하십시오. 대규모 MCP 결과의 경우, all_results=true 대신 limit=50으로 대체하고 page.next_offset을 따르십시오. 반복적으로 보이는 단어에는 skill package creation steps를 사용하여 카테고리를 추가하십시오.
서브 에이전트(subagent)의 전체 작업은 자체 세션에 존재하며, 부모 세션에서는 위임 및 그 결과만 표시할 수 있습니다.
--session-kinds subagent는 해당 세션을 나열하고, --parent-session은 특정 실행의 자식들로 범위를 좁힙니다.
빠른 시작
빈 메시지 검색이 힌트를 출력할 때, 이는 활성 쿼리와 필터에서 일치하는 항목을 찾지 못했음을 의미합니다. 이 힌트는 harness notices, 디코딩된 도구 인자(decoded tool arguments), 또는 파일 기록에 존재할 수 있는 관련 콘텐츠를 제안하지만, 그러한 콘텐츠가 실제로 존재함을 증명하지는 않습니다.
aise resume SESSION_ID는 표준 입력(stdin)이나 표준 출력(stdout)이 리디렉션될 때 해당 명령을 출력합니다. 터미널에서 이를 명시적으로 요청하려면 --dry-run을 사용하십시오.
aise COMMAND --help는 모든 매개변수와 기본값을 문서화합니다. 날짜 범위는 ISO 8601, EDTF, 기간 및 일반적인 자연어 형태를 허용하며, 값에 오프셋을 명시하거나 [Europe/Berlin]과 같은 후행 RFC 9557 시간대가 지정되지 않는 한 UTC로 읽힙니다. aise dates는 허용되는 각 패밀리를 예시와 함께 나열합니다.
MCP 서버
Claude Code에게 지난 화요일 실행이 왜 중단되었는지, 또는 리팩토링 전에 무슨 일이 있었는지 물어보십시오. 그러면 이 인덱스를 쿼리하고 대화창을 벗어나지 않고 인라인으로 답변해 줍니다. 서버는 동일한 실행 파일의 서브 커맨드(subcommand)이므로 별도로 설치할 것이 없습니다.
aise integrations install
aise integrations status
aise mcp serve
서버는 읽기 전용 SQL을 위해 search_sessions, search_messages, list_sessions, get_session, get_resume_command, get_index_status, run_skill_capability, 그리고 query_session_index를 노출합니다.
하네스가 무엇을 받게 되는지는 해당 하네스가 기대하는 형식과 위치에서 읽을 수 있는 내용에 따라 달라집니다. --client는 설치 범위를 이름이 지정된 하네스로 제한하며, 어떤 하네스도 훅(hooks)을 얻지 못합니다.
| 하네스 | 수신 항목 |
|---|
| Claude Code CLI/Desktop | MCP 설정, CLAUDE.md 가이드, 스킬 |
| ... | |
파일 복구, 내보내기(export), 분석, 명시적 재인덱싱은 aise files extract, aise export, aise analyze, 그리고 aise reindex를 사용하거나 라이브러리 API를 사용합니다. 쿼리는 인덱스를 새로 고치면서 aise 자체의 상태를 기록할 수 있습니다. --index-refresh existing-only는 SQLite 읽기 전용 모드로 열립니다. 도구 입력은 폐쇄된 스키마(closed schemas)이므로, 오타가 있는 필드는 정확한 인자 경로와 함께 실패합니다.
실패한 설치는 이미 작성했던 내용을 롤백하고, 롤백을 완료할 수 없을 경우 영수증(receipt)을 보존하며 정확한 aise integrations recover 명령어를 출력합니다. aise integrations status는 설치 프로그램 자체의 트랜잭션 잠금 하에 모든 대상을 읽기 때문에 절반만 적용된 상태를 보여주지 않습니다.
검색 비용 (Search cost)
리터럴(Literal) 및 정규식(regex) 쿼리는 단어 인덱스(word index)와 트라이그램 인덱스(trigram index)를 사용하여 후보군을 좁힌 다음, 요청된 일치를 검증합니다. 선택적 조각 필터(selective fragment)와 구조적 필터는 스캔 범위를 줄여줍니다. 퍼지 검색(Fuzzy search)은 적격한 모든 행에 점수를 매기므로, 프로젝트, 제공업체(provider), 세션 또는 날짜로 먼저 범위를 좁히는 것이 좋습니다. --receipt-level summary는 선택된 쿼리 계획을 설명합니다.
Refresh는 쿼리 비용과 별개입니다: 증분 읽기(incremental reads)는 추가된 바이트와 최대 1 MiB의 오버랩을 포함합니다. 전체 소스 폴백(Whole-source fallbacks)은 이전 체크포인트나 파서 버전, 변경된 오버랩 바이트, 그리고 인덱싱된 행을 변경하는 새로운 레코드에 적용됩니다. 소스 업데이트를 기다리려면 --index-refresh before-query를 사용하거나, 새로고침을 건너뛰려면 existing-only를 사용하십시오. 검색 비용 참고 자료(search cost reference)를 참조하십시오.
제공업체 (Providers)
모든 데이터는 사용자 자신의 기기에 있는 로컬 파일에서 읽어옵니다. 클라우드 전용 ChatGPT, Claude, Antigravity 대화 내용은 공급업체 계정에서 복사되지 않으며 이곳에서 검색할 수 없습니다.
| 제공업체 | Provider ID | 네이티브 재개 (Native resume) |
|---|
| Claude Code CLI/Desktop | claude | yes |
| ... | | |
Prime Agent는 Pi를 기반으로 구축되었지만, 자체 루트와 자식 실행 트랜스크립트를 ~/.prime/agent 아래에 유지하므로 --provider pi는 Prime 세션을 절대 반환하지 않으며, 두 기능은 별도의 ID와 재개 명령을 가집니다. Codex desktop과 Codex CLI/IDE는 ~/.codex를 공유하므로 함께 인덱싱됩니다. | | |
codex 제공업체는 해당 로컬 트랜스크립트 형식만 읽습니다. 이 제공업체는 Chat/Work 브라우저 상태를 파싱하거나, OpenAI가 통합된 데스크톱 앱에서 별도의 기록(separate histories)으로 문서화하는 클라우드 기록을 동기화하지 않습니다.
이 ID들은 제공업체 구성의 TOML 키이며, aise config paths는 각 제공업체의 활성화 상태와 효과적인 루트를 출력합니다.
필터 및 범위 (Filters and scopes)
aise list --provider claude-desktop --path ~/source/project --since 7d
...
날짜 경계(Date bounds)는 세션의 기간을 테스트하며, created_at부터 updated_at까지를 포함합니다. --since는 종료일이 해당 경계와 같거나 이후여야 하며, --until은 시작일이 그 이전에 있어야 하고, --when은 겹치는 경우에 사용됩니다. 기간(Spans)에는 공백(gaps)이 있을 수 있으므로, 일주일간의 검색 결과가 하나의 편집을 포함할 수 있습니다. 메시지, 파일 및 이벤트 분석은 각 이벤트의 타임스탬프를 사용합니다.
구성된 작업이나 기본 목적이 없는 경우, Rust, CLI 또는 Python 메시지 검색에서 제한을 생략하면 모든 리터럴(literal), 정규식(regex), 또는 텍스트 없음 매치(no-text match)를 반환합니다. 스크립트에서는 --all-results가 이를 명시적으로 알려줍니다. 세션 수준 및 MCP 검색은 기본적으로 페이지 단위로 작동합니다. 퍼지 검색(Fuzzy search)은 항상 유한한 페이지를 필요로 하며, --limit 0은 해당 명령의 도움말에 명시된 경우 전체 코퍼스(corpus)를 의미합니다.
라인 윈도우는 하나의 부호 규칙을 공유합니다. 양수(positive)는 처음 N줄을 유지하고, 음수(negative)는 마지막 N줄을 유지하며, 0은 모든 것을 의미합니다. aise show --transcript-lines는 전체 렌더링된 스크립트를 표시하고; --lines-per-message는 반환되는 각 메시지를 개별적으로 제한합니다. 둘 다 출력되는 내용을 짧게 만들 뿐 다른 것은 아무것도 건드리지 않기 때문에, 긴 페이지도 놓치는 히트 없이 스키밍(skimmable)이 가능하며, 매칭(matching), 랭킹(ranking), 결과 수(result count), 페이지네이션(pagination), 그리고 컨텍스트 멤버십(context membership)은 영향을 받지 않습니다.
인덱스는 검색 범위를 좁힐 뿐입니다. 정확(exact) 모드와 정규식(regex) 모드는 모든 후보에 대해 패턴을 다시 확인하므로, 인덱싱이 결과를 변경할 수 없습니다. --receipt-level summary는 예상치 못한 쿼리가 어떻게 계획되었는지 보여주며, full은 각 전달되지 않은 값이 어디에서 왔는지 추가합니다. MCP는 구조화된 데이터와 동일한 영수증(receipt)을 반환합니다.
<!-- aise-message-search-contract:start -->
생성 메시지 검색 참조에서 기본 설정, 허용 값 및 충돌 규칙을 확인하십시오. 활성 설정을 확인하려면 aise messages search --describe --describe-surface cli를 실행하십시오.
<!-- aise-message-search-contract:end -->
내보내기 및 분석
aise export SESSION_ID --format markdown
...
번들 목적지(bundle destination)는 이미 존재해서는 안 되므로, 실행 시 기존의 것을 병합하거나 대체하지 않습니다. aise는 전체 디렉터리를 하나의 원자적 단계(atomic step)로 게시하고 영수증을 반환하므로, 중단되어도 미완성된 번들은 남지 않습니다.
Python 및 Rust API
이들을 사용하여 aise를 외부로 실행하고 그 출력을 파싱하는 대신 인덱스를 기반으로 구축할 수 있습니다.
import ai_session_search as aise
search = aise.SessionSearch()
...
rust,no_run
use ai_session_search::SessionSearch;
fn main() -> ai_session_search::anyhow::Result<()> {
...
긴 네이티브(native) 작업은 GIL을 해제하여 다른 Python 스레드가 진행될 수 있도록 합니다. 애플리케이션 서비스 API는 제공자 중립적인(provider-neutral) 요청과 결과를 사용합니다. 단어 개수는 Python의 vocabulary()와 Rust의 AnalysisService::vocabulary를 통해 사용할 수 있으며, aise vocab은 숨겨진 호환성 명령어(compatibility command)로 남아 있습니다. 라이브러리 가이드에 전체 API, 기능 플래그(feature flags), 동시성 의미론(concurrency semantics)이 포함되어 있습니다.
설정 (Configuration)
설정할 것이 없습니다. 파일을 지정하지 않으면 모든 제공자(provider)가 플랫폼 기본 경로에서 활성화됩니다. Google AI Studio는 예외로, 기본 루트를 가지고 있지 않으므로 이를 검색하도록 [providers.aistudio].paths를 설정해야 합니다. aise config init은 모든 설정을 주석 처리하지만 데이터베이스 및 캐시 경로는 포함하여 ~/.ai-session-search/config.toml 파일을 작성합니다. 따라서 이후 릴리스의 기본값은 사용자가 그대로 두는 설정에 계속 적용됩니다. aise config example을 먼저 사용하여 미리 볼 수 있습니다.