neocore-memory 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. neocore_memory-0.2.0/.github/workflows/publish.yml +39 -0
  2. neocore_memory-0.2.0/.github/workflows/test.yml +23 -0
  3. neocore_memory-0.2.0/.gitignore +13 -0
  4. neocore_memory-0.2.0/LICENSE +202 -0
  5. neocore_memory-0.2.0/NOTICE +7 -0
  6. neocore_memory-0.2.0/PKG-INFO +331 -0
  7. neocore_memory-0.2.0/README.md +307 -0
  8. neocore_memory-0.2.0/docs/governance.md +56 -0
  9. neocore_memory-0.2.0/docs/how-it-works.md +90 -0
  10. neocore_memory-0.2.0/docs/shared-memory.md +146 -0
  11. neocore_memory-0.2.0/evals/README.md +177 -0
  12. neocore_memory-0.2.0/evals/common.py +150 -0
  13. neocore_memory-0.2.0/evals/governance.py +172 -0
  14. neocore_memory-0.2.0/evals/locomo.py +274 -0
  15. neocore_memory-0.2.0/evals/longmemeval.py +308 -0
  16. neocore_memory-0.2.0/evals/results/governance.json +30 -0
  17. neocore_memory-0.2.0/evals/results/locomo.json +37 -0
  18. neocore_memory-0.2.0/evals/results/longmemeval-s.json +49 -0
  19. neocore_memory-0.2.0/integrations/hermes/README.md +91 -0
  20. neocore_memory-0.2.0/integrations/hermes/__init__.py +427 -0
  21. neocore_memory-0.2.0/integrations/hermes/plugin.yaml +6 -0
  22. neocore_memory-0.2.0/integrations/hermes/pyproject.toml +9 -0
  23. neocore_memory-0.2.0/integrations/hermes/tests/test_provider.py +163 -0
  24. neocore_memory-0.2.0/pyproject.toml +47 -0
  25. neocore_memory-0.2.0/scripts/install/install.ps1 +52 -0
  26. neocore_memory-0.2.0/scripts/install/install.sh +50 -0
  27. neocore_memory-0.2.0/src/neocore/__init__.py +112 -0
  28. neocore_memory-0.2.0/src/neocore/__main__.py +3 -0
  29. neocore_memory-0.2.0/src/neocore/assistant/__init__.py +1 -0
  30. neocore_memory-0.2.0/src/neocore/assistant/filter.py +578 -0
  31. neocore_memory-0.2.0/src/neocore/assistant/lessons.py +100 -0
  32. neocore_memory-0.2.0/src/neocore/assistant/memory.py +1535 -0
  33. neocore_memory-0.2.0/src/neocore/assistant/neosift.py +278 -0
  34. neocore_memory-0.2.0/src/neocore/assistant/outcomes.py +245 -0
  35. neocore_memory-0.2.0/src/neocore/assistant/render.py +190 -0
  36. neocore_memory-0.2.0/src/neocore/assistant/share.py +224 -0
  37. neocore_memory-0.2.0/src/neocore/assistant/sleep.py +252 -0
  38. neocore_memory-0.2.0/src/neocore/cli.py +386 -0
  39. neocore_memory-0.2.0/src/neocore/consolidation.py +411 -0
  40. neocore_memory-0.2.0/src/neocore/embedder.py +74 -0
  41. neocore_memory-0.2.0/src/neocore/llm.py +129 -0
  42. neocore_memory-0.2.0/src/neocore/neosift_server.py +209 -0
  43. neocore_memory-0.2.0/src/neocore/recall.py +1076 -0
  44. neocore_memory-0.2.0/src/neocore/shared/__init__.py +7 -0
  45. neocore_memory-0.2.0/src/neocore/shared/admin.py +279 -0
  46. neocore_memory-0.2.0/src/neocore/shared/client.py +405 -0
  47. neocore_memory-0.2.0/src/neocore/shared/keys.py +250 -0
  48. neocore_memory-0.2.0/src/neocore/shared/manage.py +369 -0
  49. neocore_memory-0.2.0/src/neocore/shared/server.py +618 -0
  50. neocore_memory-0.2.0/src/neocore/shared/tools.py +414 -0
  51. neocore_memory-0.2.0/src/neocore/store.py +234 -0
  52. neocore_memory-0.2.0/src/neocore/temporal.py +124 -0
  53. neocore_memory-0.2.0/tests/test_assistant.py +1478 -0
  54. neocore_memory-0.2.0/tests/test_consolidation.py +388 -0
  55. neocore_memory-0.2.0/tests/test_neosift.py +284 -0
  56. neocore_memory-0.2.0/tests/test_recall.py +151 -0
  57. neocore_memory-0.2.0/tests/test_setup.py +26 -0
  58. neocore_memory-0.2.0/tests/test_share.py +158 -0
  59. neocore_memory-0.2.0/tests/test_shared.py +432 -0
  60. neocore_memory-0.2.0/tests/test_stuck_offsets.py +106 -0
