Session Ledger

Session Ledger is a self-hosted developer memory system that captures work sessions, preserves intent, and makes it easier to resume coding without rebuilding context from scratch.

Status

This repository currently contains:

• Product requirements and technical design docs
• An implementation plan for the MVP
• A FastAPI backend scaffold with database-backed endpoints
• An initial Alembic migration
• A CLI for creating projects, sessions, notes, command events, and workspace snapshots
• Shell helpers for repo-aware start, resume, note capture, snapshots, and command logging
• Local development config for Postgres, Redis, and optional Ollama

Core Product Idea

Instead of only helping write code, Session Ledger focuses on remembering:

• what a developer was trying to do
• what files and commands were involved
• what errors or blockers happened
• what likely comes next

Proposed MVP

• Capture session metadata by project and repo
• Ingest terminal commands, notes, and git-related events
• Capture workspace snapshots so resume summaries can point back to touched files
• Generate and persist a session summary and next-step recommendations
• Show a "resume work" view for a repo or branch
• Support keyword and semantic search across sessions

Repository Layout

• docs/ product and architecture documents
• backend/ FastAPI service scaffold
• frontend/ frontend planning notes and structure placeholder
• infra/ local infrastructure definitions and environment examples

Next Steps

1. Replace create_all() startup setup with migration-first lifecycle
2. Promote sessions.repository_id to a real foreign key and tighten schema integrity
3. Replace ad hoc filesystem snapshots with git-aware diff capture when a repo exists
4. Add a minimal web UI once Node is installed
5. Add semantic search and provider-backed AI summaries

Local Development

The backend is designed around Python 3.13.

Suggested startup flow once dependencies are installed:

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
alembic upgrade head
uvicorn app.main:app --reload

Example CLI usage:

python3 cli/session_ledger.py project create --name "Session Ledger" --slug "session-ledger"
python3 cli/session_ledger.py repository register-current --project-slug session-ledger
python3 cli/session_ledger.py session start-current --project-slug session-ledger --reuse-open
python3 cli/session_ledger.py note add --session-id <session_id> --text "Added persisted summaries."
python3 cli/session_ledger.py command run --session-id <session_id> -- python3 -m py_compile backend/app/main.py
python3 cli/session_ledger.py workspace snapshot-current --project-slug session-ledger
python3 cli/session_ledger.py session detail --session-id <session_id>
python3 cli/session_ledger.py resume --project-slug session-ledger --current-repo
python3 cli/session_ledger.py session close --session-id <session_id>

Infrastructure plan lives in:

• docs/ARCHITECTURE.md
• infra/docker-compose.yml