memgineering 0.0.0 → 0.2.0

package/assets/MEMGINEERING.md

@@ -0,0 +1,135 @@
+---
+name: memgineering
+description: Use whenever the user refers to something they told you before, asks what was decided, or tells you something worth keeping. The memory lives in their own folder and outlives this session; check it before answering from guesswork, and write to it when you learn something durable.
+type: skill
+version: 0.2.0
+---
+
+# memgineering
+
+The user has a **brain** — a folder of their own notes that every AI tool they
+use can read and write through the `memgineering` CLI. It outlives this
+session and this tool. Treat it as the place where what they know actually
+lives, and this conversation as temporary.
+
+## When to reach for it
+
+**Start a session by asking what you are missing.** Before working in an
+unfamiliar folder, or when someone opens with "where were we", "what should I
+know", "I've been away":
+
+```
+memgineering resurface
+```
+
+No query — it ranks by what has been recalled here before, how recently, and
+which of their core notes have gone unread. It is the answer to a vague
+question that recall cannot serve, because there is nothing to search for yet.
+
+**Recall before answering** anything that sounds like it was settled before:
+
+- "what did we decide about…", "how do I deploy this again", "왜 이렇게 했더라"
+- any question about _their_ project, setup, preferences, or past reasoning
+- before repeating advice you have no evidence they wanted
+
+```
+memgineering recall "<the question, in their words>"
+```
+
+You get cards: title, one-line summary, and an `open:` handle. Open the one
+that matters rather than all of them.
+
+```
+memgineering open <handle>                 # claims behind the card
+memgineering open <handle> --detail full   # the whole note
+```
+
+`open` also takes a note's exact title or its path, so you do not need to
+recall first when you already know what you want.
+
+**Check the evidence before trusting an old memory,** or when two of them
+disagree:
+
+```
+memgineering evidence <handle>
+```
+
+How often it has been surfaced, how often anyone read it, when it last changed
+and why. **Newer does not win**: a rule that has stood for eleven months has
+eleven months of nobody contradicting it behind it. Use whether it was actually
+reached for, not its date.
+
+**Remember when you learn something durable** — a decision, a constraint, a
+correction the user made, how something actually works:
+
+```
+memgineering remember "deploys are manual — launchctl by hand, no CD" --reason "watched it twice"
+```
+
+No approval step, by design. It is recorded and reversible (`memgineering
+undo`), so the cost of a wrong entry is one command, not a permanent mistake.
+Do not ask permission for ordinary observations — write them.
+
+**Always pass `--reason`.** Every write verb takes it and it goes in the ledger.
+It is the only part of a record that still means anything to whoever reads it
+six months from now, and it is refused if it looks like it carries a credential.
+
+**Revise when a conclusion changes:**
+
+```
+memgineering revise <handle> --claim "Deploying is manual now." --summary "manual only"
+```
+
+## What to raise with the user rather than just doing
+
+The tool does not gate writes; your judgement does. Tell them — plainly, once
+— when:
+
+- the change touches `01_BASE/` (their identity, preferences, boundaries,
+  tooling). The output marks these `⚠ critical target`.
+- you are recording something they said in passing that they may not want kept
+- what you learned contradicts a memory that is currently marked current
+
+Everything else: write it and mention it in a sentence.
+
+## Depth costs context — ask for what you need
+
+`recall` returns cards, not notes, so calling it often is cheap. Reach for more
+only when a summary is not enough:
+
+| depth              | what you get                                    |
+| ------------------ | ----------------------------------------------- |
+| `--detail card`    | title + summary (default)                       |
+| `--detail summary` | + the note's headings                           |
+| `--detail chunks`  | + every section, or one with `--section <name>` |
+| `--detail full`    | the whole note                                  |
+
+`recall "<q>" --limit 1 --detail full` is "find the best match and read it" in
+one call.
+
+## At the start of a session
+
+```
+memgineering resurface
+```
+
+Ranks by what has been recalled in this folder before, how recently, and which
+of their base notes have gone unread. No query needed — this is the one that
+tells you what you should already know here.
+
+## Rules
+
+- **Never edit brain files directly.** Use the CLI: it records what changed and
+  keeps `undo` working. A hand edit is invisible to that.
+- **Never invent a handle.** They come from `recall`, `resurface` or `open`.
+- **Full ids in durable places.** The short handle is for this conversation;
+  when you save a reference in your own memory or a document, use the full `id:`
+  that `open` prints.
+- **Nothing matched is a real answer.** Say the brain has nothing on it rather
+  than filling the gap with a guess.
+- **Their notes are theirs.** `revise` only touches the memory block in
+  frontmatter; prose is never rewritten by this tool, and should not be
+  rewritten by you without being asked.
+
+If `memgineering: command not found`, install with `npm i -g memgineering`,
+then `memgineering setup`.

