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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trace-memory
-Version: 1.0.0
+Version: 1.0.3
 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
@@ -37,8 +37,10 @@ Dynamic: license-file
 > Reduce context loss. Reduce broken agent tasks. Stop paying for tokens on chat history you don't need.
 
 [![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://python.org)
+[![PyPI version](https://badge.fury.io/py/trace-memory.svg)](https://badge.fury.io/py/trace-memory)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![OpenAI-compatible](https://img.shields.io/badge/LLM-OpenAI%20compatible-orange)](https://platform.openai.com/docs/api-reference)
+[![Benchmark](https://img.shields.io/badge/MemoryAgentBench-83.8%25-success)](benchmark_results/trace_120b_eventqa_64k_results.json)
 
 > **This repo has two parts — they are completely independent:**
 > - 🧠 **`trace_memory/`** — the lightweight memory engine. Install it, import it, and integrate it into your own app. Zero UI, zero bloat.
@@ -137,9 +139,9 @@ TRACE builds on the open-source **ChatIndex** architecture (credit: Mingtian Zha
 - **Internal nodes (TopicNodes)** — LLM-generated topic labels and summaries for each branch.
 - **Root** — a virtual anchor node.
 
-Every time an exchange is added (`tree.add()`), an LLM call classifies whether the exchange continues the current topic or starts a new branch. If a new branch, the LLM selects the most appropriate parent in the ancestry chain.
+Every time an exchange is added (`tree.add()`), TRACE forces the creation of a **new TopicNode** containing exactly one exchange. The LLM determines if it continues the current topic or starts a new branch. If it continues the topic, the new node is simply chained as a direct child of the previous one. This deep chronological chaining solves context truncation and ensures perfect, granular summarization for every single exchange.
 
-This gives TRACE a **structured map of the entire conversation history** — not a flat log — with topic metadata at every branch.
+This gives TRACE a **deep, structured map of the entire conversation history** — not a flat log — with highly granular topic metadata at every single link in the chain.
 
 **What TRACE adds to ChatIndex**: ChatIndex primarily retrieves context through a single traversal path. While effective for hierarchical exploration, information spread across multiple semantically related branches may require multiple retrieval steps. TRACE augments this with vector-based retrieval across topic summaries, allowing context from multiple branches to be surfaced simultaneously.
 
@@ -239,44 +241,29 @@ When `prune_trivial_leaves=True` is passed to `reorganize()`, TRACE detects Mess
 
 ## 4. Installation
 
-### From Source (recommended until PyPI release)
-
 ```bash
-git clone https://github.com/husain34/TRACE.git
-cd TRACE
-pip install -e .
+pip install trace-memory
 ```
 
-### Dependencies installed automatically
-
-| Package | Purpose |
-|---|---|
-| `openai>=1.0.0` | LLM API client (works with any OpenAI-compatible endpoint) |
-| `python-dotenv>=1.0.0` | `.env` file support |
-
-> **Note**: TRACE requires the bundled `trace._llm_utils` module (which provides `ChatGPT_API` and `extract_json`) for internal LLM calls.
->
-> **Note**: TRACE's VectorDatabase uses only Python's built-in `sqlite3` and `struct` modules — no external vector DB dependency required.
-
 ---
 
 ### Minimal Integration (10 lines)
 
-If you already have a chat loop and just want to plug TRACE in, this is all you need:
+If you already have a chat loop and just want to plug TRACE in, this is all you need. Since TRACE includes a powerful built-in local embedder (`BAAI/bge-base-en-v1.5`), you don't even need to configure your own embedding model!
 
 ```python
-import openai
-from trace_memory import CTree, VectorDatabase, PromptSynthesizer
-
-# 1. Boot
-client = openai.OpenAI(api_key="sk-...", base_url="http://127.0.0.1:1234/v1")
-def embed(text): return client.embeddings.create(input=[text], model="nomic-embed-text").data[0].embedding
+from trace_memory.ctree import CTree
+from trace_memory.vector_db import VectorDatabase
+from trace_memory.prompt_synthesizer import PromptSynthesizer
 
-tree = CTree(api_key="sk-...", model="gpt-4o-mini", embed_fn=embed)
+# 1. Boot the tree and attach the Vector DB
+tree = CTree(api_key="sk-...", model="gpt-4o-mini")
 tree.vdb = VectorDatabase("session.db")
+
+# 2. Setup the Prompt Synthesizer
 synth = PromptSynthesizer(ctree=tree, vector_db=tree.vdb)
 
-# 2. Each turn: build prompt → call LLM → store exchange
+# 3. Each turn: build prompt → call LLM → store exchange
 while True:
     user_input = input("You: ")
     system_prompt = synth.synthesize_prompt(
@@ -347,7 +334,8 @@ from trace_memory import CTree
 ```python
 CTree(
     max_children:   int = 5,
-    api_key:        str = None,        # falls back to OPENAI_API_KEY env var
+    api_key:        str = None,        # optional: falls back to OPENAI_API_KEY env var or "lm-studio"
+    base_url:       str = None,        # optional: route to custom endpoints (e.g. vLLM, Ollama, LM Studio)
     model:          str = "gpt-4o-mini",
     auto_save_path: str = None,        # auto-saves tree structure (not VDB) after every add() if set
     embed_fn:       Callable = None,   # optional: inject your embed function at construction time
@@ -417,7 +405,7 @@ tree.save("sessions/chat_001.json", save_conversation=True)
 
 ---
 
-##### `CTree.load(filepath: str, api_key: str = None, model: str = None) -> CTree`
+##### `CTree.load(filepath: str, api_key: str = None, base_url: str = None, model: str = None) -> CTree`
 
 Restore a tree from a JSON file.
 
@@ -616,12 +604,18 @@ ConversationVector(
 ### 7.1 With LM Studio (local)
 
 ```python
+from trace_memory import CTree
+# Connect directly via parameters
+tree = CTree(
+    base_url="http://127.0.0.1:1234/v1",
+    api_key="lm-studio",
+    model="meta-llama-3.1-8b-instruct"
+)
+
+# Or set environment variables globally
 import os
 os.environ["OPENAI_BASE_URL"] = "http://127.0.0.1:1234/v1"
 os.environ["OPENAI_API_KEY"]  = "lm-studio"
-
-from trace_memory import CTree
-tree = CTree(model="meta-llama-3.1-8b-instruct")
 ```
 
 Or use a `.env` file in your project root:

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

@@ -8,8 +8,10 @@
 > Reduce context loss. Reduce broken agent tasks. Stop paying for tokens on chat history you don't need.
 
 [![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://python.org)
+[![PyPI version](https://badge.fury.io/py/trace-memory.svg)](https://badge.fury.io/py/trace-memory)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![OpenAI-compatible](https://img.shields.io/badge/LLM-OpenAI%20compatible-orange)](https://platform.openai.com/docs/api-reference)
+[![Benchmark](https://img.shields.io/badge/MemoryAgentBench-83.8%25-success)](benchmark_results/trace_120b_eventqa_64k_results.json)
 
 > **This repo has two parts — they are completely independent:**
 > - 🧠 **`trace_memory/`** — the lightweight memory engine. Install it, import it, and integrate it into your own app. Zero UI, zero bloat.
@@ -108,9 +110,9 @@ TRACE builds on the open-source **ChatIndex** architecture (credit: Mingtian Zha
 - **Internal nodes (TopicNodes)** — LLM-generated topic labels and summaries for each branch.
 - **Root** — a virtual anchor node.
 
-Every time an exchange is added (`tree.add()`), an LLM call classifies whether the exchange continues the current topic or starts a new branch. If a new branch, the LLM selects the most appropriate parent in the ancestry chain.
+Every time an exchange is added (`tree.add()`), TRACE forces the creation of a **new TopicNode** containing exactly one exchange. The LLM determines if it continues the current topic or starts a new branch. If it continues the topic, the new node is simply chained as a direct child of the previous one. This deep chronological chaining solves context truncation and ensures perfect, granular summarization for every single exchange.
 
-This gives TRACE a **structured map of the entire conversation history** — not a flat log — with topic metadata at every branch.
+This gives TRACE a **deep, structured map of the entire conversation history** — not a flat log — with highly granular topic metadata at every single link in the chain.
 
 **What TRACE adds to ChatIndex**: ChatIndex primarily retrieves context through a single traversal path. While effective for hierarchical exploration, information spread across multiple semantically related branches may require multiple retrieval steps. TRACE augments this with vector-based retrieval across topic summaries, allowing context from multiple branches to be surfaced simultaneously.
 
@@ -210,44 +212,29 @@ When `prune_trivial_leaves=True` is passed to `reorganize()`, TRACE detects Mess
 
 ## 4. Installation
 
-### From Source (recommended until PyPI release)
-
 ```bash
-git clone https://github.com/husain34/TRACE.git
-cd TRACE
-pip install -e .
+pip install trace-memory
 ```
 
-### Dependencies installed automatically
-
-| Package | Purpose |
-|---|---|
-| `openai>=1.0.0` | LLM API client (works with any OpenAI-compatible endpoint) |
-| `python-dotenv>=1.0.0` | `.env` file support |
-
-> **Note**: TRACE requires the bundled `trace._llm_utils` module (which provides `ChatGPT_API` and `extract_json`) for internal LLM calls.
->
-> **Note**: TRACE's VectorDatabase uses only Python's built-in `sqlite3` and `struct` modules — no external vector DB dependency required.
-
 ---
 
 ### Minimal Integration (10 lines)
 
-If you already have a chat loop and just want to plug TRACE in, this is all you need:
+If you already have a chat loop and just want to plug TRACE in, this is all you need. Since TRACE includes a powerful built-in local embedder (`BAAI/bge-base-en-v1.5`), you don't even need to configure your own embedding model!
 
 ```python
-import openai
-from trace_memory import CTree, VectorDatabase, PromptSynthesizer
-
-# 1. Boot
-client = openai.OpenAI(api_key="sk-...", base_url="http://127.0.0.1:1234/v1")
-def embed(text): return client.embeddings.create(input=[text], model="nomic-embed-text").data[0].embedding
+from trace_memory.ctree import CTree
+from trace_memory.vector_db import VectorDatabase
+from trace_memory.prompt_synthesizer import PromptSynthesizer
 
-tree = CTree(api_key="sk-...", model="gpt-4o-mini", embed_fn=embed)
+# 1. Boot the tree and attach the Vector DB
+tree = CTree(api_key="sk-...", model="gpt-4o-mini")
 tree.vdb = VectorDatabase("session.db")
+
+# 2. Setup the Prompt Synthesizer
 synth = PromptSynthesizer(ctree=tree, vector_db=tree.vdb)
 
-# 2. Each turn: build prompt → call LLM → store exchange
+# 3. Each turn: build prompt → call LLM → store exchange
 while True:
     user_input = input("You: ")
     system_prompt = synth.synthesize_prompt(
@@ -318,7 +305,8 @@ from trace_memory import CTree
 ```python
 CTree(
     max_children:   int = 5,
-    api_key:        str = None,        # falls back to OPENAI_API_KEY env var
+    api_key:        str = None,        # optional: falls back to OPENAI_API_KEY env var or "lm-studio"
+    base_url:       str = None,        # optional: route to custom endpoints (e.g. vLLM, Ollama, LM Studio)
     model:          str = "gpt-4o-mini",
     auto_save_path: str = None,        # auto-saves tree structure (not VDB) after every add() if set
     embed_fn:       Callable = None,   # optional: inject your embed function at construction time
@@ -388,7 +376,7 @@ tree.save("sessions/chat_001.json", save_conversation=True)
 
 ---
 
-##### `CTree.load(filepath: str, api_key: str = None, model: str = None) -> CTree`
+##### `CTree.load(filepath: str, api_key: str = None, base_url: str = None, model: str = None) -> CTree`
 
 Restore a tree from a JSON file.
 
@@ -587,12 +575,18 @@ ConversationVector(
 ### 7.1 With LM Studio (local)
 
 ```python
+from trace_memory import CTree
+# Connect directly via parameters
+tree = CTree(
+    base_url="http://127.0.0.1:1234/v1",
+    api_key="lm-studio",
+    model="meta-llama-3.1-8b-instruct"
+)
+
+# Or set environment variables globally
 import os
 os.environ["OPENAI_BASE_URL"] = "http://127.0.0.1:1234/v1"
 os.environ["OPENAI_API_KEY"]  = "lm-studio"
-
-from trace_memory import CTree
-tree = CTree(model="meta-llama-3.1-8b-instruct")
 ```
 
 Or use a `.env` file in your project root:

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name            = "trace-memory"
-version         = "1.0.0"
+version         = "1.0.3"
 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.0 → trace_memory-1.0.3}/trace_memory/_llm_utils.py

@@ -20,6 +20,7 @@ def ChatGPT_API(
     model: str,
     prompt: str,
     api_key: str = None,
+    base_url: str = None,
     chat_history: list = None,
     temperature: float = 0,
     max_tokens: int = None,
@@ -42,10 +43,10 @@ def ChatGPT_API(
     str  — Response text, or "Error" after all retries are exhausted.
     """
     max_retries = 10
-    base_url = os.getenv("OPENAI_BASE_URL", "http://127.0.0.1:1234/v1")
+    base_url_to_use = base_url or os.getenv("OPENAI_BASE_URL", "http://127.0.0.1:1234/v1")
     api_key_to_use = api_key or os.getenv("OPENAI_API_KEY") or "lm-studio"
 
-    client = openai.OpenAI(api_key=api_key_to_use, base_url=base_url)
+    client = openai.OpenAI(api_key=api_key_to_use, base_url=base_url_to_use)
 
     for i in range(max_retries):
         try:

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

@@ -257,6 +257,7 @@ class CTree:
         self,
         max_children: int = 5,
         api_key:      str = None,
+        base_url:     str = None,
         model:        str = "gpt-4o-mini",
         auto_save_path: str = None,
         embed_fn:     Optional[Callable[[str], List[float]]] = None,
@@ -268,6 +269,7 @@ class CTree:
         self._archived_nodes: List[MessageNode] = []
         self.vdb            = None   # inject: VectorDatabase instance
         self.embed_fn       = embed_fn or _default_embed_fn   # inject: callable(text) -> List[float]
+        self.base_url       = base_url
 
         # API key resolution
         if api_key:
@@ -275,10 +277,7 @@ class CTree:
         elif os.getenv("OPENAI_API_KEY"):
             self.api_key = os.getenv("OPENAI_API_KEY")
         else:
-            raise ValueError(
-                "API key must be provided via api_key= or the "
-                "OPENAI_API_KEY environment variable."
-            )
+            self.api_key = "lm-studio"
 
         self.root: TopicNode = TopicNode(
             topic_name="ROOT",
@@ -482,11 +481,13 @@ class CTree:
         classification = self._llm_classify_message_exchange(
             user_msg, assistant_msg, candidate_nodes, system_msg
         )
+        topic_name = classification.get("new_topic_name", "")
         if classification["belongs_to_current"]:
-            return candidate_nodes[-1]
+            return self._create_new_topic_for_message(
+                user_msg, assistant_msg, candidate_nodes[-1], topic_name, system_msg
+            )
         parent_index = classification.get("new_topic_parent_index", len(candidate_nodes) - 1)
         parent_node  = candidate_nodes[parent_index]
-        topic_name   = classification.get("new_topic_name", "")
         return self._create_new_topic_for_message(
             user_msg, assistant_msg, parent_node, topic_name, system_msg
         )
@@ -534,7 +535,7 @@ class CTree:
             f"Message: {content}\n\nRespond with ONLY the topic name, nothing else."
         )
         try:
-            return ChatGPT_API(self.model, prompt, api_key=self.api_key, temperature=0.3, max_tokens=50).strip()
+            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)}"
@@ -553,7 +554,7 @@ class CTree:
             f"Respond with ONLY the topic name, nothing else."
         )
         try:
-            return ChatGPT_API(self.model, prompt, api_key=self.api_key, temperature=0.3, max_tokens=50).strip()
+            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 from message: {e}")
             return f"Topic at message {len(self.conversation) // 2}"
@@ -567,7 +568,7 @@ class CTree:
             f"in 1-2 sentences.\n\n{content}\n\nSummary:"
         )
         try:
-            return ChatGPT_API(self.model, prompt, api_key=self.api_key, temperature=0.3, max_tokens=100).strip()
+            return ChatGPT_API(self.model, prompt, api_key=self.api_key, base_url=self.base_url, temperature=0.3, max_tokens=100).strip()
         except Exception as e:
             print(f"LLM error in summarization: {e}")
             return f"Discussion about {topic_name}"
@@ -601,14 +602,15 @@ class CTree:
             f"3. CRITICAL: When choosing new_topic_parent_index — if the new topic is completely unrelated "
             f"to all listed ancestors, you MUST choose index 0 (the root/top-level). Only choose a deeper "
             f"ancestor if the new topic is a genuine sub-topic of that ancestor.\n"
-            f"4. Do NOT nest an unrelated topic under the current topic just because it is the most recent.\n\n"
+            f"4. Do NOT nest an unrelated topic under the current topic just because it is the most recent.\n"
+            f"5. ALWAYS provide a concise 'new_topic_name' (2-5 words) that summarizes this specific exchange, regardless of belongs_to_current.\n\n"
             f"Respond ONLY with valid JSON:\n"
             f"{{\"reasoning\": \"brief explanation\", \"belongs_to_current\": true|false, "
-            f"\"new_topic_name\": \"name (or N/A)\", \"new_topic_parent_index\": <index or N/A>}}\n\n"
+            f"\"new_topic_name\": \"name\", \"new_topic_parent_index\": <index or N/A>}}\n\n"
             f"Output ONLY the JSON, no other text."
         )
         try:
-            response = ChatGPT_API(self.model, prompt, api_key=self.api_key, temperature=0.1, max_tokens=200)
+            response = ChatGPT_API(self.model, prompt, api_key=self.api_key, base_url=self.base_url, temperature=0.1, max_tokens=200)
             result   = extract_json(response)
             if "new_topic_parent_index" in result:
                 raw    = result["new_topic_parent_index"]
@@ -647,7 +649,7 @@ class CTree:
             f"Output ONLY the JSON, no other text."
         )
         try:
-            response = ChatGPT_API(self.model, prompt, api_key=self.api_key, temperature=0.3, max_tokens=500)
+            response = ChatGPT_API(self.model, prompt, api_key=self.api_key, base_url=self.base_url, temperature=0.3, max_tokens=500)
             result   = extract_json(response)
             if isinstance(result, list):
                 return result
@@ -671,7 +673,7 @@ class CTree:
             f'Respond with ONLY: {{"reasoning": "...", "split_index": <int 1–{len(topic_children)-1}>}}'
         )
         try:
-            response    = ChatGPT_API(self.model, prompt, api_key=self.api_key, temperature=0.2, max_tokens=200)
+            response    = ChatGPT_API(self.model, prompt, api_key=self.api_key, base_url=self.base_url, temperature=0.2, max_tokens=200)
             result      = extract_json(response)
             split_index = _safe_int(result.get("split_index"), len(topic_children) // 2)
             return max(1, min(split_index, len(topic_children) - 1))
@@ -687,7 +689,7 @@ class CTree:
             f"Subtopics: {text}\n\nRespond with ONLY the topic name."
         )
         try:
-            name = ChatGPT_API(self.model, prompt, api_key=self.api_key, temperature=0.3, max_tokens=50).strip()
+            name = ChatGPT_API(self.model, prompt, api_key=self.api_key, base_url=self.base_url, temperature=0.3, max_tokens=50).strip()
             return name.strip("\"'")
         except Exception:
             return f"{parent_node.topic_name} – Part"
@@ -705,7 +707,7 @@ class CTree:
             f'"topic_indices": [...]}}]}}'
         )
         try:
-            response = ChatGPT_API(self.model, prompt, api_key=self.api_key, temperature=0.3, max_tokens=800)
+            response = ChatGPT_API(self.model, prompt, api_key=self.api_key, base_url=self.base_url, temperature=0.3, max_tokens=800)
             result   = extract_json(response)
             if isinstance(result, dict) and "groups" in result:
                 groups = result["groups"]
@@ -879,7 +881,7 @@ class CTree:
             json.dump(data, f, indent=2, ensure_ascii=False)
 
     @classmethod
-    def load(cls, filepath: str, api_key: str = None, model: str = None, embed_fn: Optional[Callable[[str], List[float]]] = None) -> "CTree":
+    def load(cls, filepath: str, api_key: str = None, base_url: str = None, model: str = None, embed_fn: Optional[Callable[[str], List[float]]] = None) -> "CTree":
         """
         Reconstruct a ``CTree`` from a previously saved JSON file.
 
@@ -903,6 +905,7 @@ class CTree:
         tree = cls(
             max_children = data.get("max_children", 5),
             api_key      = api_key,
+            base_url     = base_url,
             model        = model or "gpt-4o-mini",
             embed_fn     = embed_fn,
         )
@@ -994,7 +997,7 @@ class CTree:
             f'{{"related": true|false, "reason": "short reason", "merge_direction": "a_into_b"|"b_into_a"|"N/A"}}'
         )
         try:
-            response = ChatGPT_API(self.model, prompt, api_key=self.api_key, temperature=0.1, max_tokens=300)
+            response = ChatGPT_API(self.model, prompt, api_key=self.api_key, base_url=self.base_url, temperature=0.1, max_tokens=300)
             result   = extract_json(response)
             result.setdefault("related", False)
             result.setdefault("merge_direction", "N/A")

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trace-memory
-Version: 1.0.0
+Version: 1.0.3
 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
@@ -37,8 +37,10 @@ Dynamic: license-file
 > Reduce context loss. Reduce broken agent tasks. Stop paying for tokens on chat history you don't need.
 
 [![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://python.org)
+[![PyPI version](https://badge.fury.io/py/trace-memory.svg)](https://badge.fury.io/py/trace-memory)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![OpenAI-compatible](https://img.shields.io/badge/LLM-OpenAI%20compatible-orange)](https://platform.openai.com/docs/api-reference)
+[![Benchmark](https://img.shields.io/badge/MemoryAgentBench-83.8%25-success)](benchmark_results/trace_120b_eventqa_64k_results.json)
 
 > **This repo has two parts — they are completely independent:**
 > - 🧠 **`trace_memory/`** — the lightweight memory engine. Install it, import it, and integrate it into your own app. Zero UI, zero bloat.
@@ -137,9 +139,9 @@ TRACE builds on the open-source **ChatIndex** architecture (credit: Mingtian Zha
 - **Internal nodes (TopicNodes)** — LLM-generated topic labels and summaries for each branch.
 - **Root** — a virtual anchor node.
 
-Every time an exchange is added (`tree.add()`), an LLM call classifies whether the exchange continues the current topic or starts a new branch. If a new branch, the LLM selects the most appropriate parent in the ancestry chain.
+Every time an exchange is added (`tree.add()`), TRACE forces the creation of a **new TopicNode** containing exactly one exchange. The LLM determines if it continues the current topic or starts a new branch. If it continues the topic, the new node is simply chained as a direct child of the previous one. This deep chronological chaining solves context truncation and ensures perfect, granular summarization for every single exchange.
 
-This gives TRACE a **structured map of the entire conversation history** — not a flat log — with topic metadata at every branch.
+This gives TRACE a **deep, structured map of the entire conversation history** — not a flat log — with highly granular topic metadata at every single link in the chain.
 
 **What TRACE adds to ChatIndex**: ChatIndex primarily retrieves context through a single traversal path. While effective for hierarchical exploration, information spread across multiple semantically related branches may require multiple retrieval steps. TRACE augments this with vector-based retrieval across topic summaries, allowing context from multiple branches to be surfaced simultaneously.
 
@@ -239,44 +241,29 @@ When `prune_trivial_leaves=True` is passed to `reorganize()`, TRACE detects Mess
 
 ## 4. Installation
 
-### From Source (recommended until PyPI release)
-
 ```bash
-git clone https://github.com/husain34/TRACE.git
-cd TRACE
-pip install -e .
+pip install trace-memory
 ```
 
-### Dependencies installed automatically
-
-| Package | Purpose |
-|---|---|
-| `openai>=1.0.0` | LLM API client (works with any OpenAI-compatible endpoint) |
-| `python-dotenv>=1.0.0` | `.env` file support |
-
-> **Note**: TRACE requires the bundled `trace._llm_utils` module (which provides `ChatGPT_API` and `extract_json`) for internal LLM calls.
->
-> **Note**: TRACE's VectorDatabase uses only Python's built-in `sqlite3` and `struct` modules — no external vector DB dependency required.
-
 ---
 
 ### Minimal Integration (10 lines)
 
-If you already have a chat loop and just want to plug TRACE in, this is all you need:
+If you already have a chat loop and just want to plug TRACE in, this is all you need. Since TRACE includes a powerful built-in local embedder (`BAAI/bge-base-en-v1.5`), you don't even need to configure your own embedding model!
 
 ```python
-import openai
-from trace_memory import CTree, VectorDatabase, PromptSynthesizer
-
-# 1. Boot
-client = openai.OpenAI(api_key="sk-...", base_url="http://127.0.0.1:1234/v1")
-def embed(text): return client.embeddings.create(input=[text], model="nomic-embed-text").data[0].embedding
+from trace_memory.ctree import CTree
+from trace_memory.vector_db import VectorDatabase
+from trace_memory.prompt_synthesizer import PromptSynthesizer
 
-tree = CTree(api_key="sk-...", model="gpt-4o-mini", embed_fn=embed)
+# 1. Boot the tree and attach the Vector DB
+tree = CTree(api_key="sk-...", model="gpt-4o-mini")
 tree.vdb = VectorDatabase("session.db")
+
+# 2. Setup the Prompt Synthesizer
 synth = PromptSynthesizer(ctree=tree, vector_db=tree.vdb)
 
-# 2. Each turn: build prompt → call LLM → store exchange
+# 3. Each turn: build prompt → call LLM → store exchange
 while True:
     user_input = input("You: ")
     system_prompt = synth.synthesize_prompt(
@@ -347,7 +334,8 @@ from trace_memory import CTree
 ```python
 CTree(
     max_children:   int = 5,
-    api_key:        str = None,        # falls back to OPENAI_API_KEY env var
+    api_key:        str = None,        # optional: falls back to OPENAI_API_KEY env var or "lm-studio"
+    base_url:       str = None,        # optional: route to custom endpoints (e.g. vLLM, Ollama, LM Studio)
     model:          str = "gpt-4o-mini",
     auto_save_path: str = None,        # auto-saves tree structure (not VDB) after every add() if set
     embed_fn:       Callable = None,   # optional: inject your embed function at construction time
@@ -417,7 +405,7 @@ tree.save("sessions/chat_001.json", save_conversation=True)
 
 ---
 
-##### `CTree.load(filepath: str, api_key: str = None, model: str = None) -> CTree`
+##### `CTree.load(filepath: str, api_key: str = None, base_url: str = None, model: str = None) -> CTree`
 
 Restore a tree from a JSON file.
 
@@ -616,12 +604,18 @@ ConversationVector(
 ### 7.1 With LM Studio (local)
 
 ```python
+from trace_memory import CTree
+# Connect directly via parameters
+tree = CTree(
+    base_url="http://127.0.0.1:1234/v1",
+    api_key="lm-studio",
+    model="meta-llama-3.1-8b-instruct"
+)
+
+# Or set environment variables globally
 import os
 os.environ["OPENAI_BASE_URL"] = "http://127.0.0.1:1234/v1"
 os.environ["OPENAI_API_KEY"]  = "lm-studio"
-
-from trace_memory import CTree
-tree = CTree(model="meta-llama-3.1-8b-instruct")
 ```
 
 Or use a `.env` file in your project root: