# ConnectAI — Project Architecture Context

<!-- ASTRA:AUTO-START -->

## Snapshot
- **Workspace**: `ConnectAI` `v2.0.2` _(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**: 184 source files, ~31,651 lines across 5 top-level modules.

## Last Refresh
- **Time**: 2026-05-13T13:48:21.458Z
- **Files newly analysed**: 3
- **Files reused from cache**: 181

## Directory Map
```mermaid
mindmap
  root((ConnectAI))
    src/
      core/
      features/
      memory/
      retrieval/
      docs/
      lib/
    media/
    tests/
      mocks/
    core_py/
    docs/
      records/
      docs/
```

## Module Dependencies
> Arrows: which top-level module imports from which.
```mermaid
flowchart LR
    src["src/<br/>85 files"]
    media["media/<br/>6 files"]
    tests["tests/<br/>27 files"]
    core_py["core_py/<br/>6 files"]
    docs["docs/<br/>60 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 **37** files
- `src/config.ts` — referenced by **11** files
- `src/lib/paths.ts` — referenced by **10** files
- `src/lib/engine.ts` — referenced by **6** files
- `src/sidebarProvider.ts` — referenced by **6** files
- `src/retrieval/scoring.ts` — referenced by **6** files · Scoring Engine — TF-IDF + Bilingual Tokenizer 단순 includes() 키워드 매칭을 넘어서, TF-IDF 가중치 기반의 문서 스코어링을 제공합니다. 한국어/영어 양국어 토크나이저를 포함합니다.
- `src/memory/types.ts` — referenced by **6** files · Memory Type Definitions (메모리 타입 정의) Astra의 5-Layer Cognitive Memory System의 모든 타입을 정의합니다. ① Short-Term ② Long-Term ③ Project ④ Procedural ⑤ Episodic
- `src/retrieval/lessonHelpers.ts` — referenced by **5** files · 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

## Modules

### `src/` — 85 files, ~20,591 lines

**Sub-directories**
- `src/core/` (15) — Astra Path Resolver (경로 해결기) Astra의 모든 데이터 파일(.astra 디렉토리)의 경로를 중앙에서 관리합니다. 확장 프로그램의 설치 경로(extensionUri) 기반으로 .astra 디렉토
- `src/features/` (14) — Project Architecture Context (Feature 2) Builds a markdown document that captures the durable facts about a project — it
- `src/memory/` (8) — Episodic Memory (일화 기억) 과거 대화/회의/결정의 맥락 흐름을 저장합니다. 세션 종료 시 자동으로 에피소드를 요약하여 저장합니다. "왜 이렇게 결정했는지", "어떤 흐름으로 진행했는지" 기록. 저장 
- `src/retrieval/` (8) — Brain Index — persistent, mtime-keyed tokenized cache of the Second Brain RAG 검색은 매 질의마다 브레인의 모든 .md 파일을 읽고 토크나이즈해서 TF-I
- `src/docs/` (6) — src Chronicle Records
- `src/lib/` (6) — Context Manager (컨텍스트 한계 관리) "context length = 132k" 는 "답변을 132k 토큰까지 생성해도 된다" 가 아닙니다. 시스템 프롬프트 + 대화 기록 + 입력 문서 + 생성될 답변
- `src/lmstudio/` (4) — 4 files (.ts)
- `src/sidebar/` (4) — 4 files (.ts)
- `src/skills/` (4) — 4 files (.ts)
- `src/integrations/` (3) — Subset of the Telegram Bot API types we actually consume. Source: https://core.telegram.org/bots/api Only fields the bot
- `src/agents/` (2) — 2 files (.ts)
- `src/scaffolder/` (2) — Scaffolder template catalog. Templates are pure data — (projectName) => { [relativePath]: contents }. New templates are 

**Key files**
- `src/utils.ts` (268 lines)
- `src/config.ts` (209 lines)
- `src/lib/paths.ts` (151 lines)
- `src/sidebarProvider.ts` (2603 lines)
- `src/memory/types.ts` (126 lines) — Memory Type Definitions (메모리 타입 정의) Astra의 5-Layer Cognitive Memory System의 모든 타입을 정의합니다. ① Short-Term ② Long-Term ③ Project ④ Procedural ⑤ Episodic
- `src/retrieval/scoring.ts` (518 lines) — Scoring Engine — TF-IDF + Bilingual Tokenizer 단순 includes() 키워드 매칭을 넘어서, TF-IDF 가중치 기반의 문서 스코어링을 제공합니다. 한국어/영어 양국어 토크나이저를 포함합니다.
- `src/skills/agentKnowledgeMap.ts` (374 lines)
- `src/agent.ts` (3207 lines)
- `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/lib/engine.ts` (849 lines)
- `src/features/approval/approvalQueue.ts` (129 lines)
- `src/features/projectArchitecture/scanner.ts` (644 lines) — Deep static analyser for the Project Architecture Context generator. Walks the project tree (skipping the usual nodemodules / out / dist noise), pulls the role of each interesting file from its leadin
- `src/lib/contextManager.ts` (275 lines) — Context Manager (컨텍스트 한계 관리) "context length = 132k" 는 "답변을 132k 토큰까지 생성해도 된다" 가 아닙니다. 시스템 프롬프트 + 대화 기록 + 입력 문서 + 생성될 답변 + 여유분 ≤ context length 이 모듈은 요청을 보내기 전에 입력 토큰을 추정하고, - 동적으로 출력 상한(maxTokens)을 계
- `src/core/astraPath.ts` (50 lines) — Astra Path Resolver (경로 해결기) Astra의 모든 데이터 파일(.astra 디렉토리)의 경로를 중앙에서 관리합니다. 확장 프로그램의 설치 경로(extensionUri) 기반으로 .astra 디렉토리를 해결하여, 사용자 프로젝트 루트가 아닌 ConnectAI 패키지 내부에 데이터를 저장합니다. 이 모듈은 AAL(Astra Autonomou
- `src/features/projectChronicle/types.ts` (118 lines)
- `src/integrations/telegram/telegramClient.ts` (154 lines)
- `src/lmstudio/client.ts` (147 lines)
- `src/retrieval/brainIndex.ts` (325 lines) — Brain Index — persistent, mtime-keyed tokenized cache of the Second Brain RAG 검색은 매 질의마다 브레인의 모든 .md 파일을 읽고 토크나이즈해서 TF-IDF 점수를 계산했습니다 — 파일 수가 많아지면 그게 병목입니다. 이 모듈은 <brainPath>/.astra/brain-index.json 에
- `src/extension.ts` (757 lines)
- `src/features/projectArchitecture/index.ts` (515 lines) — Project Architecture Context (Feature 2) Builds a markdown document that captures the durable facts about a project — its purpose, modules, key files, constraints, decisions — so Astra can attach it t
- `src/lmstudio/activityTracker.ts` (19 lines)
- `src/memory/EpisodicMemory.ts` (278 lines) — Episodic Memory (일화 기억) 과거 대화/회의/결정의 맥락 흐름을 저장합니다. 세션 종료 시 자동으로 에피소드를 요약하여 저장합니다. "왜 이렇게 결정했는지", "어떤 흐름으로 진행했는지" 기록. 저장 위치: {brainPath}/memory/episodes/.json
- `src/memory/LongTermMemory.ts` (243 lines) — Long-Term Memory (장기 기억) 사용자의 취향, 프로젝트 목표, 반복 규칙, 과거 결정 사항을 영구적으로 저장하고 관리합니다. 저장 위치: {brainPath}/memory/longterm.json
- `src/memory/ProjectMemory.ts` (212 lines) — Project Memory (프로젝트 기억) 프로젝트별 요구사항, 코드 구조, 아키텍처 결정, 버그 기록 등을 Astra 확장 프로그램 내부에 저장하고 관리합니다. 저장 위치: {ConnectAI}/.astra/projectmemory.json (기존: {projectRoot}/.astra/ → 변경됨)
- `src/retrieval/index.ts` (514 lines) — RetrievalOrchestrator — Unified RAG Pipeline Astra의 모든 검색 소스를 통합 관리하는 오케스트레이터입니다. 검색 흐름: ① Query Planning — 의도 분류 + 검색 전략 결정 ② Parallel Search — Brain + Memory + Project + Episode 동시 검색 ③ Result Fusio

### `media/` — 6 files, ~3,304 lines

**Key files**
- `media/sidebar.css` (987 lines) — Stylesheet
- `media/sidebar.js` (1388 lines)
- `media/settings-panel.css` (210 lines) — Stylesheet
- `media/sidebar.html` (285 lines) — Astra
- `media/settings-panel.html` (164 lines) — Astra Settings
- `media/settings-panel.js` (270 lines)

### `tests/` — 27 files, ~4,802 lines
*Depends on*: `src/`

**Sub-directories**
- `tests/mocks/` (1) — 1 files (.js)

**Key files**
- `tests/agentEngine.test.ts` (646 lines) — AgentEngine Integration Tests & Performance Benchmarks 검증 대상: 1. ErrorClassifier — 오류 유형(Transient/Permanent/Abort) 자동 분류 2. ErrorRecoveryMatrix — 각 규칙이 의도한 대응 전략으로 매핑되는지 검증 3. resilientExecute — 지수 백
- `tests/lmStudioLifecycle.test.ts` (318 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/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/lmStudioStreamer.test.ts` (220 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/localPathPreflight.test.ts` (490 lines)
- `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/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/resilience_stress.test.ts` (183 lines) — Resilience & Boundary Stress Test Suite (v2.77.3) 이 테스트는 ConnectAI 엔진이 극한의 환경(인증 실패, 네트워크 차단, 타임아웃 등)에서 얼마나 안정적으로 복구되고, 신뢰성 지표(Resilience Metrics)를 정확히 기록하는지 검증합니다.
- `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/dataProcessor.test.ts` (87 lines) — / <reference types="jest" />
- `tests/findBrainFilesCache.test.ts` (80 lines) — Unit tests for findBrainFiles TTL cache.
- `tests/paths.test.ts` (84 lines) — Unit tests for the centralized path resolver.
- `tests/systemSpecs.test.ts` (90 lines) — Unit tests for SystemSpecs + HeuristicModelMemoryEstimator. Strategy: - HeuristicModelMemoryEstimator is pure — directly drive it with model ids. - NodeSystemSpecsProvider depends on os. so we test: a
- `tests/transaction.test.ts` (68 lines) — / <reference types="jest" />
- `tests/vulnerability.test.ts` (60 lines) — / <reference types="jest" />
- `tests/brainIndex.test.ts` (107 lines)
- `tests/contextManager.test.ts` (129 lines)
- `tests/lessonHelpers.test.ts` (191 lines)
- `tests/projectChronicle.test.ts` (199 lines)
- `tests/responseRecovery.test.ts` (151 lines)
- `tests/scoring.test.ts` (134 lines)
- `tests/integration_retrieval.test.ts` (91 lines)
- `tests/mocks/vscode.js` (68 lines)
- `tests/projectChronicleGuardPrompt.test.ts` (52 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/` — 60 files, ~2,545 lines

**Sub-directories**
- `docs/records/` (48) — Astra Project Chronicle Records
- `docs/docs/` (5) — docs Chronicle Records

**Key files**
- `docs/TELEGRAM_REMOTE_EXECUTION_PLAN.md` (452 lines) — Telegram Remote Execution 기획서
- `docs/AgentEngine_Architecture.md` (314 lines) — AgentEngine Architecture Document
- `docs/EXPERIENCE_MEMORY_PLAN.md` (122 lines) — Experience Memory (Mistake / Lesson Loop) — Implementation Plan
- `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/records/ConnectAI/timeline.md` (116 lines) — Project Timeline
- `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...
- `docs/records/ConnectAI/bugs/BUG-0007-volumes-data-project-antigravity-connectai-내-질문에-대한-답변이-잘-정리.md` (16 lines) — Bug: /Volumes/Data/project/Antigravity/ConnectAI 내 질문에 대한 답변이 잘 정리되서 알려주긴 하는데 focused...
- `docs/records/ConnectAI/bugs/BUG-0008-volumes-data-project-antigravity-connectai-내-질문에-대한-답변이-잘-정리.md` (16 lines) — Bug: /Volumes/Data/project/Antigravity/ConnectAI 내 질문에 대한 답변이 잘 정리되서 알려주긴 하는데 focused...
- `docs/records/ConnectAI/bugs/BUG-0009-문제점을-읽고-어떻게-개선하는게-최선인지-분석해주면-좋겠어-알겠습니다-지금부터-connectai-프로젝트-에.md` (16 lines) — Bug: 문제점을 읽고 어떻게 개선하는게 최선인지 분석해주면 좋겠어. 알겠습니다. 지금부터 ConnectAI 프로젝트에만 완전히 집중하겠습니다. ...
- `docs/records/ConnectAI/bugs/BUG-0010-문제점을-읽고-어떻게-개선하는게-최선인지-분석해주면-좋겠어-알겠습니다-지금부터-connectai-프로젝트-에.md` (16 lines) — Bug: 문제점을 읽고 어떻게 개선하는게 최선인지 분석해주면 좋겠어. 알겠습니다. 지금부터 ConnectAI 프로젝트에만 완전히 집중하겠습니다. ...

## VS Code Extension Surface
- **Extension ID**: `g1nation.astra`
- **Activation events**: `onStartupFinished`
- **Commands** (19):
  - `g1nation.newChat` — Astra: New Chat
  - `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.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.open` — Astra: Open Project Architecture Doc
- **Configuration** (38 settings):
  - `g1nation.multiAgentEnabled` *(boolean)* _(default: `false`)_ — Enable Multi-Agent Workflow (Planner -> Researcher -> Writer) for complex tasks.
  - `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 (<think>, <|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.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.
  - `g1nation.telegram.enabled` *(boolean)* _(default: `false`)_ — Enable the Telegram bot integration. When on, Astra polls a bot you configure and replies to incoming messages. Off by default — Astra remains 100% local until you opt in.
  - `g1nation.telegram.allowedChatIds` *(array)* _(default: `[]`)_ — Optional allowlist of Telegram chat IDs that may message the bot. When empty, every chat that messages the bot is accepted (use with caution).
  - `g1nation.telegram.defaultAgent` *(string)* _(default: `""`)_ — Agent name (matches an entry in the Agent ↔ Knowledge map) used to scope Second Brain retrieval for Telegram replies. Empty falls back to the map's defaultAgent, then to whole-brain search.
  - `g1nation.telegram.agentByChatId` *(object)* _(default: `{}`)_ — Per-chat override of the Telegram agent. Keys are stringified chat IDs, values are agent names from the knowledge map. Overrides telegram.defaultAgent for the listed chats.
  - `g1nation.telegram.contextChunks` *(number)* _(default: `6`)_ — How many Second Brain excerpts to inject into Telegram replies. Set 0 to disable RAG (plain prompt only).
  - `g1nation.skillKnowledgeMapPath` *(string)* _(default: `""`)_ — Absolute path to the agent ↔ knowledge mapping JSON. When empty, defaults to '<workspace>/.astra/agent-knowledge-map.json'.
  - `g1nation.skillKnowledgeMap` *(object)* _(default: `{}`)_ — Inline fallback for the agent ↔ knowledge mapping. Used only when the JSON file is missing. Shape: { defaultAgent?, agents: [{ name, knowledgeFolders, model?, description? }] }. Folder paths can be ab
  - `g1nation.agentSkillsPath` *(string)* _(default: `""`)_ — Absolute path to the agent skills folder (`.agent/skills/*.md`). When empty, defaults to '<workspace>/.agent/skills'. Use this on Windows or when your skills live outside the workspace.
  - `g1nation.embeddingModel` *(string)* _(default: `""`)_ — Embedding model registered in LM Studio / Ollama (e.g. 'text-embedding-bge-small-en-v1.5', 'nomic-embed-text', 'multilingual-e5-small'). When empty, Astra uses TF-IDF only. When set, the brain is embe
  - `g1nation.embeddingBlendAlpha` *(number)* _(default: `0.5`)_ — Hybrid score blend: 0 = pure TF-IDF (sparse / keyword), 1 = pure embedding cosine (dense / semantic), 0.5 = balanced. Only used when g1nation.embeddingModel is set. Default 0.5.
  - `g1nation.knowledgeMix.secondBrainWeight` *(number)* _(default: `50`)_ — Knowledge Mix (0–100): how heavily the assistant should lean on Second Brain evidence vs. its own general knowledge. 0 = Second Brain disabled (model knowledge only). 50 = balanced (legacy default). 1

## 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-05-13T13:48:21.458Z · signature `fefc8c65`_
<!-- ASTRA:AUTO-END -->

## Purpose
_TODO_