# Team memory starter

Version 0.1.0. This is a portable definition bundle and a verified local synthetic exercise. It does not install a hosted service or supply production access controls.

## Files

For the full team-schema context, explore the [three visual kit maps](https://hamedtaheri.com/playbook/v0.1.0/reference/kit-architecture.html) and [machine-readable architecture](https://hamedtaheri.com/playbook/v0.1.0/reference/kit-architecture.json). They describe AI Coding Memory 1.2.0; this portable starter retains its own smaller definitions and local exercise.

- [Definitions](https://hamedtaheri.com/playbook/v0.1.0/kit/definitions.json): record identities, fields, task/session states and relations.
- [Synthetic team](https://hamedtaheri.com/playbook/v0.1.0/kit/examples/team.json): a fictional project, feature, people and three tasks.
- [Guidelines](https://hamedtaheri.com/playbook/v0.1.0/kit/guidelines.md): readiness, claims, decisions, evidence and handoffs.
- [Local adapter](https://hamedtaheri.com/playbook/v0.1.0/kit/local-memory.cjs) and [behavioral tests](https://hamedtaheri.com/playbook/v0.1.0/kit/local-memory.test.cjs).
- [Provider mapping](https://hamedtaheri.com/playbook/v0.1.0/kit/personize-mapping.md): what to map and qualify for Personize.

## Try it locally

Extract the starter bundle. Use Node.js 20 or newer. Choose a new private disposable directory; initialization refuses to overwrite existing records.

```sh
node kit/local-memory.cjs init ./private-memory-demo
node kit/local-memory.cjs get ./private-memory-demo task example/service/t/003
node kit/local-memory.cjs claim ./private-memory-demo example/service/t/003 agent-a 1
node kit/local-memory.cjs claim ./private-memory-demo example/service/t/003 agent-b 1
node --test kit/local-memory.test.cjs
```

The first claim succeeds. The second exits with an error because its version or ownership is stale. Re-read the task. The tests additionally launch two real competing processes and confirm exactly one winner.

The folder is private operational state, not a contribution. Add it to your project's ignore rules if you run the exercise inside a repository. Node in a restricted Windows sandbox may require `--preserve-symlinks --preserve-symlinks-main`; ordinary installations do not generally require these flags.

## Local contract

`new Memory(directory)` creates a private store. `create(type,key,data)` refuses overwrite. `get(type,key)` returns a record or null. `update(type,key,patch,expectedVersion)` rejects a changed version. `claim(taskKey,owner,expectedVersion)` atomically requires backlog and no owner.

The store serializes writes with a directory lock and commits by rename. A busy store returns an error: re-read and retry. If a process crashes while holding the lock, recovery is manual after confirming the owning process has stopped. This is a local-filesystem exercise; shared network filesystems and distributed hosts are outside its qualified scope. It has no semantic recall, encryption, permission enforcement or lease expiry.

Task dependencies and acceptance in the fixture are reference data. The adapter demonstrates record/claim mechanics; it does not implement dependency scheduling or decide whether acceptance is satisfied. An orchestrator must apply those rules.

## Adoption exercise

Task 001 changes a fictional schema. Task 002 depends on 001. Task 003 is independent. Claim 003, record a missing-input handoff, resolve it through a decision, re-read the record, and update using its latest version. Attach verification before marking acceptance. Use the [handoff](https://hamedtaheri.com/playbook/v0.1.0/templates/handoff.md) and [acceptance](https://hamedtaheri.com/playbook/v0.1.0/templates/acceptance.md) forms.

For a production backend, qualify stable identities, atomic claims, stale-session policy, read/write permissions, retrieval scope, pagination, evidence links and non-destructive schema installation. Use the backend's native transaction/version mechanism instead of imitating the local lock across distributed machines.