tliner 0.1.4

🌟 Timeliner - AI's diary. MCP for tracking AI agent work with markdown log

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:

{
  "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:

---
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:

# 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)