Skip to content

README.md

Latest commit

 

History

History
82 lines (61 loc) · 3 KB

README.md

File metadata and controls

82 lines (61 loc) · 3 KB

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