# agentlog

> A command-line tool that stores project decisions as JSONL and uses Claude or Gemini to recall relevant decisions and reflect on patterns.

agentlog is a Python CLI by Ryan Alberts that keeps a persistent decision log for any project. Decisions are stored as JSONL lines, and Claude or Gemini is used to retrieve relevant decisions and surface patterns across them. It is published on PyPI as agentlog-cli (version 0.1.0, released April 17, 2026) under the MIT license.

## What It Is

agentlog is a decision-memory tool for teams and individuals who want to keep the reasoning behind choices instead of losing it in chat threads and documents. The README describes it as Karpathy's LLM Wiki idea shipped as a CLI with three commands: remember, recall, and reflect.

## How the workflow works

`remember` stores a decision as a JSON line with an id, timestamp, text, and auto-generated tags. Text can be typed directly or produced by piping a summary from another LLM CLI. `recall` sends a query plus all stored decisions to Claude or Gemini and returns the relevant context with connections explained. `reflect` asks the model to find patterns, contradictions, and gaps across the whole history, and saves the results to `.agentlog/reflections.md` so they accumulate.

## Design choices and model access

The project documents a deliberately minimal design: one file of roughly 200 lines of Python, JSONL storage that is grep- and git-friendly, and no embeddings, vector database, or RAG pipeline. The README states this approach works up to about 500 decisions before chunking would be needed. Claude is the default provider; Gemini can be selected per command with `--model gemini` or by setting `AGENTLOG_PROVIDER`.

## Setup path

Install with `pip install agentlog-cli` and set `ANTHROPIC_API_KEY` or `GEMINI_API_KEY`. Both provider SDKs are installed as dependencies. The package requires Python 3.9 or newer, and the CLI binary is named `agentlog`. It can also be run from source by cloning the repository and using `pip install -e .`.

## Features
- remember command stores decisions as JSONL with auto-generated tags
- recall command retrieves relevant decisions using Claude or Gemini
- reflect command finds patterns, contradictions, and gaps across decision history
- Reflections saved to .agentlog/reflections.md
- Multi-model support for Claude and Gemini via --model flag or AGENTLOG_PROVIDER
- Grep-friendly, version-controllable JSONL storage
- No embeddings, vector database, or RAG pipeline required

## Integrations
Anthropic Claude, Google Gemini, llm CLI by Simon Willison

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Version
0.1.0

## Links
- Website: https://pypi.org/project/agentlog-cli/
- Documentation: https://github.com/RyanAlberts/agentlog/blob/main/DECISIONS.md
- Repository: https://github.com/RyanAlberts/agentlog
- EveryDev.ai: https://www.everydev.ai/tools/agentlog