package/assets/memgineering-memory/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: memgineering-memory
+description: Use when the user asks about something they told you before, refers to a past decision, wants their own notes searched, or says something worth keeping. Triggers include "what did I decide about X", "check my notes", "how do we deploy again", "remember this", "is this still true", "which one do I go with", "예전에 뭐라고 정했더라", "내 노트에서 찾아줘", "이거 기억해둬", "what do you know about my setup". Covers recall, open, evidence, remember, revise, undo, and resurface against the user's own brain folder.
+type: skill
+allowed-tools: Bash(memgineering:*)
+---
+
+# Working with the user's brain
+
+A **brain** is a folder of the user's own notes. It is not this tool's
+database: they wrote those files, they can open them in any editor, and
+memgineering reads them and keeps a derived index outside the folder. Deleting
+that index costs a rebuild and nothing else.
+
+Everything below assumes the brain is already linked. If a command answers
+`no brain is linked yet`, see "Getting connected" at the bottom.
+
+## Answering from what they already know
+
+Recall first whenever the question sounds settled — a past decision, their
+setup, their preferences, why something is the way it is.
+
+```
+memgineering recall "how do we deploy"
+```
+
+```
+## recall: how do we deploy  (2 cards)
+
+### 1. Deploy is manual
+stated
+
+> launchctl kickstart on the Mac Studio, no CD pipeline
+
+`open: deploy-manual`
+```
+
+The output is already shaped for your context — headings, a quoted summary,
+and a handle. Paste it in as-is rather than reformatting it into prose.
+
+**But read it before you use it.** These are candidates ranked by relevance,
+not a list of answers: anything matching a word from the query is returned, so
+the tail of a long result can be only loosely related. That is deliberate —
+for a memory system, failing to return a note someone knows is there is worse
+than returning one they can ignore. Use the top matches that actually answer
+the question and leave the rest; quoting all of them back as if each were
+relevant is how a useful recall turns into noise.
+
+Then open only what matters:
+
+```
+memgineering open deploy-manual                      # the claims behind the card
+memgineering open deploy-manual --detail summary     # + its headings
+memgineering open deploy-manual --detail chunks      # + every section
+memgineering open deploy-manual --section preflight  # one section
+memgineering open deploy-manual --detail full        # the whole note
+```
+
+`open` takes a handle, a full id, a path inside the brain, or a note's exact
+title — so when you already know what you want, skip the recall.
+
+### When one round trip is enough
+
+```
+memgineering recall "deploy" --limit 1 --detail full
+```
+
+Best match, read whole, one call. Use this when the user's question clearly
+points at one note.
+
+### Nothing matched
+
+Say so. Only titles, aliases and summaries are searched, so suggest broader
+words — but do not go read their folder yourself to compensate. A brain that
+answers "nothing" is giving you real information.
+
+## Deciding which one to trust
+
+When two memories disagree, or one looks old enough to doubt, do not settle it
+by date.
+
+```
+memgineering evidence deploy-manual
+```
+
+```
+  surfaced       34×  (12× in this folder, 22× elsewhere)
+  opened         12×  (35% of the recalls that surfaced it)
+  last used      3 days ago
+  in the ledger  since 2026-05-02  ·  changed 2×
+
+**well-used** — it has been reached for and read. The record backs it.
+
+why it last changed:
+> CD was removed from the repo
+```
+
+**Newer does not win.** A rule that has stood for eleven months has eleven
+months of nobody contradicting it behind it; a note written last week has a
+week. What separates them is whether either was ever actually used, and what
+the last person to change their mind said. Both are in the output above.
+
+Three standings, and each is a fact rather than a grade:
+
+- **well-used** — recall returned it and somebody read it
+- **surfaced, never opened** — it keeps coming back and nobody reads it. Either
+  it does not answer those questions, or its summary does not say what it knows
+- **never recalled** — nothing has ever surfaced it. It may be perfectly true
+  and simply never needed, but nothing supports it either
+
+If it says this machine has no recall history, the numbers mean nothing yet —
+that log is local, so a brain synced to a new laptop starts empty. Say that
+rather than reporting the memory as unused.
+
+## Writing things down
+
+```
+memgineering remember "deploys are manual — launchctl by hand, no CD" \
+  --reason "watched the deploy happen by hand twice"
+```
+
+Lands immediately as its own note and is recallable at once. There is no
+approval queue: the design trades permission-before for correction-after, and
+every write records how to reverse it.
+
+**Pass `--reason` on every write.** It goes in the ledger, and it is the only
+part of the record that survives being read six months later by somebody — the
+user, or you in a new session — who no longer remembers the conversation. Every
+write verb takes it: `remember`, `revise`, `retire`, `exclude`, `undo`. The one
+on `undo` is usually the most valuable of all, because it is the moment an
+earlier conclusion turned out to be wrong.
+
+It is refused if it looks like it contains a credential. The ledger travels
+with the brain, so that would be a permanent synced copy — say what changed
+without the value, or drop the flag; the write itself is unaffected.
+
+```
+memgineering undo --reason "that belonged to the other project"   # the last change
+memgineering undo <op_id>      # a specific one
+memgineering log               # what changed, why, and what can still be undone
+```
+
+Write down: decisions and their reasons, constraints, corrections the user
+made to you, how something actually works once you found out. Skip: things
+true only inside this conversation, and anything they said they did not want
+kept.
+
+**Recall first, then decide which verb.** If what you just learned answers a
+note that is already there — the vague one, the one that says "nobody wrote
+this down" — `revise` it instead. `remember` would leave two current notes on
+the same subject and the next recall would return both, which is the
+re-discovery problem the user was trying to end. New subject → `remember`.
+Existing subject, now settled → `revise`.
+
+### Changing a conclusion
+
+```
+memgineering revise deploy-manual \
+  --claim "Deploying is manual — pushing to main does nothing." \
+  --summary "manual only, no CD"
+```
+
+- `--action supersede` (default) replaces the conclusion
+- `--action reinforce` keeps it and adds support
+- `--action conflict` records that two notes disagree without picking a winner
+- `--dry-run` shows the diff and writes nothing
+
+This only ever rewrites the memory block in a note's frontmatter. The prose is
+the user's; neither this command nor you should rewrite it uninvited.
+
+### Retiring versus excluding
+
+```
+memgineering retire <ref> --reason "the date moved"   # no longer current, still visible
+memgineering exclude path/to/note.md --reason "names an internal host"   # stop reading it
+```
+
+Retiring keeps the note in recall, ranked last and labelled. Excluding takes it
+out of the index and never touches the file. If the user says "delete", ask
+which they mean — they are different, and guessing picks one.
+
+## Starting a session
+
+```
+memgineering resurface
+```
+
+No query. It ranks by what has been recalled in this folder before, how
+recently, and which of the user's base notes have gone unread — the things you
+should already know here before they have to tell you again.
+
+## What to raise with the user
+
+The tool does not ask; you decide. Say something, once and plainly, when:
+
+- the output marks the target `⚠ critical target` — that is `01_BASE/`, the
+  files defining who they are and what you may do
+- you are about to record something said in passing that may be sensitive
+- what you learned contradicts a memory currently marked current
+
+Everything else: do it, and mention it in a sentence.
+
+## Rules
+
+- **Never edit brain files with Read/Write/Edit.** Only the CLI records the
+  change and keeps `undo` working; a hand edit is invisible to both.
+- **Never invent a handle or id.** They come from `recall`, `resurface`, `open`.
+- **Store full ids, not short handles**, anywhere durable — your own memory, a
+  document, a ticket. `open` prints the full `id:` for exactly this.
+- **`--json`** when you need to parse rather than read.
+- **Several brains** (personal, team, a repo's own) resolve by where you are.
+  If a command says the choice is ambiguous, pass `--vault <path>` — or bind
+  the directory once with `memgineering use <brain>`.
+
+## Getting connected
+
+```
+memgineering link ~/Documents/Notes      # notes they already keep
+memgineering init ~/brain                # nothing yet — creates the layout
+```
+
+`link` shows exactly what would be stored and asks first; run it in a terminal
+the user can see, and let them answer. Do not pass `--yes` on their behalf.
+
+With no terminal attached it says so instead of assuming the answer was no.
+Show them `memgineering link <path> --dry-run` — same disclosure, writes
+nothing — and run with `--yes` only once they have actually said yes.

package/assets/memgineering-setup/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: memgineering-setup
+description: Use when installing or configuring memgineering — after `npm i -g memgineering`, when the user asks to set it up, connect their notes, install it into their agents, turn auto-update on or off, or when a memgineering command reports that no brain is linked. Triggers include "set up memgineering", "connect my notes", "메모리 설정해줘", "노트 연결", "memgineering setup", "no brain is linked".
+type: skill
+allowed-tools: Bash(memgineering:*)
+---
+
+# Setting memgineering up
+
+Two things have to happen, and they are separate on purpose:
+
+1. **Register with the agents** — so this and every other AI tool on the
+   machine knows the brain exists. One command.
+2. **Connect a brain** — which folder holds the notes. This one is the user's
+   decision, and it involves showing them what gets stored.
+
+## 1. Register
+
+```
+memgineering setup --agent
+```
+
+`--agent` is the non-interactive path, meant for you: it detects the installed
+tools, injects the guidance block, installs these skills, and takes its
+remaining answers from flags rather than prompts.
+
+```
+memgineering setup --agent \
+  --tools claude,codex \        # default: everything detected
+  --auto-update on \            # default: on, and recommended
+  --hook on                     # SessionStart resurface, Claude Code only
+```
+
+Look at `memgineering setup --dry-run` first if you want to report what would
+change before changing it.
+
+**Ask the user before choosing for them** when a flag would set policy rather
+than mechanics: auto-update is the one that matters, since it means the tool
+updates itself. Recommend `on` — old versions can lose access to hosted
+features later — but it is theirs to decide.
+
+If the user would rather click than type, `memgineering setup --human` gives
+them a checkbox screen. Run it and let them drive; do not answer for them.
+
+**After setup, the agent session has to restart** for the guidance to load.
+Say so — the user will otherwise wonder why nothing changed.
+
+## 2. Connect a brain
+
+Two cases, and picking the wrong one is disruptive.
+
+**They already keep notes somewhere** — Obsidian, a folder of markdown,
+anything:
+
+```
+memgineering link ~/Documents/Notes
+```
+
+This prints exactly what would be indexed and what would be refused, including
+a sample of the real lines that would be stored, then asks. **Run it and stop.**
+Let them read it and answer. Do not pass `--yes` for them: the screen is the
+one moment they decide what this tool may read, and answering on their behalf
+takes that away.
+
+If your shell has no terminal attached, `link` will say so rather than
+pretending the answer was no. When that happens, show them the decision
+instead of making it:
+
+```
+memgineering link ~/Documents/Notes --dry-run
+```
+
+That prints the same disclosure and writes nothing: every note that would be
+indexed with the exact line that would be stored, plus any file the credential
+scanner is holding back. Put it in front of them, wait for a real yes, and
+only then run with `--yes` — which records the decision they actually made.
+
+If they cannot see your terminal at all, hand them the command rather than
+answering for them.
+
+**What to tell them, in one line before they answer:** the title and first
+paragraph of every note listed gets stored outside the folder, and if the
+session-start hook is on, a few of those summaries appear in every new session
+without anyone asking. Anything they would not want in either place goes in a
+`.memgdeny` file at the top of the folder — one path per line, no wildcards:
+
+```
+30_personal/medical.md
+journal/                 (a trailing slash covers a whole folder)
+```
+
+If it refuses because a `.memgdeny` line matches no file, that is working as
+intended — a rule with a wrong path protects nothing. Fix the paths it
+suggests, or remove the lines.
+
+**They have no notes yet**:
+
+```
+memgineering init ~/brain
+```
+
+Creates the layout — eleven folders and five base files — and links it. Then
+tell them to fill in `01_BASE/USER.md` and leave the rest; the folders are
+there for when they are needed, not as homework.
+
+### Several brains
+
+Normal: a personal one, a team folder that syncs, one per repository. Which
+one answers is decided by where you are, in this order:
+
+1. `--vault <path>`
+2. a `.memgineering` pointer file, found by walking up from the cwd
+3. the brain the current directory is inside
+4. the only one linked
+
+If it says the choice is ambiguous, bind the directory once:
+
+```
+memgineering use ~/brains/work
+```
+
+Inside a repository this writes a relative path, so it can be committed and
+will resolve for a teammate who links the same brain.
+
+## Checking it worked
+
+```
+memgineering recall "anything"     # should answer, even if with "nothing matched"
+memgineering log                   # what this brain has recorded
+```
+
+## Turning things off
+
+```
+memgineering setup --agent --auto-update off
+memgineering unlink            # stop reading a brain; notes untouched
+memgineering unlink --purge    # also delete the local index and undo snapshots
+```
+
+`MEMGINEERING_NO_UPDATE=1` skips the update check for a single run without
+changing the setting.

package/bin/memgineering.js

@@ -1,7 +1,2 @@
 #!/usr/bin/env node
-
-"use strict";
-
-console.log("memgineering is coming soon.");
-console.log("https://memgineering.com");
-
+import '../dist/index.js';