@hviana/sema 0.1.0

package/LICENSE.md

@@ -0,0 +1,117 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+> Required Notice: Copyright Sema Authors — Henrique Viana, Marcelo Oliveira dos
+> Reis, Rogerio Nascimento (hv5088@gmail.com)
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both
+strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything
+you might do with the software that would otherwise infringe the licensor's
+copyright in it for any permitted purpose. However, you may only distribute the
+software according to [Distribution License](#distribution-license) and make
+changes or new works based on the software according to
+[Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of
+the software. Your license to distribute covers distributing the software with
+changes and new works permitted by
+[Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms or the URL for them above, as well as copies of
+any plain-text lines beginning with `Required Notice:` that the licensor
+provided with the software. For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new
+works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent
+claims the licensor can license, or becomes able to license, that you would
+infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public
+knowledge, personal study, private entertainment, hobby projects, amateur
+pursuits, or religious observance, without any anticipated commercial
+application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research
+organization, public safety or health organization, environmental protection
+organization, or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do
+not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to
+anyone else, or prevent the licensor from granting licenses to anyone else.
+These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to
+infringement of any patent, your patent license for the software granted under
+these terms ends immediately. If your company makes such a claim, your patent
+license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these
+terms, or done anything with the software not covered by your licenses, your
+licenses can nonetheless continue if you come into full compliance with these
+terms, and take practical steps to correct past violations, within 32 days of
+receiving notice. Otherwise, all your licenses end immediately.
+
+## No Liability
+
+_**As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of legal
+claim.**_
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the
+**software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**Control** means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -0,0 +1,290 @@
+<div align="center">
+
+```
+███████╗ ███████╗ ███╗   ███╗  █████╗
+██╔════╝ ██╔════╝ ████╗ ████║ ██╔══██╗
+███████╗ █████╗   ██╔████╔██║ ███████║
+╚════██║ ██╔══╝   ██║╚██╔╝██║ ██╔══██║
+███████║ ███████╗ ██║ ╚═╝ ██║ ██║  ██║
+╚══════╝ ╚══════╝ ╚═╝     ╚═╝ ╚═╝  ╚═╝
+```
+
+### The mind without weights.
+
+**A reasoning engine grounded in a _vector-symbolic architecture_ and
+_instance-based memory_ — not in billions of trained parameters.**
+
+No weights. No gradients. No training loop. No neural network. No GPU.
+
+`Deterministic` · `Auditable` · `CPU-only`
+
+— ⬡ — ⬡ — ⬡ —
+
+</div>
+
+> [!IMPORTANT]
+> **© Sema is not a large language model.** Today's LLMs compress the world into
+> opaque floating-point weights and answer by sampling from them. Sema does the
+> opposite: it **keeps your knowledge as knowledge** — content-addressed,
+> inspectable, exact — and _reasons_ over it on demand. The store **is** the
+> model. What it knows, you can read. Why it answered, you can trace.
+>
+> Formally, Sema is a **non-parametric, instance-based reasoning system**: a
+> Vector Symbolic Architecture (Plate 1995; Kanerva 2009) over a
+> content-addressable memory, with inference by weighted automated deduction
+> (Knuth 1977; Felzenszwalb & McAllester 2007). Each term is grounded in
+> [HOW_IT_WORKS.md](HOW_IT_WORKS.md).
+
+---
+
+## ✦ Retrieval and reasoning, one search
+
+Two questions, asked of every query — and Sema answers both in a single pass:
+
+<div align="center">
+
+|                  | The question it asks                                 |
+| :--------------- | :--------------------------------------------------- |
+| 🔎 **Retrieval** | _"What do I already know that bears on this?"_       |
+| 🧠 **Deduction** | _"What can I conclude or decide from what I found?"_ |
+
+</div>
+
+```text
+               ┌──────────────────────────────────────────────┐
+Your question  │"The Weeping Woman was painted by Picasso."   │
+               └──────────────────────┬───────────────────────┘
+                                      ▼
+   🔎  Retrieve     resonate the query against the memory
+                    ·  "… painted by … → the painter"  (a learned pattern)
+                    ·  "Picasso → co-founded the Cubist movement"
+                                      ▼
+   🧠  Deduce       connect · derive · compose
+                    ·  lift the painter from a sentence never seen
+                    ·  follow that name onward to what it implies
+                                      ▼
+   ✅  Answer       "Pablo Picasso co-founded the Cubist movement"
+                    (a fact that appears in no word of the question)
+```
+
+Retrieval and reasoning are not two bolted-together stages — they are **one
+search** over **one memory**, which is why the answer can be something no single
+stored fact contains. Watch it happen below.
+
+---
+
+## ✦ Why Sema
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+### 🧩 Symbolic, not statistical
+
+Knowledge is stored as a **content-addressed graph**, not smeared across a
+weight matrix. Every fact is an edge you can point at. Nothing is hallucinated
+out of a probability distribution.
+
+</td>
+<td width="50%" valign="top">
+
+### 🔀 Retrieval and reasoning, unified
+
+Retrieval and reasoning are **one mechanism**, not a brittle pipeline of bolted-
+together components. A query enters the graph where it _resonates_ and a single
+lightest-derivation search composes the answer.
+
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+
+### 🔍 Fully auditable
+
+Every answer is a **derivation** over explicit facts. No black box. Trace any
+output back to the exact deposits that produced it — a hard requirement for
+regulated, high-stakes, and safety-critical deployments.
+
+</td>
+<td width="50%" valign="top">
+
+### ♻️ Deterministic & reproducible
+
+Same seed + same bytes → **identical result, every time.** No temperature, no
+sampling, no drift between runs. Reproducibility is a property of the
+architecture, not a flag you toggle.
+
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+
+### ⚡ Instant training
+
+Training **is** depositing — one pass, no epochs, no gradient descent, no
+fine-tuning jobs. Teach it a fact and it knows the fact. Now.
+
+</td>
+<td width="50%" valign="top">
+
+### 🔒 Total data sovereignty
+
+Runs entirely on **your** hardware. No API calls, no telemetry, no weights to
+leak. Everything a trained mind knows lives in a few files on your disk.
+
+</td>
+</tr>
+</table>
+
+> [!TIP]
+> **No GPU. No cluster. No cloud bill.** Sema runs on an ordinary CPU with a
+> tiny memory footprint, because it never multiplies a weight matrix — it walks
+> a graph. The economics of deploying intelligence change completely.
+
+---
+
+## ✦ See it think
+
+Give Sema four plain notes — the way you'd jot them down — then ask things **no
+note answers**. From three worked examples it learns the _shape_ of "X was
+painted by Y", lifts the painter out of a sentence it has **never seen**, and —
+in the same pass — reasons onward to a separate fact about that painter. The
+reply contains no word from the question: it is **retrieval, generalization, and
+reasoning composing as a single act**.
+
+```ts
+// demo.ts — one short session that drives the WHOLE pipeline from one memory.
+//
+// We give Sema a handful of plain notes, then ask things that no single note
+// answers. The headline query is the third one: from three worked examples Sema
+// learns the shape of "X was painted by Y", lifts the painter out of a sentence
+// it has NEVER seen, and then — in the same pass — reasons forward to a separate
+// fact about that painter. The reply contains no word from the question. That is
+// retrieval, generalization, and reasoning composing as a single act, with every
+// step traceable back to the notes behind it.
+
+import { Mind } from "../src/index.js";
+import { SQliteStore } from "../src/store-sqlite.js";
+
+async function main(): Promise<void> {
+  const mind = new Mind({ store: new SQliteStore({ path: ":memory:" }) });
+  const ask = async (q: string) => (await mind.respondText(q)).trim();
+
+  // ── Jot down what we know. Each line is just (context → what follows). ──
+  await mind.ingest([
+    // One relation, shown three times — a pattern taught purely by example:
+    ["The Mona Lisa was painted by Leonardo da Vinci.", "Leonardo da Vinci"],
+    ["The Starry Night was painted by Vincent van Gogh.", "Vincent van Gogh"],
+    [
+      "The Night Watch was painted by Rembrandt van Rijn.",
+      "Rembrandt van Rijn",
+    ],
+    // One stray fact, keyed on a name none of the examples mention:
+    ["Pablo Picasso", "Pablo Picasso co-founded the Cubist movement"],
+  ]);
+
+  // 1) GENERALIZE — apply the learned pattern to an unseen sentence and read out
+  //    the painter. "Pablo Picasso" was never given as an answer; Sema locates it
+  //    by analogy to the three examples.
+  console.log(await ask("The Weeping Woman was painted by Pablo Picasso."));
+  // → "Pablo Picasso co-founded the Cubist movement"
+  //   …and, having found the painter, it KEEPS GOING: the name bridges into the
+  //   one fact it holds about him. The answer appears in no word of the question.
+
+  // 2) COMPUTE — exact arithmetic, grounded right where the notes go silent.
+  console.log(await ask("a museum charges 12*4 for a family ticket"));
+  // → "48"
+
+  await mind.store.close();
+}
+
+main();
+```
+
+```text
+Pablo Picasso co-founded the Cubist movement
+48
+```
+
+> [!NOTE]
+> This is **[example/demo.ts](example/demo.ts)**, verbatim — run it yourself
+> with `npm run demo`. Look closely at the first answer: the question names a
+> painting Sema was never shown and asks nothing explicit, yet the reply is a
+> fact about Picasso that appears **nowhere** in the question. Sema generalized
+> "_painted by_" from three examples to recognize _Pablo Picasso_ as the answer
+> slot, then followed that name to the one thing it knows about him — retrieval,
+> an analogy, and a reasoning hop, in one query. The second answer is exact, not
+> a plausible-looking guess. Every step traces back to the four notes above.
+
+---
+
+## ✦ Engineered from three solved problems
+
+Sema is composed of three self-contained, independently documented engines. They
+are fully decoupled — Sema reaches them only through interfaces.
+
+| Engine            | What it solves                                                                             | Result                                                                                                                       |
+| :---------------- | :----------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- |
+| **`rabitq-hnsw`** | _"Given a vector, find the nodes whose gist resonates with it — fast, at scale, on disk."_ | HNSW over 1-bit RaBitQ codes · ~32× compression · bounded RAM · sub-linear queries                                           |
+| **`derive`**      | _"Explore a huge implicit space of derivations and return the single lightest one."_       | adapted A\*LD (adapted A\* Lightest Derivation) over a weighted deduction hypergraph — Sema's thinking _is_ one call to this |
+| **`alu`**         | _"Compute, exactly and symbolically, the things that are rules, not facts."_               | A tiny irreducible kernel from which arithmetic, logic, and n-dimensional computation are derived                            |
+
+---
+
+## ✦ Learn more
+
+| Document                                                                         | What's inside                                                                                                                                            |
+| :------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 📘 **[HOW_IT_WORKS.md](HOW_IT_WORKS.md)**                                        | The full theory: vector symbolic architectures, the Merkle DAG, distributional halos, weighted deduction — concepts, diagrams, and extensive pseudocode. |
+| 🛠️ **[AGENTS.md](AGENTS.md)**                                                    | The development manual: repo layout, build/test, internals, invariants, and recipes for extending the system.                                            |
+| ⚖️ **[LICENSE.md](LICENSE.md)**                                                  | PolyForm Noncommercial License 1.0.0.                                                                                                                    |
+| 💼 **[COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md)**                            | Commercial licensing terms and contact.                                                                                                                  |
+| 🤗 **[Trained examples](https://huggingface.co/buckets/hviana/sema-trained-v1)** | Pre-trained memory files you can download and use directly.                                                                                              |
+
+---
+
+<div align="center">
+
+## ⚖️ Licensing & compliance — please read
+
+</div>
+
+> [!WARNING]
+> **Sema is the product of serious, sustained research — and it is protected.**
+> It is released under the **PolyForm Noncommercial License 1.0.0**. Personal
+> study, academic research, experimentation, and use by noncommercial
+> organizations are welcome and explicitly permitted.
+
+> [!CAUTION]
+> **Commercial use requires a separate paid license.** This includes — but is
+> not limited to — use by a company; use to provide paid services or serve
+> clients; use inside a SaaS, hosted product, or any revenue-generating
+> platform; and use to reduce business costs or support business operations.
+>
+> Operating Sema commercially (artifacts and algorithmic logic) without a
+> license is a violation of its terms. See
+> **[COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md)** to obtain one, and
+> **[TRADEMARKS.md](TRADEMARKS.md)** — the **Sema** name, logos, and brand are
+> _not_ covered by the source license.
+
+<div align="center">
+
+**Respecting these terms funds the research that makes work like this
+possible.** If Sema creates value for your business, license it — and help keep
+independent, weight-free AI research alive.
+
+**© Sema Author** — Henrique Viana (creator).
+
+## Academic purpose:
+
+**hv5088@gmail.com**
+
+## Commercial licensing:
+
+**reis.marcelo@gmail.com**, **rogernact@gmail.com**
+
+**© Sema Supporters** — Marcelo Oliveira dos Reis · Rogerio Nascimento
+
+— ⬡ — ⬡ — ⬡ —
+
+</div>

package/TRADEMARKS.md

@@ -0,0 +1,19 @@
+# Trademarks and Brand Assets
+
+The software code is licensed under the PolyForm Noncommercial License 1.0.0.
+
+The following are not licensed under the software license:
+
+- redistribute its algorithmic logic: that is, how algorithms and mathematical
+  techniques are combined to develop its machinery;
+- visual identity;
+- project name;
+- logos;
+- icons;
+- brand assets;
+- domain names;
+- product names;
+- visual identity;
+- marketing materials.
+
+Permission to use the source code does not grant permission to use the brand.

package/example/demo.ts

@@ -0,0 +1,46 @@
+// demo.ts — one short session that drives the WHOLE pipeline from one memory.
+//
+// We give Sema a handful of plain notes, then ask things that no single note
+// answers. The headline query is the third one: from three worked examples Sema
+// learns the shape of "X was painted by Y", lifts the painter out of a sentence
+// it has NEVER seen, and then — in the same pass — reasons forward to a separate
+// fact about that painter. The reply contains no word from the question. That is
+// retrieval, generalization, and reasoning composing as a single act, with every
+// step traceable back to the notes behind it.
+
+import { Mind } from "../src/index.js";
+import { SQliteStore } from "../src/store-sqlite.js";
+
+async function main(): Promise<void> {
+  const mind = new Mind({ store: new SQliteStore({ path: ":memory:" }) });
+  const ask = async (q: string) => (await mind.respondText(q)).trim();
+
+  // ── Jot down what we know. Each line is just (context → what follows). ──
+  await mind.ingest([
+    // One relation, shown three times — a pattern taught purely by example:
+    ["The Mona Lisa was painted by Leonardo da Vinci.", "Leonardo da Vinci"],
+    ["The Starry Night was painted by Vincent van Gogh.", "Vincent van Gogh"],
+    [
+      "The Night Watch was painted by Rembrandt van Rijn.",
+      "Rembrandt van Rijn",
+    ],
+    // One stray fact, keyed on a name none of the examples mention:
+    ["Pablo Picasso", "Pablo Picasso co-founded the Cubist movement"],
+  ]);
+
+  // 1) GENERALIZE — apply the learned pattern to an unseen sentence and read out
+  //    the painter. "Pablo Picasso" was never given as an answer; Sema locates it
+  //    by analogy to the three examples.
+  console.log(await ask("The Weeping Woman was painted by Pablo Picasso."));
+  // → "Pablo Picasso co-founded the Cubist movement"
+  //   …and, having found the painter, it KEEPS GOING: the name bridges into the
+  //   one fact it holds about him. The answer appears in no word of the question.
+
+  // 2) COMPUTE — exact arithmetic, grounded right where the notes go silent.
+  console.log(await ask("a museum charges 12*4 for a family ticket"));
+  // → "48"
+
+  await mind.store.close();
+}
+
+main();