memgineering 0.0.0 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to `memgineering` are documented here, in the
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) style. This project
+follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+English only, deliberately: this file is read by people deciding whether to
+upgrade and by agents summarising a release, and both re-render it in whatever
+language the reader wants. The bilingual rule the monorepo applies to
+`@rayul/kordis` does not extend here.
+
+## [Unreleased]
+
+## [0.1.0] — 2026-08-09
+
+First release. A brain is a folder of your own notes; every agent you use
+reads and writes it through this one CLI.
+
+### Added
+
+- **Recall and open.** `recall <query>` returns memory cards — title, summary,
+  and a handle — rather than documents, so an agent can afford to ask on every
+  turn. `open <ref>` expands one, and takes a handle, an id, a path inside the
+  brain, or a note's exact title, so you do not have to search for something
+  you can already name.
+- **Progressive reading.** `--detail title | card | summary | chunks | full`
+  on both verbs, plus `open --section <name>`. Every stage is computed from
+  the note itself — the summary is the author's own, the chunks are their own
+  headings. Nothing is generated.
+- **Writing without an approval queue.** `remember <text>` records an
+  observation immediately, as its own note, recallable at once. `revise <ref>`
+  changes a memory's conclusion. Both are reversible with `undo`, and `log`
+  shows what changed and what can still be taken back.
+- **An operation ledger** inside the brain, so corrections travel with the
+  notes they describe. It records hashes and the changed region, never note
+  text.
+- **`resurface`** — what is worth having in view at the start of a session,
+  with no query: ranked by what has been recalled in this folder before, how
+  recently, and which base notes have gone unread.
+- **`init`** lays out a new brain — eleven folders and five base files, ready
+  to write into. **`link`** reads notes you already keep, showing the actual
+  lines that would be stored before anything is indexed.
+- **Several brains at once.** Resolution goes `--vault`, then a
+  `.memgineering` pointer found by walking up, then the brain the current
+  directory is inside, then the only one linked — and refuses rather than
+  guessing when none of those settle it. `use <brain>` writes the pointer, as
+  a relative path where it can, so it can be committed.
+- **`retire` / `unretire`** mark a memory no longer current while it stays
+  visible; **`exclude` / `unexclude`** stop reading a note entirely without
+  touching it. They are separate because "delete" means both, and guessing
+  picks one.
+- **`setup`** installs into Claude Code, Codex and Gemini CLI — `--agent` for
+  a non-interactive run, `--human` for a checkbox screen. Optionally registers
+  `resurface` to run when a Claude Code session starts.
+- **Self-update.** `update` upgrades this install, or explains why it will
+  not: when the package manager on PATH does not own the directory this copy
+  lives in — the usual case under nvm, asdf, Volta and mise — it prints the
+  command instead of running it, because updating a copy nobody runs while
+  reporting success is worse than not updating at all.
+
+### Agent guidance
+
+Ships a hub block and two sub-skills (`memgineering-memory`,
+`memgineering-setup`) installed into each detected tool's home.
+**Restart your agent session after `setup` for them to load.**
+
+[Unreleased]: https://github.com/memgineering/memgineering/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/memgineering/memgineering/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,41 @@
+memgineering
+Copyright 2026 memgineering
+
+This product includes software developed by memgineering
+(https://memgineering.com).
+
+Licensed under the Apache License, Version 2.0. See LICENSE for the full
+terms. This NOTICE file must be included in redistributions and derivative
+works, per section 4(d) of that license.
+
+
+UPDATES AND SUPPORT
+-------------------
+
+memgineering checks for a newer version at most once a day and, when
+auto-update is on, can install one. Both are stated here rather than only in
+the README because they involve the network and the user's install directory.
+
+  * The check contacts the npm registry, and optionally
+    https://memgineering.com/version-policy.json. Neither request carries
+    identifying information beyond what any HTTP client sends.
+  * `MEMGINEERING_NO_UPDATE=1` skips the check for a single run.
+    `memgineering setup --auto-update off` turns installation off for good.
+  * Installation only ever targets the version npm publishes as `latest`.
+    The policy document is advisory and can never select a version.
+
+Older versions are not disabled remotely, and nothing in this software will
+stop working locally because a newer release exists. Every published version
+remains installable from npm indefinitely. What a future release may withdraw
+is support for older clients on *hosted* services operated by memgineering —
+if that happens, the version policy will say so ahead of time and the CLI will
+print it. Upgrading restores access; nothing you have stored is affected
+either way, because your notes are files on your own disk and remain yours.
+
+
+YOUR DATA
+---------
+
+This software reads a folder of notes you point it at and keeps a derived
+index outside that folder. It does not upload your notes. Deleting the index
+costs a rebuild and nothing else. See the README for what is stored and where.

package/README.md

@@ -1,11 +1,162 @@
 # memgineering
 
-**One memory for the AI you connect.**
+One memory for the AI you connect.
 
-memgineering is building a user-owned memory layer for continuous,
-personalized work across AI tools.
+Your notes stay in a folder you own. Every agent you use — Claude Code, Codex,
+Gemini — reads and writes the same brain through one CLI, so what you told one
+of them is there for the next one, tomorrow, and in whatever tool you move to
+after that.
 
-> Coming soon.
+```bash
+npm i -g memgineering
+memgineering setup
+memgineering link ~/Documents/Notes     # or: memgineering init ~/brain
+```
 
-Website: [memgineering.com](https://memgineering.com)
+## What it does
 
+```bash
+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`
+```
+
+Cards first, not documents. Your agent gets the shape of what you know and a
+handle for the one that matters, then opens only that:
+
+```bash
+memgineering open deploy-manual                  # the claims behind the card
+memgineering open deploy-manual --detail full    # the whole note
+```
+
+And it writes, without stopping to ask:
+
+```bash
+memgineering remember "deploys are manual — launchctl by hand, no CD"
+memgineering undo                                # if that was wrong
+```
+
+## Why there is no approval step
+
+Most memory tools queue what an agent learned and wait for you to approve it.
+That tax lands on every true observation in order to catch the rare wrong one,
+and what it produces in practice is a backlog nobody reads.
+
+memgineering trades permission-before for correction-after. Every write records
+what changed, against which bytes, and how to reverse it — in a ledger that
+lives inside your brain and travels with it.
+
+```bash
+memgineering log      # what has changed, and what can still be undone
+memgineering undo <op>
+```
+
+The one thing it refuses to do is undo on top of an edit you made yourself. If
+the note moved on since, it stops and says so rather than throwing your work
+away.
+
+## Your notes stay yours
+
+- **Nothing is uploaded.** The index is derived and lives outside your notes
+  folder; deleting it costs a rebuild and nothing else.
+- **Prose is never rewritten.** `revise` only touches the memory block in a
+  note's frontmatter. Your paragraphs are yours.
+- **You decide what is read.** `link` shows the actual lines that would be
+  stored — not a description of them — before anything is indexed. Notes whose
+  content looks like a credential are refused automatically; anything else you
+  want left alone goes in `.memgdeny`.
+- **`memgineering unlink --purge`** removes every trace this tool kept locally.
+
+## Progressive reading
+
+Depth is a parameter, because context costs money.
+
+| `--detail` | what you get                                    |
+| ---------- | ----------------------------------------------- |
+| `title`    | just the titles                                 |
+| `card`     | title + summary (default)                       |
+| `summary`  | + the note's headings                           |
+| `chunks`   | + every section, or one with `--section <name>` |
+| `full`     | the whole note                                  |
+
+`memgineering recall "deploy" --limit 1 --detail full` is "find the best match
+and read it" in a single call.
+
+## Several brains
+
+A personal one, a team folder that syncs, one per repository. Which one answers
+is decided by where you are:
+
+1. `--vault <path>`
+2. a `.memgineering` pointer, found by walking up from the current directory
+3. the brain the current directory is inside
+4. the only one linked
+
+If nothing settles it, memgineering refuses and lists the candidates rather
+than guessing. To bind a directory once — a repository root, say:
+
+```bash
+memgineering use ~/brains/work    # writes a relative path when it can, so it commits
+```
+
+## Starting a session
+
+```bash
+memgineering resurface
+```
+
+No query. It ranks by what has been recalled in this folder before, how
+recently, and which of your base notes have gone unread. `memgineering setup`
+can register it to run automatically when a Claude Code session starts.
+
+## Commands
+
+|                                     |                                                       |
+| ----------------------------------- | ----------------------------------------------------- |
+| `recall <query>`                    | recall memory cards for a question                    |
+| `open <ref>`                        | open one memory — by handle, id, path, or exact title |
+| `remember <text>`                   | write something down now                              |
+| `revise <ref>`                      | change a memory's conclusion                          |
+| `undo [op]`                         | take back the last change, or a named one             |
+| `resurface`                         | what is worth having in view, unasked                 |
+| `init <path>`                       | create a brain, laid out and ready                    |
+| `link <path>`                       | read notes you already keep                           |
+| `use [brain]`                       | bind this folder to one brain                         |
+| `unlink` · `reindex` · `sync-rules` | brain housekeeping                                    |
+| `log`                               | what changed, and what can still be undone            |
+| `retire` · `unretire`               | mark a memory no longer current, or current again     |
+| `exclude` · `unexclude`             | stop reading a note entirely, or resume               |
+| `setup`                             | install into your agents                              |
+| `update`                            | update memgineering itself                            |
+
+Every command takes `--json`.
+
+## Environment
+
+|                            |                                                     |
+| -------------------------- | --------------------------------------------------- |
+| `MEMGINEERING_HOME`        | state and derived index (default `~/.memgineering`) |
+| `MEMGINEERING_JSON=1`      | force JSON output without the flag                  |
+| `MEMGINEERING_NO_UPDATE=1` | skip the version check for one run                  |
+
+## What is coming
+
+**0.2.0 — cloud brains.** Today a brain is a folder on this machine. Next it
+can also live in a memgineering account, so the same memory reaches ChatGPT,
+Claude on the web, and anywhere a browser goes. The local path is not going
+away: what syncs is your originals, your ledger and your rules — never a
+vendor's copy of your notes.
+
+## Licence
+
+Apache-2.0. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE), which also states
+the update and support policy.

package/assets/MEMGINEERING.md

@@ -0,0 +1,119 @@
+---
+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.1.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.
+
+**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"
+```
+
+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.
+
+**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`.