Metadata-Version: 2.4
Name: agentlog-cli
Version: 0.1.0
Summary: Persistent decision memory for any project. Karpathy's LLM Wiki, productized.
Author-email: Ryan Alexander Alberts <ryan.a.alberts@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/RyanAlberts/agentlog
Project-URL: Repository, https://github.com/RyanAlberts/agentlog
Project-URL: Issues, https://github.com/RyanAlberts/agentlog/issues
Project-URL: Design notes, https://github.com/RyanAlberts/agentlog/blob/main/DECISIONS.md
Keywords: llm,cli,decision-log,memory,claude,anthropic,gemini,knowledge-management,agentic-ai,ai-memory,developer-tools
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.25.0
Requires-Dist: google-generativeai>=0.5.0
Dynamic: license-file

# agentlog

**Persistent decision memory for any project.** Three commands. One file. Zero frameworks.

Inspired by [Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — which proved that the best knowledge system is just well-structured text that an LLM maintains for you. This is that idea, shipped as a CLI you can install in 30 seconds.

## The problem

Every team has a "why did we decide this?" problem. Decisions live in Slack threads, Google Docs, people's heads, and nowhere useful. Six months later, you're re-litigating the same trade-off because no one remembers the reasoning.

## The fix

```bash
# Store a decision directly
agentlog remember "Chose DynamoDB over Postgres for session store — need <10ms at 10K RPS"

# Or use AI to summarize a decision from a file (e.g., using Simon Willison's 'llm' CLI)
agentlog remember "$(llm 'Summarize the key architectural decision made here' < meeting-notes.txt)"

# Retrieve relevant decisions
agentlog recall "database choices"

# Synthesize patterns across all decisions
agentlog reflect
```

That's it. Decisions are stored as JSONL (one per line, grep-friendly, version-controllable). Retrieval and reflection use Claude or Gemini to find relevant context and surface patterns.

## Install

```bash
pip install agentlog-cli
export ANTHROPIC_API_KEY="sk-..."   # or: export GEMINI_API_KEY="..."

agentlog remember "First decision logged"
```

That's it — Anthropic and Gemini SDKs are pulled in as dependencies, so a single `pip install` covers both providers.

> **Why `agentlog-cli`, not `agentlog`?** PyPI flagged the bare name `agentlog` as confusable with an unrelated logging package. The module, CLI binary, and GitHub repo are still `agentlog` — only the `pip install` target differs (same pattern as `pillow`/`PIL`, `beautifulsoup4`/`bs4`).

<details>
<summary>Run from source (for hacking on it)</summary>

```bash
git clone https://github.com/RyanAlberts/agentlog.git
cd agentlog
pip install -e .
agentlog remember "First decision logged"
```

</details>

## How it works

`remember` stores a decision as a JSON line with auto-generated tags:
```json
{"id": "20260415-213045", "timestamp": "2026-04-15T21:30:45", "text": "Chose DynamoDB over Postgres...", "tags": ["database", "performance", "infrastructure"]}
```

`recall` sends your query + all decisions to Claude (or Gemini) and gets back the relevant context with connections explained.

`reflect` asks Claude to find patterns, contradictions, and gaps across your entire decision history. Reflections are saved to `.agentlog/reflections.md` so they accumulate over time.

## Multi-model support

Defaults to Claude (Anthropic). Switch to Gemini per-command:

```bash
agentlog recall "API design patterns" --model gemini
```

Or set a default:
```bash
export AGENTLOG_PROVIDER=gemini
```

## Design philosophy

Read [DECISIONS.md](./DECISIONS.md) for the full rationale. The short version:

- **One file, not a framework.** 200 lines of Python. Read the whole thing in 5 minutes.
- **JSONL, not a database.** Grep-friendly, git-friendly, LLM-friendly.
- **Three commands, not ten.** Remember, recall, reflect. That's the whole API surface.
- **The LLM does the heavy lifting.** No embeddings, no vector DB, no RAG pipeline. The model reads all your decisions and finds the relevant ones. This works up to ~500 decisions before you'd need to add chunking.

## Inspired by

- [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) by Andrej Karpathy — the idea that LLMs should maintain your knowledge base
- [gbrain](https://github.com/garrytan/gbrain) by Garry Tan — persistent memory for Claude Code projects
- [Simon Willison's llm](https://github.com/simonw/llm) — proof that single-purpose CLI tools for LLMs are underrated

---

Built by [Ryan Alberts](https://github.com/RyanAlberts) — Staff PM working in Agentic AI.
