Skip to content

use-guide.md

Latest commit

 

History

History
165 lines (109 loc) · 7.31 KB

use-guide.md

File metadata and controls

165 lines (109 loc) · 7.31 KB
Raw

engram — Use Guide (plain English)

Read this if you want to know what engram is for, and exactly how and when to use it. No tech background needed.

The big idea (the one-paragraph version)

You use more than one AI helper — Claude Code, Cursor, Codex, Gemini. They are smart, but the moment you close a chat, everything you taught them is gone. Next time, they start from zero. You re-explain your project. You re-explain decisions you already made. You watch them make the same mistake you already fixed last week. It is annoying and it wastes time.

engram is a shared notebook that all your AI helpers can read and write to. It lives inside your project folder. Every helper sees the same notebook. When one helper writes down a decision, the others can read it next time. The notebook is just plain text files — you can read them, and so can the helpers.

Think of it like this: your AI helpers have amnesia (they forget everything). engram is the cure.

What engram is NOT (so you don't expect the wrong thing)

  • It is not a chat history. It does not save your conversations.
  • It is not a place for everything. If something is already obvious from the code, or already written in your project notes, do not put it in engram. That would be copying for no reason.
  • It is not a to-do list. Don't store tasks here.
  • It is not magic. It searches by words, not by meaning. More on that below.

The four kinds of things you save

Every memory you save is one of four types. Picking the right type helps later.

1. decision — a choice you made, and why

Use this when you pick one way of doing something over another.

Example: "We use iron-session for login, not next-auth. We only have one admin user, so next-auth is too much."

If a future helper asks "why did we do it this way?", the answer is right here.

2. fix — the real reason something was broken

Use this when you spent time hunting a bug and found the true cause. This is gold, because bugs come back, and you do not want to solve the same puzzle twice.

Example: "The build was failing because prisma generate must run before next build. That is why the build command is prisma generate && next build."

3. preference — how you like things done

Use this for your style rules and habits.

Example: "All outreach copy in Korrin brand voice: direct, no hype, EU English spelling."

4. context — a load-bearing fact

Use this for things that are true and important, but don't fit the other three.

Example: "Phase 5 outreach is gated on Victor's approval. Do not auto-send anything."

When to save a memory (and when NOT to)

Save a memory when:

  • You just made a decision and want it to stick.
  • You found the real cause of a bug.
  • You set a preference or rule for how to work.
  • You learned something that future-you would pay to know.

Do NOT save a memory when:

  • It is already in the code. The code is the truth; don't copy it.
  • It is already in your project notes (like AGENTS.md or your wiki). Don't double up.
  • It is a small task ("fix this button today"). Use a to-do list for that.
  • It is trivial or obvious.

The rule of thumb: if a brand-new helper would get this wrong without the memory, save it. If they could figure it out by reading the code, don't.

How to use it — the two ways

Way 1: You type the commands (manual)

Open your terminal in your project folder and use these. (engramkit is the command name.)

Save a memory:

engramkit add "We use iron-session not next-auth
Single admin user only, so next-auth provider model is overkill." --type decision --tags auth,infra
  • The first line is the title. Make it short and clear. This is what shows up in lists.
  • The lines after it are the detail.
  • --type is one of: decision, fix, preference, context.
  • --tags are comma-separated words to help you filter later. Keep them simple.

Find memories later:

engramkit recall "auth login"

This searches all your memories and prints the best matches first, with the file path and a score.

See everything:

engramkit list                  # all memories
engramkit list --type fix       # just the bug root-causes
engramkit list --tag auth       # just the ones tagged auth

Delete one:

engramkit forget <id>

The <id> is the short code shown when you list (like 3df49472).

Way 2: Your AI helper does it for you (automatic)

After you run engramkit init once in your project, your AI helpers (Claude Code, Cursor, etc.) get two new tools: recall and remember.

  • They will recall (search) before they start hard work, so they don't repeat past mistakes.
  • They will remember (save) after a decision or fix, so future sessions inherit it.
  • When you start a new session, the whole index (a one-line summary of every memory) is shown to the helper automatically. No prompting needed.

You can also just ask: "remember this decision" or "recall what we decided about auth."

The most important search tip (read this)

engram searches by words, not by meaning. So:

  • If your memory says "DB", searching for "database" will not find it. Search for "db" instead.
  • Use the actual words that are in the memory.
  • Be specific. "prisma build order" beats "database stuff".

This is the one big limitation of version 1. Smarter "meaning" search is on the roadmap. For now: use the real words.

How engram fits with a bigger notes system (like Obsidian)

If you already keep a big notes vault (some people use Obsidian for this), do not copy everything into engram. They have different jobs:

  • Your big notes vault = the library. Deep, long, hand-written, cross-project. Read it when you need the full story.
  • engram = the quick sticky notes welded to the code. Short, sharp, auto-shown to helpers.

The best trick: save an engram memory that points into your vault.

Example: "Full security roadmap is in the vault: read korrin-security-roadmap.md for depth. WF1 and WF2 guards are shipped."

Now a helper can recall "security" and get the pointer in one second, instead of guessing which long file to read.

Setting it up in a new project (the short version)

  1. Open a terminal in your project folder.
  2. Run engramkit init. This creates a .engram/ folder and wires up your AI helpers.
  3. Commit the .engram/ folder (and the helper config files) to git, so it's saved with your project.
  4. Start saving memories with engramkit add ....
  5. Done. Your helpers now share a brain.

Golden rules (print these)

  1. Save the hard-won stuff. Decisions, root-causes, preferences, load-bearing facts.
  2. Don't save the obvious stuff. If the code already says it, leave it alone.
  3. First line = the title. Make it short and clear. It's what everyone sees first.
  4. Search with real words. "db", not "database" (if that's what you wrote).
  5. Recall before you decide. Always check what's already there before you re-decide.
  6. No secrets. This gets committed to git. Never put passwords, keys, or private data in it.
  7. Keep it tidy. Once a week, run engramkit list, and forget anything stale or wrong.

That's it. You now know everything you need to use engram well.