Metadata-Version: 2.4
Name: lysofdev-ailog
Version: 1.0.0
Summary: File-based AI work log with semantic search — a git log for why AI agents made changes
Project-URL: Homepage, https://github.com/EstebanHernandez1523/ailog
Project-URL: Repository, https://github.com/EstebanHernandez1523/ailog
Project-URL: Issues, https://github.com/EstebanHernandez1523/ailog/issues
Author-email: Esteban Hernandez <hernandez.dev.services@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,devlog,llm,rag,semantic-search
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: numpy>=1.26
Requires-Dist: voyageai>=0.3
Provides-Extra: dev
Requires-Dist: hatch>=1.9; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# ailog

A file-based AI work log with semantic search. Think `git log`, but for _why_ AI agents made changes — searchable by meaning, not just keywords.

AI tools append entries describing their reasoning. You (or another agent) can later search those entries semantically to understand the codebase.

```
$ ailog search "why did we change the auth flow"

Top 3 results for: why did we change the auth flow

2026-05-18 14:22  claude  abc12345 [auth] [refactor]  score=0.941
Extracted JWT validation into shared middleware because three routes were
duplicating the same token-expiry logic. Silent 401s are now propagated correctly.

2026-05-17 09:11  claude  def67890 [auth]  score=0.812
Switched from session cookies to JWTs to support the mobile client, which
can't use httpOnly cookies cross-origin.
```

## Installation

```bash
# pip
pip install ailog

# uv (recommended)
uv tool install ailog
```

Requires Python 3.11+.

## Setup

Get a free API key from [Voyage AI](https://www.voyageai.com) (200M tokens/month free tier), then:

```bash
export VOYAGE_API_KEY="your-key-here"
```

Add this to your shell profile (`~/.zshrc`, `~/.bashrc`) to make it permanent.

## Getting started

Initialize ailog inside a git repository:

```bash
ailog init
```

This creates an empty `.ailog` log, an `ailog.toml` config, and adds the
regenerable embedding cache (`.ailog.cache/`) to `.gitignore`. Commit `.ailog`
and `ailog.toml`; the cache stays local.

## Usage

> Every command below accepts `--json` for machine-readable output (no colors,
> no decoration) — useful when another AI tool consumes the log.

### Adding entries

AI agents call `ailog add` after completing a task:

```bash
ailog add "Refactored the pricing engine because three services were computing
discounts independently with different rounding logic. Consolidated into
PricingService.calculate() with a shared RoundingMode enum."

# With tags and agent name
ailog add "Fixed race condition in order processor" \
  --agent claude \
  --tag bugfix \
  --tag async
```

### Searching

```bash
# Semantic proximity search
ailog search "why did we change the payment flow"

# Return more results
ailog search "database connection handling" --top 10

# Filter by tag before searching
ailog search "auth changes" --tag security
```

### Browsing the log

```bash
# Full chronological log (most recent first)
ailog log

# Compact one-liner per entry
ailog log --oneline

# Filter by tag or agent
ailog log --tag refactor
ailog log --agent claude --limit 20
```

### Stats

```bash
ailog stats
```

```
ailog stats
  File:     /your/repo/.ailog
  Entries:  47  (47 with embeddings)
  Span:     2026-04-01 → 2026-05-18

  Agents:
    claude: 38
    human: 9

  Tags:
    refactor: 14
    bugfix: 11
    auth: 6
```

### Committing the log

The `.ailog` file and `ailog.toml` are meant to be committed — that's the point. If your entries contain sensitive information, add `.ailog` to `.gitignore` instead.

In `inline` mode the embedding vectors live in `.ailog` and are large float arrays; you can hide them from diffs with a `.gitattributes` diff driver that strips the `embedding` field. In `cache` mode (the default) this is unnecessary — `.ailog` holds only text.

### Git hook

Link commits to the log entry that motivated them:

```bash
ailog install-hook
```

This installs a `post-commit` hook that appends an `Ailog-Entry: <id>` trailer to each commit message, so you can trace from `git log` directly to the reasoning behind a change. Re-running `ailog install-hook` is safe — it detects an existing ailog hook and does nothing.

## How it works

- The `.ailog` text log is the source of truth: append-only JSONL at the repo root
- Search embeds the query with the same model and ranks entries by cosine similarity
- No external database — everything lives in plain files you can commit

### Storage modes

`ailog.toml` selects how embeddings are stored:

| Mode              | `.ailog` contains        | Embeddings live in                  | Trade-off                                                       |
| ----------------- | ------------------------ | ----------------------------------- | --------------------------------------------------------------- |
| `cache` (default) | text entries only        | gitignored `.ailog.cache/` (SQLite) | clean diffs, small git history; re-embeds once on a fresh clone |
| `inline`          | text + embedding vectors | the committed `.ailog` itself       | works fully offline; git history grows with every entry         |

In `cache` mode the embedding cache is a **derived artifact** — never committed.
After cloning the repo onto a new machine, run:

```bash
ailog reindex
```

to rebuild it (`search` also rebuilds lazily on first use). Switching the
`model` in `ailog.toml` and running `ailog reindex` re-embeds everything.

### Entry format

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "ts": "2026-05-18T14:22:00+00:00",
  "agent": "claude",
  "tags": ["auth", "refactor"],
  "msg": "Extracted JWT validation into middleware..."
}
```

In `inline` mode the entry also carries an `"embedding"` field.

## Embedding model

Uses Voyage AI's `voyage-code-3` model, which is purpose-built for code and mixed code/text retrieval. Anthropic recommends Voyage AI for RAG use cases (they acquired the company).

### Rate limits on the free tier

Voyage AI's free tier allows **200M tokens/month** but caps requests at **3 RPM** until you add a payment method to your account. This limit applies across all API calls — `ailog add` and `ailog search` each consume one request, so running several commands back-to-back will trigger a `RateLimitError`.

To lift the cap: add a payment method at [dashboard.voyageai.com](https://dashboard.voyageai.com/) (the free token allowance still applies). After a few minutes, your rate limit increases to the standard tier.

If you hit the limit, ailog will print a clear error message and exit — no data is lost, and re-running the command once the window resets works fine.

## License

MIT — see [LICENSE](LICENSE).

## Development

### Running tests

Install dev dependencies:

```bash
uv sync --extra dev
```

Then run the test suite:

```bash
uv run pytest
```

Run with coverage:

```bash
uv run pytest --cov
```

### Linting and type checking

```bash
uv run ruff check .
uv run mypy src
```

CI runs the test suite (Python 3.11 and 3.12) plus `ruff` and `mypy` on every
push and pull request.
