3.7 KiB
name, description
| name | description |
|---|---|
| Tembo | Tembo is the project memory (elephant never forgets). Reads .tembo/notes.md facts and .tembo/log.md change log. Use at session start, after discovering a non-obvious project fact, or when flushing a session before pausing. |
Tembo
Project memory. Elephant never forgets, but keep it small:
.tembo/notes.md durable facts, read at session start
.tembo/log.md short chronological log of meaningful changes
Project root = git rev-parse --show-toplevel, else the current directory. If
there is no .tembo/ yet, create it only when there is something worth
writing. Never write memory outside the project root.
Budgets
Hard limits, enforced on every write:
| File | Limit | Overflow |
|---|---|---|
notes.md |
40 lines | merge duplicates, then drop the least useful |
log.md |
60 lines | drop oldest |
If you cannot fit a fact, it is not worth keeping.
Format
One line per entry, newest last, - [YYYY-MM-DD] tag: text. Tags: hardware,
build, cmd, api, gotcha.
notes.md:
# Tembo memory
<!-- Durable, non-obvious facts. Max 40 lines. One per line. -->
- [2026-11-21] gotcha: KiCad 10 pin-header footprints put pad 1 at the origin, not the centre.
- [2026-11-21] cmd: KiCad python bindings only run under the bundled 3.9 interpreter.
log.md:
# Tembo log
<!-- One line per meaningful change. Max 60 lines. Newest last. -->
- [2026-11-21] Routed the carrier, DRC 0/0, exported gerbers.
Read
At the start of work in a project with .tembo/:
- Read
notes.mdin full. - Read the last ~20 lines of
log.mdfor recent context.
Do not announce that you read them. Use them silently.
Write
Append a notes.md line when a fact passes this test:
Would this have saved 10 minutes if I had known it at the start?
Good: non-obvious tool behaviour, hardware/board quirks, commands that are not in the README, decisions with a reason, traps.
Bad, do not write:
- anything obvious from the code,
git log, README or AGENTS.md - secrets, tokens, personal data, customer data
- code blocks, stack traces, file dumps, long URLs
- "created X" unless the why or a non-obvious constraint matters
- plans, TODOs, speculation
Append a log.md line when a meaningful unit of work is done: feature landed,
bug root-caused, board routed, dependency swapped. Not every file edit.
Never rewrite or reorder existing entries. Pruning to budget is the only edit allowed.
Remember (/tembo <fact>)
When invoked with an argument, treat it as a fact to keep:
- Read both files.
- Rewrite the argument into one line:
- [YYYY-MM-DD] tag: text. - Pick the closest tag; write it as stated, do not invent context.
- Dedupe against existing lines; append.
- Prune to budget. Confirm in one short line.
If the argument is too vague to be useful later, ask once for the missing detail instead of guessing.
Flush (/tembo with no argument)
Run this before pausing or ending a session.
- Review the session: what was discovered, what changed, what was verified.
- Read both files.
- Pick 0-5 facts that pass the test above and are not already recorded.
- Pick 0-4 log lines for meaningful changes.
- Dedupe against existing lines; merge near-duplicates.
- Append, prune to budget, keep one blank line after the HTML comment.
- Report two lines: facts added, log lines added. If nothing qualified, say
tembo: nothing worth keepingand write nothing.
Do not ask for confirmation. Do not paste file contents back; a short summary is enough.
Safety
- Never store secrets or credentials.
- Never delete
.tembo/or another author's facts wholesale. - If
.tembo/is gitignored, still follow the same format; it is just local.