Metadata-Version: 2.4
Name: tliner
Version: 0.1.4
Summary: 🌟 Timeliner - AI's diary. MCP for tracking AI agent work with markdown log
Author-email: "sinai.io" <r@sinai.io>
License: Proprietary
Keywords: ai-agents,fastmcp,logging,markdown,mcp,milestones
Requires-Python: >=3.10
Requires-Dist: fastmcp==2.12.2
Requires-Dist: loguru==0.7.3
Requires-Dist: pydantic==2.11.7
Requires-Dist: python-frontmatter==1.1.0
Requires-Dist: typer==0.17.4
Provides-Extra: dev
Requires-Dist: pytest-mock==3.15.0; extra == 'dev'
Requires-Dist: pytest==8.4.2; extra == 'dev'
Description-Content-Type: text/markdown

# Timeliner

Auto-documenting memory layer for AI coding agents. Timeliner logs your AI development sessions as timestamped markdown files, giving AI agents perfect recall of past decisions, implementations, and context.

## Feature Highlights

- **Zero-friction logging** - AI agents auto-save work via `/save` command
- **Markdown storage** - Human-readable logs with YAML frontmatter
- **MCP integration** - Works with Claude Code, Cline, and other MCP-enabled tools
- **Timestamp-based IDs** - Precise microsecond task IDs for reliable tracking
- **Rich context** - Capture outcomes, tags, metadata (PRs, commits, issues)

## Use Cases

**Software Development:**
- Document bug fix decisions and attempted solutions
- Track refactoring steps and rationale across sessions
- Log feature implementation progress with context for handoffs
- Record code review findings and resolution strategies

**Research & Learning:**
- Maintain experiment logs with results and insights
- Build a learning journal of concepts explored
- Track hypothesis evolution in technical investigations
- Document library/API exploration findings

## Installation

### 1. Configure MCP Server

Add to your MCP config:

```json
{
  "mcpServers": {
    "timeliner": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "uv tool run tliner serve"
      ],
      "env": {
        "TIMELINER_WORK_FOLDER": "${PWD}/docs",
      }
    }
  }
}
```

### 2. Add `/save` Command (Optional but Recommended)

Create `.claude/commands/save.md` in your project:

```markdown
---
description: "Save findings/outcomes into a Timeline"
---
# Save Command
Execute the save operation according to the next rules.
## Flow
1.  **Generate Content**:
    *   Generate the outcomes for the current step following the "Content Structure" and "Rules".
2.  **Save to Timeliner**:
    *   Call `mcp__timeliner__save_step` with the following parameters:
        *   `task_id`: Use the memorized `task_id` if you have one. If this is the first time saving for this task, send an **empty string** (`""`). The system will create a new task and return the new `task_id`.
        *   `title`: Up to 5 words which represent essence of the step.
        *   `outcomes`: The exact content that you just generated.
    *   **VERY IMPORTANT**: If a new `task_id` is returned, you MUST memorize it for all future `save_step` calls for this task.
    
## Content Structure

1. **Summary**: Describe current step summary and general flow of investigation.
2. **Facts**: Main goal is describing outcomes as facts with GREAT details (not only summary).
3. **User Input**: Note ALL user's input and direction they want to go.
4. **Resources**: Note ALL resources used (files, links, tools, commands, etc) with direct links (full path/URL/command).

## Rules
1. **Avoids**: NO hypothesis, NO assumptions, NO speculations, NO generalizations. Facts ONLY.
2. **Evidence**: Including evidences for statements is mandatory:
    - Link to source files with line numbers: `[cmd line flags](../src/go/flags.go#L94)`
    - Links to external resources: `[config docs](https://example.com/docs/setup.html)`
3. **Structure**: 
    - All main sections within the `outcomes` (e.g., Summary, Facts, User Input) MUST start with a level 2 heading (`##`). Do NOT use level 1 headings.
    - Fit all outcomes in ONE chapter, don't split into several chapters.
    - Use sub-sections inside the `Facts` chapter only. Every fact must be the level 3 heading (`###`). 
    - Do not use level 4 and higher headings. Use multi-level numerated/bullet lists instead ("outliner" style). 
```

## Quick Start

### Using the `/save` Command

1. Run `/save` in your Agent Tool, when you feel you have made significant progress or decisions. 
2. File will be created/updated in your configured `TIMELINER_WORK_FOLDER`.

## MCP Tools Reference

## CLI Commands

For manual inspection and debugging:

```bash
# List all tasks
TIMELINER_WORK_FOLDER="${PWD}/aiplans" uv tool run tliner task-list

# Show all steps for a task
TIMELINER_WORK_FOLDER="${PWD}/aiplans" uv tool run tliner task-show <task_id>

# Run MCP server manually
TIMELINER_WORK_FOLDER="${PWD}/aiplans" uv tool run tliner serve

```

## Data Structure

- **Location:**  specified in `TIMELINER_WORK_FOLDER` env var
- **Filename:** `YYYY_MM_DD-HHMMSS-kebab-case-title.md`
- **Format:** Markdown with YAML frontmatter


## Configuration

### Environment Variables
- `TIMELINER_WORK_FOLDER`: Storage directory (default: `work/docs`)