Palimpsest

⚠️ Development Status: This project is undergoing a fundamental redesign based on learnings from initial development and user testing. A new approach is being developed that addresses core architectural limitations discovered during v0.0.x development.

This repository remains available for reference and learning purposes. Updates will be announced when the new direction is ready for public use.

Their model. Your code. Your work.

The Problem

Developer: "How did I fix that async timeout issue last month?"
AI: "I don't remember your previous conversations..."
Developer: *scrolls through 47 chat histories* 😵‍💫

The Solution

What if your AI coding assistant could learn from every session you've ever had?

Palimpsest captures the traces of your AI collaboration sessions. The breakthrough moments. The dead ends. The "aha!" discoveries.

Your debugging wisdom, preserved.

Warning: This project is in early development. APIs are unstable and subject to change.

Get Started

# Clone the repository
git clone https://github.com/davidgibsonp/palimpsest.git
cd palimpsest

# Install with uv
uv sync

CLI Usage

# Initialize palimpsest in your project
palimpsest init

# Add a trace from a JSON file
palimpsest add trace_file.json

# Search your traces
palimpsest search "full-text search"

# List recent traces
palimpsest list

# Show detailed trace information
palimpsest show <trace-id>

# See collection statistics
palimpsest stats

Example Trace Data

echo '{
  "problem_statement": "How to optimize database queries in Django ORM?",
  "outcome": "Implemented select_related and prefetch_related optimizations",
  "execution_steps": [
    {
      "step_number": 1,
      "action": "analyze", 
      "content": "Profiled slow queries using Django Debug Toolbar"
    },
    {
      "step_number": 2,
      "action": "implement",
      "content": "Added select_related for foreign keys, prefetch_related for many-to-many"
    }
  ],
  "tags": ["django", "orm", "performance", "optimization"],
  "domain": "backend"
}' > trace_file.json

MCP Server for AI Agents

# Start MCP server for AI integration
palimpsest server start

# AI agents can now use 5 MCP tools:
# - create_trace(), search_traces(), get_trace()
# - list_traces(), get_stats()

Features

🔬 Local-first - Your traces stay on your machine
🔍 Searchable - Fast full-text search with SQLite FTS5
🤝 Shareable - Help others (when you want to)
🧠 Smart - AI assistants that actually remember and learn
⚡ Fast - <1s response time for typical operations
🔌 Dual Interface - CLI for humans, MCP for AI agents

Documentation

• Quick Start Guide - Get up and running in minutes
• Interface Documentation - CLI and MCP Server usage
• API Reference - Complete command and tool reference
• Architecture Overview - Technical implementation details

Get Involved

⭐ Star to follow progress 💬 Questions? Ideas? Open an issue

---

Like a palimpsest, where traces of previous writings remain beneath new text.