Metadata-Version: 2.4
Name: tliner
Version: 0.1.7
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 decisions and rationale during coding sessions
- Track refactoring steps
- Log feature implementation progress

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

## Installation

### Automatic Setup (Claude)

- Run the installer command in your project root:
```bash
uvx --from tliner tliner-install
```

- Automatically configures `.mcp.json` and creates `/save` command in `.claude/commands/`
- Documents wil be stored in `docs/timeline/` by default.
- To specify a different storage folder, use `uvx --from tliner tliner-install --work-folder <PATH_TO_STORE_DOCS>`.

### Manual Setup

Add to `.mcp.json`:

```json
{
  "mcpServers": {
    "timeliner": {
      "type": "stdio",
      "command": "uvx",
      "args": ["tliner@latest", "serve"],
      "env": {"TIMELINER_WORK_FOLDER": "${PWD}/docs/timeline"}
    }
  }
}
```

Create `.claude/commands/save.md`:

```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` (`docs/timeline/` by default).

## CLI Commands

For manual inspection and debugging:

```bash
# List all tasks
TIMELINER_WORK_FOLDER="${PWD}/docs/timeline" uvx tliner@latest task-list

# Show all steps for a task
TIMELINER_WORK_FOLDER="${PWD}/docs/timeline" uvx tliner@latest task-show <task_id>

# Run MCP server manually
TIMELINER_WORK_FOLDER="${PWD}/docs/timeline" uvx tliner@latest 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`)
