ihow-memory 0.1.0-alpha.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,15 @@
+iHow Memory Core
+Copyright 2026 iHow Memory contributors
+
+This product includes software developed as part of the iHow Memory project
+(https://github.com/iHow1/ihow-memory-core).
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this software except in compliance with the License.
+You may obtain a copy of the License in the accompanying LICENSE file or at:
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+iHow Memory is local-first: the open-source core runs entirely on the user's
+machine with no telemetry and no required network calls. See README for the
+privacy statement.

package/README.md

@@ -0,0 +1,250 @@
+# iHow Memory
+
+Local-first shared memory for AI agents. The alpha core stores Markdown locally, indexes it with Node's built-in SQLite FTS5, returns citations, and exposes the same governed memory flow through CLI and stdio MCP.
+
+- No account
+- No telemetry
+- No required network calls
+- No embedding model or API key required
+- Cloud and sync are disabled by default
+
+> Alpha software. Back up runtime configuration before editing it, and use a demo space until you have reviewed the local file layout.
+
+## 2-Minute Quickstart
+
+Requirements:
+
+- Node.js `>=22.12`
+- macOS or Linux for the current alpha validation lane
+- A writable local directory
+
+### 1. Inspect and initialize
+
+During repository development:
+
+```bash
+git clone https://github.com/iHow1/ihow-memory-core.git
+cd ihow-memory-core
+npm run cli -- doctor
+npm run cli -- init --space demo --runtime codex
+```
+
+After the npm package is published:
+
+```bash
+npx ihow-memory init --space demo --runtime codex
+```
+
+Use one of:
+
+```bash
+ihow-memory init --space demo --runtime claude-code
+ihow-memory init --space demo --runtime codex
+ihow-memory init --space demo --runtime cursor
+```
+
+`init` creates a local managed workspace and prints the matching MCP configuration snippet. It does not edit runtime configuration automatically.
+It also copies the small zero-dependency JavaScript runtime into `<state-root>/<space>/.runtime/`, so the MCP configuration does not depend on an `npx` cache directory.
+
+Before pasting the snippet:
+
+1. Back up the existing runtime configuration file.
+2. Paste the generated snippet.
+3. Restart or reload the runtime.
+4. Run `ihow-memory doctor --runtime <runtime>` again.
+
+### 2. Run the local proof
+
+```bash
+ihow-memory proof --space demo-proof
+```
+
+Expected flow:
+
+```text
+agent A write candidate
+-> governed promote
+-> agent B search/read
+-> citation
+-> audit event
+-> cloud disabled / local only
+```
+
+### 3. Connect an AI runtime
+
+The generated snippet starts:
+
+```text
+node mcp/server.js
+```
+
+with `cwd` set to:
+
+```text
+<state-root>/<space>/.runtime
+```
+
+Available MCP tools:
+
+- `memory.search`
+- `memory.read`
+- `memory.write_candidate`
+- `memory.promote`
+- `memory.durable_promote`
+- `memory.status`
+
+### 4. Verify the result
+
+Ask runtime A to write a non-sensitive candidate. Ask runtime B to search for the marker and read the cited file. Confirm:
+
+- the search result contains a citation path and snippet;
+- the read result contains the original marker;
+- an audit event exists;
+- status reports `cloud=false` and `sync.enabled=false`.
+
+## Doctor and Diagnostics
+
+Run:
+
+```bash
+ihow-memory doctor --runtime codex
+```
+
+`doctor` checks:
+
+- Node version;
+- `node:sqlite` availability;
+- memory root writability;
+- selected runtime setup guidance;
+- retrieval engine readiness;
+- index manifest;
+- local-only cloud/sync state.
+
+For a redacted report:
+
+```bash
+ihow-memory doctor --runtime codex --share-diagnostics
+```
+
+The report omits memory content, replaces local paths with placeholders, and redacts secret-like values. It is printed locally and is not uploaded.
+
+## Feedback
+
+```bash
+ihow-memory feedback --runtime codex
+```
+
+This prints:
+
+- a prefilled GitHub issue URL;
+- a Markdown issue template;
+- a redacted doctor summary.
+
+No issue is submitted automatically.
+
+## Reset and Uninstall
+
+Remove a managed demo space:
+
+```bash
+ihow-memory reset --space demo
+```
+
+Use the same `--root <dir>` value if the demo was initialized under a custom root:
+
+```bash
+ihow-memory reset --root <state-root> --space demo
+```
+
+Safety boundary:
+
+- `reset` requires an explicit `--space`;
+- `reset` only removes managed spaces;
+- `reset` refuses `--memory-root`, so it cannot delete an existing shared memory root.
+
+Uninstall steps:
+
+1. Remove the `ihow-memory` entry from the AI runtime's MCP configuration.
+2. Restore the configuration backup if needed.
+3. Delete demo spaces with `ihow-memory reset`.
+4. Remove a global npm install with `npm uninstall -g ihow-memory`.
+5. Delete any remaining custom state root only after reviewing its contents.
+
+## Workspace Modes
+
+### Managed Space
+
+Default layout:
+
+```text
+<state-root>/<space>/
+  memory/
+    candidate/inbox/
+    scopes/
+    _events/
+  history/
+  index.sqlite
+  index-manifest.json
+```
+
+### Existing Memory Root
+
+Use an existing Markdown memory directory without moving it:
+
+```bash
+ihow-memory doctor \
+  --memory-root <memory-root> \
+  --state-root <state-root>
+```
+
+Write boundary:
+
+- existing durable Markdown is read-only by default;
+- candidates are written under `memory/_mcp/candidates/`;
+- normal promote writes staging files under `memory/_mcp/promoted/`;
+- audit events stay under `memory/_mcp/_events/`;
+- SQLite state stays under `<state-root>`, outside the memory root.
+
+## Retrieval Engine
+
+The default `fts` provider uses only Node built-in modules and `node:sqlite` FTS5:
+
+- zero third-party runtime dependencies;
+- zero embedding downloads;
+- zero model/API requirements;
+- citation-bearing lexical search.
+
+The optional `vector-gguf` provider runs as a separate local process. If it is unconfigured, missing, slow, or unhealthy, retrieval falls back visibly to FTS. Governance, write guards, and audit behavior do not change with the retrieval provider.
+
+## Development Proofs
+
+From a clone of the source repository (these scripts are not part of the npm package):
+
+```bash
+npm run proof
+npm run dogfood
+```
+
+`dogfood` requires explicit local paths:
+
+```bash
+MEMORY_ROOT=<memory-root> \
+IHOW_MEMORY_STATE_ROOT=<state-root> \
+npm run dogfood
+```
+
+## Hosted Runtime
+
+A single-tenant HTTP runtime exists for development and controlled deployment. It is **not** part of the published npm package and is not the self-serve alpha path: no accounts, billing, hosted sync, or web console.
+
+## Package Status
+
+Alpha prerelease (`0.1.0-alpha.0`). The npm tarball ships only the local CLI, the stdio MCP server, and the read-only local console (`ihow-memory console`). The single-tenant hosted runtime, TypeScript sources, and internal proof scripts are intentionally not part of the published package.
+
+## Privacy
+
+The open-source core runs locally with no telemetry and no required network calls. Memory content is not included in diagnostics. `feedback` only prints a template; the user decides whether to submit it.
+
+## License
+
+Apache License 2.0. See [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE).

package/TRADEMARK.md

@@ -0,0 +1,24 @@
+# Trademark Policy / 商标政策
+
+**iHow**, **iHow Memory**, **Yihow**, and associated logos are trademarks of the iHow Memory project and its owner.
+
+## The code is open. The brand is protected. / 代码开放,品牌受保护
+
+The source code is licensed under **Apache-2.0** — you are free to use, modify, fork, and redistribute it under those terms.
+
+**However, the trademarks (the names "iHow" / "iHow Memory" / "Yihow", and the logos) are NOT licensed under Apache-2.0.**
+
+代码可自由 fork / 修改 / 再分发(遵循 Apache-2.0);但**名称与 logo 不在 Apache-2.0 授权范围内**。
+
+### You may NOT / 不可
+- Use the names or logos in a way that suggests endorsement, affiliation, or official status without permission. / 以暗示官方背书、关联或官方身份的方式使用名称或 logo。
+- Name a fork or derivative "iHow Memory" (or a confusingly similar name) so as to mislead users about its origin. / 给 fork / 衍生品起名 "iHow Memory" 或近似名,误导用户来源。
+- Use the marks as your own product or company name. / 把商标用作你自己的产品 / 公司名。
+
+### You may / 可以
+- State factually that your product "is built on" / "is compatible with" / "is a fork of" iHow Memory, as long as it is not misleading. / 如实说明"基于 / 兼容 / fork 自" iHow Memory(只要不误导)。
+- Use the name in documentation, articles, and discussion that refer to this project. / 在引用本项目的文档、文章、讨论中使用名称。
+
+**If you distribute a modified version, please use a different name** to avoid confusion. / **分发修改版请改用别的名字**以避免混淆。
+
+Questions / 咨询: open an issue or contact the maintainers.

package/bin/ihow-memory.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const REQUIRED_NODE = '22.12.0';
+
+function versionParts(value) {
+  return value
+    .replace(/^v/, '')
+    .split('.')
+    .slice(0, 3)
+    .map((part) => Number.parseInt(part, 10) || 0);
+}
+
+function versionAtLeast(actual, expected) {
+  const left = versionParts(actual);
+  const right = versionParts(expected);
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] > right[index]) return true;
+    if (left[index] < right[index]) return false;
+  }
+  return true;
+}
+
+const actualNode = process.env.IHOW_MEMORY_TEST_NODE_VERSION || process.versions.node;
+const command = process.argv[2] || 'help';
+
+if (!versionAtLeast(actualNode, REQUIRED_NODE)) {
+  console.error('doctor: failed');
+  console.error(`- fail node: v${actualNode}`);
+  console.error('  hint: Install Node >= 22.12, then rerun: ihow-memory doctor.');
+  console.error('  example: nvm install 22 && nvm use 22');
+  console.error('- action sqlite: skipped until Node is upgraded');
+  console.error('cloud: disabled / local only');
+  if (command !== 'doctor') {
+    console.error(`command "${command}" was not started because this package requires Node >= 22.12.`);
+  }
+  process.exitCode = 1;
+} else {
+  const packageDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const cliPath = path.join(packageDir, 'dist', 'cli.js');
+  const child = spawnSync(process.execPath, [cliPath, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    env: process.env,
+  });
+  if (child.error) {
+    console.error(`Unable to start iHow Memory: ${child.error.message}`);
+    process.exitCode = 1;
+  } else {
+    process.exitCode = child.status ?? 1;
+  }
+}