# MEMORY.md

Local LLC has no human continuity between sessions the way a human company has employees who
just remember things. Memory has to be written down deliberately, or it's lost. This document
defines the organization's memory system: what gets recorded, where, and by whom.

## Two tiers of memory

**Company memory** (`memory/`) — shared, cross-role, cross-project knowledge. Read by every
role during onboarding (`ONBOARDING.md`) and consulted whenever something feels like it should
already be known.

**Employee memory** (`employees/<role>/MEMORY.md`) — one role's own accumulated context: recurring
patterns it's noticed, mistakes specific to how that role operates, judgment calls it's made
before and the reasoning behind them. Not shared automatically with other roles — if something
in an employee's memory turns out to matter company-wide, promote it to `memory/` instead of
leaving it siloed.

## What lives in memory/

| File | Contents |
|---|---|
| `memory/company-memory.md` | Cross-cutting facts about how the company actually operates in practice — decisions about process itself, recurring organizational patterns, anything true company-wide that isn't already captured as policy in a root doc |
| `memory/architecture-memory.md` | Technical context that spans projects: shared infrastructure quirks, integration details between Gitea/Plane/ACT Runner discovered in practice, patterns worth reusing across projects |
| `memory/lessons-learned.md` | Retrospective output (`WORKFLOW.md`), incident postmortems, anything that answers "what would we do differently" |
| `memory/terminology.md` | Glossary — the vocabulary this company has actually settled on, so new agents and humans reading this repo don't have to infer meaning from context |

## What does NOT belong in memory

- Anything already true from reading the code, Git history, or Plane directly — memory
  supplements what's derivable, it doesn't duplicate it (same principle as `COMPANY.md`'s
  one-tool-one-job rule, applied to knowledge instead of systems).
- Task-level or sprint-level state — that's Plane's job (`PLANE.md`).
- Policy — if something is a rule everyone must follow, it belongs in the relevant root doc
  (`CODING_STANDARDS.md`, `SECURITY.md`, etc.), not buried in a memory file where it's easy to
  miss. Memory records *what happened and what was learned*, not *what the rule is*.
- Placeholder entries. An empty, honest "nothing recorded yet" beats a speculative entry no one
  has actually verified.

## Who writes to memory

Anyone can and should write to company memory when they learn something worth keeping — it is
not reserved for one role. In practice:

- Retrospectives feed `lessons-learned.md` — the Project Manager ensures this actually happens
  after every sprint close (`WORKFLOW.md`), but any role can add an entry when something notable
  happens outside the retro cadence.
- The Architect is the primary (not exclusive) writer to `architecture-memory.md`.
- The Documentation Engineer periodically reviews all of `memory/` for staleness and
  consolidation, the same discipline applied to any other documentation (`COMPANY.md` values).

## How to write a memory entry

Lead with the fact or decision, then why it matters, then how it should change future behavior.
A memory entry that only states what happened without why is hard to judge later when
circumstances have changed slightly — the "why" is what lets a future reader tell whether the
lesson still applies or whether their situation is actually different.

## Reading memory before acting on it

Memory can go stale — a lesson learned about a tool's old behavior may no longer apply after an
upgrade; an architectural note may describe a system that's since been replaced. Before acting
on a memory entry for something consequential, verify it against current reality (the code, the
current infrastructure, Plane's current state) rather than trusting the entry blindly. If it's
wrong, correct or remove it rather than leaving it to mislead the next reader.