connectai/.astra/project-context/architecture.md

ConnectAI — Project Architecture Context

Snapshot

• Workspace: ConnectAI v2.2.247 (absolute path varies by environment; resolved from the active VS Code workspace)
• Description: The personal intelligence layer for Antigravity and VS Code. A private cognitive partner for deep project context, memory, and proactive strategic decision-making.
• Stack: TypeScript, Node.js, VS Code Extension, LM Studio SDK, Test runner
• Stats: 560 source files, ~83,576 lines across 5 top-level modules.

Last Refresh

• Time: 2026-06-12T14:30:58.311Z
• Files newly analysed: 3
• Files reused from cache: 557

Directory Map

mindmap
  root((ConnectAI))
    src/
      features/
      sidebar/
      lib/
      agent/
      intelligence/
      retrieval/
    media/
    tests/
      helpers/
      integration/
      mocks/
    core_py/
    docs/
      records/
      docs/
      plans/

Module Dependencies

Arrows: which top-level module imports from which.

flowchart LR
    src["src/<br/>317 files"]
    media["media/<br/>6 files"]
    tests["tests/<br/>58 files"]
    core_py["core_py/<br/>6 files"]
    docs["docs/<br/>173 files"]
    tests --> src

Entry Points

Files to read first when learning the codebase.

• src/extension.ts
• media/sidebar.html — Astra
• package.json — npm package manifest

Hub Files

Imported by many other files — touching these has wide blast radius.

• src/utils.ts — referenced by 102 files
• src/config.ts — referenced by 38 files
• src/agent.ts — referenced by 34 files
• src/core/services.ts — referenced by 17 files
• src/features/company/index.ts — referenced by 14 files · Public API for 1인 기업 모드. Consumers (sidebarProvider, chatHandlers, command handlers) import from this barrel so internal layout can move around without touching every call site.
• src/features/company/types.ts — referenced by 14 files · Type definitions for the 1인 기업 (One-Person Company) mode. The mode turns the user into a virtual CEO that dispatches work to a roster of specialist agents. Each turn produces a session directory conta
• src/retrieval/brainIndex.ts — referenced by 12 files · Brain Index — persistent, mtime-keyed tokenized cache of the Second Brain RAG 검색은 매 질의마다 브레인의 모든 .md 파일을 읽고 토크나이즈해서 TF-IDF 점수를 계산했습니다 — 파일 수가 많아지면 그게 병목입니다. 이 모듈은 /.astra/brain-index.json 에
• src/integrations/telegram/telegramClient.ts — referenced by 12 files

Modules

src/ — 317 files, ~61,263 lines

Sub-directories

• src/features/ (112) — Generic event-sourced store — append-only .jsonl 파일 1개를 읽고/쓰는 공통 기반. 배경: customers, hire, runway, feedback 4개 store 가 같은
• src/sidebar/ (35) — Brain profile lifecycle 의 pure helpers — sidebarProvider 의 add/edit/delete 흐름에서 modal UI 와 config 쓰기를 제외한 데이터 변환 만 격리. 현
• src/lib/ (33) — Astra Mode Architecture Context Builder. 의도: 사용자가 Astra 자체의 mode 디자인 (Guard vs Multi-Agent 가 별도 모드여야 하는지) 을 묻는 메타 질문에 답할
• src/agent/ (31) — 한·영 깨진 토큰 감지·수리 — 소형 로컬 모델의 토큰 붕괴 보정. 증상: 한국어 단어 중간에 영문 토큰이 섞임 — "덩어리"→"덩ey", "결과적으로"→"결ently". 프롬프트 규칙([출력 위생])으로는 못 막는
• src/intelligence/ (18) — Confidence Engine — 답변 확신도 0~100 결정론적 산출. Self-Evolving OS 마스터 플랜 Phase 2 / Track 1-1. 신뢰 조건 T4 "확신이 없으면 사람에게 묻는다" 의 측정
• src/retrieval/ (18) — Actionability Scoring — 검색 결과를 "현재 작업 상태" 신호로 재가중. 기존 TF-IDF (단어 매칭) + recency (시간) 만으로는 "지금 이 사용자가 하고 있는 작업과 직접 연결 된 문서
• src/core/ (15) — Astra Path Resolver (경로 해결기) Astra의 모든 데이터 파일(.astra 디렉토리)의 경로를 중앙에서 관리합니다. 확장 프로그램의 설치 경로(extensionUri) 기반으로 .astra 디렉토
• src/extension/ (13) — 두뇌(Second Brain) 기본 위치 부트스트랩 — 첫 실행 온보딩. 문제: 두뇌 미설정 시 config 가 ~/.g1nation-brain(숨김 점폴더)로 조용히 폴백했다. - 폴더가 실제로 생성되지 않고, 설
• src/memory/ (9) — Episodic Memory (일화 기억) 과거 대화/회의/결정의 맥락 흐름을 저장합니다. 세션 종료 시 자동으로 에피소드를 요약하여 저장합니다. "왜 이렇게 결정했는지", "어떤 흐름으로 진행했는지" 기록. 저장
• src/docs/ (6) — src Chronicle Records
• src/integrations/ (6) — Per-chat conversation history for the Telegram bot. Why this exists: the previous bot was stateless — every inbound mess
• src/lmstudio/ (4) — 4 files (.ts)

Key files

