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.
- neocore_memory-0.2.0/.github/workflows/publish.yml +39 -0
- neocore_memory-0.2.0/.github/workflows/test.yml +23 -0
- neocore_memory-0.2.0/.gitignore +13 -0
- neocore_memory-0.2.0/LICENSE +202 -0
- neocore_memory-0.2.0/NOTICE +7 -0
- neocore_memory-0.2.0/PKG-INFO +331 -0
- neocore_memory-0.2.0/README.md +307 -0
- neocore_memory-0.2.0/docs/governance.md +56 -0
- neocore_memory-0.2.0/docs/how-it-works.md +90 -0
- neocore_memory-0.2.0/docs/shared-memory.md +146 -0
- neocore_memory-0.2.0/evals/README.md +177 -0
- neocore_memory-0.2.0/evals/common.py +150 -0
- neocore_memory-0.2.0/evals/governance.py +172 -0
- neocore_memory-0.2.0/evals/locomo.py +274 -0
- neocore_memory-0.2.0/evals/longmemeval.py +308 -0
- neocore_memory-0.2.0/evals/results/governance.json +30 -0
- neocore_memory-0.2.0/evals/results/locomo.json +37 -0
- neocore_memory-0.2.0/evals/results/longmemeval-s.json +49 -0
- neocore_memory-0.2.0/integrations/hermes/README.md +91 -0
- neocore_memory-0.2.0/integrations/hermes/__init__.py +427 -0
- neocore_memory-0.2.0/integrations/hermes/plugin.yaml +6 -0
- neocore_memory-0.2.0/integrations/hermes/pyproject.toml +9 -0
- neocore_memory-0.2.0/integrations/hermes/tests/test_provider.py +163 -0
- neocore_memory-0.2.0/pyproject.toml +47 -0
- neocore_memory-0.2.0/scripts/install/install.ps1 +52 -0
- neocore_memory-0.2.0/scripts/install/install.sh +50 -0
- neocore_memory-0.2.0/src/neocore/__init__.py +112 -0
- neocore_memory-0.2.0/src/neocore/__main__.py +3 -0
- neocore_memory-0.2.0/src/neocore/assistant/__init__.py +1 -0
- neocore_memory-0.2.0/src/neocore/assistant/filter.py +578 -0
- neocore_memory-0.2.0/src/neocore/assistant/lessons.py +100 -0
- neocore_memory-0.2.0/src/neocore/assistant/memory.py +1535 -0
- neocore_memory-0.2.0/src/neocore/assistant/neosift.py +278 -0
- neocore_memory-0.2.0/src/neocore/assistant/outcomes.py +245 -0
- neocore_memory-0.2.0/src/neocore/assistant/render.py +190 -0
- neocore_memory-0.2.0/src/neocore/assistant/share.py +224 -0
- neocore_memory-0.2.0/src/neocore/assistant/sleep.py +252 -0
- neocore_memory-0.2.0/src/neocore/cli.py +386 -0
- neocore_memory-0.2.0/src/neocore/consolidation.py +411 -0
- neocore_memory-0.2.0/src/neocore/embedder.py +74 -0
- neocore_memory-0.2.0/src/neocore/llm.py +129 -0
- neocore_memory-0.2.0/src/neocore/neosift_server.py +209 -0
- neocore_memory-0.2.0/src/neocore/recall.py +1076 -0
- neocore_memory-0.2.0/src/neocore/shared/__init__.py +7 -0
- neocore_memory-0.2.0/src/neocore/shared/admin.py +279 -0
- neocore_memory-0.2.0/src/neocore/shared/client.py +405 -0
- neocore_memory-0.2.0/src/neocore/shared/keys.py +250 -0
- neocore_memory-0.2.0/src/neocore/shared/manage.py +369 -0
- neocore_memory-0.2.0/src/neocore/shared/server.py +618 -0
- neocore_memory-0.2.0/src/neocore/shared/tools.py +414 -0
- neocore_memory-0.2.0/src/neocore/store.py +234 -0
- neocore_memory-0.2.0/src/neocore/temporal.py +124 -0
- neocore_memory-0.2.0/tests/test_assistant.py +1478 -0
- neocore_memory-0.2.0/tests/test_consolidation.py +388 -0
- neocore_memory-0.2.0/tests/test_neosift.py +284 -0
- neocore_memory-0.2.0/tests/test_recall.py +151 -0
- neocore_memory-0.2.0/tests/test_setup.py +26 -0
- neocore_memory-0.2.0/tests/test_share.py +158 -0
- neocore_memory-0.2.0/tests/test_shared.py +432 -0
- 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,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
|
+
[](https://github.com/VincentPorquet777/neocore/actions/workflows/test.yml)
|
|
28
|
+
[](LICENSE)
|
|
29
|
+

|
|
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).
|