lysofdev-ailog 1.0.0

File-based AI work log with semantic search — a git log for why AI agents made changes

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

# pip
pip install ailog

# uv (recommended)
uv tool install ailog

Requires Python 3.11+.

Setup

Get a free API key from Voyage AI (200M tokens/month free tier), then:

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:

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:

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

# 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

# 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

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:

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:

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

{
  "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 (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.

Development

Running tests

Install dev dependencies:

uv sync --extra dev

Then run the test suite:

uv run pytest

Run with coverage:

uv run pytest --cov

Linting and type checking

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.