• src/utils.ts (485 lines)
• src/config.ts (661 lines)
• src/agent.ts (1670 lines)
• src/features/company/types.ts (446 lines) — Type definitions for the 1인 기업 (One-Person Company) mode. The mode turns the user into a virtual CEO that dispatches work to a roster of specialist agents. Each turn produces a session directory conta
• src/core/services.ts (176 lines)
• src/sidebarProvider.ts (3487 lines)
• src/integrations/telegram/telegramClient.ts (154 lines)
• src/agent/actions/types.ts (41 lines)
• src/lib/contextManager.ts (278 lines) — Context Manager (컨텍스트 한계 관리) "context length = 132k" 는 "답변을 132k 토큰까지 생성해도 된다" 가 아닙니다. 시스템 프롬프트 + 대화 기록 + 입력 문서 + 생성될 답변 + 여유분 ≤ context length 이 모듈은 요청을 보내기 전에 입력 토큰을 추정하고, - 동적으로 출력 상한(maxTokens)을 계
• src/retrieval/brainIndex.ts (566 lines) — Brain Index — persistent, mtime-keyed tokenized cache of the Second Brain RAG 검색은 매 질의마다 브레인의 모든 .md 파일을 읽고 토크나이즈해서 TF-IDF 점수를 계산했습니다 — 파일 수가 많아지면 그게 병목입니다. 이 모듈은 /.astra/brain-index.json 에
• src/retrieval/scoring.ts (541 lines) — Scoring Engine — TF-IDF + Bilingual Tokenizer 단순 includes() 키워드 매칭을 넘어서, TF-IDF 가중치 기반의 문서 스코어링을 제공합니다. 한국어/영어 양국어 토크나이저를 포함합니다.
• src/features/company/companyConfig.ts (896 lines) — State + config plumbing for 1인 기업 모드. Two surfaces: - CompanyState (runtime data: enabled flag, company name, which agents are active, per-agent model overrides). Persisted in VS Code's globalState so
• src/lib/paths.ts (151 lines)
• src/skills/agentKnowledgeMap.ts (374 lines)
• src/features/datacollect/slashRouter.ts (201 lines)
• src/retrieval/types.ts (66 lines) — Retrieval Types (검색 결과 통합 타입) 모든 검색 소스(Brain, Memory, Project, Episode)의 결과를 통합 인터페이스로 정의합니다.
• src/intelligence/requirementGraph.ts (273 lines) — Requirement Graph — 업무 유형별 필수 요소 정의 + 감지 + 커버리지 검사. Self-Evolving Digital Employee OS 마스터 플랜(docs/SELFEVOLVINGOSMASTERPLAN.md) Phase 1 / Track 2-1. 신뢰 조건 T3 "품질이 일관적이다 — 필수 요소 누락 없음" 담당. 동작 2단계: 1. In
• src/lib/contextBuilders/promptDetection.ts (107 lines) — 사용자 prompt 의 의도 분류 류 detection helpers. 모두 stateless 정규식 매칭. 옛 코드는 agent.ts 의 private 메서드로 박혀 있었는데, system prompt 빌더 (buildJarvisProjectBriefContext 등) 가 이걸 의존하면서 god-file 안에서 서로 얽힘. 헬퍼만 먼저 떼면 의존 그래프가
• src/memory/types.ts (151 lines) — Memory Type Definitions (메모리 타입 정의) Astra의 5-Layer Cognitive Memory System의 모든 타입을 정의합니다. ① Short-Term ② Long-Term ③ Project ④ Procedural ⑤ Episodic
• src/features/stocks/types.ts (53 lines) — Stocks 모듈 공유 타입. investresults/targetstocks.json 스키마를 그대로 받아서, ConnectAI 의 /.astra/stocks.json 으로 옮긴 뒤 같은 필드명을 유지. 한글 필드명은 사용자의 도메인 데이터라 변경하지 않는다 — 마이그레이션 충돌 회피 + 사용자가 직접 JSON 편집할 때 frictio
• src/retrieval/lessonHelpers.ts (325 lines) — Lesson / Experience Memory — pure helpers (no vscode dependency) "Lesson" = a markdown file in the active brain that captures a past mistake/risk and how to avoid repeating it. Identified by a lessons
• src/intelligence/confidenceEngine.ts (165 lines) — Confidence Engine — 답변 확신도 0~100 결정론적 산출. Self-Evolving OS 마스터 플랜 Phase 2 / Track 1-1. 신뢰 조건 T4 "확신이 없으면 사람에게 묻는다" 의 측정 기반 — Escalation Engine 의 입력. 설계 원칙 (termValidator 와 동일): LLM 호출 없음. 검색 그라운딩 신호(턴
• src/intelligence/reflectionStore.ts (162 lines) — Reflection Store — 업무 turn 회고 기록 + Failure Pattern 집계. Self-Evolving OS 마스터 플랜 Phase 1 / Track 2-4 (Reflection Engine v1) + Phase 3 / Track 3-6 (Failure Pattern DB v1 시드). 신뢰 조건 T5 "같은 실수를 반복하지 않는다" 의
• src/extension/telegramCommands.ts (103 lines)
• src/security.ts (159 lines)

media/ — 6 files, ~7,799 lines

Key files

• media/sidebar.css (2114 lines) — Stylesheet
• media/sidebar.js (3947 lines)
• media/sidebar.html (539 lines) — Astra
• media/settings-panel.html (440 lines) — Astra Settings
• media/settings-panel.js (505 lines)
• media/settings-panel.css (254 lines) — Stylesheet

tests/ — 58 files, ~8,276 lines

Depends on: src/

Sub-directories

• tests/helpers/ (1) — MockLLMClient — IAIService 의 Mock 구현체. 의도: 회사 모드 dispatcher / ChunkedWriter / ceoPlanner 등 LLM 을 호출하는 코드 경로를 CI 환경에서도 테스
• tests/integration/ (1) — MockLLMClient 자체의 sanity test. 이게 통과하면 dispatcher / ceoPlanner / ChunkedWriter 등 IAIService 를 받는 코드가 실제 LLM 없이 단위 / inte
• tests/mocks/ (1) — 1 files (.js)

Key files

• tests/helpers/mockLLMClient.ts (112 lines) — MockLLMClient — IAIService 의 Mock 구현체. 의도: 회사 모드 dispatcher / ChunkedWriter / ceoPlanner 등 LLM 을 호출하는 코드 경로를 CI 환경에서도 테스트 가능하게. 실제 Ollama / LM Studio 없이도 응답을 미리 정의하거나 동적으로 생성 가능. 사용 예: const ai = new
• tests/agentEngine.test.ts (413 lines) — AgentEngine Tests — Chunked Writer Architecture 예전 buildup(planner → researcher → reflector → writer → synthesizer)을 단일 ChunkedWriter 의 outline → section[N] → polish 로 교체한 뒤의 회귀 테스트. 다루는 범위: 1. ErrorC
• tests/lmStudioLifecycle.test.ts (330 lines) — Unit tests for ModelLifecycleManager. Strategy: inject mock ILMStudioClient and a simple in-memory IActivityTracker. No real LM Studio or SDK is touched — the manager file does not import the SDK dire
• tests/localPathPreflight.test.ts (520 lines)
• tests/telegramBot.test.ts (363 lines) — Unit tests for TelegramBot + truncateForTelegram. Strategy: - TelegramBot is driven by an injected ITelegramClient stub. We script getUpdates to return queued batches and assert that: - the offset cur
• tests/criticReflectionEval.test.ts (200 lines) — Critic Agent / Reflection Store / Task Eval Harness (Self-Evolving OS P1 잔여 + P3) 테스트.
• tests/lmStudioStreamer.test.ts (222 lines) — Unit tests for LMStudioStreamer. Strategy: inject a fake ILMStudioClient that returns a fake model handle whose respond() yields a controllable async iterable. No real SDK or WebSocket touched.
• tests/secondBrainTrace.test.ts (407 lines)
• tests/approvalQueue.test.ts (164 lines) — Unit tests for ApprovalQueue. Strategy: drive enqueue → approve / reject / clear / pre-empt directly, confirm the onChange event fires at the right moments and callbacks fire exactly once.
• tests/confidenceEngine.test.ts (175 lines) — Confidence Engine + Escalation Engine (Self-Evolving OS Phase 2) 단위 테스트. 순수 함수만 검증 — vscode 의존 없음.
• tests/correctionLoop.test.ts (158 lines) — Correction Loop 단위 테스트 — 순수 로직 (감지·프로필·레슨·큐 등록·영속화). LLM 의존 부분(classifyCorrection)은 엔드포인트 실패 → 휴리스틱 fallback 경로만 검증.
• tests/knowledgeOps.test.ts (174 lines) — Knowledge Validation / Belief Revision / Decay / Debt (Self-Evolving OS Phase 4 — 지식 운영) 테스트.
• tests/meetRegistration.test.ts (110 lines) — /meet 확신 게이트 — 분류·confirm 파싱·날짜 정규화 테스트. 정책: 확정+기한만 자동, 진행미정/기한미정/조건부는 보류, 반복은 첫 1회, 과거 날짜는 등록하되 완료확인 표기, 기한 해석 불가 확정건은 보류(추측 등록 금지).
• tests/needEngineQueue.test.ts (159 lines) — Gap Detector / Need Engine / Knowledge Inventory / Learning Queue (Self-Evolving OS Phase 3 — 성장 루프 코어) 테스트.
• tests/projectScaffolder.test.ts (135 lines) — Unit tests for FileSystemProjectScaffolder. Drives against a real temp directory so end-to-end file IO + path-traversal defenses are exercised.
• tests/requirementGraph.test.ts (126 lines) — Requirement Graph (Self-Evolving OS Phase 1 / Track 2-1) 단위 테스트. 순수 함수만 검증 — vscode 의존 없음.
• tests/researchSkill.test.ts (122 lines) — Research Agent / Skill Score / Success Pattern DB (Self-Evolving OS Phase 6) 테스트.
• tests/resilience_stress.test.ts (197 lines) — Resilience & Boundary Stress Test Suite (v2.77.3) 이 테스트는 ConnectAI 엔진이 극한의 환경(인증 실패, 네트워크 차단, 타임아웃 등)에서 얼마나 안정적으로 복구되고, 신뢰성 지표(Resilience Metrics)를 정확히 기록하는지 검증합니다.
• tests/retrievalEvalEmbedding.test.ts (106 lines) — 하이브리드(sparse+dense) 검색 측정 — 청크 TF-IDF vs 청크+임베딩 (alpha sweep). 평소 테스트 런에서는 skip (실제 두뇌 + 로컬 임베딩 서버 필요). 수동 실행: ASTRAEVALBRAIN="E:/Wiki/2nd/10Wiki/Topics" \ ASTRAEVALEMBEDMODEL="text-embedding-nomic-em
• tests/skillInjectionService.test.ts (172 lines) — Unit tests for FileSystemSkillInjectionService. Strategy: drive the service against a real temp directory so path-traversal defenses and writeFileSync paths are exercised end-to-end. The service accep
• tests/sleepDigest.test.ts (101 lines) — Sleep-time 사전 소화 — 순수 로직 테스트 (대상 선정·노후화 판정·노트 형식). LLM 호출(runSleepDigestOnce)은 제외 — 통합 검증은 수동 명령으로.
• tests/stocksCriteria.test.ts (129 lines) — criteriaEval — /stocks judge 결정론 평가기 테스트. 픽스처는 옛 LLM 프롬프트에 명시돼 있던 사용자의 실제 분류 예시 3종 (마녀공장/기가비스/엔켐) — 코드 판정이 사용자 패턴과 일치해야 한다.
• tests/alignmentResearch.test.ts (208 lines)
• tests/conflictCheck.test.ts (65 lines) — Schedule Conflict Check (Self-Evolving OS Track 6-2/6-3) 테스트.
• tests/dataProcessor.test.ts (87 lines) — /

core_py/ — 6 files, ~409 lines

Key files

• core_py/events.py (64 lines)
• core_py/inference.py (91 lines)
• core_py/loader.py (61 lines)
• core_py/monitoring.py (56 lines)
• core_py/optimizer.py (55 lines)
• core_py/queue_worker.py (82 lines)

docs/ — 173 files, ~5,829 lines

Sub-directories

• docs/records/ (157) — Astra Project Chronicle Records
• docs/docs/ (5) — docs Chronicle Records
• docs/plans/ (2) — Alignment Self-Learning 개선 계획 (v2 — 적대적 리뷰 반영)

Key files

• docs/TELEGRAM_REMOTE_EXECUTION_PLAN.md (452 lines) — Telegram Remote Execution 기획서
• docs/records/ConnectAI/timeline.md (422 lines) — Project Timeline
• docs/AgentEngine_Architecture.md (314 lines) — AgentEngine Architecture Document
• docs/SELF_EVOLVING_OS_MASTER_PLAN.md (275 lines) — ASTRA Self-Evolving Digital Employee OS — 마스터 개발 계획 v1.1
• docs/ASTRA_OFFICE_REFACTOR.md (198 lines) — Astra Office Refactor — Design Doc
• docs/EXPERIENCE_MEMORY_PLAN.md (122 lines) — Experience Memory (Mistake / Lesson Loop) — Implementation Plan
• docs/plans/alignment-self-learning-plan.md (194 lines) — Alignment Self-Learning 개선 계획 (v2 — 적대적 리뷰 반영)
• docs/plans/web-fetch-and-mode-parity-plan.md (102 lines) — 웹 접근 + 모드 동등성 수정 계획 (v2 — 적대적 리뷰 + 재검증 반영)
• docs/records/ConnectAI/development/2026-05-02_connectai_project_knowledge_overview.md (121 lines) — Astra Project Knowledge Overview
• docs/records/ConnectAI/development/2026-05-03_connectai_project_knowledge_overview.md (121 lines) — Astra Project Knowledge Overview
• docs/Advanced_Features_Implementation_Guide.md (40 lines) — Advanced Features Implementation Guide
• docs/PROJECT_CHRONICLE_GUARD_ROADMAP.md (43 lines) — Project Chronicle Guard: Search Engine Roadmap
• docs/UX_UI_Consistency_Guidelines.md (44 lines) — UX/UI Consistency Guidelines
• docs/docs/records/docs/README.md (18 lines) — docs Chronicle Records
• docs/docs/records/docs/bugs/BUG-0001-viewed-integration-retrieval-test-ts-1-59-integration-retrie.md (16 lines) — Bug: Viewed integrationretrieval.test.ts:1-59 integrationretrieval.test.ts를 통해 ...
• docs/docs/records/docs/chronicle.config.json (11 lines) — JSON configuration
• docs/docs/records/docs/project-profile.md (31 lines) — Project Profile
• docs/docs/records/docs/timeline.md (7 lines) — Project Timeline
• docs/records/ConnectAI/README.md (18 lines) — Astra Project Chronicle Records
• docs/records/ConnectAI/bugs/BUG-0001-volumes-data-project-antigravity-connectai-프로젝트-코드-리뷰-해줄-수-있.md (16 lines) — Bug: /Volumes/Data/project/Antigravity/ConnectAI 프로젝트 코드 리뷰 해줄 수 있어? 개선할 부분이 있는지, 그러고...
• docs/records/ConnectAI/bugs/BUG-0002-지금-내가-분석-요청하고-너가-답을-줄때-아래-템플릿에-맞춰-답을-써주고-있는데-개선-포인트가-있는지-확인해.md (16 lines) — Bug: 지금 내가 분석 요청하고 너가 답을 줄때 아래 템플릿에 맞춰 답을 써주고 있는데, 개선 포인트가 있는지 확인해줘. ## 내가 보는 위험 가장 큰...
• docs/records/ConnectAI/bugs/BUG-0003-volumes-data-project-antigravity-connectai-내-질문에-대한-답변이-잘-정리.md (16 lines) — Bug: /Volumes/Data/project/Antigravity/ConnectAI 내 질문에 대한 답변이 잘 정리되서 알려주긴 하는데 focused...
• docs/records/ConnectAI/bugs/BUG-0004-volumes-data-project-antigravity-connectai-내-질문에-대한-답변이-잘-정리.md (16 lines) — Bug: /Volumes/Data/project/Antigravity/ConnectAI 내 질문에 대한 답변이 잘 정리되서 알려주긴 하는데 focused...
• docs/records/ConnectAI/bugs/BUG-0005-다시한번-답줘-volumes-data-project-antigravity-connectai-내-질문에-대한-.md (16 lines) — Bug: 다시한번 답줘. /Volumes/Data/project/Antigravity/ConnectAI 내 질문에 대한 답변이 잘 정리되서 알려주긴 하는...
• docs/records/ConnectAI/bugs/BUG-0006-volumes-data-project-antigravity-connectai-내-질문에-대한-답변이-잘-정리.md (16 lines) — Bug: /Volumes/Data/project/Antigravity/ConnectAI 내 질문에 대한 답변이 잘 정리되서 알려주긴 하는데 focused...

VS Code Extension Surface

• Extension ID: g1nation.astra
• Activation events: onStartupFinished
• Commands (39):
  • g1nation.newChat — Astra: New Chat
  • g1nation.eval.retrieval — Astra: 검색 평가 실행 (recall@k / MRR)
  • g1nation.eval.tasks — Astra: 업무 평가 실행 (회의록 골든셋)
  • g1nation.growth.report — Astra: 성장 리포트 (Reflection 추이)
  • g1nation.growth.learningQueue — Astra: 학습 큐 갱신 (Need Engine)
  • g1nation.knowledge.decayAudit — Astra: 지식 노후 점검 (Knowledge Decay)
  • g1nation.research.runQueue — Astra: 학습 실행 (Research Agent — 승인된 큐 항목)
  • g1nation.growthCycle.runNow — Astra: 주간 성장 사이클 지금 실행 (평가→학습큐→노후점검→승인분 실행)
  • g1nation.embeddings.backfill — Astra: 두뇌 임베딩 전체 색인
  • g1nation.sleepDigest.runNow — Astra: 지식 사전 소화 지금 실행 (Sleep-time Digest)
  • g1nation.conflictScan.runNow — Astra: 지식 충돌 스캔 지금 실행 (신규 문서 ↔ 기존 지식)
  • g1nation.exportChat — Astra: Export Chat as Markdown
  • g1nation.explainSelection — Astra: Explain Selected Code
  • g1nation.focusChat — Astra: Focus Chat Input
  • g1nation.showBrainNetwork — Astra: Show Brain Topology
  • g1nation.approval.focus — Astra: Focus Approval Panel
  • g1nation.scaffoldProject — Astra: Scaffold New Project
  • g1nation.telegram.setBotToken — Astra: Set Telegram Bot Token
  • g1nation.telegram.clearBotToken — Astra: Clear Telegram Bot Token
  • g1nation.telegram.testConnection — Astra: Test Telegram Connection
  • g1nation.settings.focus — Astra: Open Settings Panel
  • g1nation.skills.editKnowledgeMap — Astra: Edit Agent ↔ Knowledge Map
  • g1nation.openChat — Astra: Open Chat (Editor Column)
  • g1nation.setupDatacollect — Astra: Setup Datacollect Dependencies (yt-dlp, youtube-transcript-api)
  • g1nation.lesson.create — Astra: New Lesson (Experience Memory)
  • g1nation.lesson.fromConversation — Astra: New Lesson from Current Conversation
  • g1nation.lesson.manage — Astra: Browse / Manage Lessons
  • g1nation.architecture.refresh — Astra: Refresh Project Architecture Context
  • g1nation.architecture.detach — Astra: Detach Project Architecture Context
  • g1nation.architecture.attach — Astra: Attach Project Architecture Context
  • g1nation.architecture.open — Astra: Open Project Architecture Doc
  • g1nation.company.toggle — Astra: Toggle 1인 기업 Mode
  • g1nation.company.manage — Astra: Manage 1인 기업 Agents
  • g1nation.company.openSessions — Astra: Open 1인 기업 Sessions Folder
  • g1nation.company.pixelOffice.open — Astra: Open Pixel Office (Full Screen)
  • g1nation.calendar.connect — Astra: Google Calendar (iCal) 연결 📅
  • g1nation.calendar.refresh — Astra: Google Calendar 새로고침 📅
  • g1nation.calendar.connectOAuth — Astra: Google Calendar OAuth 연결 (쓰기) 🔐
  • g1nation.devilAgent.toggle — Astra: Toggle Devil Agent 🎭
• Configuration (149 settings):
  • g1nation.multiAgentEnabled (boolean) (default: false) — Enable Multi-Agent Workflow (Planner -> Researcher -> Writer) for complex tasks.
  • g1nation.datacollectBridgeTarget (string) (default: "local")
  • g1nation.datacollectBridgeUrl (string) (default: "http://127.0.0.1:3002") — [local 타깃] Wiki/Datacollect MCP Bridge URL. /benchmark, /youtube, /wikify chat slash commands route here. The Bridge must be running (npm run bridge in the Datacollect project).
  • g1nation.datacollectBridgeNasUrl (string) (default: "")
  • g1nation.datacollectBridgeNasToken (string) (default: "")
  • g1nation.datacollectSavePath (string) (default: "")
  • g1nation.datacollectCrawlDepth (number) (default: 1)
  • g1nation.datacollectMaxPages (number) (default: 8)
  • g1nation.datacollectSynthesisTemperature (number) (default: 0.1)
  • g1nation.chatTemperature (number) (default: 0.3)
  • g1nation.meetUsesTasks (boolean) (default: true)
  • g1nation.meetUsesCalendar (boolean) (default: false)
  • g1nation.meetVerifyPass (boolean) (default: false)
  • g1nation.dailyBriefing.enabled (boolean) (default: true)
  • g1nation.dailyBriefing.time (string) (default: "09:30")
  • g1nation.sleepDigest.enabled (boolean) (default: true)
  • g1nation.sleepDigest.time (string) (default: "03:00")
  • g1nation.growthCycle.enabled (boolean) (default: true)
  • g1nation.growthCycle.day (number) (default: 0)
  • g1nation.growthCycle.time (string) (default: "20:00")
  • g1nation.growthCycle.autoRunApproved (boolean) (default: true)
  • g1nation.teamVoiceGuide (string) (default: "")
  • g1nation.memoryEnabled (boolean) (default: true) — Enable layered memory injection before each model response.
  • g1nation.memoryShortTermMessages (number) (default: 8) — Number of recent conversation messages included as short-term memory.
  • g1nation.memoryMediumTermSessions (number) (default: 5) — Number of recent saved chat sessions included as medium-term memory.
  • g1nation.memoryLongTermFiles (number) (default: 6) — Number of relevant Second Brain markdown files included as long-term memory.
  • g1nation.ollamaUrl (string) (default: "http://127.0.0.1:11434") — Base URL for Ollama or LM Studio. Default: http://127.0.0.1:11434
  • g1nation.defaultModel (string) (default: "gemma4:e2b") — Default model name to use for chat requests.
  • g1nation.requestTimeout (number) (default: 300) — Request timeout in seconds. Default: 300
  • g1nation.contextLength (number) (default: 32768) — Model context window in tokens (prompt + generation combined). Set this to the value your loaded model is actually running with in LM Studio / Ollama. Astra budgets prompt and output against this so i
  • g1nation.maxOutputTokens (number) (default: 4096) — Upper bound on tokens generated per response. The effective limit is reduced automatically when the prompt is large so input + output stays within g1nation.contextLength. Default: 4096
  • g1nation.contextSafetyMargin (number) (default: 2048) — Tokens kept free as a safety buffer for token-count estimation error. Default: 2048
  • g1nation.contextOverflowPolicy (string) (default: "stopAtLimit") — Fallback behavior (LM Studio) if the prompt still exceeds the context window after Astra's own budgeting. 'stopAtLimit' fails clearly so you notice; 'truncateMiddle'/'rollingWindow' drop content silen
  • g1nation.autoCompactHistory (boolean) (default: true) — Automatically drop the oldest conversation messages from the request when the prompt would exceed the context budget (the on-screen chat history is unaffected). Default: true
  • g1nation.smallModelContextCap (number) (default: 0) — Optional safety knob, OFF by default (0). Some very small models (≤3B) emit an empty/EOS response when given a prompt near their context window even though it nominally fits. If you observe that with
  • g1nation.autoContinueOnOutputLimit (boolean) (default: true) — When a reply is cut off because it hit the output-token limit, Astra continues it internally (compressed request — original question + the answer so far, not the whole context again) and shows one mer
  • g1nation.maxAutoContinuations (number) (default: 4) — Maximum number of automatic continuation rounds per reply (prevents runaway loops). Raise it (e.g. 5–6) for long-form answers on slow local models; set 0 to disable auto-continuation. Default: 4
  • g1nation.finalOnlyRetryOnThoughtLeak (boolean) (default: true) — If the model emits only hidden reasoning (, <|channel|>thought, "Thinking Process:" …) and no user-visible answer, Astra silently re-asks it for the final answer only. Hidden reasoning is never
  • g1nation.lmStudio.idleTimeoutMs (number) (default: 300000) — Auto-eject the loaded LM Studio model after this many milliseconds of inactivity. Set to 0 to disable. Default: 300000 (5 minutes).
  • g1nation.lmStudio.autoLoadOnSelect (boolean) (default: true) — Automatically load LM Studio models into memory when selected from the Astra sidebar.
  • g1nation.lmStudio.sampling.topP (number) (default: 0.9) — Nucleus sampling cutoff. Small / quantized models often spew wrong-neighbour tokens (한글 깨짐: 붕괴→붕점) when the tail is wide. Lower (0.8–0.9) tightens; 1.0 disables. Applied to both SDK and REST paths.
  • g1nation.lmStudio.sampling.topK (number) (default: 20) — Top-K sampling cutoff. 0 disables. Default 20 — tighter for small models, raise to 40–80 for large models that already sample well.
  • g1nation.lmStudio.sampling.minP (number) (default: 0.05) — Min-P floor — discards tokens with probability below this fraction of the top token. Good defence against rare-token glitches. 0 disables.
  • g1nation.lmStudio.sampling.repeatPenalty (number) (default: 1.1) — Repeat / frequency penalty to curb stutter (것입니다서입니다…). 1.0 disables. Values 1.05–1.2 are typical.
  • g1nation.lmStudio.statsInBudget (boolean) (default: true) — Show token/s and time-to-first-token from LM Studio prediction stats in the context-budget badge after each turn (SDK path only).
  • g1nation.lmStudio.draftModel (string) (default: "") — [Speculative decoding] LM Studio model key of a small draft model (e.g. 'gemma-2b-it') used to accelerate the main model. Empty disables. 1.5–3x throughput on large models. The draft must be downloade
  • g1nation.lmStudio.load.flashAttention (boolean) (default: true) — [Load option] Enable Flash Attention when loading models. Faster generation + lower memory on compatible hardware, especially helpful for long contexts. Default: true.
  • g1nation.lmStudio.load.gpuOffloadRatio (string) (default: "max") — [Load option] How much of the model to offload to GPU. 'max' = all (default), 'off' = CPU only, or a number 0–1 (e.g. '0.5' = half). Numeric strings are parsed.
  • g1nation.lmStudio.load.offloadKVCacheToGpu (boolean) (default: true) — [Load option] Keep KV cache on GPU memory. Faster but requires VRAM headroom. Default: true.
  • g1nation.lmStudio.load.keepModelInMemory (boolean) (default: true) — [Load option] Prevent the model from being swapped out of system memory. Improves interactive responsiveness; raises RAM use. Default: true.
  • g1nation.lmStudio.load.useFp16ForKVCache (boolean) (default: false) — [Load option] Store KV cache in FP16 (halves cache memory). Tiny quality impact for most models — try if you run out of VRAM at long contexts. Default: false.
  • g1nation.lmStudio.load.evalBatchSize (number) (default: 0) — [Load option] Token batch size during evaluation. 0 = engine default. Higher (512–1024) improves prefill speed on GPU at the cost of memory.
  • g1nation.localBrainPath (string) (default: "") — Folder path for your local Second Brain knowledge base. Leave empty to use the default folder.
  • g1nation.brainProfiles (array) (default: []) — Multiple brain profiles. Each item supports id, name, localBrainPath, secondBrainRepo, and description.
  • g1nation.activeBrainId (string) (default: "") — Active brain profile id used for the current chat context.
  • g1nation.secondBrainRepo (string) (default: "") — Optional GitHub repository URL used for Second Brain sync.
  • g1nation.autoPushBrain (boolean) (default: false) — Automatically commit and push Second Brain changes after updates.
  • g1nation.maxContextSize (number) (default: 32000) — Maximum character count for active file context. Default: 32000
  • g1nation.maxAutoSteps (number) (default: 50) — Maximum autonomous steps the agent can take per request. Default: 50
  • g1nation.dryRun (boolean) (default: false) — If enabled, the agent will ask for approval before committing any file changes.
  • …and 89 more

Dependencies

• Runtime (2): @lmstudio/sdk, pdf-parse
• Dev (8): @types/jest, @types/node, @types/vscode, @vercel/ncc, esbuild, jest, ts-jest, typescript

README Excerpt

Pulled from the project root README — first ~2 KB.

Astra (by g1nation)

Astra는 Antigravity 및 VS Code 환경에서 작동하는 대표님 전용 **지능형 운영 레이어(Personal Intelligence Layer)**입니다. 단순한 명령 수행을 넘어, 프로젝트의 맥락과 대표님의 의사결정 패턴을 학습하여 최적의 전략적 조언을 제공하는 독립적인 인지 파트너입니다.

🌌 Antigravity & VS Code Unified Assistant

Astra는 범용 AI와 달리 특정 플랫폼에 종속되지 않으며, Antigravity 워크스페이스의 깊은 맥락과 VS Code의 강력한 개발 도구를 하나로 연결합니다.

1. 전용 지능형 판단 체계 (Personal Cognition Layer)

v4.0 운영 정책이 코어에 이식되어 데이터의 신뢰도를 대표님의 기준에 맞춰 스스로 평가합니다. 상충되는 정보 발견 시 즉각적인 **[CONFLICT WARNING]**을 통해 객관적인 판단 근거를 제시합니다.

2. 고밀도 전략 지식망 (Strategic Knowledge Hub)

대표님의 Second Brain과 Antigravity 내의 모든 지식을 온톨로지 기반으로 구조화합니다. 비즈니스 전략, 기술 아키텍처, 리스크 관리가 하나로 통합된 지식 그래프를 통해 추론의 깊이를 보장합니다.

3. 선제적 파트너십 (Proactive Partnership)

작업이 완료된 후, 대표님이 다음에 내려야 할 **전략적 의사결정 포크(Decision Forks)**를 선제적으로 제안합니다. 사용자의 명령을 기다리지 않고, 프로젝트의 흐름을 먼저 읽고 길을 제시합니다.

🛠️ 주요 기능 및 권한

Astra는 대표님의 명시적인 승인 하에 로컬 시스템의 강력한 제어 권한을 행사하여 생산성을 극대화합니다.

작업 범주	설명
플랫폼 최적화	Antigravity 워크스페이스와 VS Code 사이의 유기적인 맥락 전환 및 동기화를 지원합니다.
자율 워크플로우	다중 에이전트 협업을 통해 복잡한 비즈니스 요구사항을 즉시 실행 가능한 단계별 계획으로 분해합니다.
지식 자산화	흩어진 정보들을 P-Reinforce v3.0 표준에 맞게 위키화하여 영구적인 지식 자산으로 전환합니다.
보안 및 프라이버시	100% 로컬 환경에서 작동하여 대표님의 소중한 데이터가 외부로 유출되지 않음을 보장합니다.

🚀 설치 및 시작하기

패키지 설치

1. g1nation에서 배포된 최신 v2.65.0 VSIX 파일을 확보합니다.
2. VS Code 명령 팔레트(Cmd+Shift+P)에서 Extensions: Install from VSIX를 선택하여 설치합니다.
3. Antigravity 환경과 연동하여 나만의 지능형 레이어를 활성화합니다.

---

Designed for High-Performance Decision Making. Copyright (C) g1nation. All rights reserved.

Last auto-scan: 2026-06-12T14:30:58.311Z · signature 314f69

Purpose

Astra (g1nation) — 로컬 LLM 기반의 개인 지능형 운영 레이어. VS Code 확장으로 LM Studio / Ollama 와 채팅하면서 프로젝트 컨텍스트 / 메모리 / 작업 자동화 를 단일 UI 에서 처리. 100% 로컬 (cloud LLM 은 opt-in 라우팅).

Top-level 동작 흐름

User ↘                                              ↗ webview (chat UI)
       sidebar.html / sidebar.js  ←——  chatHandlers
                        │                    │
                        │                    ├─ slash router (/research /youtube /stocks 등)
                        │                    │
                        ↓                    ↓
              SidebarChatProvider ──→  AgentExecutor (agent.ts, 1,529 lines)
                                              │
                       ┌──────────────────────┴──────────────────────┐
                       ↓                      ↓                      ↓
              handlePrompt phases      executeActions (8 그룹)   LLM I/O (agent/llm)
              (agent/handlePrompt)     (agent/actions)            createStreamingRequest
                                                                  streamChatOnce
                                                                  callNonStreaming
                       │
                       ↓
              [PRIOR TURN CONCLUSION]   ← 대화 연속성 anchor
              + Mode Bridge + Context Blocks + System Prompt + Budget

핵심 디자인 패턴

1. God-file 분해 (R50–R59, 2026-05). agent.ts 2731→1529 lines, extension.ts 1145→349 lines. 25개 신규 모듈 (src/agent/**, src/extension/**). 패턴:

• Pure free functions + deps object — this.X 의존성을 callback dep 으로 명시 (e.g. callNonStreaming(deps, params))
• Thin wrappers on the class — AgentExecutor 의 메서드는 deps 묶어서 free function 으로 위임. 외부 caller signature 보존.
• Action handlers (15+ tags) 는 HandlerContext 공유 ctx 객체로 통일 — 8개 그룹 (file/run/list/brain/calendar/sheets/tasks).
• handlePrompt 1,100줄 → 7 phase 모듈 (buildTurnContextBlocks / buildModeBridgeContext / build{Agent,Astra}ModeSystemPrompt / computeBudgetedRequest / processFinalAnswer / applyAutoContinuation).

2. 대화 연속성 (v2.2.150~157). 작은 로컬 모델 (gemma 4B 등) 이 follow-up 정정/보강 turn 에 echo/parrot 하는 문제 해결:

• [PRIOR TURN CONCLUSION] block — 직전 assistant 답변의 첫 문장을 system prompt 에 anchor
• [CONVERSATION CONTINUITY & REVISION] rule — echo 금지, 최소 3-5 문장 구조 강제
• Thin follow-up classifier (isThinFollowUp) — 짧은 follow-up turn 에서 Guard 의 4-section boilerplate (## 요청 요약 등) suppress
• Slash 결과 chatHistory mirror — slash 명령 결과를 webview 와 함께 agent.chatHistory 에 push (capture wrapper). 다음 turn LLM 이 직전 명령 출력 인식. getHistory() 가 filtered copy 반환하는 silent bug fix 포함.

3. Slash 명령 시스템. src/features/datacollect/slashRouter.ts 의 registry. 등록된 명령: /research /benchmark /youtube /blog /wikify /meet /stocks. webview 의 / 자동완성 dropdown 으로 노출. 각 명령은 (arg, view, context) => Promise<boolean> 시그니처 통일.

4. Stocks feature (v2.2.152~158). 새 도메인 — 한국 주식 모니터링/발굴:

• .astra/stocks.json 저장소 (workspace root)
• Yahoo Finance 현재가 갱신, g1nation.stocks.spreadsheetId 로 Google Sheets 동기화 (calendar OAuth scope 재사용)
• KST 09:00 / 15:00 watcher 자동 트리거 → Telegram 보고서
• 8 키워드 자동 필터 (ROE/성장성/유동성/수익성/영업효율/기술력/안정성/PBR) — llmJudge.ts 와 stockDiscovery.ts 가 동일 임계값 공유
• /stocks discover — Naver 비공식 JSON API (m.stock.naver.com/api/...) 로 시가총액 페이지 + 펀더멘털 (ROE/영업이익률/유보율) 크롤 후 8 키워드 필터 → 통과한 종목 → LLM Top 5 매력도 분석 → Telegram 자동 발송
• /stocks judge <symbol> — LLM 으로 4-criteria 필터 자동 판정 + JSON 업데이트

5. 5-Layer Cognitive Memory. src/memory/:

• Short-Term (대화 단기) / Long-Term (Second Brain) / Project (프로젝트 기록) / Procedural (스킬) / Episodic (세션 요약)
• TF-IDF + 한/영 이중 토크나이저 (src/retrieval/scoring.ts)
• 옵션: embedding hybrid (g1nation.embeddingModel 설정 시 dense+sparse blend)
• Knowledge Mix policy — Second Brain 의존도 (0-100) 사용자 조절 가능

6. 1인 기업 모드 (Company Mode). src/features/company/:

• 가상 회사 — 사용자 = CEO, 에이전트 = 직원. 명령 분류기 → dispatcher → 직군별 specialist → CEO 검수 → 산출물
• 각 turn 은 session directory 에 _brief.md / _report.md / 에이전트별 산출물 영구 기록
• LLM 호출 인터페이스: IAIService.chat({system, user}) (mock 가능 → tests/helpers/mockLLMClient.ts)

7. Context budget (src/lib/contextManager.ts). 매 turn 마다 system + history + input 의 토큰 예산 계산, output 상한 동적 조절. smallModelContextCap 옵션으로 ≤3B 모델의 EOS-first 환각 회피.

8. Cloud LLM routing (src/features/providers/). openrouter: / anthropic: / gemini: prefix 가 model id 에 있으면 자동 cloud SDK 라우팅. SSE 응답은 OpenAI 호환 형식으로 normalize → 로컬 path 와 동일 consumer.

진입 파일 (학습 순서)

1. src/extension.ts — activation, 모든 wiring (사이드바 / approval / telegram / stocks watcher / slash router)
2. src/sidebarProvider.ts — webview lifecycle, message dispatch (chatHandlers / settings)
3. src/agent.ts — AgentExecutor (thin wrappers + chatHistory 상태)
4. src/agent/handlePrompt/ — 한 turn 의 7-phase pipeline
5. src/features/stocks/ — 최근 새 도메인 사례 (slash + watcher + LLM + Telegram 통합)

활성 작업 (2026-05)

• 완료: god-file 분해 R50–R59, Stocks feature 전체 파이프라인, 대화 연속성 fix
• 진행 가능 (paused): /stocks discover 의 시가총액 범위 자동 유도 (사용자 드롭 요청)
• 남은 큰 영역: slashRouter.ts (1,127 lines), dispatcher.ts (1,364 lines), sidebarProvider.ts (3,194 lines) — 별도 god-file 분해 대상이나 ROI 검토 필요