gingko-record

Gingko Record

Gingko persists observations and actions across sessions. A good step is read by future-you months later with no surrounding conversation — make it self-contained.

Command

gingko memory append-step "<observation>" "<action>"

The CLI auto-resolves the active session_id from ~/.gingko/. If no session is active, this is a silent no-op — surface that to the user instead of retrying. For structured args without shell escaping, use the MCP tool mcp__plugin_gingko_gingko__append_step with explicit session_id (get it via gingko memory session-id).

When to Record

• A bug fix — capture the root cause, not the symptom.
• A non-obvious decision — why option A over B.
• A meaningful refactor or rename.
• An investigation that yielded a finding (even if the bug stays open).
• An architectural choice, library selection, or schema/migration decision.
• A surprise — anything that violated your prior model of the code.

When NOT to Record

• Trivial Q&A with no code change.
• Reading files without acting on them.
• Mid-step before you have a result — wait until the result is in.
• Information trivially derivable from git log or current code.
• User preferences or workflow rules — those belong in CLAUDE.md / auto-memory, not Gingko.

Anatomy of a Good Step

Observation = the state of the world before you acted. Include the smallest unique anchor that lets future-you find the place again: file path, function name, error text, or invariant. Concrete over general.

Weak	Strong
"Tests were broken"	"Gingko.MemoryTest failed at lib/gingko/memory_test.exs:142 because start_session/1 rejected nil agent, but the schema marked it optional"
"Auth was buggy"	"Token refresh in AuthController.refresh/2 returned 401 when JWT skew window was 0; production set skew=30s via env"
"Looked at the code"	"Read lib/gingko/mcp/tools/recall.ex — it forwards to Gingko.Memory.recall/1 and never validates project_id length"

Action = what you decided/changed and why the alternatives were rejected. The "why" is the part that's expensive to recover later.

Weak	Strong
"Fixed it"	"Added when is_binary(agent) and agent != \"\" guard in start_session/1. Did not change the schema — that would break older clients"
"Refactored"	"Extracted summary rendering into Gingko.Summaries.MarkdownRenderer; three callers were duplicating headline+body. Kept the old function as a 1-line delegate to avoid churn in tests"
"Added a test"	"Added regression test at recall_test.exs:88 for empty project_id. Used assert_raise rather than assert match? because the contract is to crash, not return {:error, _}"

Granularity

One step per coherent decision. Don't bundle a five-step refactor into one giant action — recall returns whole nodes, so an over-long action becomes a wall of unrelated content. Don't fragment either: "renamed variable" alone is noise. Target one paragraph of observation, one paragraph of action.

Shell Escaping

The CLI takes positional arguments. Single-quote the body for content with shell-special characters:

gingko memory append-step \
  'Failed at lib/gingko/mcp/tools/recall.ex:42 — Repo.get(Project, id) returned nil when id was Unicode-normalized differently than at insert time' \
  'Added Unicode.normalize/2 on input in lib/gingko/projects.ex:18. Considered comparing normalized forms at query time but rejected — write-side normalization keeps reads simple'

If both quote styles appear in the content, switch to the MCP tool mcp__plugin_gingko_gingko__append_step with structured args.

Failure Modes

• No active session — session-id is empty, append-step is a no-op. The SessionStart hook owns lifecycle; tell the user it didn't fire, don't call start-session yourself.
• Service unreachable — append-step warns on stderr and exits 0. Note the lost step to the user; nothing is queued.
• Quoting truncation — if the recorded text looks cut off, fall back to the MCP tool.