{"id":50734463,"url":"https://github.com/joungminsung/semanticfs","last_synced_at":"2026-06-10T12:02:56.764Z","repository":{"id":347971498,"uuid":"1195917106","full_name":"joungminsung/SemanticFS","owner":"joungminsung","description":"FUSE-based semantic filesystem — access files by meaning, not paths. 자연어로 파일에 접근하는 시맨틱 파일시스템.","archived":false,"fork":false,"pushed_at":"2026-03-30T10:09:23.000Z","size":144,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T10:10:26.221Z","etag":null,"topics":["cli","embeddings","filesystem","fuse","nlp","open-source","rust","semantic-search","sqlite","tree-sitter"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joungminsung.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-30T07:33:14.000Z","updated_at":"2026-03-30T10:09:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/joungminsung/SemanticFS","commit_stats":null,"previous_names":["joungminsung/semanticfs"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/joungminsung/SemanticFS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joungminsung%2FSemanticFS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joungminsung%2FSemanticFS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joungminsung%2FSemanticFS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joungminsung%2FSemanticFS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joungminsung","download_url":"https://codeload.github.com/joungminsung/SemanticFS/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joungminsung%2FSemanticFS/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34151276,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","embeddings","filesystem","fuse","nlp","open-source","rust","semantic-search","sqlite","tree-sitter"],"created_at":"2026-06-10T12:02:55.645Z","updated_at":"2026-06-10T12:02:56.755Z","avatar_url":"https://github.com/joungminsung.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003eSemanticFS\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\n    \u003cstrong\u003eFUSE-based semantic filesystem — access files by meaning, not paths\u003c/strong\u003e\n  \u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e |\n    \u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e |\n    \u003ca href=\"#how-it-works\"\u003eHow It Works\u003c/a\u003e |\n    \u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n---\n\n\u003e **\"폴더 정리는 끝났다. 의미로 찾아라.\"**\n\nSemanticFS는 기존 디렉토리 경로 대신 **자연어**로 파일에 접근할 수 있게 하는 FUSE 기반 파일시스템입니다. 파일은 원본 위치에 그대로 있고, SemanticFS가 그 위에 의미 기반 뷰를 제공합니다.\n\n```bash\ncd /mnt/semantic\n\nls \"React 프로젝트\"\n# users.route.ts    auth.controller.ts    middleware.ts\n\nls \"2024년에 작성한 TypeScript 파일\"\n# app.tsx    config.ts    utils.ts\n\ncat \"최근 수정한 README\"/README.md\n# ...file contents...\n\nls \"에러 로그가 포함된 파일\"\n# server.log    error-handler.ts    crash-report.txt\n```\n\n같은 파일이 쿼리에 따라 다른 가상 경로에 나타납니다.\n\n## Why SemanticFS?\n\n**1960년대부터 변하지 않은 계층적 디렉토리 구조의 한계:**\n\n- `report.pdf`는 `/work/2024/`에 넣어야 하나, `/projects/clientA/`에 넣어야 하나?\n- \"지난달에 작업한 API 관련 파일\"을 찾으려면 폴더를 하나하나 뒤져야 합니다\n- Spotlight/Everything은 키워드 매칭일 뿐, **의미 기반 검색**이 불가능합니다\n\n**SemanticFS는 이 문제를 파일시스템 레벨에서 해결합니다:**\n\n| 기존 | SemanticFS |\n|------|-----------|\n| `/home/user/projects/2024/react/my-app/src/App.tsx` | `ls \"React 메인 컴포넌트\"` |\n| Spotlight 키워드 검색 | 시맨틱 + 키워드 하이브리드 검색 |\n| 별도 앱 필요 (Obsidian, Notion) | `ls`, `cat`, `vim`, VS Code 등 기존 도구 그대로 |\n| 온라인 API 호출 | 완전 로컬, 오프라인 동작 |\n\n## Features\n\n- **자연어 경로** — `ls \"에러 로그가 포함된 파일\"` 같은 의미 기반 탐색\n- **하이브리드 검색** — 시맨틱 임베딩 + FTS5 키워드 검색을 [RRF](https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf)로 병합\n- **계층적 청킹** — tree-sitter AST 파싱으로 코드는 함수/클래스 단위, 문서는 섹션 단위로 인덱싱\n- **한국어 + 영어 혼합 쿼리** — 다국어 임베딩 모델로 네이티브 지원\n- **Full Write 지원** — `mv`, `cp`, `rm`이 WAL(Write-Ahead Log)로 보호된 실제 파일 조작으로 매핑\n- **Progressive Enhancement** — Ollama 있으면 시맨틱, ONNX도 가능, 둘 다 없으면 키워드 폴백\n- **크로스플랫폼** — Linux, macOS, Windows 지원 (FUSE 추상화 레이어)\n- **제로 설정** — `semfs mount ~/Documents /mnt/semantic` 한 줄이면 동작\n- **3-Layer 캐시** — 쿼리 결과 / 임베딩 / 파싱된 쿼리 각각 독립 캐시 + 정밀 무효화\n\n## Quick Start\n\n**Rust, FUSE, 빌드 도구 — 전부 자동으로 설치됩니다:**\n\n```bash\ngit clone https://github.com/joungminsung/SemanticFS.git\ncd SemanticFS\n./scripts/setup-dev.sh   # Rust + FUSE + 빌드 + 테스트 원스텝\n```\n\n설치 후 바로 사용:\n\n```bash\n# 시스템에 설치\ncargo install --path crates/semfs-cli\n\n# 파일 인덱싱\nsemfs index ~/Documents\n\n# 자연어로 검색 (마운트 없이도 동작)\nsemfs search \"React 프로젝트\"\nsemfs search \"2024년에 작성한 Python 코드\"\nsemfs search \"에러 처리 관련 함수\"\n\n# 상태 확인\nsemfs status\n\n# 진단\nsemfs diagnose\n```\n\n### FUSE 마운트 (선택 — macFUSE/libfuse3 설치 필요)\n\n```bash\n# macOS: brew install --cask macfuse\n# Linux: sudo apt install fuse3 libfuse3-dev\n\n# FUSE 지원 빌드\ncargo build --workspace --features semfs-cli/fuse\n\nmkdir -p /tmp/semantic\nsemfs mount ~/Documents /tmp/semantic\n\n# 자연어로 파일 탐색\ncd /tmp/semantic\nls \"TypeScript API 라우터\"\ncat \"최근 수정한 README\"/README.md\n```\n\n## Installation\n\n### Option 1: From Source (추천)\n\n```bash\ngit clone https://github.com/joungminsung/SemanticFS.git\ncd SemanticFS\n./scripts/setup-dev.sh   # Rust, FUSE, 빌드 도구 자동 설치\ncargo install --path crates/semfs-cli\n```\n\n### Option 2: One-liner\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/joungminsung/SemanticFS/main/scripts/install.sh | sh\n```\n\npre-built 바이너리를 먼저 시도하고, 없으면 자동으로 Rust 설치 + 소스 빌드합니다.\n\n### Option 3: Cargo\n\n```bash\ncargo install semanticfs\n```\n\n### `setup-dev.sh`가 하는 일\n\n| Step | What | Auto? |\n|------|------|:---:|\n| Rust toolchain | `rustup` + stable (1.75+) | Yes |\n| Dev tools | `rustfmt`, `clippy`, `cargo-audit` | Yes |\n| FUSE (macOS) | macFUSE via Homebrew | Yes (커널 확장 수동 승인 필요) |\n| FUSE (Linux) | `libfuse3-dev` via apt/dnf/pacman | Yes |\n| Xcode CLT (macOS) | C compiler (SQLite, tree-sitter 빌드용) | Yes |\n| Build + Test | `cargo build \u0026\u0026 cargo test` | Yes |\n\n### Embedding Model (선택)\n\n임베딩 모델 없이도 **FTS5 키워드 검색**으로 동작합니다. 시맨틱 검색을 원하면:\n\n```bash\n# Option A: Ollama (추천)\nbrew install ollama        # or: curl -fsSL https://ollama.ai/install.sh | sh\nollama serve \u0026\nollama pull multilingual-e5-base\n\n# Option B: ONNX (서버 없이, 빌드 시 --features semfs-embed/onnx)\nmkdir -p ~/.semanticfs/models\n# all-MiniLM-L6-v2.onnx 다운로드 후 위 경로에 배치\n```\n\n## How It Works\n\n### Architecture\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│  User: ls \"React 프로젝트\"                                   │\n│         ↓                                                    │\n│  ┌─────────────┐   ┌──────────────┐   ┌──────────────────┐  │\n│  │  semfs-cli   │──▶│  semfs-fuse   │──▶│   semfs-core     │  │\n│  │  (clap CLI)  │   │ (FUSE mount) │   │                  │  │\n│  └─────────────┘   └──────────────┘   │ ┌──────────────┐ │  │\n│                                        │ │ Query Parser │ │  │\n│                                        │ │ \"React 프로젝트\"│ │  │\n│                                        │ │  → semantic   │ │  │\n│                                        │ │  + filters    │ │  │\n│                                        │ └──────┬───────┘ │  │\n│                                        │        ↓         │  │\n│                                        │ ┌──────────────┐ │  │\n│  ┌──────────────┐                      │ │   Hybrid     │ │  │\n│  │ semfs-embed   │◀─────────────────────│ │  Retriever   │ │  │\n│  │ Ollama/ONNX  │  embed query          │ │ (RRF fusion) │ │  │\n│  └──────────────┘                      │ └──────┬───────┘ │  │\n│                                        │        ↓         │  │\n│                                        │  ┌─────────────┐ │  │\n│                                        │  │ semfs-storage│ │  │\n│                                        │  │ SQLite+FTS5  │ │  │\n│                                        │  │ VectorStore  │ │  │\n│                                        │  │ WAL + Cache  │ │  │\n│                                        │  └─────────────┘ │  │\n│                                        └──────────────────┘  │\n│                                                 ↓             │\n│  Result: users.route.ts  auth.controller.ts  middleware.ts   │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### Crate 구조\n\n```\nsemanticfs/\n├── crates/\n│   ├── semfs-storage/   # SQLite + FTS5, Vector Store, WAL, 3-Layer Cache\n│   ├── semfs-embed/     # Embedder trait + Ollama / ONNX / Noop 구현\n│   ├── semfs-watch/     # notify 기반 파일 감시 + debounce\n│   ├── semfs-core/      # Query Parser, Hybrid Retriever (RRF), Indexer, VFS\n│   ├── semfs-fuse/      # FUSE 추상화 (Linux/macOS/Windows)\n│   └── semfs-cli/       # CLI (clap) — mount, search, index, diagnose 등\n├── tests/               # 통합 테스트 + proptest\n└── benches/             # 벤치마크\n```\n\n각 crate는 독립적으로 이해하고 기여할 수 있습니다. 전체 코드베이스를 알 필요 없습니다.\n\n### 검색 파이프라인\n\n```\n\"2024년에 작성한 React 프로젝트 중 TypeScript 파일\"\n                    ↓\n            ┌───────────────┐\n            │  Query Parser  │\n            └───────┬───────┘\n                    ↓\n  semantic_query: \"React 프로젝트\"\n  filters: [DateRange(2024), Extension(.ts, .tsx)]\n                    ↓\n     ┌──────────────┴──────────────┐\n     ↓                             ↓\n┌─────────┐                ┌─────────────┐\n│ Semantic │  (embedding)  │   Keyword    │  (FTS5)\n│ Search   │                │   Search    │\n└────┬────┘                └──────┬──────┘\n     └──────────┬─────────────────┘\n                ↓\n        ┌──────────────┐\n        │  RRF Fusion   │  score(d) = Σ 1/(k + rank_i(d))\n        └──────┬───────┘\n               ↓\n        ┌──────────────┐\n        │ Filter Apply  │  DateRange + Extension\n        └──────┬───────┘\n               ↓\n         Final Results\n```\n\n### Key Design Decisions\n\n| 항목 | 결정 | 근거 |\n|------|------|------|\n| 임베딩 | Ollama + ONNX 동등 지원 | Progressive enhancement |\n| 벡터 검색 | In-memory cosine similarity (LanceDB optional) | 의존성 최소화 |\n| 텍스트 검색 | SQLite FTS5 | Zero config, 검증된 기술 |\n| 코드 청킹 | tree-sitter AST | 함수/클래스 계층 보존 |\n| Write 보호 | WAL (Write-Ahead Log) | 크래시 시 원자성 보장 |\n| 동시성 | 멀티스레드 + crossbeam channels | fuser 호환, 명확한 스레드 경계 |\n| 캐싱 | L1 쿼리 / L2 임베딩 / L3 파싱 | 정밀 무효화, 레이어별 독립 관리 |\n\n## CLI Reference\n\n```bash\n# 마운트/언마운트 (FUSE feature 필요)\nsemfs mount \u003csource_dir\u003e \u003cmount_point\u003e [--model MODEL] [--read-only]\nsemfs unmount \u003cmount_point\u003e\n\n# 인덱싱\nsemfs index \u003cdirectory\u003e              # 증분 인덱싱\nsemfs reindex [directory]            # 전체 재인덱싱\n\n# 검색\nsemfs search \u003cquery\u003e [--limit N]     # 자연어 검색\n\n# 설정\nsemfs config set \u003ckey\u003e \u003cvalue\u003e       # 설정 변경\nsemfs config get \u003ckey\u003e               # 설정 조회\n\n# 진단\nsemfs status                         # 인덱스 상태\nsemfs diagnose [query|index|cache]   # 문제 진단\nsemfs diagnose --json                # JSON 출력 (버그 리포트용)\n```\n\n## Configuration\n\n```toml\n# ~/.semanticfs/config.toml\n\n[source]\npaths = [\"~/Documents\", \"~/Projects\"]\nignore = [\"node_modules\", \".git\", \"dist\", \"__pycache__\", \"*.lock\", \"target\"]\nmax_file_size = \"50MB\"\n\n[embedding]\nprovider = \"auto\"                # \"auto\" | \"ollama\" | \"onnx\"\nmodel = \"multilingual-e5-base\"   # 다국어 모델 (한국어+영어)\nbatch_size = 100\ndimensions = 768\n\n[search]\nalpha = 0.7                      # 시맨틱 가중치 (0.0=키워드만, 1.0=시맨틱만)\nmax_results = 100\ncache_size = 1000                # L1 쿼리 캐시 엔트리 수\n\n[index]\nwatch = true                     # 파일 변경 시 자동 재인덱싱\ninterval = \"5s\"                  # 디바운스 간격\n```\n\n## Performance Targets\n\n| Metric | Target |\n|--------|--------|\n| Initial indexing | 1,000 files/min |\n| Query response (warm cache) | \u003c 200ms |\n| Query response (cold) | \u003c 2s |\n| Memory (100K files) | \u003c 500MB |\n| Incremental reindex (single file) | \u003c 1s |\n\n## Supported File Types\n\n| Category | Extensions | Chunking |\n|----------|-----------|----------|\n| Source Code | `.rs`, `.py`, `.js`, `.ts`, `.go`, `.java` | tree-sitter AST (함수/클래스/모듈 계층) |\n| Text/Docs | `.md`, `.txt`, `.rst` | 섹션/문단 기반 |\n| Config/Data | `.json`, `.yaml`, `.toml`, `.csv` | 구조 파싱 |\n| Others | `.html`, `.css`, `.sql`, `.sh`, etc. | 텍스트 폴백 |\n\n## Roadmap\n\n- [x] Core: Query Parser + Hybrid Retriever + RRF\n- [x] Storage: SQLite + FTS5 + WAL + 3-Layer Cache\n- [x] Embedding: Ollama + ONNX + Noop fallback\n- [x] Indexer: tree-sitter AST + 계층적 청킹\n- [x] CLI: mount, search, index, status, diagnose, config\n- [x] FUSE: Linux + macOS + Windows 추상화\n- [x] Write: mv/cp/rm with WAL protection\n- [ ] LanceDB ANN integration (현재 in-memory cosine)\n- [ ] Image embedding (CLIP)\n- [ ] PDF/DOCX text extraction\n- [ ] Audio/Video (Whisper + CLIP)\n- [ ] VS Code extension\n\n## Contributing\n\n기여를 환영합니다! [CONTRIBUTING.md](CONTRIBUTING.md)에서 상세한 가이드를 확인하세요.\n\n```bash\ngit clone https://github.com/joungminsung/SemanticFS.git\ncd SemanticFS\n./scripts/setup-dev.sh\ncargo test --workspace\n```\n\n`good-first-issue` 라벨이 붙은 이슈부터 시작하면 좋습니다.\n\n## License\n\nDual-licensed under [MIT](LICENSE-MIT) and [Apache 2.0](LICENSE-APACHE).\n\n## Acknowledgments\n\n- [fuser](https://github.com/cberner/fuser) — Rust FUSE implementation\n- [tree-sitter](https://tree-sitter.github.io/) — AST parsing\n- [Ollama](https://ollama.ai/) — Local LLM/embedding serving\n- [SQLite FTS5](https://www.sqlite.org/fts5.html) — Full-text search\n- Gifford et al., \"Semantic File Systems\" (1991, MIT) — Original concept\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoungminsung%2Fsemanticfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoungminsung%2Fsemanticfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoungminsung%2Fsemanticfs/lists"}