codeatrium 0.1.0__py3-none-any.whl

codeatrium/__init__.py

@@ -0,0 +1,3 @@
+"""codeatrium — Memory palace for AI coding agents"""
+
+__version__ = "0.1.0"

codeatrium/__main__.py

@@ -0,0 +1,5 @@
+"""python -m codeatrium エントリポイント"""
+
+from codeatrium.cli import app
+
+app()

codeatrium/cli/__init__.py

@@ -0,0 +1,295 @@
+"""loci CLI エントリポイント — サブコマンド登録のみ"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from codeatrium.cli.distill_cmd import distill
+from codeatrium.cli.hook_cmd import hook_app
+from codeatrium.cli.index_cmd import index
+from codeatrium.cli.prime_cmd import prime
+from codeatrium.cli.search_cmd import context, search
+from codeatrium.cli.server_cmd import server_app
+from codeatrium.cli.show_cmd import dump, show
+from codeatrium.cli.status_cmd import status
+
+app = typer.Typer(help="CLI-first memory layer for AI coding agents")
+
+DEFAULT_DISTILL_RECENT = 50
+
+
+@app.command()
+def init(
+    skip_existing: Annotated[
+        bool,
+        typer.Option("--skip-existing", help="既存 exchange の蒸留をスキップする"),
+    ] = False,
+    distill_limit: Annotated[
+        int | None,
+        typer.Option("--distill-limit", help="既存 exchange のうち直近 N 件のみ蒸留対象にする"),
+    ] = None,
+    min_chars: Annotated[
+        int | None,
+        typer.Option("--min-chars", help="既存 exchange の最小文字数フィルタ（省略時は対話で選択）"),
+    ] = None,
+) -> None:
+    """プロジェクトルートに .codeatrium/memory.db を初期化する"""
+    from codeatrium.db import get_connection, init_db
+    from codeatrium.indexer import index_file, parse_exchanges
+    from codeatrium.paths import (
+        db_path,
+        find_project_root,
+        resolve_claude_projects_path,
+    )
+
+    root = find_project_root()
+    db = db_path(root)
+
+    if db.exists():
+        typer.echo(f"Already initialized: {db}")
+        return
+
+    # 既存セッションの検出
+    target_dir = resolve_claude_projects_path(root)
+    jsonl_files = list(target_dir.rglob("*.jsonl")) if target_dir else []
+
+    # --- 対話フェーズ（DB 作成前にすべての質問を完了する） ---
+    resolved_min_chars = 50
+    skip_count = 0
+    skip_strategy = "recent"
+    total_exchanges = 0
+    run_distill_now = False
+
+    if jsonl_files:
+        resolved_min_chars = _resolve_min_chars(jsonl_files, min_chars)
+
+        total_exchanges = sum(
+            len(parse_exchanges(jsonl, min_chars=resolved_min_chars))
+            for jsonl in jsonl_files
+        )
+
+        if total_exchanges > 0:
+            skip_count, skip_strategy = _resolve_skip_count(
+                total_exchanges, skip_existing, distill_limit
+            )
+
+            distill_count = total_exchanges - skip_count
+            if distill_count > 0:
+                run_distill_now = _ask_run_distill_now(distill_count)
+
+    # --- 実行フェーズ（ここから DB・ファイルを作成） ---
+    init_db(db)
+
+    config_path = db.parent / "config.toml"
+    if not config_path.exists():
+        config_path.write_text(
+            "# Codeatrium configuration\n"
+            "\n"
+            "[distill]\n"
+            '# model = "claude-haiku-4-5-20251001"\n'
+            "# batch_limit = 20\n"
+            "# min_chars = 100   # この文字数未満の exchange は蒸留スキップ\n"
+            "\n"
+            "[index]\n"
+            "# min_chars = 50   # trivial フィルタ閾値（文字数）\n"
+        )
+
+    typer.echo(f"Initialized: {db}")
+
+    from codeatrium.cli.prime_cmd import inject_claude_md
+
+    if inject_claude_md(root):
+        typer.echo(f"Updated: {root / 'CLAUDE.md'} (codeatrium section)")
+
+    if total_exchanges == 0:
+        return
+
+    actual_total = 0
+    for jsonl in jsonl_files:
+        actual_total += index_file(jsonl, db, min_chars=resolved_min_chars)
+
+    typer.echo(f"Indexed {actual_total} existing exchange(s).")
+
+    if skip_count > 0:
+        order_clause = (
+            "ORDER BY LENGTH(user_content) + LENGTH(agent_content) ASC"
+            if skip_strategy == "longest"
+            else "ORDER BY ply_start ASC"
+        )
+        con = get_connection(db)
+        con.execute(
+            f"""
+            UPDATE exchanges SET distilled_at = 'skipped'
+            WHERE distilled_at IS NULL
+            AND id IN (
+                SELECT id FROM exchanges
+                WHERE distilled_at IS NULL
+                {order_clause}
+                LIMIT ?
+            )
+            """,
+            (skip_count,),
+        )
+        con.commit()
+        con.close()
+        remaining = actual_total - skip_count
+        typer.echo(f"Marked {skip_count} exchange(s) as skipped. {remaining} will be distilled.")
+    else:
+        typer.echo(f"All {actual_total} exchange(s) will be distilled.")
+
+    if run_distill_now:
+        from codeatrium.config import load_config
+        from codeatrium.distiller import distill_all
+
+        cfg = load_config(root)
+        typer.echo("Running distillation...")
+        def _on_progress(cur: int, tot: int, error: str | None = None) -> None:
+            if error:
+                typer.echo(f"  [{cur}/{tot}] error: {error}", err=True)
+            else:
+                typer.echo(f"  [{cur}/{tot}] distilled", err=True)
+
+        count = distill_all(
+            db,
+            model=cfg.distill_model,
+            on_progress=_on_progress,
+            project_root=str(root),
+            distill_min_chars=cfg.distill_min_chars,
+        )
+        typer.echo(f"Distilled {count} exchange(s).")
+
+
+_MIN_CHARS_CANDIDATES = [50, 100, 200, 500]
+
+
+def _count_exchanges_by_threshold(
+    jsonl_files: list[Path], thresholds: list[int]
+) -> dict[int, int]:
+    """各閾値ごとの exchange 件数をカウントする。min_chars=0 で全件パースして集計。"""
+    from codeatrium.indexer import parse_exchanges
+
+    # 全 exchange の combined 文字数を収集
+    lengths: list[int] = []
+    for jsonl in jsonl_files:
+        for ex in parse_exchanges(jsonl, min_chars=0):
+            lengths.append(len(ex.user_content) + len(ex.agent_content))
+
+    return {t: sum(1 for length in lengths if length >= t) for t in thresholds}
+
+
+def _resolve_min_chars(
+    jsonl_files: list[Path], min_chars_flag: int | None
+) -> int:
+    """init 時の min_chars を決定する。フラグ指定済みならそのまま、未指定なら対話。"""
+    if min_chars_flag is not None:
+        return min_chars_flag
+
+    counts = _count_exchanges_by_threshold(jsonl_files, _MIN_CHARS_CANDIDATES)
+
+    # exchange が0件なら対話不要
+    if counts.get(_MIN_CHARS_CANDIDATES[0], 0) == 0:
+        return _MIN_CHARS_CANDIDATES[0]
+
+    typer.echo("\nMin chars threshold for existing exchanges:")
+    for i, threshold in enumerate(_MIN_CHARS_CANDIDATES, 1):
+        label = " (default)" if threshold == 50 else ""
+        typer.echo(f"  [{i}] {threshold} chars{label} — {counts[threshold]} exchanges")
+    typer.echo(f"  [{len(_MIN_CHARS_CANDIDATES) + 1}] Custom")
+
+    choice = typer.prompt("Choice", default="1")
+
+    for i, threshold in enumerate(_MIN_CHARS_CANDIDATES, 1):
+        if choice == str(i):
+            return threshold
+
+    if choice == str(len(_MIN_CHARS_CANDIDATES) + 1):
+        return typer.prompt("Min chars threshold?", type=int)
+
+    typer.echo("Invalid choice. Using default (50).")
+    return 50
+
+
+def _ask_run_distill_now(distill_count: int) -> bool:
+    """蒸留を今すぐ実行するか聞く。"""
+    typer.echo(
+        f"\nStart distillation now? ({distill_count} exchanges, uses claude --print)"
+    )
+    typer.echo("  [1] No — distill on next session start (default)")
+    typer.echo("  [2] Yes — run now")
+
+    choice = typer.prompt("Choice", default="1")
+    return choice == "2"
+
+
+def _ask_distill_priority() -> str:
+    """蒸留対象の優先順位を選択する。"""
+    typer.echo("\nDistill priority:")
+    typer.echo("  [1] Recent — newest exchanges first")
+    typer.echo("  [2] Longest — longest exchanges first")
+
+    choice = typer.prompt("Choice", default="1")
+
+    if choice == "2":
+        return "longest"
+    return "recent"
+
+
+def _resolve_skip_count(
+    total: int, skip_existing: bool, distill_limit: int | None
+) -> tuple[int, str]:
+    """スキップする exchange 数と優先順位を決定する。フラグ or 対話プロンプト。
+
+    Returns: (skip_count, strategy) where strategy is "recent" or "longest"
+    """
+    if skip_existing:
+        return total, "recent"
+    if distill_limit is not None:
+        skip = max(0, total - distill_limit)
+        strategy = _ask_distill_priority() if skip > 0 else "recent"
+        return skip, strategy
+
+    # 対話プロンプト
+    typer.echo(
+        f"\nFound {total} existing exchanges from past sessions.\n"
+        "Distillation uses claude --print (Haiku) and consumes tokens.\n"
+        "⚠ Skipped exchanges cannot be distilled later.\n"
+    )
+    typer.echo("How should existing exchanges be handled?")
+    typer.echo("  [1] Skip all — only distill future sessions")
+    typer.echo(f"  [2] Distill last {DEFAULT_DISTILL_RECENT} — recent history only")
+    typer.echo(f"  [3] Distill all — {total} exchanges (token consumption)")
+    typer.echo("  [4] Custom — specify how many exchanges to distill")
+
+    choice = typer.prompt("Choice", default="1")
+
+    if choice == "1":
+        return total, "recent"
+    elif choice == "3":
+        return 0, "recent"
+
+    if choice == "2":
+        skip = max(0, total - DEFAULT_DISTILL_RECENT)
+    elif choice == "4":
+        n = typer.prompt("How many exchanges to distill?", type=int)
+        skip = max(0, total - n)
+    else:
+        typer.echo("Invalid choice. Skipping all existing exchanges.")
+        return total, "recent"
+
+    strategy = _ask_distill_priority() if skip > 0 else "recent"
+    return skip, strategy
+
+
+app.command()(index)
+app.command()(distill)
+app.command()(search)
+app.command()(context)
+app.command()(status)
+app.command()(show)
+app.command()(dump)
+app.command()(prime)
+app.add_typer(hook_app, name="hook")
+app.add_typer(server_app, name="server")

codeatrium/cli/distill_cmd.py

@@ -0,0 +1,76 @@
+"""loci distill コマンド"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+
+def distill(
+    limit: Annotated[
+        int | None,
+        typer.Option("--limit", "-n", help="処理する最大件数（省略時は全件）"),
+    ] = None,
+) -> None:
+    """未蒸留の exchange を claude -p で蒸留して palace_objects を生成する"""
+    import os
+
+    from codeatrium.config import load_config
+    from codeatrium.distiller import distill_all
+    from codeatrium.paths import db_path, find_project_root
+
+    root = find_project_root()
+    db = db_path(root)
+    cfg = load_config(root)
+
+    if not db.exists():
+        typer.echo("Not initialized. Run `loci init` first.", err=True)
+        raise typer.Exit(1)
+
+    lock_path = db.parent / "distill.lock"
+
+    # ロック取得: O_CREAT | O_EXCL で原子的に作成（TOCTOU 防止）
+    try:
+        fd = os.open(lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        os.write(fd, str(os.getpid()).encode())
+        os.close(fd)
+    except FileExistsError:
+        # 既存ロックのプロセスが生きているか確認
+        try:
+            existing_pid = int(lock_path.read_text().strip())
+            os.kill(existing_pid, 0)
+            typer.echo(
+                f"loci distill is already running (PID {existing_pid}). Exiting.",
+                err=True,
+            )
+            raise typer.Exit(0)
+        except (ValueError, ProcessLookupError, PermissionError):
+            # stale lock — 再取得
+            lock_path.unlink(missing_ok=True)
+            try:
+                fd = os.open(lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+                os.write(fd, str(os.getpid()).encode())
+                os.close(fd)
+            except FileExistsError:
+                typer.echo("loci distill: lost lock race after stale cleanup. Exiting.", err=True)
+                raise typer.Exit(0)
+
+    def _on_progress(cur: int, tot: int, error: str | None = None) -> None:
+        if error:
+            typer.echo(f"  [{cur}/{tot}] error: {error}", err=True)
+        else:
+            typer.echo(f"  [{cur}/{tot}] distilled", err=True)
+
+    try:
+        count = distill_all(
+            db,
+            limit=limit,
+            model=cfg.distill_model,
+            on_progress=_on_progress,
+            project_root=str(root),
+            distill_min_chars=cfg.distill_min_chars,
+        )
+        typer.echo(f"Distilled {count} exchange(s).")
+    finally:
+        lock_path.unlink(missing_ok=True)

codeatrium/cli/hook_cmd.py

@@ -0,0 +1,24 @@
+"""loci hook install コマンド"""
+
+from __future__ import annotations
+
+import typer
+
+hook_app = typer.Typer(help="Claude Code hook 管理")
+
+
+@hook_app.command("install")
+def hook_install() -> None:
+    """Claude Code の Stop / SessionStart フックに loci を登録する。
+
+    Stop (async):      loci index    — 毎ターン・ノンブロッキング
+    SessionStart:      loci distill  — CC起動・/clear・/resume・compact 時
+                       claude --print サブセッションは SessionStart を発火しないためループなし
+    """
+    from codeatrium.config import load_config
+    from codeatrium.hooks import install_hooks
+    from codeatrium.paths import find_project_root
+
+    cfg = load_config(find_project_root())
+    _changed, message = install_hooks(batch_limit=cfg.distill_batch_limit)
+    typer.echo(message)

codeatrium/cli/index_cmd.py

@@ -0,0 +1,62 @@
+"""loci index コマンド"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+
+def index(
+    path: Annotated[
+        Path | None, typer.Option(help="インデックス対象ディレクトリ")
+    ] = None,
+    verbose: Annotated[bool, typer.Option("--verbose", "-v")] = False,
+) -> None:
+    """未処理の .jsonl を処理して exchanges テーブルに登録する（FTS5 自動同期）"""
+    from codeatrium.config import load_config
+    from codeatrium.db import init_db
+    from codeatrium.indexer import index_file
+    from codeatrium.paths import (
+        db_path,
+        find_project_root,
+        resolve_claude_projects_path,
+    )
+
+    root = find_project_root()
+    db = db_path(root)
+
+    if not db.exists() and not (root / ".codeatrium").exists():
+        typer.echo("Not initialized. Run `loci init` first.", err=True)
+        raise typer.Exit(1)
+
+    init_db(db)
+    cfg = load_config(root)
+
+    target_dir = path or resolve_claude_projects_path(root)
+    if target_dir is None:
+        typer.echo("Claude projects dir not found. Use --path to specify.", err=True)
+        raise typer.Exit(1)
+
+    jsonl_files = list(target_dir.rglob("*.jsonl"))
+    if not jsonl_files:
+        typer.echo("No .jsonl files found.")
+        return
+
+    total_exchanges = 0
+    files_with_new = 0
+    for jsonl in jsonl_files:
+        count = index_file(jsonl, db, min_chars=cfg.index_min_chars)
+        if count == 0:
+            continue
+        files_with_new += 1
+        if verbose:
+            typer.echo(f"  {jsonl.name}: {count} exchanges")
+        total_exchanges += count
+
+    if total_exchanges == 0:
+        typer.echo("Nothing new to index.")
+        return
+
+    typer.echo(f"Indexed {files_with_new} file(s), {total_exchanges} exchange(s).")

codeatrium/cli/prime_cmd.py

@@ -0,0 +1,90 @@
+"""loci prime — SessionStart Hook でエージェントのコンテキストにインストラクションを注入する"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+BEGIN_MARKER = "<!-- BEGIN CODEATRIUM -->"
+END_MARKER = "<!-- END CODEATRIUM -->"
+
+PRIME_TEXT = """\
+## Past Memory Search (codeatrium)
+
+Use `loci search` to find past implementations, decisions, and code locations.
+
+### When to use
+
+- When asked "where did we implement X?" or "where is X?"
+- When checking if a similar bug was fixed before
+- When verifying if a feature already exists
+- When looking up the reasoning behind a past design decision
+- Before editing code you lack context about — use `loci context --symbol` to review past discussions
+- Before refactoring or changing the behavior of a function — use `loci context --symbol` to check past design decisions
+
+### Commands
+
+```bash
+# Semantic search
+loci search "query" --json --limit 5
+
+# Reverse lookup: code symbol -> past conversations
+loci context --symbol "symbol_name" --json
+
+# Retrieve verbatim conversation (use verbatim_ref from search results)
+loci show "<verbatim_ref>" --json
+```\
+"""
+
+CLAUDE_MD_SECTION = f"""\
+{BEGIN_MARKER}
+## Past Memory Search (codeatrium)
+
+IMPORTANT: Command usage is injected automatically at session start via `loci prime` (SessionStart hook).
+If not in context, run `loci prime`.
+
+### Rules
+
+1. **Search before implementing** — always check if something was discussed or built before starting work.
+2. **Check symbols when you lack context** — run `loci context --symbol` before changing a function you don't have enough background on.
+3. **Use technical terms** — queries with exact symbol names, error messages, or parameter names yield better results.
+4. **Follow up with `loci show`** — when `exchange_core` is ambiguous, fetch the full verbatim conversation.
+{END_MARKER}\
+"""
+
+
+def prime() -> None:
+    """エージェント向けインストラクションを stdout に出力する。
+
+    SessionStart Hook で自動実行され、エージェントのコンテキストウィンドウに
+    使い方を注入する。CLAUDE.md にテンプレートを貼る必要がなくなる。
+    """
+    typer.echo(PRIME_TEXT)
+
+
+def inject_claude_md(project_root: Path) -> bool:
+    """CLAUDE.md にマーカー付きセクションを挿入・更新する。
+
+    Returns: True if file was modified.
+    """
+    claude_md = project_root / "CLAUDE.md"
+
+    if claude_md.exists():
+        content = claude_md.read_text()
+        if BEGIN_MARKER in content:
+            # マーカー内を更新
+            before = content[: content.index(BEGIN_MARKER)]
+            after = content[content.index(END_MARKER) + len(END_MARKER) :]
+            new_content = before + CLAUDE_MD_SECTION + after
+            if new_content == content:
+                return False
+            claude_md.write_text(new_content)
+            return True
+        else:
+            # 末尾に追加
+            claude_md.write_text(content.rstrip() + "\n\n" + CLAUDE_MD_SECTION + "\n")
+            return True
+    else:
+        claude_md.write_text("# CLAUDE.md\n\n" + CLAUDE_MD_SECTION + "\n")
+        return True

codeatrium/cli/search_cmd.py

@@ -0,0 +1,128 @@
+"""loci search / loci context コマンド"""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+
+def search(
+    query: Annotated[str, typer.Argument(help="検索クエリ")],
+    limit: Annotated[int, typer.Option("--limit", "-n", help="返す件数")] = 5,
+    json_output: Annotated[bool, typer.Option("--json", help="JSON で出力")] = False,
+) -> None:
+    """BM25(V) + HNSW(D) RRF でクエリに近い過去会話を返す"""
+    from codeatrium.embedder import Embedder
+    from codeatrium.paths import db_path, find_project_root
+    from codeatrium.search import search_combined
+
+    root = find_project_root()
+    db = db_path(root)
+
+    if not db.exists():
+        typer.echo("Not initialized. Run `loci init` first.", err=True)
+        raise typer.Exit(1)
+
+    embedder = Embedder()
+    query_vec = embedder.embed(query)
+    results = search_combined(db, query, query_vec, limit=limit)
+
+    if not results:
+        typer.echo("No results found.")
+        return
+
+    if json_output:
+        output = [
+            {
+                "exchange_core": r.exchange_core,
+                "specific_context": r.specific_context,
+                "rooms": r.rooms,
+                "symbols": r.symbols,
+                "verbatim_ref": r.verbatim_ref,
+            }
+            for r in results
+        ]
+        typer.echo(json.dumps(output, ensure_ascii=False, indent=2))
+    else:
+        for i, r in enumerate(results, 1):
+            typer.echo(f"\n[{i}] score={r.score:.4f}")
+            if r.exchange_core:
+                typer.echo(f"    {r.exchange_core}")
+            for sym in r.symbols[:2]:
+                typer.echo(f"    {sym['file']}:{sym['line']}  {sym['name']}")
+            if r.verbatim_ref:
+                typer.echo(f"    {r.verbatim_ref}")
+
+
+def context(
+    symbol: Annotated[
+        str, typer.Option("--symbol", "-s", help="シンボル名（部分一致）")
+    ],
+    limit: Annotated[int, typer.Option("--limit", "-n", help="返す件数")] = 5,
+    json_output: Annotated[bool, typer.Option("--json", help="JSON で出力")] = False,
+) -> None:
+    """シンボル名から関連する過去会話を逆引きする"""
+    from codeatrium.db import get_connection
+    from codeatrium.paths import db_path, find_project_root
+
+    root = find_project_root()
+    db = db_path(root)
+
+    if not db.exists():
+        typer.echo("Not initialized. Run `loci init` first.", err=True)
+        raise typer.Exit(1)
+
+    con = get_connection(db)
+    rows = con.execute(
+        """
+        SELECT
+            s.symbol_name,
+            s.symbol_kind,
+            s.file_path,
+            s.signature,
+            s.line,
+            e.id        AS exchange_id,
+            e.user_content,
+            e.agent_content,
+            p.exchange_core,
+            p.specific_context
+        FROM symbols s
+        JOIN palace_objects p ON p.id = s.palace_object_id
+        JOIN exchanges e ON e.id = p.exchange_id
+        WHERE s.symbol_name LIKE ?
+        LIMIT ?
+        """,
+        (f"%{symbol}%", limit),
+    ).fetchall()
+    con.close()
+
+    if not rows:
+        typer.echo("No results found.")
+        return
+
+    if json_output:
+        output = [
+            {
+                "symbol_name": r["symbol_name"],
+                "symbol_kind": r["symbol_kind"],
+                "file_path": r["file_path"],
+                "signature": r["signature"],
+                "line": r["line"],
+                "exchange_id": r["exchange_id"],
+                "exchange_core": r["exchange_core"],
+                "specific_context": r["specific_context"],
+                "user_content": r["user_content"],
+                "agent_content": r["agent_content"],
+            }
+            for r in rows
+        ]
+        typer.echo(json.dumps(output, ensure_ascii=False, indent=2))
+    else:
+        for i, r in enumerate(rows, 1):
+            typer.echo(f"\n[{i}] {r['symbol_kind']} {r['symbol_name']}")
+            typer.echo(f"    {r['file_path']}:{r['line']}")
+            typer.echo(f"    {r['signature']}")
+            if r["exchange_core"]:
+                typer.echo(f"    Core: {r['exchange_core']}")