n3memorycore-free 1.3.1__tar.gz

n3memorycore_free-1.3.1/LICENSE

@@ -0,0 +1,190 @@
+                                 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 the 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 the 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 any 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
+
+   Copyright 2026 NeuralNexusNote / ArnolfJp019
+
+   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.

n3memorycore_free-1.3.1/NOTICE

@@ -0,0 +1,4 @@
+N3MemoryCore (N3MC)
+Copyright 2026 NeuralNexusNote / ArnolfJp019
+
+This product is part of the NeuralNexusNote project.

n3memorycore_free-1.3.1/PKG-INFO

@@ -0,0 +1,296 @@
+Metadata-Version: 2.4
+Name: n3memorycore-free
+Version: 1.3.1
+Summary: Persistent hybrid-search memory store for Claude Code (Free Edition)
+Author: N3MemoryCore contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/NeuralNexusNote/n3mc-free
+Project-URL: Issues, https://github.com/NeuralNexusNote/n3mc-free/issues
+Keywords: claude,claude-code,memory,rag,embedding,sqlite-vec
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: sentence-transformers>=2.5
+Requires-Dist: sqlite-vec>=0.1.6
+Requires-Dist: uuid7>=0.1.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: httpx>=0.27; extra == "test"
+Dynamic: license-file
+
+# N3MemoryCore (N3MC)
+> A NeuralNexusNote™ product
+
+🛡️ AI-Native Development Policy
+This project prioritizes Instructions over Static Code. Please read our Development Philosophy to understand why you should let AI generate your execution environment.
+
+> 🇯🇵 **[Click here for the Japanese Documentation (日本語版)](./README_JP.md)**
+> 🛡️ **[Development Philosophy & AI-Native Policy](./PHILOSOPHY.md)**
+
+> I know Java and C#, but Python is completely new to me.
+> The code Claude Code generated — I built it without fully understanding it.
+>
+> But I tested it, refined the specification, rebuilt it,
+> and shipped both Japanese and English versions — Free and Pro.
+>
+> Because if I could do it, so can you.
+>
+> The first draft of the specification was written by Copilot.
+> Claude Code turned it into working code. Gemini reviewed it.
+> Iterated across three AIs — that process is N3MemoryCore.
+
+N3MemoryCore gives Claude Code long-term memory across sessions.
+**Two install paths supported**: drop the spec into Claude Code and let it build the system, or `pip install` the reference build and run `n3mc --init`. Either way, no manual hook editing. (See [Setup](#setup) below.)
+
+---
+
+## Features
+
+- 💾 **Fully local** — Your conversations stay on your machine. Nothing sent to the cloud.
+- 🔍 **Semantic search** — Finds relevant past conversations even when the exact words differ. Multilingual by default (`intfloat/multilingual-e5-base`) — works for Japanese, English, Chinese, Korean, and ~100 other languages out of the box. Swap to a language-specialised model via `config.json` if you need higher single-language precision.
+- 🔄 **Persistent across sessions** — Pick up tomorrow where you left off today.
+- ⚡ **Works automatically** — Saving and searching happen automatically. No manual steps needed.
+- 🤖 **Multi-agent ready** — Multiple AI agents share one memory DB. Each agent prioritizes its own memories while accessing the team's collective knowledge.
+- 🏢 **Team & organization support** — Deploy the server on your network and share memories across your entire team.
+- 🔗 **DB merge ready** — Databases built from the same specification are fully compatible. Transfer knowledge when handing off roles, or import memories accumulated in other environments — the DB structure is designed for integration from the ground up.
+- 💰 **Reduces token waste** — No more re-explaining past context. Memory search uses local embeddings (zero Claude tokens), and accurate context injection means fewer corrections and back-and-forth.
+
+## How It Works
+
+```
+User's message
+    │
+    ▼
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│  1. Auto-save │────▶│ 2. Semantic   │────▶│ 3. Context    │
+│  Save last    │     │    search     │     │    injection   │
+│  response     │     │  Find related │     │  Feed to       │
+│  to DB        │     │  memories     │     │  Claude        │
+└──────────────┘     └──────────────┘     └──────────────┘
+                                                 │
+                                                 ▼
+                                          Claude responds
+                                          with full context
+```
+
+Powered by Claude Code's hook system. Everything happens automatically — no user action required.
+
+### Relationship with Claude's built-in auto-memory
+
+Claude Code has a built-in auto-memory system (`~/.claude/projects/.../memory/`). N3MemoryCore **complements it rather than competing with it**.
+
+| | Claude auto-memory | N3MemoryCore RAG |
+|---|---|---|
+| **Strengths** | Reliable, loads every session, great for fixed facts | Conversation context, detailed history |
+| **Weaknesses** | Cannot capture conversation flow or context | Depends on search quality; not guaranteed to surface |
+| **Best for** | User profile, folder paths, stable settings | Conversation threads, past decisions, reasoning |
+
+**Recommended usage:**
+- **Fixed information needed every session** (folder paths, user preferences) → save to auto-memory
+- **Conversation context and history** (discussion threads, past decisions) → N3MemoryCore accumulates automatically
+
+## Free vs Pro
+
+| | Free | Pro |
+|---|---|---|
+| Core features (save, search, auto) | ✅ | ✅ |
+| Refresh (dedup & update) | - | ✅ Auto-replaces outdated memories |
+| Session/environment bias | - | ✅ Prioritizes recent & local context |
+| GC (garbage collection) | - | ✅ Auto-cleanup of old memories |
+| Import/Export | - | ✅ Data migration & sharing |
+| Delete | - | ✅ Individual record deletion |
+
+**Start with Free.** You can upgrade to Pro later using the Upgrade specification.
+
+## Specification Files
+
+| File | Description |
+|---|---|
+| `N3MemoryCore_v1.2.0_Free_JP.md` | Free edition (Japanese) |
+| `N3MemoryCore_v1.2.0_Free_EN.md` | Free edition (English) |
+
+> 💡 **A note on annotations in the specification**
+> Throughout the specification file (Markdown), you'll find annotations describing the design intent behind each instruction — written to give you precise control over AI behavior. Before having Claude generate the code, take a moment to read through them. They contain more than just code: the logic behind how to work with AI effectively.
+
+## Setup
+
+There are two supported setup paths. Pick whichever fits your style.
+
+### Path A — AI-Native Setup (canonical)
+
+1. Pick a specification file from the table above
+2. Drop the file into the Claude Code prompt
+3. Say: "Please implement this."
+
+That's it. Claude Code writes the code, configures the hooks, and sets everything up.
+Setup takes roughly 15–30 minutes (varies by environment and model).
+Memory kicks in from the next session.
+
+### Path B — Quick Start with `pip`
+
+If you'd rather skip the AI implementation step and use the reference build directly:
+
+#### 1. Install
+
+```bash
+git clone https://github.com/NeuralNexusNote/n3mc-free.git
+cd n3mc-free
+pip install -e .          # or  pip install .
+```
+
+Requirements: Python 3.10+. The first server start will download the embedding model (`intfloat/multilingual-e5-base`, ~470 MB) — expect a 2–10 minute one-time delay.
+
+#### 2. Connect to Claude Code
+
+```bash
+n3mc --init
+```
+
+This single command does **everything** needed to wire N3MC into Claude Code:
+
+- Creates `~/.n3mc/` (data lives here — DB, config, audit log, PID file).
+- Writes `~/.n3mc/config.json` with auto-generated `owner_id` / `local_id`.
+- Registers the `UserPromptSubmit` and `Stop` hooks in **your user-global** `~/.claude/settings.json`, pointing to the installed `n3mc-hook` / `n3mc-stop-hook` entry-point scripts. The "user-global" location is essential — it means hooks fire from **any** project directory, not just this repo.
+
+The command is idempotent: re-running it is safe and won't create duplicates.
+
+#### 3. Verify the hook registration
+
+Run this one-liner — it should print `OK`:
+
+```bash
+python -c "import json,os; s=json.load(open(os.path.expanduser('~/.claude/settings.json'))); h=s.get('hooks',{}); assert any('n3mc' in c.get('command','').lower() for e in h.get('UserPromptSubmit',[]) for c in e.get('hooks',[])), 'UserPromptSubmit hook missing'; assert any('n3mc' in c.get('command','').lower() for e in h.get('Stop',[]) for c in e.get('hooks',[])), 'Stop hook missing'; print('OK')"
+```
+
+If you see `OK`, the hooks are registered correctly. If you see an `AssertionError`, re-run `n3mc --init`.
+
+#### 4. Restart Claude Code
+
+Close **every** running Claude Code session (terminal CLI windows, IDE extensions like VS Code's "Claude Code" panel, etc.) and start a fresh one. Hooks are read at session startup; sessions started before `n3mc --init` will not pick up the new hooks.
+
+#### 5. Confirm it's working
+
+In a fresh Claude Code session, send any message. After Claude responds, run:
+
+```bash
+n3mc --list
+```
+
+You should see at least two records — one with a `[user]` prefix (your message) and one with a `[claude]` prefix (Claude's response). If the list is empty, jump to **Troubleshooting** below.
+
+#### Optional: change where data lives
+
+Override the data location by setting `N3MC_HOME=/path/to/dir` before running `n3mc --init` (the chosen path is then permanent for that install).
+
+---
+
+### Troubleshooting (Path B)
+
+**`n3mc: command not found` after `pip install`**
+Your Python `Scripts/` (Windows) or `bin/` (macOS/Linux) directory is not on `PATH`. Either add it to `PATH`, or invoke as `python -m n3memorycore.n3memory --init` instead.
+
+**`--list` shows zero records after a real conversation**
+You opened the Claude Code session **before** running `n3mc --init`. Close it completely and open a new session — hooks are loaded at session start.
+
+**Hooks register, but nothing saves**
+Check the audit log:
+```bash
+cat ~/.n3mc/.memory/audit.log | tail -3
+```
+Each user prompt should produce one JSON line. If the file is empty, the hooks aren't firing — confirm Step 3's verification command prints `OK`, and confirm `~/.claude/settings.json` (user-global, not project-local) was the file modified.
+
+**`n3mc --search` returns nothing the first time, but works after**
+The `intfloat/multilingual-e5-base` model is downloading (~470 MB) on the first call. Wait 2–10 minutes for the download to finish, then retry.
+
+### What to expect after setup
+
+Once setup is complete, everything works automatically from the next session:
+- Past conversations relevant to your current message are retrieved and injected automatically
+- Claude responds with full context ("Regarding what we discussed last time...")
+- Saving and searching happen in the background — no action needed on your part
+
+### Backup and restore
+
+To migrate memories to another environment or keep a safe backup, save these 2 files
+from `~/.n3mc/`:
+- `.memory/n3memory.db` — the memory database
+- `config.json` — contains `owner_id` and `local_id` UUIDv4 keys
+
+These 2 files must be kept together. If the keys don't match, owner verification will fail.
+
+### Uninstall
+
+```bash
+pip uninstall n3memorycore-free
+rm -rf ~/.n3mc/                                      # delete data (irreversible)
+# Then manually remove the hook entries from ~/.claude/settings.json.
+```
+
+Or, if you set up via Path A, ask Claude Code: "Please uninstall N3MemoryCore."
+
+## ID Hierarchy
+
+N3MemoryCore uses 5 ID fields to identify the origin and context of each record:
+
+| ID | Stored in | Generated | Granularity | Purpose |
+|---|---|---|---|---|
+| `id` (PK) | DB record | Per record (UUIDv7, time-ordered) | **One record** | Unique identifier for each memory — used for deletion and dedup |
+| `owner_id` | `config.json` | First startup (UUIDv4) | **Owner / N3MC server** | Identifies whose data this is — for shared/multi-user scenarios and import provenance |
+| `session_id` | In-memory or supplied by host | Per task / project / conversation (UUIDv4) | **Task / project / conversation** | Groups memories that belong to one task / project / conversation. In Free, drives the `b_session` ranking bias (match=1.0, mismatch=0.6) so the ongoing exchange ranks above unrelated past sessions |
+| `local_id` (agent_id) | `config.json` / API | First startup (UUIDv4), or per request | **Agent / install** | UUIDv4 identifier for the speaking agent. Each agent gets its own UUID in multi-agent setups (in Free, stored but not used in ranking; `b_local` is a Pro feature) |
+| `agent_name` | DB record | Per buffer call (free-form string) | **Agent display name** | Human-readable label for the agent (e.g. `"claude-code"`) |
+
+```
+owner_id  (one N3MC server / data owner)
+  └── session_id  (one task / project / conversation)
+        └── local_id  (the speaking agent within that session)
+              ├── agent_name  (its display name: "claude-code", etc.)
+              └── id  (one memory record)
+```
+
+## Requirements
+
+- **Claude Code** (required)
+- **Python 3.10+**
+- **OS**: Windows 11 (tested) / macOS and Linux (designed for, but not yet verified)
+
+> To check if Python is installed, run `python --version` in your terminal.
+> If missing, Claude Code will guide you during setup.
+
+## Extensibility
+
+N3MemoryCore is built from a specification, so extending it is as simple as asking Claude Code.
+
+- **MCP server** — Expose N3MC as an MCP server so other AI tools can access the memory
+- **PostgreSQL migration** — Move from SQLite to PostgreSQL + pgvector for team-scale deployments
+- **Custom search logic** — Tune bias coefficients and ranking formulas
+- **Alternative embedding models** — Swap in a different model to suit your use case
+- **Custom ID fields** — Add fields like `project_id` or `tag` to organize memories your way
+- **PDF import** — Extract text from PDF files and store them as searchable memories
+- **Hashtag support** — Claude auto-tags memories with `#hashtags` for filtered search (e.g. `--search "#AWS"`) — works with existing FTS, no DB changes needed
+
+Just load the specification into Claude Code and say what you want to add.
+
+## ⚠️ Disclaimer
+
+- **No support, no claims**: This project is provided as-is with no support. Questions, bug reports, and feature requests are not guaranteed a response. Use entirely at your own discretion.
+- **Use at your own risk**: This system runs on AI-generated code. The author is not responsible for any data changes or issues caused by its use.
+- **Backup first**: Always back up your current environment before running this on important projects.
+
+---
+
+Apache License 2.0 — Copyright (C) 2026 NeuralNexusNote™ / ArnolfJp019
+See [LICENSE](./LICENSE) for details.