trace-memory 1.0.4__tar.gz → 1.0.6__tar.gz

{trace_memory-1.0.4/trace_memory.egg-info → trace_memory-1.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trace-memory
-Version: 1.0.4
+Version: 1.0.6
 Summary: TRACE — Temporal Retrieval And Context Engine: self-healing hierarchical memory for LLM agents.
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/husain34/TRACE
@@ -25,6 +25,7 @@ License-File: NOTICE
 Requires-Dist: openai>=1.0.0
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: sentence-transformers>=2.2.0
+Requires-Dist: numpy>=1.21.0
 Dynamic: license-file
 
 <div align="center">
@@ -208,14 +209,13 @@ Result: The AI aggressively stopped the user.
 ```
 Phase 1 — Collect all frozen (inactive) TopicNodes
 Phase 2 — Generate missing summaries; embed all candidates
-Phase 3 — Compute pairwise cosine similarity
-Phase 4 — For each pair above threshold, apply 4 axioms:
+Phase 3 — Compute pairwise cosine similarity; for each pair above threshold, apply 4 axioms:
               Axiom 1 — Chronological Guard
               Axiom 2 — Frozen State check
               Axiom 3 — Similarity threshold (default 0.55)
               Axiom 4 — LLM Veto
            If all 4 pass → merge (newer becomes child of older)
-Phase 5 — Optional: prune trivial leaf messages
+Phase 4 — Optional: prune trivial leaf messages
 ```
 
 #### The Four Axioms in Detail
@@ -403,16 +403,13 @@ tree.save("sessions/chat_001.json", save_conversation=True)
 
 `save_conversation=True` embeds the raw message list so the session can be fully restored later.
 
----
-
-##### `CTree.load(filepath: str, api_key: str = None, base_url: str = None, model: str = None) -> CTree`
+##### `CTree.load(filepath: str, api_key: str = None, base_url: str = None, model: str = None, embed_fn: Callable = None) -> CTree`
 
 Restore a tree from a JSON file.
 
 ```python
 tree = CTree.load("sessions/chat_001.json", api_key="sk-...", embed_fn=embed)
-tree.vdb       = VectorDatabase("sessions/chat_001.db")
-
+tree.vdb = VectorDatabase("sessions/chat_001.db")
 ```
 
 ---
@@ -473,7 +470,7 @@ ROOT (sub-nodes: 3)
 
 A local SQLite vector store with two active tables: conversation vectors and topic summaries.
 
-> **Note on Scaling:** TRACE uses pure Python (`sqlite3` and `struct`) to avoid heavy dependencies and run instantly on any machine. This is perfectly sufficient for local agents and moderate conversation histories. However, for massive scale (millions of vectors), you will need to swap this module for a dedicated vector database like FAISS or Chroma.
+> **Note on Scaling:** TRACE uses SQLite (`sqlite3`) for storage, `numpy` for fast cosine similarity, and `struct` for compact binary packing — all chosen to keep the footprint small while running on any machine. For massive scale (millions of vectors), swap this module for FAISS or Chroma.
 
 ```python
 from trace_memory import VectorDatabase
@@ -487,8 +484,6 @@ vdb = VectorDatabase("path/to/session.db")  # creates the DB if it doesn't exist
 
 ---
 
----
-
 #### Conversation methods
 
 ##### `vdb.add_conversation_message(msg: ConversationVector)`
@@ -573,6 +568,7 @@ system_prompt = synth.synthesize_prompt(
     query_vector           = embed("Is the cake safe for Sarah?"),
     active_node            = tree.current_node,
     recent_messages        = tree.conversation[-6:],
+    top_k_docs             = 3,     # max topic branch paths to surface
     top_k_history          = 2,     # max past messages to recall
     min_history_similarity = 0.50,  # min cosine score for conversation recall
 )
@@ -641,15 +637,25 @@ tree = CTree(api_key="sk-...", model="gpt-4o-mini")
 
 ### 7.3 With NVIDIA NIM / any OpenAI-compatible endpoint
 
-```python
-import os
-os.environ["OPENAI_BASE_URL"] = "https://integrate.api.nvidia.com/v1"
-os.environ["OPENAI_API_KEY"]  = "nvapi-..."
+Point the `base_url` to your endpoint.
 
-from trace_memory import CTree
-tree = CTree(model="meta/llama-3.1-70b-instruct")
+```python
+tree = CTree(
+    api_key="your-nvidia-api-key",
+    base_url="https://integrate.api.nvidia.com/v1",
+    model="meta/llama-3.1-8b-instruct"
+)
 ```
 
+### 7.4 Best Practices for LLM Selection
+
+**Do not use "Reasoning" models (DeepSeek R1, Claude 3.7 Sonnet thinking mode, o1) for the internal `CTree` engine.**
+
+When `CTree` runs in the background, it performs simple, deterministic classification tasks (e.g., naming a topic in 3 words, or extracting a JSON boolean). Reasoning models are built for complex logic and will waste massive amounts of compute "thinking" about simple tasks. Worse, reasoning models often exceed TRACE's strict internal token limits (`max_tokens=50` or `200`) designed to keep background operations fast, causing the LLM to get cut off mid-thought and breaking the internal JSON parsers.
+
+*   **For the `CTree` internal model:** Always use a fast, standard model (e.g., `gpt-4o-mini`, `meta-llama-3.1-8b-instruct`).
+*   **For your actual chat application:** You can (and should!) use whatever massive reasoning model you prefer to generate the final response to the user. TRACE is completely decoupled from your front-end chat completion.
+
 ---
 
 ## 8. Edge-Case Stress Tests & Validation
@@ -684,6 +690,8 @@ TRACE loads `.env` automatically if `python-dotenv` is installed.
 |---|---|---|
 | `openai` | ≥ 1.0.0 | ✅ Yes |
 | `python-dotenv` | ≥ 1.0.0 | ✅ Yes |
+| `sentence-transformers` | ≥ 2.2.0 | ✅ Yes (local embed fallback) |
+| `numpy` | ≥ 1.21.0 | ✅ Yes (cosine similarity) |
 | `sqlite3` | built-in | ✅ Yes (no install needed) |
 | `struct` | built-in | ✅ Yes (no install needed) |
 

{trace_memory-1.0.4 → trace_memory-1.0.6}/README.md

@@ -179,14 +179,13 @@ Result: The AI aggressively stopped the user.
 ```
 Phase 1 — Collect all frozen (inactive) TopicNodes
 Phase 2 — Generate missing summaries; embed all candidates
-Phase 3 — Compute pairwise cosine similarity
-Phase 4 — For each pair above threshold, apply 4 axioms:
+Phase 3 — Compute pairwise cosine similarity; for each pair above threshold, apply 4 axioms:
               Axiom 1 — Chronological Guard
               Axiom 2 — Frozen State check
               Axiom 3 — Similarity threshold (default 0.55)
               Axiom 4 — LLM Veto
            If all 4 pass → merge (newer becomes child of older)
-Phase 5 — Optional: prune trivial leaf messages
+Phase 4 — Optional: prune trivial leaf messages
 ```
 
 #### The Four Axioms in Detail
@@ -374,16 +373,13 @@ tree.save("sessions/chat_001.json", save_conversation=True)
 
 `save_conversation=True` embeds the raw message list so the session can be fully restored later.
 
----
-
-##### `CTree.load(filepath: str, api_key: str = None, base_url: str = None, model: str = None) -> CTree`
+##### `CTree.load(filepath: str, api_key: str = None, base_url: str = None, model: str = None, embed_fn: Callable = None) -> CTree`
 
 Restore a tree from a JSON file.
 
 ```python
 tree = CTree.load("sessions/chat_001.json", api_key="sk-...", embed_fn=embed)
-tree.vdb       = VectorDatabase("sessions/chat_001.db")
-
+tree.vdb = VectorDatabase("sessions/chat_001.db")
 ```
 
 ---
@@ -444,7 +440,7 @@ ROOT (sub-nodes: 3)
 
 A local SQLite vector store with two active tables: conversation vectors and topic summaries.
 
-> **Note on Scaling:** TRACE uses pure Python (`sqlite3` and `struct`) to avoid heavy dependencies and run instantly on any machine. This is perfectly sufficient for local agents and moderate conversation histories. However, for massive scale (millions of vectors), you will need to swap this module for a dedicated vector database like FAISS or Chroma.
+> **Note on Scaling:** TRACE uses SQLite (`sqlite3`) for storage, `numpy` for fast cosine similarity, and `struct` for compact binary packing — all chosen to keep the footprint small while running on any machine. For massive scale (millions of vectors), swap this module for FAISS or Chroma.
 
 ```python
 from trace_memory import VectorDatabase
@@ -458,8 +454,6 @@ vdb = VectorDatabase("path/to/session.db")  # creates the DB if it doesn't exist
 
 ---
 
----
-
 #### Conversation methods
 
 ##### `vdb.add_conversation_message(msg: ConversationVector)`
@@ -544,6 +538,7 @@ system_prompt = synth.synthesize_prompt(
     query_vector           = embed("Is the cake safe for Sarah?"),
     active_node            = tree.current_node,
     recent_messages        = tree.conversation[-6:],
+    top_k_docs             = 3,     # max topic branch paths to surface
     top_k_history          = 2,     # max past messages to recall
     min_history_similarity = 0.50,  # min cosine score for conversation recall
 )
@@ -612,15 +607,25 @@ tree = CTree(api_key="sk-...", model="gpt-4o-mini")
 
 ### 7.3 With NVIDIA NIM / any OpenAI-compatible endpoint
 
-```python
-import os
-os.environ["OPENAI_BASE_URL"] = "https://integrate.api.nvidia.com/v1"
-os.environ["OPENAI_API_KEY"]  = "nvapi-..."
+Point the `base_url` to your endpoint.
 
-from trace_memory import CTree
-tree = CTree(model="meta/llama-3.1-70b-instruct")
+```python
+tree = CTree(
+    api_key="your-nvidia-api-key",
+    base_url="https://integrate.api.nvidia.com/v1",
+    model="meta/llama-3.1-8b-instruct"
+)
 ```
 
+### 7.4 Best Practices for LLM Selection
+
+**Do not use "Reasoning" models (DeepSeek R1, Claude 3.7 Sonnet thinking mode, o1) for the internal `CTree` engine.**
+
+When `CTree` runs in the background, it performs simple, deterministic classification tasks (e.g., naming a topic in 3 words, or extracting a JSON boolean). Reasoning models are built for complex logic and will waste massive amounts of compute "thinking" about simple tasks. Worse, reasoning models often exceed TRACE's strict internal token limits (`max_tokens=50` or `200`) designed to keep background operations fast, causing the LLM to get cut off mid-thought and breaking the internal JSON parsers.
+
+*   **For the `CTree` internal model:** Always use a fast, standard model (e.g., `gpt-4o-mini`, `meta-llama-3.1-8b-instruct`).
+*   **For your actual chat application:** You can (and should!) use whatever massive reasoning model you prefer to generate the final response to the user. TRACE is completely decoupled from your front-end chat completion.
+
 ---
 
 ## 8. Edge-Case Stress Tests & Validation
@@ -655,6 +660,8 @@ TRACE loads `.env` automatically if `python-dotenv` is installed.
 |---|---|---|
 | `openai` | ≥ 1.0.0 | ✅ Yes |
 | `python-dotenv` | ≥ 1.0.0 | ✅ Yes |
+| `sentence-transformers` | ≥ 2.2.0 | ✅ Yes (local embed fallback) |
+| `numpy` | ≥ 1.21.0 | ✅ Yes (cosine similarity) |
 | `sqlite3` | built-in | ✅ Yes (no install needed) |
 | `struct` | built-in | ✅ Yes (no install needed) |
 

{trace_memory-1.0.4 → trace_memory-1.0.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name            = "trace-memory"
-version         = "1.0.4"
+version         = "1.0.6"
 description     = "TRACE — Temporal Retrieval And Context Engine: self-healing hierarchical memory for LLM agents."
 readme          = "README.md"
 license         = { text = "Apache-2.0" }
@@ -30,9 +30,10 @@ classifiers = [
 ]
 
 dependencies = [
-    "openai>=1.0.0",         # LLM API client (supports any OpenAI-compatible endpoint)
-    "python-dotenv>=1.0.0",  # .env file support
-    "sentence-transformers>=2.2.0", # local fallback for embeddings
+    "openai>=1.0.0",                   # LLM API client (supports any OpenAI-compatible endpoint)
+    "python-dotenv>=1.0.0",            # .env file support
+    "sentence-transformers>=2.2.0",    # local fallback embedder (BAAI/bge-base-en-v1.5)
+    "numpy>=1.21.0",                   # cosine similarity in vector_db
 ]
 
 

{trace_memory-1.0.4 → trace_memory-1.0.6}/trace_memory/__init__.py

@@ -25,7 +25,7 @@ from .ctree import CTree, Node, TopicNode, MessageNode
 from .vector_db import VectorDatabase, ConversationVector
 from .prompt_synthesizer import PromptSynthesizer
 
-__version__ = "1.0.0"
+__version__ = "1.0.6"
 __author__  = "Husain"
 __license__ = "Apache-2.0"
 

{trace_memory-1.0.4 → trace_memory-1.0.6}/trace_memory/_llm_utils.py

@@ -76,7 +76,6 @@ def _normalize_for_json(text: str) -> str:
     """Normalise common LLM JSON formatting quirks before parsing."""
     text = text.replace(": N/A", ": null")
     text = text.replace(": True",  ": true").replace(": False", ": false").replace(": None", ": null")
-    text = text.replace(": True,", ": true,").replace(": False,", ": false,").replace(": None,", ": null,")
     text = text.replace(",}", "}").replace(",]", "]")
     text = text.replace("\r\n", " ").replace("\n", " ").replace("\r", " ")
     text = " ".join(text.split())

{trace_memory-1.0.4 → trace_memory-1.0.6}/trace_memory/ctree.py

@@ -13,7 +13,7 @@ exchange into a tree of named topic branches, with:
 
 Typical usage
 -------------
-    from trace import CTree, VectorDatabase, PromptSynthesizer
+    from trace_memory import CTree, VectorDatabase, PromptSynthesizer
 
     # 1. Boot the engine
     tree = CTree(api_key="sk-...", model="gpt-4o-mini")
@@ -54,6 +54,7 @@ from typing import List, Dict, Optional, Tuple, Any, Callable
 from dataclasses import dataclass, field
 
 from ._llm_utils import ChatGPT_API, extract_json
+from .vector_db import cosine_similarity
 
 # ── Helpers ───────────────────────────────────────────────────────────────────
 
@@ -94,16 +95,20 @@ class Node:
     ----------
     children       : Direct child nodes.
     parent         : Parent node (None for root).
-    sub_node_count : Cached count of direct children.
+    sub_node_count : Live count of direct children (dynamic property).
     created_at     : Unix timestamp of node birth (set once, never changed).
     """
 
-    def __init__(self, children=None, parent=None, sub_node_count=0):
+    def __init__(self, children=None, parent=None):
         self.children: List["Node"] = children or []
         self.parent: Optional["Node"] = parent
-        self.sub_node_count: int = sub_node_count
         self.created_at: float = time.time()
 
+    @property
+    def sub_node_count(self) -> int:
+        """Dynamically computed — always reflects the real number of direct children."""
+        return len(self.children)
+
     def is_leaf(self) -> bool:
         return len(self.children) == 0
 
@@ -365,8 +370,9 @@ class CTree:
                 end_index   = node.end_index,
                 depth       = depth,
             )
-        except Exception:
-            pass  # embedding failures must never crash the tree
+        except Exception as e:
+            import sys
+            print(f"[TRACE] \u26a0 VDB upsert failed for node '{node.topic_name}': {e}", file=sys.stderr)
 
     # ── Public: add exchange ──────────────────────────────────────────────────
 
@@ -541,34 +547,8 @@ class CTree:
         parent.children.append(new_topic)
         return new_topic
 
-    def _create_new_node(self, message, start_index, parent, topic_name=""):
-        if not topic_name or not topic_name.strip():
-            topic_name = self._llm_generate_topic(message, parent)
-        new_topic = TopicNode(
-            topic_name=topic_name,
-            start_index=start_index,
-            end_index=start_index,
-            parent=parent,
-        )
-        parent.children.append(new_topic)
-        return new_topic
-
     # ── LLM helpers ───────────────────────────────────────────────────────────
 
-    def _llm_generate_topic(self, message, parent=None) -> str:
-        content = message.get("content", "")
-        context = f"\nParent topic: {parent.topic_name}" if (parent and parent.topic_name != "ROOT") else ""
-        prompt  = (
-            f"Given the following message, generate a concise topic name "
-            f"(2-5 words) that captures its main subject.{context}\n\n"
-            f"Message: {content}\n\nRespond with ONLY the topic name, nothing else."
-        )
-        try:
-            return ChatGPT_API(self.model, prompt, api_key=self.api_key, base_url=self.base_url, temperature=0.3, max_tokens=50).strip()
-        except Exception as e:
-            print(f"LLM error in topic generation: {e}")
-            return f"Topic at index {len(self.conversation)}"
-
     def _llm_generate_topic_from_message(
         self, user_msg, assistant_msg, parent=None, system_msg=None
     ) -> str:
@@ -829,10 +809,11 @@ class CTree:
             def _in_subtree(n, target):
                 if n is target: return True
                 return any(_in_subtree(c, target) for c in n.children)
-            for sn in root_node.children:
-                if isinstance(sn, TopicNode) and _in_subtree(sn, self.current_node):
-                    break
-            else:
+            current_found = any(
+                isinstance(child, TopicNode) and _in_subtree(child, self.current_node)
+                for child in root_node.children
+            )
+            if not current_found:
                 self.current_node = last_subtopic_node
 
     # ── Public utilities ──────────────────────────────────────────────────────
@@ -951,38 +932,42 @@ class CTree:
     def _reconstruct_node(self, node_data: dict, parent):
         node_type = node_data.get("type", "topic")
         if node_type == "message":
-            msg_start_idx = node_data.get("message_index", node_data.get("pair_index", 0) * 2)
-            user_msg = assistant_msg = {}
+            msg_idx    = node_data.get("message_index", 0)
+            user_msg   = assistant_msg = {}
             system_msg = None
-            for i in range(max(0, msg_start_idx - 1), min(len(self.conversation), msg_start_idx + 4)):
-                if i < len(self.conversation) and self.conversation[i].get("role") == "user":
-                    if i > 0 and self.conversation[i - 1].get("role") == "system":
-                        system_msg = self.conversation[i - 1]
-                    user_msg = self.conversation[i]
-                    if i + 1 < len(self.conversation) and self.conversation[i + 1].get("role") == "assistant":
-                        assistant_msg = self.conversation[i + 1]
+            if self.conversation:
+                for i in range(max(0, msg_idx - 1), min(len(self.conversation), msg_idx + 4)):
+                    if self.conversation[i].get("role") == "user":
+                        user_msg = self.conversation[i]
+                        if i > 0 and self.conversation[i - 1].get("role") == "system":
+                            system_msg = self.conversation[i - 1]
+                        if i + 1 < len(self.conversation) and self.conversation[i + 1].get("role") == "assistant":
+                            assistant_msg = self.conversation[i + 1]
                         break
-            node = MessageNode(
-                user_message      = user_msg,
-                assistant_message = assistant_msg,
-                system_message    = system_msg,
-                message_index     = msg_start_idx,
-                parent            = parent,
-            )
-        else:
-            node = TopicNode(
-                topic_name  = node_data.get("topic_name", ""),
-                summary     = node_data.get("summary", ""),
-                start_index = node_data.get("start_index", 0),
-                end_index   = node_data.get("end_index", 0),
-                parent      = parent,
+            else:
+                import warnings
+                warnings.warn(
+                    "[TRACE] Tree loaded without conversation history (save_conversation=False). "
+                    "MessageNode content will be empty. Re-save with save_conversation=True.",
+                    stacklevel=2,
+                )
+            return MessageNode(
+                user_message=user_msg, assistant_message=assistant_msg,
+                system_message=system_msg, message_index=msg_idx, parent=parent,
             )
-            if "node_id" in node_data:
-                node.node_id = node_data["node_id"]
-            node.created_at = node_data.get("created_at", node.created_at)
-            for child_data in node_data.get("children", []):
-                node.children.append(self._reconstruct_node(child_data, parent=node))
-        node.sub_node_count = node_data.get("sub_node_count", 0)
+        # TopicNode
+        node = TopicNode(
+            topic_name  = node_data.get("topic_name", ""),
+            summary     = node_data.get("summary", ""),
+            start_index = node_data.get("start_index", 0),
+            end_index   = node_data.get("end_index", 0),
+            parent      = parent,
+        )
+        if "node_id" in node_data:
+            node.node_id = node_data["node_id"]
+        node.created_at = node_data.get("created_at", node.created_at)
+        for child_data in node_data.get("children", []):
+            node.children.append(self._reconstruct_node(child_data, parent=node))
         return node
 
     def _find_current_node(self, node):
@@ -1116,10 +1101,7 @@ class CTree:
             )
             print(f"Merged {stats['merged']} branches in {stats['duration_secs']:.1f}s")
         """
-        import time as _time
-        from .vector_db import cosine_similarity as _cos
-
-        t0      = _time.time()
+        t0      = time.time()
         merged  = pruned = skipped = 0
 
         # Phase 1 — collect frozen candidates
@@ -1165,7 +1147,7 @@ class CTree:
                 if na.node_id not in embeddings or nb.node_id not in embeddings:
                     skipped += 1
                     continue
-                sim = _cos(embeddings[na.node_id], embeddings[nb.node_id])
+                sim = cosine_similarity(embeddings[na.node_id], embeddings[nb.node_id])
                 if sim < similarity_threshold:
                     continue
                 older, newer = (na, nb) if na.created_at <= nb.created_at else (nb, na)
@@ -1215,5 +1197,5 @@ class CTree:
             "merged":        merged,
             "pruned":        pruned,
             "skipped":       skipped,
-            "duration_secs": _time.time() - t0,
+            "duration_secs": time.time() - t0,
         }

{trace_memory-1.0.4 → trace_memory-1.0.6}/trace_memory/prompt_synthesizer.py

@@ -92,7 +92,7 @@ class PromptSynthesizer:
         _walk(self.tree.root)
         return result
 
-    def _get_surgical_context(self, query_vector) -> str:
+    def _get_surgical_context(self, query_vector, top_k_docs: int = 3) -> str:
         """
         Multi-path surgical retrieval (the heart of TRACE):
 
@@ -138,7 +138,7 @@ class PromptSynthesizer:
                     unique_nodes_ordered.append((node, similarity))
 
         # Now rank paths by similarity and take the top-3
-        all_ancestor_sets_ranked = sorted(all_ancestor_sets, key=lambda x: x[0], reverse=True)[:3]
+        all_ancestor_sets_ranked = sorted(all_ancestor_sets, key=lambda x: x[0], reverse=True)[:top_k_docs]
 
         blocks = ["── SURGICAL MEMORY CONTEXT (top matched topics + ancestry) ──"]
         for i, (similarity, ancestors) in enumerate(all_ancestor_sets_ranked, 1):
@@ -159,8 +159,9 @@ class PromptSynthesizer:
         query_vector:           list,
         active_node,
         recent_messages:        list,
-        top_k_history:          int   = 2,
-        min_history_similarity: float = 0.50,
+        top_k_docs:             int   = 3,     # max topic branches to surface in surgical context
+        top_k_history:          int   = 5,
+        min_history_similarity: float = 0.25,
     ) -> str:
         """
         Assemble the full enriched system prompt for the next LLM turn.
@@ -171,6 +172,7 @@ class PromptSynthesizer:
         query_vector           : Embedding of *user_query*.
         active_node            : ``tree.current_node``.
         recent_messages        : Tail of ``tree.conversation`` (e.g. last 6 msgs).
+        top_k_docs             : Max number of topic-branch paths to surface in surgical context.
         top_k_history          : Max past conversation messages to recall.
         min_history_similarity : Minimum cosine score for conversation recall.
 
@@ -196,7 +198,7 @@ class PromptSynthesizer:
             )
         """
         # 1. Surgical multi-path memory context
-        narrative_block  = self._get_surgical_context(query_vector)
+        narrative_block  = self._get_surgical_context(query_vector, top_k_docs)
 
         # 2. Cross-thread conversation recall
         history_matches = self.vdb.search_conversation(

{trace_memory-1.0.4 → trace_memory-1.0.6}/trace_memory/vector_db.py

@@ -29,11 +29,7 @@ def unpack_float_vector(blob):
         return []
     num_floats = len(blob) // 4
     format_string = '<' + str(num_floats) + 'f'
-    unpacked = struct.unpack(format_string, blob)
-    result = []
-    for val in unpacked:
-        result.append(val)
-    return result
+    return list(struct.unpack(format_string, blob))
 
 def cosine_similarity(v1, v2):
     if not v1 or not v2 or len(v1) != len(v2):
@@ -94,7 +90,7 @@ class VectorDatabase:
 
 
 
-    def search_conversation(self, query_vector, top_k=2, min_similarity=0.5):
+    def search_conversation(self, query_vector, top_k=5, min_similarity=0.25):
         if not query_vector:
             return []
         conn = sqlite3.connect(self.db_path)

{trace_memory-1.0.4 → trace_memory-1.0.6/trace_memory.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trace-memory
-Version: 1.0.4
+Version: 1.0.6
 Summary: TRACE — Temporal Retrieval And Context Engine: self-healing hierarchical memory for LLM agents.
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/husain34/TRACE
@@ -25,6 +25,7 @@ License-File: NOTICE
 Requires-Dist: openai>=1.0.0
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: sentence-transformers>=2.2.0
+Requires-Dist: numpy>=1.21.0
 Dynamic: license-file
 
 <div align="center">
@@ -208,14 +209,13 @@ Result: The AI aggressively stopped the user.
 ```
 Phase 1 — Collect all frozen (inactive) TopicNodes
 Phase 2 — Generate missing summaries; embed all candidates
-Phase 3 — Compute pairwise cosine similarity
-Phase 4 — For each pair above threshold, apply 4 axioms:
+Phase 3 — Compute pairwise cosine similarity; for each pair above threshold, apply 4 axioms:
               Axiom 1 — Chronological Guard
               Axiom 2 — Frozen State check
               Axiom 3 — Similarity threshold (default 0.55)
               Axiom 4 — LLM Veto
            If all 4 pass → merge (newer becomes child of older)
-Phase 5 — Optional: prune trivial leaf messages
+Phase 4 — Optional: prune trivial leaf messages
 ```
 
 #### The Four Axioms in Detail
@@ -403,16 +403,13 @@ tree.save("sessions/chat_001.json", save_conversation=True)
 
 `save_conversation=True` embeds the raw message list so the session can be fully restored later.
 
----
-
-##### `CTree.load(filepath: str, api_key: str = None, base_url: str = None, model: str = None) -> CTree`
+##### `CTree.load(filepath: str, api_key: str = None, base_url: str = None, model: str = None, embed_fn: Callable = None) -> CTree`
 
 Restore a tree from a JSON file.
 
 ```python
 tree = CTree.load("sessions/chat_001.json", api_key="sk-...", embed_fn=embed)
-tree.vdb       = VectorDatabase("sessions/chat_001.db")
-
+tree.vdb = VectorDatabase("sessions/chat_001.db")
 ```
 
 ---
@@ -473,7 +470,7 @@ ROOT (sub-nodes: 3)
 
 A local SQLite vector store with two active tables: conversation vectors and topic summaries.
 
-> **Note on Scaling:** TRACE uses pure Python (`sqlite3` and `struct`) to avoid heavy dependencies and run instantly on any machine. This is perfectly sufficient for local agents and moderate conversation histories. However, for massive scale (millions of vectors), you will need to swap this module for a dedicated vector database like FAISS or Chroma.
+> **Note on Scaling:** TRACE uses SQLite (`sqlite3`) for storage, `numpy` for fast cosine similarity, and `struct` for compact binary packing — all chosen to keep the footprint small while running on any machine. For massive scale (millions of vectors), swap this module for FAISS or Chroma.
 
 ```python
 from trace_memory import VectorDatabase
@@ -487,8 +484,6 @@ vdb = VectorDatabase("path/to/session.db")  # creates the DB if it doesn't exist
 
 ---
 
----
-
 #### Conversation methods
 
 ##### `vdb.add_conversation_message(msg: ConversationVector)`
@@ -573,6 +568,7 @@ system_prompt = synth.synthesize_prompt(
     query_vector           = embed("Is the cake safe for Sarah?"),
     active_node            = tree.current_node,
     recent_messages        = tree.conversation[-6:],
+    top_k_docs             = 3,     # max topic branch paths to surface
     top_k_history          = 2,     # max past messages to recall
     min_history_similarity = 0.50,  # min cosine score for conversation recall
 )
@@ -641,15 +637,25 @@ tree = CTree(api_key="sk-...", model="gpt-4o-mini")
 
 ### 7.3 With NVIDIA NIM / any OpenAI-compatible endpoint
 
-```python
-import os
-os.environ["OPENAI_BASE_URL"] = "https://integrate.api.nvidia.com/v1"
-os.environ["OPENAI_API_KEY"]  = "nvapi-..."
+Point the `base_url` to your endpoint.
 
-from trace_memory import CTree
-tree = CTree(model="meta/llama-3.1-70b-instruct")
+```python
+tree = CTree(
+    api_key="your-nvidia-api-key",
+    base_url="https://integrate.api.nvidia.com/v1",
+    model="meta/llama-3.1-8b-instruct"
+)
 ```
 
+### 7.4 Best Practices for LLM Selection
+
+**Do not use "Reasoning" models (DeepSeek R1, Claude 3.7 Sonnet thinking mode, o1) for the internal `CTree` engine.**
+
+When `CTree` runs in the background, it performs simple, deterministic classification tasks (e.g., naming a topic in 3 words, or extracting a JSON boolean). Reasoning models are built for complex logic and will waste massive amounts of compute "thinking" about simple tasks. Worse, reasoning models often exceed TRACE's strict internal token limits (`max_tokens=50` or `200`) designed to keep background operations fast, causing the LLM to get cut off mid-thought and breaking the internal JSON parsers.
+
+*   **For the `CTree` internal model:** Always use a fast, standard model (e.g., `gpt-4o-mini`, `meta-llama-3.1-8b-instruct`).
+*   **For your actual chat application:** You can (and should!) use whatever massive reasoning model you prefer to generate the final response to the user. TRACE is completely decoupled from your front-end chat completion.
+
 ---
 
 ## 8. Edge-Case Stress Tests & Validation
@@ -684,6 +690,8 @@ TRACE loads `.env` automatically if `python-dotenv` is installed.
 |---|---|---|
 | `openai` | ≥ 1.0.0 | ✅ Yes |
 | `python-dotenv` | ≥ 1.0.0 | ✅ Yes |
+| `sentence-transformers` | ≥ 2.2.0 | ✅ Yes (local embed fallback) |
+| `numpy` | ≥ 1.21.0 | ✅ Yes (cosine similarity) |
 | `sqlite3` | built-in | ✅ Yes (no install needed) |
 | `struct` | built-in | ✅ Yes (no install needed) |
 

{trace_memory-1.0.4 → trace_memory-1.0.6}/trace_memory.egg-info/requires.txt

@@ -1,3 +1,4 @@
 openai>=1.0.0
 python-dotenv>=1.0.0
 sentence-transformers>=2.2.0
+numpy>=1.21.0