PHPackages                             voku/agent-session - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. voku/agent-session

ActiveLibrary[Utility & Helpers](/categories/utility)

voku/agent-session
==================

Working-memory layer for coding agents: per-task session plans, decisions, assumptions, checkpoints, claim metadata, and retention.

0.0.1(today)10MITPHPPHP ^8.3CI passing

Since Jun 20Pushed todayCompare

[ Source](https://github.com/voku/agent-session)[ Packagist](https://packagist.org/packages/voku/agent-session)[ Docs](https://github.com/voku/agent-session)[ RSS](/packages/voku-agent-session/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (2)Versions (2)Used By (0)

Agent Session (`voku/agent-session`)
====================================

[](#agent-session-vokuagent-session)

The **working-memory** layer of the governed agentic-coding loop.

A *task* is durable intent. A *session* is the temporary, mutable context an agent needs to finish that task: the plan, the assumptions it had to make, the decisions it took, the validation it ran, and resumable checkpoints. Working memory is meant to be volatile — it helps complete the current task and then it gets pruned. It is **not** project memory, and it must not quietly become durable architecture.

This package keeps that layer explicit, claimable, and bounded.

What it manages
---------------

[](#what-it-manages)

Each session is one directory under a sessions root (default `session_plan/`):

```
session_plan/
  2026-06-07-remove-session-access/
    session.json        # metadata: task id, status, claim, base commit, checkpoints
    plan.md
    assumptions.md
    decisions.md
    validation.md
    checkpoints/
      index.md
      001-discovery.md

```

`session.json` carries the **claim metadata** that makes parallel agents safe: `claimed_by`, `claimed_at`, and `base_commit`.

Requirements
------------

[](#requirements)

RequirementVersionPHP8.3 or newerInstall
-------

[](#install)

```
composer require voku/agent-session
```

CLI
---

[](#cli)

```
agent-session start --task task.002.remove-session-access --by lars --base-commit abc123
agent-session claim 2026-06-07-remove-session-access --by lars      # refuses a live claim by someone else unless --force
agent-session checkpoint 2026-06-07-remove-session-access --title "Implementation" --body "Updated the primary service."
agent-session record 2026-06-07-remove-session-access --kind decision   --title "Keep change module-scoped" --body "..."
agent-session record 2026-06-07-remove-session-access --kind assumption --title "Missing-context behaviour" --body "..."
agent-session close 2026-06-07-remove-session-access --status done
agent-session list --status active
agent-session show  2026-06-07-remove-session-access

# retention: working memory must be able to disappear
agent-session prune --keep-days 30 --status done,dropped --dry-run
```

Use `--root PATH` to point at a sessions directory other than `/session_plan`.

Where it fits
-------------

[](#where-it-fits)

This is one layer of the loop. It pairs with:

- `voku/agent-kanban` — the durable tasks the sessions serve.
- `voku/agent-learning` — findings/proposals distilled *from* a finished session.
- `voku/agent-recall-compiler` — the briefing compiled *before* a session.
- `voku/agent-loop` — the unified `agent-loop` binary that exposes all of them (`agent-loop session …`).

Development
-----------

[](#development)

```
composer install
composer ci   # validate + phpunit + phpstan (level 8)
```

License
-------

[](#license)

MIT — see [LICENSE](LICENSE).

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance100

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

0d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/6456fe693db197c458272cb758bf78958bc7d3e787ccd59db4bf3cf41654316a?d=identicon)[voku](/maintainers/voku)

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/voku-agent-session/health.svg)

```
[![Health](https://phpackages.com/badges/voku-agent-session/health.svg)](https://phpackages.com/packages/voku-agent-session)
```

###  Alternatives

[elhebert/laravel-sri

Subresource Integrity hash generator for laravel

39241.9k](/packages/elhebert-laravel-sri)[mtdowling/burgomaster

Packages up PHP packages into zips and phars

2780.9k12](/packages/mtdowling-burgomaster)[francescomalatesta/laravel-circuit-breaker

A circuit breaker pattern implementation for the Laravel framework

2919.2k2](/packages/francescomalatesta-laravel-circuit-breaker)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)