# Sessions Logger

## Purpose

`Sessions Logger` is a lightweight, repo-local context migration aid.

Its role is to capture the important state of an ongoing agent-assisted session in a form that can travel with the repository across machines, tools, or future sessions.

It is **not** the source of truth for the project. The source of truth remains the codebase, tests, docs, issue tracker, specs, handoff files, and other primary artifacts. The logger exists to reduce context loss, not to replace proper project documentation.

## Why this file exists

Agent session memory is hard to migrate cleanly.

Even when the full repo, documents, datasets, and static artifacts are available, a lot of useful working context can still be lost between:

- machine changes
- new chat sessions
- agent switches
- interruptions mid-task
- long investigations with partial conclusions

A `sessions_logger.md` file gives the agent a simple place to periodically record what happened, what changed, what was decided, what remains uncertain, and what should happen next.

## Design principles

### 1. Lightweight over exhaustive

This file should stay easy to update. Prefer concise, high-signal entries over long narratives.

### 2. Not app-specific

This logger is intentionally generic. It should work for software projects, notebooks, research workflows, engineering analysis, documentation work, or mixed projects.

### 3. Useful for migration

Entries should help a future agent quickly answer:

- What was done?
- Why was it done?
- What files or artifacts changed?
- What decisions were made?
- What is still unresolved?
- What should be done next?

### 4. Secondary, not authoritative

The logger may drift from reality.

Reasons include:

- logging started after the project already existed
- the agent forgot to log some work
- a third party changed the repo without updating the log
- implementation changed after a decision was logged
- an earlier direction became obsolete

Because of this, the agent should treat the logger as a navigation aid and summary layer, then cross-check against the actual repo and current artifacts.

### 5. Obsolescence should be explicit

When a previous idea, implementation path, or conclusion is no longer valid, do not silently overwrite history. Keep a short note that it became obsolete and why.

## Recommended agent behavior

When using `sessions_logger.md`, the agent should:

1. read the latest entries first
2. treat the file as guidance, not proof
3. cross-reference the repo, specs, tests, and current files
4. log major work periodically during the session
5. log both progress and unresolved blockers
6. note when earlier plans or assumptions became obsolete
7. keep entries short, factual, and easy to scan

## What to log

A good entry usually includes:

- date and optional time marker
- high-level work completed
- important files created or modified
- decisions or conclusions reached
- known issues or blockers
- next recommended step

Optional but often useful:

- commands or workflows discovered to matter
- gotchas found during debugging
- assumptions made
- external dependencies or environment constraints
- references to handoff/spec files

## What not to log

Avoid turning this into a duplicate of full project documentation.

Usually do **not** include:

- large code dumps
- long meeting-style transcripts
- detailed specs already stored elsewhere
- exhaustive commit-by-commit narration
- information that is trivial or obvious from the repo state

## Suggested update rhythm

Update the logger:

- after finishing a meaningful chunk of work
- before ending a session
- after resolving an important bug
- after locking a significant decision
- when discovering a blocker that future sessions must know

For long sessions, periodic logging is better than trying to reconstruct everything at the end.

## Suggested structure

```md
# Sessions Logger

## YYYY-MM-DD
- Did X.
- Changed Y.
- Decided Z because ...
- Known issue: ...
- Next: ...

## YYYY-MM-DD (later)
- Follow-up change ...
- Obsolete: earlier plan to do X is no longer preferred because ...
```

## Entry template

```md
## YYYY-MM-DD
- Completed:
  - ...
- Changed artifacts:
  - ...
- Decisions:
  - ...
- Known issues / blockers:
  - ...
- Next:
  - ...
```

## Compact entry template

```md
## YYYY-MM-DD
- Completed: ...
- Changed: ...
- Decision: ...
- Blocker: ...
- Next: ...
```

## Obsolescence pattern

Use short explicit notes such as:

```md
- Obsolete: earlier plan to use X is no longer preferred after Y was discovered.
- Obsolete: prior assumption that file A was the source of the bug was not confirmed.
- Superseded: manual workflow replaced by automated helper in `tools/...`.
```

## Example based on a real project-style log

A practical sessions log can look like the attached demo, which records created helpers, notebook changes, tests, refactors, and a remaining bug to follow up on. It shows the right level of detail for this pattern: concrete enough to migrate context, but still concise. fileciteturn1file0

## Recommended positioning in a repo

Typical locations:

- repo root: `sessions_logger.md`
- `docs/sessions_logger.md`
- `llm/sessions_logger.md`

Choose one stable location and keep it consistent so future agents can find it quickly.

## Final note for future agents

This file is a context bridge, not a contract.

Use it to accelerate understanding, then verify against the current repository state before making decisions or implementing changes.

