trace-memory 1.0.3__tar.gz → 1.0.5__tar.gz

{trace_memory-1.0.3/trace_memory.egg-info → trace_memory-1.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trace-memory
-Version: 1.0.3
+Version: 1.0.5
 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
@@ -495,6 +495,9 @@ vdb = VectorDatabase("path/to/session.db")  # creates the DB if it doesn't exist
 
 Store an embedded past conversation message for cross-thread recall.
 
+> [!NOTE]
+> As of TRACE 1.0.4, `CTree.add()` calls this **automatically** behind the scenes. You only need to call this manually if you are managing the Vector DB independently of a CTree.
+
 ```python
 from trace_memory import ConversationVector
 import time, uuid
@@ -638,15 +641,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

{trace_memory-1.0.3 → trace_memory-1.0.5}/README.md

@@ -466,6 +466,9 @@ vdb = VectorDatabase("path/to/session.db")  # creates the DB if it doesn't exist
 
 Store an embedded past conversation message for cross-thread recall.
 
+> [!NOTE]
+> As of TRACE 1.0.4, `CTree.add()` calls this **automatically** behind the scenes. You only need to call this manually if you are managing the Vector DB independently of a CTree.
+
 ```python
 from trace_memory import ConversationVector
 import time, uuid
@@ -609,15 +612,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

{trace_memory-1.0.3 → trace_memory-1.0.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name            = "trace-memory"
-version         = "1.0.3"
+version         = "1.0.5"
 description     = "TRACE — Temporal Retrieval And Context Engine: self-healing hierarchical memory for LLM agents."
 readme          = "README.md"
 license         = { text = "Apache-2.0" }

{trace_memory-1.0.3 → trace_memory-1.0.5}/trace_memory/ctree.py

@@ -427,6 +427,35 @@ class CTree:
         else:
             self._add_message(msg_dict)
 
+        if self.vdb:
+            from .vector_db import ConversationVector
+            import uuid
+            
+            ancestors = self.get_ancestors(self.current_node, include_self=True, exclude_root=False)
+            thread_path = " → ".join([n.topic_name for n in ancestors]) if ancestors else "ROOT"
+            
+            start_idx = msg_dict["index"]
+            for i, msg in enumerate(messages):
+                role = msg.get("role", "")
+                text = msg.get("content", "")
+                if not text or not isinstance(text, str):
+                    continue
+                
+                try:
+                    embed_vec = self.embed_fn(text)
+                    c_vec = ConversationVector(
+                        message_id=str(uuid.uuid4()),
+                        message_index=start_idx + i,
+                        role=role,
+                        text=text,
+                        embedding=embed_vec,
+                        timestamp=time.time(),
+                        thread_path=thread_path
+                    )
+                    self.vdb.add_conversation_message(c_vec)
+                except Exception:
+                    pass
+
         if self.auto_save_path:
             self.save(self.auto_save_path, save_conversation=True)
 

{trace_memory-1.0.3 → trace_memory-1.0.5}/trace_memory/prompt_synthesizer.py

@@ -159,8 +159,8 @@ class PromptSynthesizer:
         query_vector:           list,
         active_node,
         recent_messages:        list,
-        top_k_history:          int   = 2,
-        min_history_similarity: float = 0.50,
+        top_k_history:          int   = 5,
+        min_history_similarity: float = 0.25,
     ) -> str:
         """
         Assemble the full enriched system prompt for the next LLM turn.

{trace_memory-1.0.3 → trace_memory-1.0.5}/trace_memory/vector_db.py

@@ -94,7 +94,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.3 → trace_memory-1.0.5/trace_memory.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trace-memory
-Version: 1.0.3
+Version: 1.0.5
 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
@@ -495,6 +495,9 @@ vdb = VectorDatabase("path/to/session.db")  # creates the DB if it doesn't exist
 
 Store an embedded past conversation message for cross-thread recall.
 
+> [!NOTE]
+> As of TRACE 1.0.4, `CTree.add()` calls this **automatically** behind the scenes. You only need to call this manually if you are managing the Vector DB independently of a CTree.
+
 ```python
 from trace_memory import ConversationVector
 import time, uuid
@@ -638,15 +641,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