loci_memory 0.0.1__tar.gz

loci_memory-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2026] [Daniel Roque Gonçalves de Almeida]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

loci_memory-0.0.1/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: loci_memory
+Version: 0.0.1
+Summary: Chroma based MCP Server - Provide memory capabilities using Vector Database for LLM Applications
+License-Expression: MIT
+Keywords: chroma,mcp,vector-database,llm,memory,holographic
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: chromadb>=1.0.16
+Requires-Dist: fastmcp>=3.2.3
+Requires-Dist: typing-extensions>=4.13.1
+Dynamic: license-file
+
+## Features
+
+- **Flexible Client Types**
+  - Ephemeral (in-memory) for testing and development
+  - Persistent for file-based storage
+
+- **Collection Management**
+  - Create, modify, and delete collections
+  - List all collections with pagination support
+  - Get collection information and statistics
+  - Configure HNSW parameters for optimized vector search
+  - Select embedding functions when creating collections
+
+- **Document Operations**
+  - Add documents with optional metadata and custom IDs
+  - Query documents using semantic search
+  - Advanced filtering using metadata and document content
+  - Retrieve documents by IDs or filters
+  - Full text search capabilities
+
+### Supported Tools
+
+- `chroma_list_collections` - List all collections with pagination support
+- `chroma_create_collection` - Create a new collection with optional HNSW configuration
+- `chroma_peek_collection` - View a sample of documents in a collection
+- `chroma_get_collection_info` - Get detailed information about a collection
+- `chroma_get_collection_count` - Get the number of documents in a collection
+- `chroma_modify_collection` - Update a collection's name or metadata
+- `chroma_delete_collection` - Delete a collection
+- `chroma_add_documents` - Add documents with optional metadata and custom IDs
+- `chroma_query_documents` - Query documents using semantic search with advanced filtering
+- `chroma_get_documents` - Retrieve documents by IDs or filters with pagination
+- `chroma_update_documents` - Update existing documents' content, metadata, or embeddings
+- `chroma_delete_documents` - Delete specific documents from a collection
+
+### Embedding Functions
+Chroma MCP supports several embedding functions: `default`, `cohere`, `openai`, `jina`, `voyageai`, and `roboflow`.
+
+The embedding functions utilize Chroma's collection configuration, which persists the selected embedding function of a collection for retrieval. Once a collection is created using the collection configuration, on retrieval for future queries and inserts, the same embedding function will be used, without needing to specify the embedding function again. Embedding function persistance was added in v1.0.0 of Chroma, so if you created a collection using version <=0.6.3, this feature is not supported.
+
+When accessing embedding functions that utilize external APIs, please be sure to add the environment variable for the API key with the correct format, found in [Embedding Function Environment Variables](#embedding-function-environment-variables)
+
+## Usage with LM Studio
+
+Add the following to your `mcp.json` file:
+
+```json
+"chroma": {
+    "command": "uvx",
+    "args": [
+        "loci-memory",
+        "--client-type",
+        "persistent",
+        "--data-dir",
+        "/full/path/to/your/data/directory"
+    ]
+}
+
+[GitHub-flavored Markdown](https://guides.github.com/features/mastering-markdown/)

loci_memory-0.0.1/README.md

@@ -0,0 +1,59 @@
+## Features
+
+- **Flexible Client Types**
+  - Ephemeral (in-memory) for testing and development
+  - Persistent for file-based storage
+
+- **Collection Management**
+  - Create, modify, and delete collections
+  - List all collections with pagination support
+  - Get collection information and statistics
+  - Configure HNSW parameters for optimized vector search
+  - Select embedding functions when creating collections
+
+- **Document Operations**
+  - Add documents with optional metadata and custom IDs
+  - Query documents using semantic search
+  - Advanced filtering using metadata and document content
+  - Retrieve documents by IDs or filters
+  - Full text search capabilities
+
+### Supported Tools
+
+- `chroma_list_collections` - List all collections with pagination support
+- `chroma_create_collection` - Create a new collection with optional HNSW configuration
+- `chroma_peek_collection` - View a sample of documents in a collection
+- `chroma_get_collection_info` - Get detailed information about a collection
+- `chroma_get_collection_count` - Get the number of documents in a collection
+- `chroma_modify_collection` - Update a collection's name or metadata
+- `chroma_delete_collection` - Delete a collection
+- `chroma_add_documents` - Add documents with optional metadata and custom IDs
+- `chroma_query_documents` - Query documents using semantic search with advanced filtering
+- `chroma_get_documents` - Retrieve documents by IDs or filters with pagination
+- `chroma_update_documents` - Update existing documents' content, metadata, or embeddings
+- `chroma_delete_documents` - Delete specific documents from a collection
+
+### Embedding Functions
+Chroma MCP supports several embedding functions: `default`, `cohere`, `openai`, `jina`, `voyageai`, and `roboflow`.
+
+The embedding functions utilize Chroma's collection configuration, which persists the selected embedding function of a collection for retrieval. Once a collection is created using the collection configuration, on retrieval for future queries and inserts, the same embedding function will be used, without needing to specify the embedding function again. Embedding function persistance was added in v1.0.0 of Chroma, so if you created a collection using version <=0.6.3, this feature is not supported.
+
+When accessing embedding functions that utilize external APIs, please be sure to add the environment variable for the API key with the correct format, found in [Embedding Function Environment Variables](#embedding-function-environment-variables)
+
+## Usage with LM Studio
+
+Add the following to your `mcp.json` file:
+
+```json
+"chroma": {
+    "command": "uvx",
+    "args": [
+        "loci-memory",
+        "--client-type",
+        "persistent",
+        "--data-dir",
+        "/full/path/to/your/data/directory"
+    ]
+}
+
+[GitHub-flavored Markdown](https://guides.github.com/features/mastering-markdown/)

loci_memory-0.0.1/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "loci_memory"
+version = "0.0.1"
+description = "Chroma based MCP Server - Provide memory capabilities using Vector Database for LLM Applications"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+
+keywords = ["chroma", "mcp", "vector-database", "llm", "memory","holographic"]
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules"
+]
+
+dependencies = [
+    "chromadb>=1.0.16",
+    "fastmcp>=3.2.3",
+    "typing-extensions>=4.13.1",
+]
+
+[project.scripts]
+loci_memory = "loci_memory.loci:main"

loci_memory-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

loci_memory-0.0.1/src/__init__.py

@@ -0,0 +1 @@
+#   Empty

loci_memory-0.0.1/src/holographic/__init__.py

@@ -0,0 +1,325 @@
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import Any, Dict, List
+
+from .store import MemoryStore
+from .retrieval import FactRetriever
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Tool schemas
+# ---------------------------------------------------------------------------
+
+FACT_STORE_SCHEMA = {
+    "name": "fact_store",
+    "description": (
+        "Deep structured memory with algebraic reasoning. "
+        "Use alongside the memory tool — memory for always-on context, "
+        "fact_store for deep recall and compositional queries.\n\n"
+        "ACTIONS (simple → powerful):\n"
+        "• add — Store a fact the user would expect you to remember.\n"
+        "• search — Keyword lookup ('editor config', 'deploy process').\n"
+        "• probe — Entity recall: ALL facts about a person/thing.\n"
+        "• related — What connects to an entity? Structural adjacency.\n"
+        "• reason — Compositional: facts connected to MULTIPLE entities simultaneously.\n"
+        "• contradict — Memory hygiene: find facts making conflicting claims.\n"
+        "• update/remove/list — CRUD operations.\n\n"
+        "IMPORTANT: Before answering questions about the user, ALWAYS probe or reason first."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "action": {
+                "type": "string",
+                "enum": ["add", "search", "probe", "related", "reason", "contradict", "update", "remove", "list"],
+            },
+            "content": {"type": "string", "description": "Fact content (required for 'add')."},
+            "query": {"type": "string", "description": "Search query (required for 'search')."},
+            "entity": {"type": "string", "description": "Entity name for 'probe'/'related'."},
+            "entities": {"type": "array", "items": {"type": "string"}, "description": "Entity names for 'reason'."},
+            "fact_id": {"type": "integer", "description": "Fact ID for 'update'/'remove'."},
+            "category": {"type": "string", "enum": ["user_pref", "project", "tool", "general"]},
+            "tags": {"type": "string", "description": "Comma-separated tags."},
+            "trust_delta": {"type": "number", "description": "Trust adjustment for 'update'."},
+            "min_trust": {"type": "number", "description": "Minimum trust filter (default: 0.3)."},
+            "limit": {"type": "integer", "description": "Max results (default: 10)."},
+        },
+        "required": ["action"],
+    },
+}
+
+FACT_FEEDBACK_SCHEMA = {
+    "name": "fact_feedback",
+    "description": (
+        "Rate a fact after using it. Mark 'helpful' if accurate, 'unhelpful' if outdated. "
+        "This trains the memory — good facts rise, bad facts sink."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "action": {"type": "string", "enum": ["helpful", "unhelpful"]},
+            "fact_id": {"type": "integer", "description": "The fact ID to rate."},
+        },
+        "required": ["action", "fact_id"],
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# Holographic Memory implementation
+# ---------------------------------------------------------------------------
+
+class HolographicMemoryProvider():
+    """Holographic memory with structured facts, entity resolution, and HRR retrieval."""
+
+    def __init__(self):
+        return
+
+    @property
+    def name(self) -> str:
+        return "holographic"
+
+    def is_available(self) -> bool:
+        return True  # SQLite is always available, numpy is optional
+
+    def initialize(self, session_id: str) -> None:
+        #from loci_constants import get_loci_home
+        #_loci_home = str(get_loci_home())
+        _loci_home = ".loci_memory"
+        _default_db = _loci_home + "/memory_store.db"
+        db_path = _default_db
+        default_trust = float(0.5)
+        hrr_dim = int(1024)
+        hrr_weight = float(0.3)
+        temporal_decay = int(0)
+
+        self._store = MemoryStore(db_path=db_path, default_trust=default_trust, hrr_dim=hrr_dim)
+        self._retriever = FactRetriever(
+            store=self._store,
+            temporal_decay_half_life=temporal_decay,
+            hrr_weight=hrr_weight,
+            hrr_dim=hrr_dim,
+        )
+        self._session_id = session_id
+
+    def system_prompt_block(self) -> str:
+        if not self._store:
+            return ""
+        try:
+            total = self._store._conn.execute(
+                "SELECT COUNT(*) FROM facts"
+            ).fetchone()[0]
+        except Exception:
+            total = 0
+        if total == 0:
+            return (
+                "# Holographic Memory\n"
+                "Active. Empty fact store — proactively add facts the user would expect you to remember.\n"
+                "Use fact_store(action='add') to store durable structured facts about people, projects, preferences, decisions.\n"
+                "Use fact_feedback to rate facts after using them (trains trust scores)."
+            )
+        return (
+            f"# Holographic Memory\n"
+            f"Active. {total} facts stored with entity resolution and trust scoring.\n"
+            f"Use fact_store to search, probe entities, reason across entities, or add facts.\n"
+            f"Use fact_feedback to rate facts after using them (trains trust scores)."
+        )
+
+    def prefetch(self, query: str, *, session_id: str = "") -> str:
+        if not self._retriever or not query:
+            return ""
+        try:
+            results = self._retriever.search(query, min_trust=self._min_trust, limit=5)
+            if not results:
+                return ""
+            lines = []
+            for r in results:
+                trust = r.get("trust_score", r.get("trust", 0))
+                lines.append(f"- [{trust:.1f}] {r.get('content', '')}")
+            return "## Holographic Memory\n" + "\n".join(lines)
+        except Exception as e:
+            logger.debug("Holographic prefetch failed: %s", e)
+            return ""
+
+    def sync_turn(self, user_content: str, assistant_content: str, *, session_id: str = "") -> None:
+        # Holographic memory stores explicit facts via tools, not auto-sync.
+        # The on_session_end hook handles auto-extraction if configured.
+        pass
+
+    def get_tool_schemas(self) -> List[Dict[str, Any]]:
+        return [FACT_STORE_SCHEMA, FACT_FEEDBACK_SCHEMA]
+
+    def handle_tool_call(self, tool_name: str, args: Dict[str, Any], **kwargs) -> str:
+        if tool_name == "fact_store":
+            return self._handle_fact_store(args)
+        elif tool_name == "fact_feedback":
+            return self._handle_fact_feedback(args)
+        return (f"Unknown tool: {tool_name}")
+
+    def on_session_end(self, messages: List[Dict[str, Any]]) -> None:
+        if not self._config.get("auto_extract", False):
+            return
+        if not self._store or not messages:
+            return
+        self._auto_extract_facts(messages)
+
+    def on_memory_write(self, action: str, target: str, content: str) -> None:
+        """Mirror built-in memory writes as facts."""
+        if action == "add" and self._store and content:
+            try:
+                category = "user_pref" if target == "user" else "general"
+                self._store.add_fact(content, category=category)
+            except Exception as e:
+                logger.debug("Holographic memory_write mirror failed: %s", e)
+
+    def shutdown(self) -> None:
+        self._store = None
+        self._retriever = None
+
+    #
+    # -- Tool handlers -------------------------------------------------------
+    #
+    def _handle_fact_store(self, args: dict) -> str:
+        try:
+            action = args["action"]
+            store = self._store
+            retriever = self._retriever
+
+            if action == "add":
+                fact_id = store.add_fact(
+                    args["content"],
+                    category=args.get("category", "general"),
+                    tags=args.get("tags", ""),
+                )
+                return json.dumps({"fact_id": fact_id, "status": "added"})
+
+            elif action == "search":
+                results = retriever.search(
+                    args["query"],
+                    category=args.get("category"),
+                    min_trust=float(args.get("min_trust", self._min_trust)),
+                    limit=int(args.get("limit", 10)),
+                )
+                return json.dumps({"results": results, "count": len(results)})
+
+            elif action == "probe":
+                results = retriever.probe(
+                    args["entity"],
+                    category=args.get("category"),
+                    limit=int(args.get("limit", 10)),
+                )
+                return json.dumps({"results": results, "count": len(results)})
+
+            elif action == "related":
+                results = retriever.related(
+                    args["entity"],
+                    category=args.get("category"),
+                    limit=int(args.get("limit", 10)),
+                )
+                return json.dumps({"results": results, "count": len(results)})
+
+            elif action == "reason":
+                entities = args.get("entities", [])
+                if not entities:
+                    return ("reason requires 'entities' list")
+                results = retriever.reason(
+                    entities,
+                    category=args.get("category"),
+                    limit=int(args.get("limit", 10)),
+                )
+                return json.dumps({"results": results, "count": len(results)})
+
+            elif action == "contradict":
+                results = retriever.contradict(
+                    category=args.get("category"),
+                    limit=int(args.get("limit", 10)),
+                )
+                return json.dumps({"results": results, "count": len(results)})
+
+            elif action == "update":
+                updated = store.update_fact(
+                    int(args["fact_id"]),
+                    content=args.get("content"),
+                    trust_delta=float(args["trust_delta"]) if "trust_delta" in args else None,
+                    tags=args.get("tags"),
+                    category=args.get("category"),
+                )
+                return json.dumps({"updated": updated})
+
+            elif action == "remove":
+                removed = store.remove_fact(int(args["fact_id"]))
+                return json.dumps({"removed": removed})
+
+            elif action == "list":
+                facts = store.list_facts(
+                    category=args.get("category"),
+                    min_trust=float(args.get("min_trust", 0.0)),
+                    limit=int(args.get("limit", 10)),
+                )
+                return json.dumps({"facts": facts, "count": len(facts)})
+
+            else:
+                return (f"Unknown action: {action}")
+
+        except KeyError as exc:
+            return (f"Missing required argument: {exc}")
+        except Exception as exc:
+            return (str(exc))
+
+    def _handle_fact_feedback(self, args: dict) -> str:
+        try:
+            fact_id = int(args["fact_id"])
+            helpful = args["action"] == "helpful"
+            result = self._store.record_feedback(fact_id, helpful=helpful)
+            return json.dumps(result)
+        except KeyError as exc:
+            return (f"Missing required argument: {exc}")
+        except Exception as exc:
+            return (str(exc))
+
+    # -- Auto-extraction (on_session_end) ------------------------------------
+
+    def _auto_extract_facts(self, messages: list) -> None:
+        _PREF_PATTERNS = [
+            re.compile(r'\bI\s+(?:prefer|like|love|use|want|need)\s+(.+)', re.IGNORECASE),
+            re.compile(r'\bmy\s+(?:favorite|preferred|default)\s+\w+\s+is\s+(.+)', re.IGNORECASE),
+            re.compile(r'\bI\s+(?:always|never|usually)\s+(.+)', re.IGNORECASE),
+        ]
+        _DECISION_PATTERNS = [
+            re.compile(r'\bwe\s+(?:decided|agreed|chose)\s+(?:to\s+)?(.+)', re.IGNORECASE),
+            re.compile(r'\bthe\s+project\s+(?:uses|needs|requires)\s+(.+)', re.IGNORECASE),
+        ]
+
+        extracted = 0
+        for msg in messages:
+            if msg.get("role") != "user":
+                continue
+            content = msg.get("content", "")
+            if not isinstance(content, str) or len(content) < 10:
+                continue
+
+            for pattern in _PREF_PATTERNS:
+                if pattern.search(content):
+                    try:
+                        self._store.add_fact(content[:400], category="user_pref")
+                        extracted += 1
+                    except Exception:
+                        pass
+                    break
+
+            for pattern in _DECISION_PATTERNS:
+                if pattern.search(content):
+                    try:
+                        self._store.add_fact(content[:400], category="project")
+                        extracted += 1
+                    except Exception:
+                        pass
+                    break
+
+        if extracted:
+            logger.info("Auto-extracted %d facts from conversation", extracted)
+