@@ -0,0 +1,39 @@
1
+ name: publish
2
+
3
+ # Uploads to PyPI with trusted publishing (no token stored anywhere). PyPI must list this repo,
4
+ # workflow `publish.yml` and environment `pypi` as a trusted publisher for `neocore-memory`.
5
+ on:
6
+ release:
7
+ types: [published]
8
+ workflow_dispatch:
9
+
10
+ jobs:
11
+ build:
12
+ runs-on: ubuntu-latest
13
+ steps:
14
+ - uses: actions/checkout@v4
15
+ - uses: actions/setup-python@v5
16
+ with:
17
+ python-version: "3.12"
18
+ - run: pip install build twine
19
+ - run: python -m build
20
+ - run: twine check dist/*
21
+ - uses: actions/upload-artifact@v4
22
+ with:
23
+ name: dist
24
+ path: dist/
25
+
26
+ pypi:
27
+ needs: build
28
+ runs-on: ubuntu-latest
29
+ environment:
30
+ name: pypi
31
+ url: https://pypi.org/project/neocore-memory/
32
+ permissions:
33
+ id-token: write
34
+ steps:
35
+ - uses: actions/download-artifact@v4
36
+ with:
37
+ name: dist
38
+ path: dist/
39
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,23 @@
1
+ name: test
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ jobs:
9
+ test:
10
+ strategy:
11
+ fail-fast: false
12
+ matrix:
13
+ os: [ubuntu-latest, windows-latest, macos-latest]
14
+ python: ["3.10", "3.12"]
15
+ runs-on: ${{ matrix.os }}
16
+ steps:
17
+ - uses: actions/checkout@v4
18
+ - uses: actions/setup-python@v5
19
+ with:
20
+ python-version: ${{ matrix.python }}
21
+ - run: pip install -e ".[embed,dev]"
22
+ - run: ruff check src tests
23
+ - run: pytest -q
@@ -0,0 +1,13 @@
1
+ __pycache__/
2
+ *.pyc
3
+ .venv/
4
+ dist/
5
+ build/
6
+ *.egg-info/
7
+ .pytest_cache/
8
+ .ruff_cache/
9
+ *.db
10
+ *.db-wal
11
+ *.db-shm
12
+ evals/data/
13
+ evals/runs/
@@ -0,0 +1,202 @@
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright [yyyy] [name of copyright owner]
191
+
192
+ Licensed under the Apache License, Version 2.0 (the "License");
193
+ you may not use this file except in compliance with the License.
194
+ You may obtain a copy of the License at
195
+
196
+ http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+ Unless required by applicable law or agreed to in writing, software
199
+ distributed under the License is distributed on an "AS IS" BASIS,
200
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+ See the License for the specific language governing permissions and
202
+ limitations under the License.
@@ -0,0 +1,7 @@
1
+ NeoCore
2
+ Copyright 2026 Vincent Porquet
3
+
4
+ NeoSift 32M (the model downloaded by `neocore sift install`) is fine-tuned from
5
+ cross-encoder/ettin-reranker-32m-v1 (https://huggingface.co/cross-encoder/ettin-reranker-32m-v1),
6
+ licensed under the Apache License 2.0, which is in turn fine-tuned from
7
+ jhu-clsp/ettin-encoder-32m (https://huggingface.co/jhu-clsp/ettin-encoder-32m).
@@ -0,0 +1,331 @@
1
+ Metadata-Version: 2.5
2
+ Name: neocore-memory
3
+ Version: 0.2.0
4
+ Summary: Governed long-term memory for AI assistants: recalls only what the moment needs. Shared memory for Claude Code and Codex.
5
+ Project-URL: Homepage, https://github.com/VincentPorquet777/neocore
6
+ Author: Vincent Porquet
7
+ License-Expression: Apache-2.0
8
+ License-File: LICENSE
9
+ License-File: NOTICE
10
+ Keywords: agents,claude-code,codex,llm,long-term-memory,memory,rag
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
15
+ Requires-Python: >=3.10
16
+ Provides-Extra: dev
17
+ Requires-Dist: pytest>=8; extra == 'dev'
18
+ Requires-Dist: ruff>=0.5; extra == 'dev'
19
+ Provides-Extra: embed
20
+ Requires-Dist: numpy>=1.24; extra == 'embed'
21
+ Requires-Dist: onnxruntime>=1.17; extra == 'embed'
22
+ Requires-Dist: tokenizers>=0.15; extra == 'embed'
23
+ Description-Content-Type: text/markdown
24
+
25
+ # NeoCore
26
+
27
+ [![test](https://github.com/VincentPorquet777/neocore/actions/workflows/test.yml/badge.svg)](https://github.com/VincentPorquet777/neocore/actions/workflows/test.yml)
28
+ [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
29
+ ![Python](https://img.shields.io/badge/python-3.10%2B-blue)
30
+
31
+ **Long-term memory for AI assistants that recalls only what the moment needs, and never what it
32
+ shouldn't.**
33
+
34
+ NeoCore gives Claude Code and Codex one shared memory of your past sessions. It can also be
35
+ dropped into any assistant as a Python library. Recall makes **zero LLM calls**: it is local,
36
+ takes milliseconds and costs nothing (the optional [NeoSift](#neosift-the-local-relevance-filter)
37
+ filter is a small local model on your graphics card, no API either). Every recalled line is quoted verbatim and dated, with a
38
+ receipt pointing to its source. Governance (who may see what, what was revoked, what was
39
+ corrected) is enforced at recall time, not left to the model.
40
+
41
+ | | NeoCore |
42
+ | --- | --- |
43
+ | LoCoMo (10 conversations, 1,540 questions) | **87.5%** (gpt-4.1-mini reader) |
44
+ | LongMemEval-S (500 questions) | **89.6%** (gpt-4.1-mini reader, gpt-4o judge) |
45
+ | Governance: leaks under maximal pressure | **0 leaks** in 1,540 questions (an ungoverned store leaked on all 1,540) |
46
+ | Model calls per recall | **0**: p50 22 ms on a laptop CPU, offline |
47
+
48
+ All numbers come from this repository's code (`evals/`), run through the public package. See
49
+ [Evals](#evals) for the setup and the honest caveats.
50
+
51
+ ## Why another memory?
52
+
53
+ The context window is small and your history is large. Most memory layers either stuff the
54
+ window with everything that matches, or call an LLM on every turn to decide what to remember and
55
+ recall. NeoCore starts from a different idea. Think of how a person remembers: you don't scan
56
+ your whole life to answer a question. You recall the few things this moment is about. You trust
57
+ that what you recall is still true, and you know what you were told in confidence.
58
+
59
+ - **Relevant, not just similar.** Hybrid recall (BM25 + local embeddings, fused) is spent on a
60
+ byte budget in order of relevance. An optional relevance filter keeps only what helps with
61
+ this prompt. A chat is never sent again what it already holds.
62
+ - **Newest wins.** A nightly "sleep" pass groups related facts and retires the stale ones
63
+ ("the API runs v1.17" gives way to "the API runs v1.18"). A retired fact never arrives without
64
+ what replaced it.
65
+ - **Learns from mistakes.** When something went wrong, a "Lesson:" is formed and shown first next
66
+ time ("never deploy the worker while a job is running").
67
+ - **Governed by construction.** Scopes, revocation, audited erasure, edited messages (only the
68
+ latest revision counts) and abandoned conversation branches are all filters applied before
69
+ ranking. A fact is recalled only while *every* message it came from may be.
70
+ - **Exact and traceable.** Excerpts are verbatim slices of what was said. Their offsets point
71
+ into the stored message. Relative dates are resolved (`last Friday [= 19 May 2023]`) and
72
+ clearly marked as NeoCore's note, not speech.
73
+ - **Shared between assistants.** What you decided with Claude Code on Monday is there for Codex
74
+ on Tuesday, and the other way round.
75
+
76
+ ## Quick start: Claude Code and Codex
77
+
78
+ ```bash
79
+ pipx install "neocore-memory[embed] @ git+https://github.com/VincentPorquet777/neocore"
80
+ neocore setup
81
+ ```
82
+
83
+ `neocore setup` does four things:
84
+
85
+ - downloads the bge-small embedder (~35 MB, CPU);
86
+ - adds a prompt hook and a stop hook to `~/.claude/settings.json` (merged, backup kept);
87
+ - adds an MCP server and the same hooks to `~/.codex/config.toml` (inside marked lines);
88
+ - writes `~/.neocore/config.json`.
89
+
90
+ Codex will ask you to trust the new hooks the first time they run. `neocore uninstall` removes
91
+ the hooks and keeps your memory. `neocore doctor` checks the install. Run
92
+ `neocore setup --dry-run` to see the plan first.
93
+
94
+ After setup:
95
+
96
+ - **Every prompt** gets the memory that matters, as hook context, in well under a second. A warm
97
+ local daemon serves it.
98
+ - **Every finished reply** starts a background sync. It reads new turns from Claude Code and
99
+ Codex transcripts (prompts and final replies only; tool output is skipped and obvious secrets
100
+ are redacted) and indexes them.
101
+ - **In the background**, your own Codex or Claude Code sign-in forms dated facts, runs sleep and
102
+ writes lessons (see `neocore.llm`). No API key is needed. Nothing is sent anywhere else.
103
+ - **Relevance filter (NeoSift):** on a machine with a graphics card, setup installs
104
+ [NeoSift](#neosift-the-local-relevance-filter), NeoCore's own small model that keeps only the
105
+ memories that help with this prompt. It is free and local. Without a graphics card, set
106
+ `OPENROUTER_API_KEY` before `neocore setup` to use a small hosted decision model instead
107
+ (~$0.0007 per prompt), or recall injects its top matches within the budget.
108
+ - **Help improve NeoSift (opt-in):** setup asks once whether to share prompts and recalled
109
+ memories to train NeoSift. It is off unless you say yes. See
110
+ [what is shared](#help-improve-neosift-opt-in).
111
+
112
+ Useful commands:
113
+
114
+ ```bash
115
+ neocore recall "how did we deploy the worker last time"
116
+ neocore status # counts and configuration
117
+ neocore stats --days 7 # live relevance, latency and error estimates
118
+ neocore forget claude-code:<session-id> # erase a conversation for good (audited)
119
+ neocore sift status # NeoSift: installed, graphics card, in use
120
+ neocore share status # opt-in sharing: on/off, rows waiting and sent
121
+ ```
122
+
123
+ ## NeoSift: the local relevance filter
124
+
125
+ Recall finds candidates by words and meaning, but many of them only share words with the
126
+ prompt. NeoSift is a 32M-parameter cross-encoder that reads the prompt, the end of the turn
127
+ before it and each candidate memory, and gives the chance that the memory would help. Only the
128
+ best are injected (score >= 0.4, at most 12).
129
+
130
+ It was trained on real coding-assistant prompts whose candidate memories were graded by a
131
+ frontier model (GPT-6.1). On 103 held-out real prompts, ranking useful memories above useless
132
+ ones:
133
+
134
+ | Scorer | Where it runs | Score |
135
+ | --- | --- | --- |
136
+ | GPT-6.1 (the teacher) | hosted | 0.970 |
137
+ | TypeSafe Jev 1.13 | hosted, ~$0.0007 per prompt | 0.931 |
138
+ | **NeoSift 32M** | **your graphics card, free** | **0.914** |
139
+
140
+ On prompts where no memory was useful, NeoSift still let something through 40% of the time,
141
+ against 74% for Jev. On 885 real prompts graded *after* their replies, the default cut-off
142
+ injected 5.7 memories per prompt and caught 66% of the memories the replies needed. Raising the
143
+ cut-off trades needed memories away about as fast as it saves space.
144
+
145
+ **It needs a graphics card.** One prompt (48 candidates) takes 0.07 s on an RTX 3080, but 7-8 s
146
+ on a desktop processor, longer than a prompt can wait. So `neocore setup` installs it only when
147
+ it finds an NVIDIA card or Apple silicon, and only if a speed check passes:
148
+
149
+ ```bash
150
+ neocore sift install # or: neocore setup (does it when a graphics card is found)
151
+ neocore sift remove
152
+ ```
153
+
154
+ It lives in `~/.neocore/sift`: its own Python environment (torch, transformers, ~2-3 GB), the
155
+ pinned model (~120 MB, hash-checked) and a server on `127.0.0.1` that keeps nothing. If it ever
156
+ cannot answer in time, that prompt gets unfiltered recall instead of none. NeoSift is
157
+ fine-tuned from [Ettin](https://huggingface.co/cross-encoder/ettin-reranker-32m-v1)
158
+ (Apache-2.0); see [NOTICE](NOTICE).
159
+
160
+ ## Help improve NeoSift (opt-in)
161
+
162
+ NeoSift gets better with more real prompts. `neocore setup` asks once:
163
+
164
+ > Help improve NeoSift? If you say yes, NeoCore sends the prompts it recalls memory for, the
165
+ > end of the turn before each, the memories it offered and their scores, encrypted, to the
166
+ > NeoCore team. An AI model grades them
167
+ > and they are used only to train NeoSift, which outputs scores and cannot reproduce text. Your
168
+ > content is never used as knowledge, shared or sold. It is stored encrypted so future versions
169
+ > keep learning from it. Off by default. Stop any time with `neocore share off`, or remove
170
+ > everything you sent with `neocore share delete`.
171
+
172
+ What that means exactly (the code is [share.py](src/neocore/assistant/share.py)):
173
+
174
+ - **Sent:** the prompt, your previous message (first 600 characters) and the end of the
175
+ assistant's previous reply (last 800 characters), which is what NeoSift reads, and the
176
+ memories recall offered with their scores, after NeoCore's usual secret redaction. Never the
177
+ reply to the prompt, tool output or whole conversations. Prompts of fewer than three words
178
+ are skipped (nothing to learn from), and at most 300 rows a day.
179
+ - **How:** compressed, over HTTPS, in small batches, at most every six hours. On arrival each
180
+ batch is encrypted with a key that only our training machine holds; the receiving service
181
+ cannot read it back, and it keeps a batch only until the training machine has collected it.
182
+ `neocore share off` also drops rows not yet sent.
183
+ - **Used for:** grading by an AI model and training NeoSift. Nothing else.
184
+ - **Deleting:** your install sends with a random secret id (in `~/.neocore/share/id`; we store
185
+ only its hash). `neocore share delete` deletes everything sent with it, including rows already
186
+ collected for training (within a day), turns sharing off and starts a new id.
187
+
188
+ ## One memory across machines
189
+
190
+ Run the memory on one always-on machine (a home PC or a small VPS) and connect every other
191
+ machine to it. Tell Claude Code on your laptop something once; Codex on your desktop knows it in
192
+ its next chat's first message.
193
+
194
+ ```bash
195
+ # on the machine that keeps the memory
196
+ neocore server init --person alex --device laptop --device desktop
197
+ # on each device, with the key file that device was given
198
+ neocore connect --url https://memory.example.com --key-file laptop.key
199
+ ```
200
+
201
+ Each device has its own key, stored hashed on the server and revocable at once. Keys carry
202
+ scopes, so one server can keep separate memories that never mix. Nothing is lost while the server
203
+ is away: a device's transcripts are its queue. Admin commands (`neocore server scopes`, `audit`,
204
+ `export`, `forget`) never show memory text unless asked to export it. One-command installers for
205
+ Linux, macOS and Windows are in `scripts/install/`. Full guide:
206
+ [docs/shared-memory.md](docs/shared-memory.md).
207
+
208
+ ## Quick start: Hermes Agent
209
+
210
+ NeoCore is a memory provider for [Hermes Agent](https://github.com/NousResearch/hermes-agent)
211
+ (0.22.2 or newer):
212
+
213
+ ```bash
214
+ hermes plugins install VincentPorquet777/neocore/integrations/hermes
215
+ hermes memory setup # pick "neocore"
216
+ ```
217
+
218
+ Each turn is kept verbatim in the profile, and dated excerpts are recalled before the next turns
219
+ with zero model calls. By default each messaging chat keeps its own memory. The agent also gets
220
+ `neocore_search` and `neocore_forget` tools. Settings, what is stored and the one-time model
221
+ download are described in [integrations/hermes](integrations/hermes/README.md).
222
+
223
+ ## Quick start: any assistant
224
+
225
+ ```python
226
+ from neocore import Memory
227
+
228
+ memory = Memory("memory.db") # uses the embedder `neocore setup` downloaded, if present
229
+
230
+ memory.add(conversation="chat-1", user="I moved to Lisbon in May for the Feedzai job.",
231
+ assistant="Congratulations on the move!", at="2026-05-03T10:00:00Z")
232
+ memory.add(conversation="chat-2", user="My card PIN hint is in the blue notebook.",
233
+ scope="private")
234
+
235
+ result = memory.recall("Where do I work now?", scopes=["internal"])
236
+ print(result.rendered) # dated, verbatim, budgeted block for your prompt
237
+ print(result.receipt) # every delivered excerpt: evidence id + character offsets
238
+ ```
239
+
240
+ - `memory.revoke(evidence_id, reason=...)` hides a message until `memory.store.restore(...)`.
241
+ - `memory.forget(evidence_id, reason=...)` deletes the text and keeps an audit tombstone.
242
+ - `memory.abandon_branch(branch_id, reason=...)` drops an edited-away branch.
243
+ - `memory.form_facts(ask)` forms dated facts with any model: `neocore.llm` has Codex CLI, Claude
244
+ CLI and OpenAI-compatible backends.
245
+
246
+ The only required dependency is the Python standard library. `pip install neocore-memory[embed]`
247
+ adds dense recall (numpy, onnxruntime, tokenizers).
248
+
249
+ ## How it works
250
+
251
+ ```
252
+ your prompt ──► hook ──► warm daemon ──► Governed Recall ──► (optional filter) ──► context
253
+ │ permitted? scope · revoked · branch · revision
254
+ │ rank BM25 + bge-small, reciprocal-rank fused
255
+ │ render verbatim, dated, budgeted, receipts
256
+ finished reply ──► sync ──► store (SQLite: immutable messages + access log)
257
+ └──► background, your own Codex/Claude sign-in:
258
+ facts (dated, cite their messages) · sleep (newest wins) · lessons
259
+ ```
260
+
261
+ - **Store** (`neocore/store.py`): one immutable row per message. An append-only access log
262
+ covers revoke, restore and forget, and a branch log covers abandoned branches. Nothing is ever
263
+ updated in place.
264
+ - **Recall** (`neocore/recall.py`): permission is decided first. Ranking only ever sees permitted
265
+ messages, so a forbidden message cannot "rank its way in".
266
+ - **Formation, sleep, lessons** (`neocore/assistant/`): facts are add-only and cite their
267
+ sources. Sleep judges groups of near-duplicate facts (current, history, superseded, outdated,
268
+ duplicate) and every verdict can be undone. Lessons cite the facts they draw on.
269
+
270
+ More in [docs/how-it-works.md](docs/how-it-works.md) and [docs/governance.md](docs/governance.md).
271
+
272
+ ## Evals
273
+
274
+ Everything below runs through `neocore.Memory` and `GovernedRecall` from this repository. The
275
+ recall step makes no model calls. Reader and judge are the only models. See
276
+ [evals/README.md](evals/README.md) to reproduce them.
277
+
278
+ | Benchmark | Questions | NeoCore | Reader / judge | Recall p50 | Cost |
279
+ | --- | --- | --- | --- | --- | --- |
280
+ | LoCoMo (10 conversations, categories 1–4) | 1,540 | **87.5%** | gpt-4.1-mini / gpt-4o-mini | 22 ms | $2.42 |
281
+ | LongMemEval-S | 500 | **89.6%** | gpt-4.1-mini / gpt-4o (official prompts) | 20 ms | $1.52 |
282
+ | Governance (leaks) | 1,540 | **0** (control: 1,540) | none | 14 ms | $0 |
283
+
284
+ By category:
285
+
286
+ | LoCoMo | | LongMemEval-S | |
287
+ | --- | --- | --- | --- |
288
+ | single-hop (841) | 91.8% | single-session-user (70) | 98.6% |
289
+ | temporal (321) | 88.2% | knowledge-update (78) | 92.3% |
290
+ | multi-hop (282) | 82.3% | temporal-reasoning (133) | 91.7% |
291
+ | open-domain (96) | 63.5% | single-session-preference (30) | 90.0% |
292
+ | | | single-session-assistant (56) | 87.5% |
293
+ | | | abstention (30, overlaps the others) | 86.7% |
294
+ | | | multi-session (133) | 82.0% |
295
+
296
+ Recall makes no model calls in every row. The cost is the reader and judge calls through
297
+ OpenRouter.
298
+
299
+ Caveats, stated plainly:
300
+
301
+ - **Tuned on these benchmarks.** Recall settings (budget, top-k, the 30% fact share) were tuned
302
+ on a stratified pilot of LongMemEval-S and four LoCoMo conversations, so these are not fully
303
+ held-out numbers.
304
+ - **Facts formed once.** Facts were formed once per session with gpt-4o-mini and are reused here
305
+ (`evals/data/*facts*`).
306
+ - **Lenient LoCoMo judge.** Our LoCoMo judge prompt is generous about wording, like the Mem0
307
+ protocol, but it is our own prompt.
308
+ - **Others' headline figures use bigger models.** Zep's 94.7% on LoCoMo uses gpt-5.4 to answer
309
+ and to judge; Mem0's 94.4% (LongMemEval) and 92.5% (LoCoMo) do not state their answering model or
310
+ judge. With the same small answering model as ours, published LoCoMo results range from 64% to
311
+ 93%, and some systems score above NeoCore. We have not re-run them. The like-for-like comparison,
312
+ with sources, is in [Where NeoCore stands](https://aiforge.uk/blog/where-neocore-stands/).
313
+
314
+ ## Status and limits
315
+
316
+ NeoCore 0.2 is beta.
317
+
318
+ - **Battle-tested scale is modest.** The assistant integration has run daily on one developer's
319
+ Claude Code and Codex history (thousands of turns), and the engine has run behind three
320
+ production assistants. Scale tests on large corpora are still to come.
321
+ - **NeoSift needs a graphics card.** Machines without one use the hosted scorer or unfiltered
322
+ recall. A faster model for processors is a future training round.
323
+ - **NeoSift has learned mostly from one developer's coding prompts so far.** On two business
324
+ assistants' prompts it agreed with its teacher less well (0.68 against 0.80, an earlier
325
+ round). Opt-in sharing is how it learns everyone's.
326
+ - **Windows, macOS and Linux.** The daemon and hooks are developed on Windows and use only the
327
+ standard library elsewhere. Please report issues.
328
+
329
+ ## License
330
+
331
+ Apache-2.0. See [LICENSE](LICENSE).