memgineering 0.0.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,147 @@
+# 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.2.0] — 2026-08-09
+
+The record can say why, and you can see what a memory is actually worth.
+
+### Added
+
+- **`evidence <ref>`** — how much a memory has been used, and why it last
+  changed: how often recall surfaced it, how often anyone opened it, when it
+  was last read, how many times it has been revised, and the reason attached to
+  the most recent change. Every number comes from records that already existed;
+  nothing new is collected, and running it records nothing of its own — so
+  measuring a memory cannot change where `resurface` ranks it.
+- **A standing for each memory** — `well-used`, `surfaced, never opened`, or
+  `never recalled` — computed from usage rather than declared. It is withheld
+  entirely when this machine has no recall history yet, since that log is local
+  state and a brain copied to a new machine starts empty.
+- **`--reason` on every write verb.** `remember`, `exclude`, `unexclude` and
+  `undo` accept one for the first time; `revise`, `retire` and `unretire`
+  already did. The reason on an `undo` is usually the most valuable of the set.
+- **`log` shows the reason** without needing `--verbose`.
+
+### Fixed
+
+- **`revise --reason` and `retire --reason` were silently discarded.** Both
+  flags shipped in 0.1.0, and `retire --help` described the reason as "kept in
+  the record". It was not kept anywhere: only creating a brand-new note ever
+  read the field, so on the ordinary path — changing a note that already exists
+  — the text went nowhere. Reasons given to those commands are now recorded in
+  the operation ledger, where `log` and `evidence` can show them.
+
+- **`recall` now names the language barrier** when a query cannot reach the
+  brain. Search matches text, so an English query never reaches Korean notes
+  however it is worded — and the old zero-result footer suggested broader
+  wording, the one remedy that cannot work. Four testers hit this and came
+  within one command of telling their user the brain held nothing on a subject
+  it had notes about. The warning also appears above results, because the
+  failure is rarely a clean zero: a couple of English scaffolding notes match
+  and look like an answer.
+- **`use` with no argument now says which brain you are on**, and how it
+  resolved — by pointer, by containment, or by being the only one linked. Its
+  own help had always promised this; it reported only whether a pointer file
+  existed, and three testers went and read the config file by hand instead.
+- **`open` no longer tells you to hand-edit frontmatter** when a note states no
+  conclusion. It points at `memgineering revise --claim`, which is the
+  sanctioned path — the previous hint contradicted the bolded rule against
+  editing brain files directly, and a hand edit is invisible to `undo`.
+- **`evidence` no longer implies a well-used memory is a correct one.** A note
+  the repository flatly contradicted was described as backed by the record.
+  Usage is attendance, and where a memory contradicts another the output now
+  says plainly that usage cannot settle which is right.
+- **`evidence` sees a contradiction declared by either note.** The `contradicts`
+  edge lives on whichever note a revise happened to touch, so the warning above
+  fired on only one of the two — and stayed silent on the other, which is the
+  side a reader is more likely to be trusting by mistake.
+- **`evidence` divides the open rate by the number printed beside it.** It used
+  to divide by recalls while `surfaced` also counted resurfacings, so the two
+  figures and the percentage reconciled with none of each other.
+- **`remember --reason` help disambiguated** — it records why you are writing
+  something down, not why the fact is true. One tester nearly filed the
+  substance of a note there, where recall would never show it.
+
+### Changed
+
+- A reason that looks like it contains credential material is refused, with the
+  pattern named and the value never echoed. The ledger travels with the brain,
+  so an unscreened reason would become a permanent synced copy of a secret —
+  and the deny layer that screens notes does not look at the ledger. The write
+  itself is unaffected: rephrase, or drop the flag.
+- Operation records carry a `rationale` field and `rule_version` is now 2.
+  Ledgers written by 0.1.x still read correctly; an older line simply reports
+  no reason given, which is what happened.
+
+### Agent guidance
+
+The bundled hub and the `memgineering-memory` skill now cover `evidence` and
+ask for `--reason` on every write, including the rule that a newer memory does
+not automatically win. **Restart your agent session after upgrading** so the
+new guidance is loaded.
+
+## [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.