memgineering 0.0.0 → 0.1.0

package/assets/memgineering-memory/SKILL.md

@@ -0,0 +1,177 @@
+---
+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", "예전에 뭐라고 정했더라", "내 노트에서 찾아줘", "이거 기억해둬", "what do you know about my setup". Covers recall, open, 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.
+
+## Writing things down
+
+```
+memgineering remember "deploys are manual — launchctl by hand, no CD"
+```
+
+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.
+
+```
+memgineering undo              # the last change
+memgineering undo <op_id>      # a specific one
+memgineering log               # what has changed, 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                  # stop reading it entirely
+```
+
+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';