DiamondLightSource / DiamondLightSource/smartem-devtools
Make Claude's project knowledge portable: private memory/transcripts, derived public AGENTS.md
- Lingua principale
- TypeScript
- Stelle
- 0
- Fork
- 0
- Metriche di merge delle PR
- Nessuna PR unita negli ultimi 30g
Descrizione
Rescoped. The problem is unchanged and has become urgent - none of the three approaches below
was implemented, and a workstation migration is now imminent. The solution has changed: rather
than syncing the memory directory into this repository, the knowledge is split into a **private
tier** and a **public artefact derived from it**.
## Current state
- `~/.claude/projects/-home-vredchenko-dev-ERIC/memory/` is a plain directory, not a symlink.
It holds **32 memory files, ~204 KB**.
- The same project directory holds **35 session transcripts, ~127 MB** (238 MB across all
projects).
- No `claude-code/memory/` exists in this repository.
- `ERIC/CLAUDE.md` - the file that orients every session - lives in a workspace root that is
**not a git repository**, so it is itself unversioned and machine-local.
All of this exists only on the workstation being replaced.
## Why the original recommendation no longer works
Approach A proposed symlinking the memory directory into this repository, noting at the time
that the memory set "looks clean - generic professional content only". That is no longer true.
The current set includes personal working preferences and contract status, notes on which
colleague owns which environment and gaps in that knowledge, handover-risk notes about
uncommitted work, and content derived from a document marked `Classification: Internal`.
This repository is public. Committing that set would be a disclosure, and no amount of
pre-commit review makes an auto-writing directory safe to point at a public repository - the
failure mode is a memory written between review and commit.
## Approach: two tiers, with derivation rather than sync
**Private tier - the raw material.** Memory files and session transcripts. Lives in the private
forge, not on GitHub. The natural home is alongside the workstation-as-code repository, since a
symlinked memory directory is workstation configuration.
**Public tier - `AGENTS.md`.** A curated, tool-agnostic instruction file in the repository,
*written from* the private tier rather than synced from it. It carries what a future developer
or agent genuinely needs - project conventions, architecture facts, repository layout,
established decisions - and nothing personal, internal-classified, or about colleagues.
The essential property is that **the public artefact is derived by a deliberate editorial step**.
Nothing flows automatically from private to public, so no automated write can leak.
## Cautions that must be handled
**Transcripts contain known secrets.** This is not hypothetical: #199 records that a raw
`GRAYLOG_PASSWORD_SECRET` was printed into a session's tool output and notes that the value
"lives in the Claude Code transcript for that session". Transcripts therefore need scrubbing or
encryption before being stored anywhere, including in a private repository. Treat them as
sensitive artefacts rather than as logs.
**127 MB is archive-shaped, not git-shaped.** Committing transcripts directly will make the
repository unpleasant to clone and will grow without bound. Options: store them outside git with
a backup mechanism, use LFS, or retain only a rolling window. Memory files (204 KB) have no such
problem and can be versioned normally.
**`ERIC/CLAUDE.md` needs a home too.** It is currently unversioned and would be lost with the
machine. It is also the most obvious seed for `AGENTS.md` - much of it is already the curated,
impersonal content the public tier wants.
## Work
- Decide the private tier's location and whether transcripts are versioned, archived, or pruned.
- Symlink `~/.claude/projects/-home-vredchenko-dev-ERIC/memory/` to the private location, and
document the step so it can be repeated on the new workstation and any future one.
- Triage the current 32 memory files into "would belong in a public `AGENTS.md`" and "private
only". This is the actual work, and the original issue assumed it away.
- Write `AGENTS.md` from that first group plus `ERIC/CLAUDE.md`.
- Decide how `AGENTS.md` and `CLAUDE.md` relate - whether one is canonical and the other refers
to it, or whether `CLAUDE.md` is retired in favour of the tool-agnostic name. Note there is
already an `AGENTS.md` precedent elsewhere in the workspace, under `repos/OpenHack/`.
- Decide the refresh cadence for the derivation, since a derived artefact goes stale silently.
## Still open from the original issue
- Other Claude Code projects outside ERIC have their own local memory directories - out of
scope here, but the same problem.
- Whether a hook should surface uncommitted memory changes during normal git workflow.
Guida per i contributori
Nessuna guida per i contributori indicizzata per questo repository
Valutazione
Questa issue non è ancora stata valutata.