neocore-memory 0.2.0__py3-none-any.whl

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/__init__.py ADDED
@@ -0,0 +1,112 @@
1
+ """NeoCore: governed long-term memory that recalls only what the moment needs.
2
+
3
+ For Claude Code and Codex, run ``neocore setup``. To give any other assistant a memory::
4
+
5
+ from neocore import Memory
6
+
7
+ memory = Memory("memory.db")
8
+ memory.add(conversation="chat-1", user="I moved to Lisbon in May.", assistant="Noted!")
9
+ print(memory.recall("When did I move to Lisbon?").rendered)
10
+
11
+ Recall makes no model calls. With the embedder installed (``pip install neocore-memory[embed]``
12
+ and ``neocore setup``) it also finds paraphrases ("Where do I live now?"); without it, recall
13
+ matches words (BM25). Facts (``form_facts``) are optional and use any model you pass.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import os
19
+ from collections.abc import Callable, Sequence
20
+ from pathlib import Path
21
+ from typing import Any
22
+
23
+ __version__ = "0.2.0"
24
+
25
+ from neocore.recall import GovernedRecall, RecallResult # noqa: E402
26
+ from neocore.store import Store # noqa: E402
27
+
28
+ __all__ = ["GovernedRecall", "Memory", "RecallResult", "Store", "__version__"]
29
+
30
+
31
+ def default_embedder_dir() -> Path | None:
32
+ """The embedder ``neocore setup`` downloads, when it and the ``embed`` extra are present."""
33
+ home = Path(os.environ.get("NEOCORE_HOME") or Path.home() / ".neocore")
34
+ folder = home / "models" / "bge-small-en-v1.5-onnx-Q"
35
+ if not (folder / "model_optimized.onnx").exists():
36
+ return None
37
+ try:
38
+ import numpy # noqa: F401
39
+ import onnxruntime # noqa: F401
40
+ import tokenizers # noqa: F401
41
+ except ImportError:
42
+ return None
43
+ return folder
44
+
45
+
46
+ class Memory:
47
+ """A store plus recall, for any assistant. Everything lives in one SQLite file."""
48
+
49
+ def __init__(self, path: str | Path = ":memory:", *,
50
+ embedder_dir: str | Path | None = "auto", threads: int = 2,
51
+ **recall_options: Any) -> None:
52
+ """``embedder_dir="auto"`` uses the embedder ``neocore setup`` downloaded, if any; pass
53
+ a folder to choose one, or ``None`` for word matching only."""
54
+ self.store = Store(path)
55
+ embedder = None
56
+ if embedder_dir == "auto":
57
+ embedder_dir = default_embedder_dir()
58
+ if embedder_dir:
59
+ from neocore.embedder import LocalEmbedder
60
+
61
+ embedder = LocalEmbedder(Path(embedder_dir).expanduser(), threads=threads)
62
+ self.engine = GovernedRecall(
63
+ self.store, embedder=embedder,
64
+ embedding_model=embedder.model_id if embedder else "", **recall_options)
65
+
66
+ def add(self, *, conversation: str, user: str, assistant: str = "",
67
+ at: str | None = None, turn: str = "", revision: str = "1", branch: str = "",
68
+ scope: str = "internal", metadata: dict[str, Any] | None = None) -> list[str]:
69
+ """Remember one exchange. ``at`` is an ISO time (default now); ``scope`` is who may
70
+ recall it (recall names the scopes it may read)."""
71
+ return self.store.capture_turn(
72
+ thread_id=conversation, user=user, assistant=assistant, occurred_at=at,
73
+ turn_id=turn, revision=revision, branch_id=branch, scope=scope, metadata=metadata)
74
+
75
+ def recall(self, query: str, *, scopes: Sequence[str] = ("internal",),
76
+ exclude_conversation: str = "", **options: Any) -> RecallResult:
77
+ """What memory holds for ``query``: a dated, budgeted block (``.rendered``) and a
78
+ receipt naming every source. Zero model calls."""
79
+ excluded = [str(r["evidence_id"]) for r in self.store.rows(
80
+ "SELECT evidence_id FROM evidence WHERE thread_id=?", (exclude_conversation,))
81
+ ] if exclude_conversation else []
82
+ return self.engine.recall(query, allowed_scopes=set(scopes),
83
+ exclude_evidence_ids=excluded, **options)
84
+
85
+ def form_facts(self, ask: Callable[[str, dict[str, Any]], dict[str, Any]], *,
86
+ max_batches: int = 4, roles: Sequence[str] = ("user",)) -> dict[str, int]:
87
+ """Turn new messages into short dated facts with ``ask(prompt, schema) -> dict`` (see
88
+ ``neocore.llm`` for Codex, Claude and OpenAI-compatible backends)."""
89
+ from neocore.assistant.memory import _fact_extractor
90
+
91
+ return self.engine.form_facts(_fact_extractor(ask), former="memory",
92
+ max_batches=max_batches, roles=roles)
93
+
94
+ def sleep(self, ask: Callable[[str, dict[str, Any]], dict[str, Any]], *,
95
+ max_calls: int = 8) -> dict[str, int]:
96
+ """Newest wins: judge groups of related facts with ``ask`` so recall shows a replaced
97
+ fact only beside what replaced it. Needs ``Memory(..., consolidation="sleep.json")``
98
+ and the embedder (facts are grouped by meaning)."""
99
+ if self.engine.consolidation is None:
100
+ raise ValueError("pass consolidation=<verdicts file> to Memory to use sleep")
101
+ self.engine.backfill(None)
102
+ return self.engine.consolidate(ask, max_calls=max_calls)
103
+
104
+ def revoke(self, evidence_id: str, *, reason: str) -> None:
105
+ self.store.revoke(evidence_id, reason=reason)
106
+
107
+ def forget(self, evidence_id: str, *, reason: str) -> None:
108
+ self.store.forget(evidence_id, reason=reason)
109
+ self.engine.refresh()
110
+
111
+ def abandon_branch(self, branch_id: str, *, reason: str) -> None:
112
+ self.store.abandon_branch(branch_id, reason=reason)
neocore/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from neocore.cli import main
2
+
3
+ main()
@@ -0,0 +1 @@
1
+ """NeoCore for coding assistants: capture, recall, formation and sleep for Claude Code and Codex."""