fridai 0.1.0__tar.gz

fridai-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,57 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/fridai
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build
+        run: python -m build
+
+      - name: Check package metadata
+        run: twine check dist/*
+
+      - name: Verify version matches tag
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          echo "pyproject version=$VERSION tag=$TAG"
+          test "$VERSION" = "$TAG"
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: Release ${{ github.ref_name }}
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

fridai-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,47 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: pip install -e .
+      - name: Run tests
+        run: python -m unittest discover -s tests -v
+
+  # Verify fastembed actually works once (needs a model download). Isolated with
+  # continue-on-error so network/HF flakiness doesn't fail the whole run — the test job
+  # above is the authoritative gate.
+  embed-smoke:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Cache fastembed model
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/fastembed
+          key: fastembed-nomic-embed-text-v1.5
+      - name: Install
+        run: pip install -e .
+      - name: fastembed embedding smoke
+        run: python scripts/embed_smoke.py

fridai-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+.venv/
+venv/
+env/
+dist/
+build/
+
+# Test / tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.coverage
+.coverage.*
+htmlcov/
+
+# fastembed / model caches (if created inside the repo)
+fastembed_cache/
+.fastembed_cache/
+local_cache/
+
+# Environment
+.env
+.env.*
+.python-version
+
+# IDEs / editors
+.idea/
+.vscode/
+*.iml
+*.swp
+*.swo
+*~
+.\#*
+
+# OS
+.DS_Store
+Thumbs.db

fridai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chloe Jungah Kim (chloeeekim)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fridai-0.1.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: fridai
+Version: 0.1.0
+Summary: Local MCP server for recalling past code, commits, and AI conversations — search-only, no local LLM required
+Project-URL: Homepage, https://github.com/chloeeekim/fridai
+Project-URL: Repository, https://github.com/chloeeekim/fridai
+Project-URL: Issues, https://github.com/chloeeekim/fridai/issues
+Author-email: Chloe Jungah Kim <hiyaku0317@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Chloe Jungah Kim (chloeeekim)
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Requires-Dist: fastembed>=0.3
+Requires-Dist: mcp>=1.0
+Requires-Dist: numpy>=1.21
+Description-Content-Type: text/markdown
+
+# fridai 🛠️
+
+*English | [한국어](README.ko.md)*
+
+A lightweight **MCP server** that lets coding agents (Claude Code, etc.) recall your past
+**code, commits, and AI conversations** via the `recall` tool — **100% local**.
+Search & recall only — **no local LLM required.**
+
+- **Search-only (read-only).** The calling agent (an LLM) does the reasoning; fridai
+  just returns evidence with sources.
+- **Local embeddings (fastembed, onnx).** No Ollama or external API. Semantic search works
+  out of the box (falls back to lexical if fastembed isn't installed).
+- **Multi-agent history.** Auto-indexes Claude Code · OpenAI Codex CLI · Gemini CLI conversations.
+- **Private by design.** Your memory never leaves the machine; secrets are auto-masked at index time.
+
+**Status:** early development. **Requires** Python 3.10+ and `git` (for code/commit indexing).
+
+## How it works
+
+1. **Index** (`fridai index`) builds a local database from three source types:
+   - **AI conversations** — parses each agent's session logs into question→answer *turns*, and
+     matches a question to its **resulting git commit** (time window ∩ touched files).
+   - **Code** — chunks git-tracked files by function/class (line-window fallback), with line ranges.
+   - **Commits** — indexes git commit history (subject + changed files).
+2. Everything is stored in **sqlite + FTS5** (lexical) plus **float32 vectors** at `~/.fridai/index.db`.
+3. **Recall** fuses lexical (BM25) and vector (cosine) results via **RRF**, then reranks so real work
+   artifacts (code/commits/edited turns) outrank bare question turns, and dedupes repeated questions.
+
+## Install
+
+```bash
+git clone https://github.com/chloeeekim/fridai.git
+cd fridai
+pipx install .            # isolated (recommended). Or: pip install -e .  in a venv
+```
+
+Pulls `numpy` + `fastembed` (onnx) + `mcp`. Registers the `fridai` command.
+
+## Quickstart
+
+```bash
+fridai index --source all             # build the index (current repo + all agent conversations)
+fridai stats                          # index overview
+claude mcp add fridai -- fridai mcp   # register with Claude Code
+```
+
+After registering, the agent recalls via the `recall` tool. Re-run `fridai index` anytime to
+refresh — it's **incremental** (only changed files/sessions/new commits are reprocessed), so it's cheap.
+
+## CLI reference
+
+| Command | Description |
+| :--- | :--- |
+| `fridai index` | Build/update the index. |
+| `fridai mcp` | Run the stdio MCP server. |
+| `fridai stats` | Print document counts by source. |
+
+`index` flags:
+
+| Flag | Meaning |
+| :--- | :--- |
+| `--source agent\|code\|commits\|all` | What to index (default `all`). `agent` = all AI conversations. |
+| `--path DIR` | Target repo for code/commits (default: current directory). |
+| `--reindex` | Ignore incremental state and rebuild everything. |
+| `--no-embed` | Skip embeddings (lexical index only). |
+| `--no-prune` | Keep chunks of files deleted from git (code). |
+| `--no-redact` | Turn off secret masking (on by default). |
+
+## The `recall` tool (MCP)
+
+The server exposes one tool, `recall(query, k=5, repo="", source_type="")`:
+
+- `query` — search text (natural language and/or code identifiers).
+- `k` — max results (default 5).
+- `repo` — empty = current working repo (server detects cwd); `"all"` = every repo; `"<name>"` = a specific repo.
+- `source_type` — empty = all; one of `agent_turn` · `code` · `commit` · `note`.
+
+It returns text with numbered, cited hits for the agent to read — for example:
+
+```
+fridai recall — 2 memory item(s) for "docker mount" (all repos, with sources):
+
+### [1] myrepo 2026-07-01 [codex] session:how did I add the docker mount?
+Q: how did I add the docker mount?
+A: added a bind mount via volumes.
+
+### [2] myrepo/docker-compose.yml:1-20
+volumes: ...
+```
+
+Non-Claude sources are tagged (`🤖 codex` / `🤖 gemini` in the CLI, `[codex]`/`[gemini]` in citations).
+
+## Registering with other MCP clients
+
+fridai is a standard **stdio MCP server** — the launch command is `fridai mcp`. Any MCP-capable
+client can use it. For clients that read an `mcpServers` config:
+
+```json
+{
+  "mcpServers": {
+    "fridai": { "command": "fridai", "args": ["mcp"] }
+  }
+}
+```
+
+## Indexed agent sources
+
+| Agent | Default data path | Override env var |
+| :--- | :--- | :--- |
+| Claude Code | `~/.claude/projects/` | `FRIDAI_CLAUDE_PROJECTS` |
+| OpenAI Codex CLI | `~/.codex/sessions/` | `FRIDAI_CODEX_SESSIONS` |
+| Gemini CLI | `~/.gemini/tmp/` | `FRIDAI_GEMINI_SESSIONS` |
+
+A missing agent directory is silently skipped.
+
+## Security
+
+Secrets (AWS keys, GitHub/Slack tokens, PEM private keys, JWTs, `password=`…) are auto-masked
+at index time (on by default). Nothing is sent off the machine.
+
+```bash
+fridai index --source code --no-redact   # disable masking
+echo "*.env" >> .fridaiignore                 # exclude paths (repo root or ~/.fridai/)
+```
+
+The high-entropy heuristic is **off by default** (too many false positives on long identifiers);
+enable it with `FRIDAI_REDACT_ENTROPY=1`.
+
+## Environment variables
+
+| Variable | Default | Description |
+| :--- | :--- | :--- |
+| `FRIDAI_HOME` | `~/.fridai` | Data home (index DB, etc.). |
+| `FRIDAI_CLAUDE_PROJECTS` | `~/.claude/projects` | Claude Code transcript location. |
+| `FRIDAI_CODEX_SESSIONS` | `~/.codex/sessions` | Codex CLI session location. |
+| `FRIDAI_GEMINI_SESSIONS` | `~/.gemini/tmp` | Gemini CLI session location. |
+| `FRIDAI_EMBED_BACKEND` | auto | `none` disables embeddings (lexical only). |
+| `FRIDAI_FASTEMBED_MODEL` | `nomic-ai/nomic-embed-text-v1.5` | fastembed model name. |
+| `FRIDAI_REDACT_ENTROPY` | off | `1` enables the high-entropy secret heuristic. |
+| `FRIDAI_WORK_PENALTY` | `8` | How far to demote pure question turns in ranking. `0` disables. |
+| `FRIDAI_COMMIT_WINDOW_MIN` | `180` | Minutes window for matching a question to its resulting commit. |
+
+**Embedder consistency:** index and query with the same embedder. Mixing models makes vectors
+incomparable even at the same dimension — the store then falls back to lexical search. Reindex
+(`--reindex`) after switching models.
+
+## Development
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests
+```
+
+CI (GitHub Actions) runs the suite on Python 3.10–3.14 plus a fastembed smoke check on every push/PR.
+Tests are hermetic — `tests/__init__.py` isolates all `FRIDAI_*` paths and disables the embedder,
+so no real `~/.fridai`/`~/.codex`/etc. is touched and no model is downloaded.
+
+See [`docs/build-order.md`](docs/build-order.md) for the design & build-order rationale.
+
+## License
+
+MIT.

fridai-0.1.0/README.ko.md

@@ -0,0 +1,156 @@
+# fridai 🛠️
+
+*[English](README.md) | 한국어*
+
+코딩 에이전트(Claude Code 등)가 `recall` 툴로 당신의 과거 **코드·커밋·AI 대화 기록**을
+**100% 로컬**에서 회수하게 해주는 경량 **MCP 서버**. 검색·회수 전용 — **로컬 LLM이 필요 없습니다.**
+
+- **검색 전용(read-only).** 추론은 호출하는 에이전트(LLM)가 하고, fridai는 출처 포함 근거만 회수.
+- **로컬 임베딩(fastembed, onnx).** Ollama·외부 API 불필요. 시맨틱 검색이 기본 동작(fastembed 없으면 어휘 검색 폴백).
+- **멀티 에이전트 기록.** Claude Code · OpenAI Codex CLI · Gemini CLI 대화를 자동 인덱싱.
+- **설계상 프라이버시.** 기억은 기기 밖으로 안 나가고, 시크릿은 인덱싱 시 자동 마스킹.
+
+**상태:** 초기 개발. **요구사항:** Python 3.10+ 및 `git`(코드·커밋 인덱싱용).
+
+## 동작 원리
+
+1. **인덱싱**(`fridai index`)이 세 가지 소스로 로컬 DB를 만듭니다:
+   - **AI 대화** — 각 에이전트의 세션 로그를 질문→답변 *턴*으로 파싱하고, 질문을 **결과 git 커밋**과
+     매칭(시간창 ∩ 건드린 파일).
+   - **코드** — git 추적 파일을 함수/클래스 단위로 청킹(폴백은 N줄 윈도우), 인용용 라인범위 보존.
+   - **커밋** — git 커밋 히스토리(제목 + 변경 파일) 인덱싱.
+2. 모두 `~/.fridai/index.db`의 **sqlite + FTS5**(어휘) + **float32 벡터**로 저장.
+3. **회수**는 어휘(BM25)와 벡터(코사인)를 **RRF**로 융합한 뒤, 실제 작업 산물(코드/커밋/편집 턴)이
+   단순 질문 턴보다 위로 오게 재랭킹하고 반복 질문을 중복 제거합니다.
+
+## 설치
+
+```bash
+git clone https://github.com/chloeeekim/fridai.git
+cd fridai
+pipx install .            # 격리 설치(권장). 또는 venv에서 pip install -e .
+```
+
+`numpy` + `fastembed`(onnx) + `mcp`가 딸려옵니다. `fridai` 명령이 등록됩니다.
+
+## 빠른 시작
+
+```bash
+fridai index --source all             # 인덱스 생성(현재 레포 + 모든 에이전트 대화)
+fridai stats                          # 인덱스 개요
+claude mcp add fridai -- fridai mcp   # Claude Code에 등록
+```
+
+등록 후 에이전트가 `recall` 툴로 회수합니다. 언제든 `fridai index`를 다시 돌리면 갱신되는데,
+**증분**(변경된 파일·세션·새 커밋만 재처리)이라 가볍습니다.
+
+## CLI 레퍼런스
+
+| 명령 | 설명 |
+| :--- | :--- |
+| `fridai index` | 인덱스 생성/갱신. |
+| `fridai mcp` | stdio MCP 서버 실행. |
+| `fridai stats` | 소스별 문서 수 출력. |
+
+`index` 플래그:
+
+| 플래그 | 의미 |
+| :--- | :--- |
+| `--source agent\|code\|commits\|all` | 인덱싱 대상(기본 `all`). `agent` = 모든 AI 대화. |
+| `--path DIR` | code/commits 대상 레포(기본: 현재 디렉터리). |
+| `--reindex` | 증분 무시하고 전체 재구성. |
+| `--no-embed` | 임베딩 생략(어휘 인덱스만). |
+| `--no-prune` | git에서 삭제된 파일의 청크 유지(code). |
+| `--no-redact` | 시크릿 마스킹 끄기(기본 ON). |
+
+## `recall` 툴 (MCP)
+
+서버는 단일 툴 `recall(query, k=5, repo="", source_type="")`을 노출합니다:
+
+- `query` — 검색어(자연어 및/또는 코드 식별자).
+- `k` — 최대 결과 수(기본 5).
+- `repo` — 빈값 = 현재 작업 레포(서버 cwd 감지); `"all"` = 전체; `"<이름>"` = 특정 레포.
+- `source_type` — 빈값 = 전체; `agent_turn` · `code` · `commit` · `note` 중 하나.
+
+에이전트가 읽을 수 있게 번호·출처가 달린 텍스트를 반환합니다. 예:
+
+```
+fridai recall — 2 memory item(s) for "docker mount" (all repos, with sources):
+
+### [1] myrepo 2026-07-01 [codex] session:how did I add the docker mount?
+Q: how did I add the docker mount?
+A: added a bind mount via volumes.
+
+### [2] myrepo/docker-compose.yml:1-20
+volumes: ...
+```
+
+비-Claude 소스는 태깅됩니다(CLI에선 `🤖 codex`/`🤖 gemini`, 출처엔 `[codex]`/`[gemini]`).
+
+## 다른 MCP 클라이언트에 등록
+
+fridai는 표준 **stdio MCP 서버**이고 실행 명령은 `fridai mcp` 입니다. MCP를 지원하는 어떤
+클라이언트에서도 쓸 수 있습니다. `mcpServers` 설정을 읽는 클라이언트라면:
+
+```json
+{
+  "mcpServers": {
+    "fridai": { "command": "fridai", "args": ["mcp"] }
+  }
+}
+```
+
+## 연동 에이전트 경로
+
+| 에이전트 | 기본 데이터 경로 | 오버라이드 환경변수 |
+| :--- | :--- | :--- |
+| Claude Code | `~/.claude/projects/` | `FRIDAI_CLAUDE_PROJECTS` |
+| OpenAI Codex CLI | `~/.codex/sessions/` | `FRIDAI_CODEX_SESSIONS` |
+| Gemini CLI | `~/.gemini/tmp/` | `FRIDAI_GEMINI_SESSIONS` |
+
+없는 에이전트 디렉터리는 조용히 건너뜁니다.
+
+## 보안
+
+시크릿(AWS 키, GitHub/Slack 토큰, PEM 개인키, JWT, `password=` 등)은 인덱싱 시 자동 마스킹됩니다(기본 ON).
+기기 밖으로 아무것도 나가지 않습니다.
+
+```bash
+fridai index --source code --no-redact   # 마스킹 끄기
+echo "*.env" >> .fridaiignore                 # 경로 제외(레포 루트 또는 ~/.fridai/)
+```
+
+고엔트로피 휴리스틱은 긴 식별자 오탐이 많아 **기본 OFF**입니다. `FRIDAI_REDACT_ENTROPY=1`로 켭니다.
+
+## 환경변수
+
+| 변수 | 기본값 | 설명 |
+| :--- | :--- | :--- |
+| `FRIDAI_HOME` | `~/.fridai` | 데이터 홈(인덱스 DB 등). |
+| `FRIDAI_CLAUDE_PROJECTS` | `~/.claude/projects` | Claude Code transcript 위치. |
+| `FRIDAI_CODEX_SESSIONS` | `~/.codex/sessions` | Codex CLI 세션 위치. |
+| `FRIDAI_GEMINI_SESSIONS` | `~/.gemini/tmp` | Gemini CLI 세션 위치. |
+| `FRIDAI_EMBED_BACKEND` | 자동 | `none`이면 임베딩 끔(어휘만). |
+| `FRIDAI_FASTEMBED_MODEL` | `nomic-ai/nomic-embed-text-v1.5` | fastembed 모델명. |
+| `FRIDAI_REDACT_ENTROPY` | off | `1`이면 고엔트로피 시크릿 휴리스틱 활성. |
+| `FRIDAI_WORK_PENALTY` | `8` | 순수 질문 턴 강등 정도. `0`이면 끔. |
+| `FRIDAI_COMMIT_WINDOW_MIN` | `180` | 질문↔결과 커밋 매칭 시간창(분). |
+
+**임베더 일치:** 인덱싱과 쿼리는 같은 임베더로. 모델을 섞으면 차원이 같아도 벡터가 호환되지 않아
+어휘 검색으로 폴백합니다. 모델을 바꿨으면 `--reindex`.
+
+## 개발
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests
+```
+
+CI(GitHub Actions)가 push/PR마다 Python 3.10–3.14에서 테스트 + fastembed 실동작 스모크를 돌립니다.
+테스트는 격리돼 있어(`tests/__init__.py`가 모든 `FRIDAI_*` 경로를 임시로 두고 임베더를 끔) 실제
+`~/.fridai`·`~/.codex` 등을 건드리지 않고 모델도 받지 않습니다.
+
+설계·구축 순서 근거는 [`docs/build-order.md`](docs/build-order.md) 참고(영문).
+
+## 라이선스
+
+MIT.

fridai-0.1.0/README.md

@@ -0,0 +1,161 @@
+# fridai 🛠️
+
+*English | [한국어](README.ko.md)*
+
+A lightweight **MCP server** that lets coding agents (Claude Code, etc.) recall your past
+**code, commits, and AI conversations** via the `recall` tool — **100% local**.
+Search & recall only — **no local LLM required.**
+
+- **Search-only (read-only).** The calling agent (an LLM) does the reasoning; fridai
+  just returns evidence with sources.
+- **Local embeddings (fastembed, onnx).** No Ollama or external API. Semantic search works
+  out of the box (falls back to lexical if fastembed isn't installed).
+- **Multi-agent history.** Auto-indexes Claude Code · OpenAI Codex CLI · Gemini CLI conversations.
+- **Private by design.** Your memory never leaves the machine; secrets are auto-masked at index time.
+
+**Status:** early development. **Requires** Python 3.10+ and `git` (for code/commit indexing).
+
+## How it works
+
+1. **Index** (`fridai index`) builds a local database from three source types:
+   - **AI conversations** — parses each agent's session logs into question→answer *turns*, and
+     matches a question to its **resulting git commit** (time window ∩ touched files).
+   - **Code** — chunks git-tracked files by function/class (line-window fallback), with line ranges.
+   - **Commits** — indexes git commit history (subject + changed files).
+2. Everything is stored in **sqlite + FTS5** (lexical) plus **float32 vectors** at `~/.fridai/index.db`.
+3. **Recall** fuses lexical (BM25) and vector (cosine) results via **RRF**, then reranks so real work
+   artifacts (code/commits/edited turns) outrank bare question turns, and dedupes repeated questions.
+
+## Install
+
+```bash
+git clone https://github.com/chloeeekim/fridai.git
+cd fridai
+pipx install .            # isolated (recommended). Or: pip install -e .  in a venv
+```
+
+Pulls `numpy` + `fastembed` (onnx) + `mcp`. Registers the `fridai` command.
+
+## Quickstart
+
+```bash
+fridai index --source all             # build the index (current repo + all agent conversations)
+fridai stats                          # index overview
+claude mcp add fridai -- fridai mcp   # register with Claude Code
+```
+
+After registering, the agent recalls via the `recall` tool. Re-run `fridai index` anytime to
+refresh — it's **incremental** (only changed files/sessions/new commits are reprocessed), so it's cheap.
+
+## CLI reference
+
+| Command | Description |
+| :--- | :--- |
+| `fridai index` | Build/update the index. |
+| `fridai mcp` | Run the stdio MCP server. |
+| `fridai stats` | Print document counts by source. |
+
+`index` flags:
+
+| Flag | Meaning |
+| :--- | :--- |
+| `--source agent\|code\|commits\|all` | What to index (default `all`). `agent` = all AI conversations. |
+| `--path DIR` | Target repo for code/commits (default: current directory). |
+| `--reindex` | Ignore incremental state and rebuild everything. |
+| `--no-embed` | Skip embeddings (lexical index only). |
+| `--no-prune` | Keep chunks of files deleted from git (code). |
+| `--no-redact` | Turn off secret masking (on by default). |
+
+## The `recall` tool (MCP)
+
+The server exposes one tool, `recall(query, k=5, repo="", source_type="")`:
+
+- `query` — search text (natural language and/or code identifiers).
+- `k` — max results (default 5).
+- `repo` — empty = current working repo (server detects cwd); `"all"` = every repo; `"<name>"` = a specific repo.
+- `source_type` — empty = all; one of `agent_turn` · `code` · `commit` · `note`.
+
+It returns text with numbered, cited hits for the agent to read — for example:
+
+```
+fridai recall — 2 memory item(s) for "docker mount" (all repos, with sources):
+
+### [1] myrepo 2026-07-01 [codex] session:how did I add the docker mount?
+Q: how did I add the docker mount?
+A: added a bind mount via volumes.
+
+### [2] myrepo/docker-compose.yml:1-20
+volumes: ...
+```
+
+Non-Claude sources are tagged (`🤖 codex` / `🤖 gemini` in the CLI, `[codex]`/`[gemini]` in citations).
+
+## Registering with other MCP clients
+
+fridai is a standard **stdio MCP server** — the launch command is `fridai mcp`. Any MCP-capable
+client can use it. For clients that read an `mcpServers` config:
+
+```json
+{
+  "mcpServers": {
+    "fridai": { "command": "fridai", "args": ["mcp"] }
+  }
+}
+```
+
+## Indexed agent sources
+
+| Agent | Default data path | Override env var |
+| :--- | :--- | :--- |
+| Claude Code | `~/.claude/projects/` | `FRIDAI_CLAUDE_PROJECTS` |
+| OpenAI Codex CLI | `~/.codex/sessions/` | `FRIDAI_CODEX_SESSIONS` |
+| Gemini CLI | `~/.gemini/tmp/` | `FRIDAI_GEMINI_SESSIONS` |
+
+A missing agent directory is silently skipped.
+
+## Security
+
+Secrets (AWS keys, GitHub/Slack tokens, PEM private keys, JWTs, `password=`…) are auto-masked
+at index time (on by default). Nothing is sent off the machine.
+
+```bash
+fridai index --source code --no-redact   # disable masking
+echo "*.env" >> .fridaiignore                 # exclude paths (repo root or ~/.fridai/)
+```
+
+The high-entropy heuristic is **off by default** (too many false positives on long identifiers);
+enable it with `FRIDAI_REDACT_ENTROPY=1`.
+
+## Environment variables
+
+| Variable | Default | Description |
+| :--- | :--- | :--- |
+| `FRIDAI_HOME` | `~/.fridai` | Data home (index DB, etc.). |
+| `FRIDAI_CLAUDE_PROJECTS` | `~/.claude/projects` | Claude Code transcript location. |
+| `FRIDAI_CODEX_SESSIONS` | `~/.codex/sessions` | Codex CLI session location. |
+| `FRIDAI_GEMINI_SESSIONS` | `~/.gemini/tmp` | Gemini CLI session location. |
+| `FRIDAI_EMBED_BACKEND` | auto | `none` disables embeddings (lexical only). |
+| `FRIDAI_FASTEMBED_MODEL` | `nomic-ai/nomic-embed-text-v1.5` | fastembed model name. |
+| `FRIDAI_REDACT_ENTROPY` | off | `1` enables the high-entropy secret heuristic. |
+| `FRIDAI_WORK_PENALTY` | `8` | How far to demote pure question turns in ranking. `0` disables. |
+| `FRIDAI_COMMIT_WINDOW_MIN` | `180` | Minutes window for matching a question to its resulting commit. |
+
+**Embedder consistency:** index and query with the same embedder. Mixing models makes vectors
+incomparable even at the same dimension — the store then falls back to lexical search. Reindex
+(`--reindex`) after switching models.
+
+## Development
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests
+```
+
+CI (GitHub Actions) runs the suite on Python 3.10–3.14 plus a fastembed smoke check on every push/PR.
+Tests are hermetic — `tests/__init__.py` isolates all `FRIDAI_*` paths and disables the embedder,
+so no real `~/.fridai`/`~/.codex`/etc. is touched and no model is downloaded.
+
+See [`docs/build-order.md`](docs/build-order.md) for the design & build-order rationale.
+
+## License
+
+MIT.