mdmemory 0.1.2__py3-none-any.whl

mdmemory/__init__.py

@@ -0,0 +1,54 @@
+"""MdMemory - Markdown-first, LLM-driven memory framework.
+
+A Markdown-first, LLM-driven memory framework that organizes agent knowledge 
+into a hierarchical Knowledge Tree. It prioritizes context efficiency by using 
+a hierarchical folder structure and a "Hybrid Indexing" strategy, ensuring the 
+agent only loads what is necessary.
+
+Core Features:
+    - Human-Readable: Data stored as standard .md files on the filesystem
+    - LLM-Organized: Uses LLM to automatically determine folder structure
+    - Context-Aware: Hybrid indexing strategy keeps the root index compact
+    - Efficient Navigation: Central index.md and .registry.json for direct access
+    - Provider Agnostic: Works with any LLM provider via callbacks
+
+Example Usage:
+    >>> from mdmemory import MdMemory
+    >>> memory = MdMemory()  # Uses defaults: LiteLLMCallback + "./MdMemory"
+    >>> topic = memory.store("user1", "My knowledge content")
+    >>> content = memory.get("user1", topic)
+    >>> index = memory.retrieve("user1")
+"""
+
+__title__ = "mdmemory"
+__version__ = "0.1.0"
+__author__ = "Contributors"
+__license__ = "MIT"
+__copyright__ = "Copyright 2026 Contributors"
+__description__ = (
+    "Markdown-first, LLM-driven memory framework organized "
+    "into a hierarchical Knowledge Tree"
+)
+
+from .core import (
+    MdMemory,
+    LLMCallback,
+    LiteLLMCallback,
+    OpenAICallback,
+    AnthropicCallback,
+)
+from .models import FrontMatter, LLMResponse
+
+__all__ = [
+    "MdMemory",
+    "LLMCallback",
+    "LiteLLMCallback",
+    "OpenAICallback",
+    "AnthropicCallback",
+    "FrontMatter",
+    "LLMResponse",
+    "__version__",
+    "__title__",
+    "__author__",
+    "__license__",
+]

mdmemory/core.py

@@ -0,0 +1,487 @@
+"""Core MdMemory implementation."""
+
+import asyncio
+import json
+import re
+import shutil
+from datetime import datetime
+from pathlib import Path
+from typing import Callable, Dict, List, Optional
+
+from .models import FrontMatter, LLMResponse
+from .registry import PathRegistry
+from .utils import (
+    ensure_dir_exists,
+    line_count,
+    parse_topic_title,
+    read_markdown_file,
+    save_json_safe,
+    write_markdown_file,
+)
+
+# Type alias for LLM callback function
+LLMCallback = Callable[[List[Dict[str, str]]], str]
+
+
+class LiteLLMCallback:
+    """Built-in callback for LiteLLM integration."""
+
+    def __init__(self, model: str = "gpt-3.5-turbo"):
+        """Initialize LiteLLM callback.
+
+        Args:
+            model: LLM model name (default: gpt-3.5-turbo)
+        """
+        self.model = model
+        self.completion = None
+        self._initialize()
+
+    def _initialize(self):
+        """Lazy initialize LiteLLM to avoid import errors."""
+        try:
+            from litellm import completion
+
+            self.completion = completion
+        except ImportError:
+            raise ImportError("LiteLLM not installed. Install with: pip install litellm")
+
+    def __call__(self, messages: List[Dict[str, str]]) -> str:
+        """Call LiteLLM API.
+
+        Args:
+            messages: List of message dicts with 'role' and 'content'
+
+        Returns:
+            LLM response as string
+        """
+        if self.completion is None:
+            self._initialize()
+
+        response = self.completion(model=self.model, messages=messages)
+        return response.choices[0].message.content
+
+
+class OpenAICallback:
+    """Built-in callback for OpenAI integration."""
+
+    def __init__(self, model: str = "gpt-3.5-turbo", api_key: Optional[str] = None):
+        """Initialize OpenAI callback.
+
+        Args:
+            model: OpenAI model name (default: gpt-3.5-turbo)
+            api_key: OpenAI API key (if not set, uses OPENAI_API_KEY env var)
+        """
+        self.model = model
+        self.api_key = api_key
+        self.client = None
+        self._initialize()
+
+    def _initialize(self):
+        """Lazy initialize OpenAI client."""
+        try:
+            from openai import OpenAI
+
+            self.client = OpenAI(api_key=self.api_key) if self.api_key else OpenAI()
+        except ImportError:
+            raise ImportError("OpenAI not installed. Install with: pip install openai")
+
+    def __call__(self, messages: List[Dict[str, str]]) -> str:
+        """Call OpenAI API.
+
+        Args:
+            messages: List of message dicts with 'role' and 'content'
+
+        Returns:
+            LLM response as string
+        """
+        if self.client is None:
+            self._initialize()
+
+        response = self.client.chat.completions.create(model=self.model, messages=messages)
+        return response.choices[0].message.content
+
+
+class AnthropicCallback:
+    """Built-in callback for Anthropic Claude integration."""
+
+    def __init__(self, model: str = "claude-3-sonnet-20240229", api_key: Optional[str] = None):
+        """Initialize Anthropic callback.
+
+        Args:
+            model: Claude model name (default: claude-3-sonnet-20240229)
+            api_key: Anthropic API key (if not set, uses ANTHROPIC_API_KEY env var)
+        """
+        self.model = model
+        self.api_key = api_key
+        self.client = None
+        self._initialize()
+
+    def _initialize(self):
+        """Lazy initialize Anthropic client."""
+        try:
+            from anthropic import Anthropic
+
+            self.client = Anthropic(api_key=self.api_key) if self.api_key else Anthropic()
+        except ImportError:
+            raise ImportError("Anthropic not installed. Install with: pip install anthropic")
+
+    def __call__(self, messages: List[Dict[str, str]]) -> str:
+        """Call Anthropic API.
+
+        Args:
+            messages: List of message dicts with 'role' and 'content'
+
+        Returns:
+            LLM response as string
+        """
+        if self.client is None:
+            self._initialize()
+
+        response = self.client.messages.create(model=self.model, messages=messages, max_tokens=4096)
+        return response.content[0].text
+
+
+class MdMemory:
+    """Markdown-first, LLM-driven memory framework."""
+
+    SYSTEM_PROMPT = """You are the MdMemory Librarian. Your goal is to maintain a clean, hierarchical Markdown Knowledge Tree. When storing data, choose a logical path. When optimizing, group related files into sub-directories to keep the root index under 50 lines. Always return JSON containing: `action`, `recommended_path`, `frontmatter`, and `optimize_suggested`."""
+
+    def __init__(
+        self,
+        llm_callback: Optional[LLMCallback] = None,
+        storage_path: str = "./MdMemory",
+        optimize_threshold: int = 20,
+    ):
+        """Initialize MdMemory.
+
+        Args:
+            llm_callback: Callback function for LLM calls.
+                         Signature: (messages: List[Dict[str, str]]) -> str
+                         Messages format: [{"role": "user", "content": "prompt"}]
+                         Should return LLM response as a string (preferably JSON)
+                         If not provided, uses LiteLLMCallback with gpt-3.5-turbo
+            storage_path: Root path for storage (default: ./MdMemory)
+            optimize_threshold: Line count threshold for triggering optimize
+        """
+        # Use LiteLLMCallback as default if not provided
+        if llm_callback is None:
+            llm_callback = LiteLLMCallback()
+
+        self.llm_callback = llm_callback
+        self.storage_path = Path(storage_path)
+        self.optimize_threshold = optimize_threshold
+
+        # Initialize storage structure
+        ensure_dir_exists(self.storage_path)
+
+        # Load or create registry
+        self.registry_path = self.storage_path / ".registry.json"
+        # Ensure registry file exists
+        if not self.registry_path.exists():
+            save_json_safe(self.registry_path, {})
+        self.registry = PathRegistry(self.registry_path)
+
+        # Initialize root index
+        self.root_index_path = self.storage_path / "index.md"
+        if not self.root_index_path.exists():
+            self._init_root_index()
+
+    def _init_root_index(self) -> None:
+        """Initialize the root index.md."""
+        metadata = {
+            "title": "MdMemory Root Index",
+            "created_at": datetime.now().isoformat(),
+        }
+        content = "# Knowledge Tree\n\nWelcome to MdMemory. This is the root index.\n\n"
+        write_markdown_file(self.root_index_path, metadata, content)
+
+    def _get_llm_decision(self, action: str, context: Dict[str, str]) -> Optional[LLMResponse]:
+        """Call LLM for organizational decisions.
+
+        Args:
+            action: The action type ("store", "optimize", etc.)
+            context: Context dict for the LLM
+
+        Returns:
+            LLMResponse or None if error
+        """
+        try:
+            # Prepare the prompt
+            prompt = f"""
+{self.SYSTEM_PROMPT}
+
+Action: {action}
+Context: {json.dumps(context, indent=2)}
+
+Please respond with a JSON object containing:
+- action: The action being performed
+- recommended_path: The logical folder path (e.g., "coding/python")
+- frontmatter: Object with topic, summary, tags
+- optimize_suggested: Boolean indicating if optimization is needed
+"""
+
+            # Call LLM callback with messages
+            messages = [{"role": "user", "content": prompt}]
+            response_text = self.llm_callback(messages)
+
+            # Try to extract JSON from response
+            try:
+                json_match = re.search(r"\{.*\}", response_text, re.DOTALL)
+                if json_match:
+                    response_json = json.loads(json_match.group())
+                    return LLMResponse(**response_json)
+            except (json.JSONDecodeError, ValueError):
+                pass
+
+            return None
+        except Exception as e:
+            print(f"LLM call error: {e}")
+            return None
+
+    def store(self, usr_id: str, query: str, topic: Optional[str] = None) -> Optional[str]:
+        """Store a memory item.
+
+        Args:
+            usr_id: User ID
+            query: The content to store
+            topic: Topic identifier (optional - LLM will generate if not provided)
+
+        Returns:
+            The topic ID that was used/generated, or None if failed
+        """
+        # Prepare context for LLM
+        context = {"query": query, "user_id": usr_id}
+        if topic:
+            context["topic"] = topic
+        else:
+            context["topic"] = (
+                "NOT_PROVIDED - Please generate a concise topic ID from the query content"
+            )
+
+        # Call LLM to determine folder path and frontmatter
+        llm_response = self._get_llm_decision("store", context)
+
+        if not llm_response:
+            # Fallback: use provided topic or generate simple one from query
+            if topic:
+                used_topic = topic
+                recommended_path = "uncategorized"
+            else:
+                # Generate simple topic from first 30 chars of query
+                used_topic = query[:30].replace(" ", "_").replace("\n", "_").lower()
+                recommended_path = "uncategorized"
+
+            frontmatter = FrontMatter(
+                topic=used_topic,
+                summary=query[:100],
+                tags=[],
+                created_at=datetime.now().isoformat(),
+            )
+        else:
+            # Use LLM-determined topic (from frontmatter or generated)
+            used_topic = llm_response.frontmatter.topic
+            recommended_path = llm_response.recommended_path
+            frontmatter = llm_response.frontmatter
+
+        # Set timestamps
+        frontmatter.created_at = datetime.now().isoformat()
+        frontmatter.updated_at = datetime.now().isoformat()
+
+        # Create file path
+        folder_path = self.storage_path / recommended_path
+        ensure_dir_exists(folder_path)
+        file_path = folder_path / f"{used_topic}.md"
+
+        # Write the file
+        metadata = frontmatter.model_dump()
+        success = write_markdown_file(file_path, metadata, query)
+
+        if success:
+            # Update registry
+            relative_path = str(file_path.relative_to(self.storage_path))
+            self.registry.put(used_topic, relative_path)
+
+            # Update parent index
+            self._update_index_for_path(recommended_path, used_topic, frontmatter.summary)
+
+            # Check if optimization is needed
+            if llm_response and llm_response.optimize_suggested:
+                self.optimize(usr_id)
+
+            return used_topic
+
+        return None
+
+    def _update_index_for_path(self, folder_path: str, topic: str, summary: str) -> None:
+        """Update the appropriate index file for a folder.
+
+        Args:
+            folder_path: Relative folder path (e.g., "coding/python")
+            topic: Topic name
+            summary: One-line summary
+        """
+        parts = folder_path.split("/")
+
+        # Update root index if storing directly
+        if len(parts) == 1:
+            self._append_to_index(self.root_index_path, topic, summary)
+        else:
+            # Create/update sub-index
+            sub_index_path = self.storage_path / folder_path / "index.md"
+            ensure_dir_exists(sub_index_path.parent)
+
+            if not sub_index_path.exists():
+                metadata = {"title": f"Index: {folder_path.replace('/', ' > ')}"}
+                content = f"# {folder_path.replace('/', ' > ')}\n\n"
+                write_markdown_file(sub_index_path, metadata, content)
+
+            self._append_to_index(sub_index_path, topic, summary)
+
+    def _append_to_index(self, index_path: Path, topic: str, summary: str) -> None:
+        """Append an entry to an index file.
+
+        Args:
+            index_path: Path to the index file
+            topic: Topic name
+            summary: One-line summary
+        """
+        metadata, content = read_markdown_file(index_path)
+        topic_title = parse_topic_title(topic)
+        new_entry = f"- **{topic_title}**: {summary}\n"
+
+        if new_entry not in content:
+            content += new_entry
+            write_markdown_file(index_path, metadata, content)
+
+    def retrieve(self, usr_id: str) -> str:
+        """Retrieve the root index (knowledge tree overview).
+
+        Args:
+            usr_id: User ID
+
+        Returns:
+            Content of root index.md
+        """
+        metadata, content = read_markdown_file(self.root_index_path)
+        return content
+
+    def get(self, usr_id: str, topic: str) -> Optional[str]:
+        """Get full content of a specific topic.
+
+        Args:
+            usr_id: User ID
+            topic: Topic identifier
+
+        Returns:
+            Full content (frontmatter + markdown) or None if not found
+        """
+        relative_path = self.registry.get(topic)
+        if not relative_path:
+            return None
+
+        file_path = self.storage_path / relative_path
+        if not file_path.exists():
+            return None
+
+        metadata, content = read_markdown_file(file_path)
+
+        # Return frontmatter + content
+        import frontmatter as fm
+
+        post = fm.Post(content, **metadata)
+        return fm.dumps(post)
+
+    def delete(self, usr_id: str, topic: str) -> bool:
+        """Delete a topic from memory.
+
+        Args:
+            usr_id: User ID
+            topic: Topic identifier
+
+        Returns:
+            True if successful
+        """
+        relative_path = self.registry.get(topic)
+        if not relative_path:
+            return False
+
+        file_path = self.storage_path / relative_path
+        try:
+            if file_path.exists():
+                file_path.unlink()
+            self.registry.delete(topic)
+
+            # Update index files
+            self._prune_from_indexes(topic, file_path)
+
+            return True
+        except Exception as e:
+            print(f"Error deleting {topic}: {e}")
+            return False
+
+    def _prune_from_indexes(self, topic: str, file_path: Path) -> None:
+        """Remove topic from all relevant index files.
+
+        Args:
+            topic: Topic identifier
+            file_path: File path (to find parent folders)
+        """
+        topic_title = parse_topic_title(topic)
+
+        # Update parent folder index if exists
+        parent_index = file_path.parent / "index.md"
+        if parent_index.exists():
+            metadata, content = read_markdown_file(parent_index)
+            content = content.replace(f"- **{topic_title}**:", "")
+            if content.strip():
+                write_markdown_file(parent_index, metadata, content)
+
+    def optimize(self, usr_id: str) -> None:
+        """Optimize the knowledge tree structure.
+
+        Args:
+            usr_id: User ID
+        """
+        # Analyze root index
+        metadata, content = read_markdown_file(self.root_index_path)
+        lines = content.strip().split("\n")
+
+        if len(lines) > self.optimize_threshold:
+            # Get list of folders and their files
+            folders = {}
+            for item in self.storage_path.iterdir():
+                if item.is_dir() and not item.name.startswith("."):
+                    md_files = list(item.glob("*.md"))
+                    if md_files:
+                        folders[item.name] = md_files
+
+            # Call LLM to suggest optimization
+            context = {
+                "current_structure": list(folders.keys()),
+                "total_root_lines": len(lines),
+                "threshold": self.optimize_threshold,
+            }
+
+            llm_response = self._get_llm_decision("optimize", context)
+
+            if llm_response:
+                # LLM response should contain recommendations for reorganization
+                self._apply_optimization(llm_response)
+
+    def _apply_optimization(self, llm_response: LLMResponse) -> None:
+        """Apply optimization recommendations from LLM.
+
+        Args:
+            llm_response: LLM response with optimization suggestions
+        """
+        # This is a placeholder for applying optimization
+        # In production, the LLM response would contain specific reorganization steps
+        pass
+
+    def list_topics(self) -> Dict[str, str]:
+        """List all topics in the registry.
+
+        Returns:
+            Dictionary of topic ID -> path mappings
+        """
+        return self.registry.list_all()

mdmemory/models.py

@@ -0,0 +1,26 @@
+"""Data models for MdMemory."""
+
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+
+class FrontMatter(BaseModel):
+    """Frontmatter metadata for Markdown files."""
+
+    topic: str
+    summary: str
+    tags: List[str] = Field(default_factory=list)
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+    custom: Dict[str, Any] = Field(default_factory=dict)
+
+
+class LLMResponse(BaseModel):
+    """Expected response from LLM for organizational decisions."""
+
+    action: str  # "store", "optimize", etc.
+    recommended_path: str
+    frontmatter: FrontMatter
+    optimize_suggested: bool = False
+    reason: Optional[str] = None
+    generated_topic: Optional[str] = None  # Topic generated by LLM if not provided by user

mdmemory/registry.py

@@ -0,0 +1,85 @@
+"""Registry management for MdMemory."""
+
+import json
+from pathlib import Path
+from typing import Optional
+from .utils import load_json_safe, save_json_safe
+
+
+class PathRegistry:
+    """Manages the global path map (.registry.json)."""
+
+    def __init__(self, registry_path: Path):
+        """Initialize registry.
+
+        Args:
+            registry_path: Path to .registry.json file
+        """
+        self.registry_path = registry_path
+        self._cache = load_json_safe(registry_path)
+
+    def get(self, topic_id: str) -> Optional[str]:
+        """Get physical path for a topic ID.
+
+        Args:
+            topic_id: The topic identifier
+
+        Returns:
+            Relative path to the file, or None if not found
+        """
+        return self._cache.get(topic_id)
+
+    def put(self, topic_id: str, path: str) -> bool:
+        """Register a topic ID to a physical path.
+
+        Args:
+            topic_id: The topic identifier
+            path: Relative path to the file
+
+        Returns:
+            True if successful
+        """
+        self._cache[topic_id] = path
+        return save_json_safe(self.registry_path, self._cache)
+
+    def delete(self, topic_id: str) -> bool:
+        """Remove a topic from the registry.
+
+        Args:
+            topic_id: The topic identifier
+
+        Returns:
+            True if successful
+        """
+        if topic_id in self._cache:
+            del self._cache[topic_id]
+            return save_json_safe(self.registry_path, self._cache)
+        return True
+
+    def update_path(self, old_path: str, new_path: str) -> bool:
+        """Update all references from old_path to new_path (for optimize).
+
+        Args:
+            old_path: The old relative path
+            new_path: The new relative path
+
+        Returns:
+            True if successful
+        """
+        updated = False
+        for topic_id, path in self._cache.items():
+            if path == old_path:
+                self._cache[topic_id] = new_path
+                updated = True
+        if updated:
+            return save_json_safe(self.registry_path, self._cache)
+        return True
+
+    def list_all(self) -> dict:
+        """Return all mappings."""
+        return self._cache.copy()
+
+    def reload(self) -> bool:
+        """Reload registry from disk."""
+        self._cache = load_json_safe(self.registry_path)
+        return True

mdmemory/utils.py

@@ -0,0 +1,84 @@
+"""Utility functions for MdMemory."""
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict
+import frontmatter as fm
+
+
+def load_json_safe(filepath: Path) -> Dict[str, Any]:
+    """Load JSON file with error handling."""
+    if not filepath.exists():
+        return {}
+    try:
+        with open(filepath, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, IOError) as e:
+        print(f"Error loading {filepath}: {e}")
+        return {}
+
+
+def save_json_safe(filepath: Path, data: Dict[str, Any]) -> bool:
+    """Save JSON file with error handling."""
+    try:
+        filepath.parent.mkdir(parents=True, exist_ok=True)
+        with open(filepath, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+        return True
+    except IOError as e:
+        print(f"Error saving {filepath}: {e}")
+        return False
+
+
+def read_markdown_file(filepath: Path) -> tuple[dict, str]:
+    """Read Markdown file with frontmatter.
+
+    Returns (frontmatter_dict, content)
+    """
+    if not filepath.exists():
+        return {}, ""
+    try:
+        with open(filepath, "r", encoding="utf-8") as f:
+            post = fm.load(f)
+        return post.metadata, post.content
+    except Exception as e:
+        print(f"Error reading {filepath}: {e}")
+        return {}, ""
+
+
+def write_markdown_file(filepath: Path, metadata: dict, content: str) -> bool:
+    """Write Markdown file with frontmatter."""
+    try:
+        filepath.parent.mkdir(parents=True, exist_ok=True)
+        post = fm.Post(content, **metadata)
+        with open(filepath, "w", encoding="utf-8") as f:
+            f.write(fm.dumps(post))
+        return True
+    except Exception as e:
+        print(f"Error writing {filepath}: {e}")
+        return False
+
+
+def ensure_dir_exists(dirpath: Path) -> bool:
+    """Ensure directory exists."""
+    try:
+        dirpath.mkdir(parents=True, exist_ok=True)
+        return True
+    except Exception as e:
+        print(f"Error creating directory {dirpath}: {e}")
+        return False
+
+
+def parse_topic_title(filename: str) -> str:
+    """Convert filename (e.g., 'python.md') to title (e.g., 'Python')."""
+    return filename.replace(".md", "").replace("_", " ").title()
+
+
+def line_count(filepath: Path) -> int:
+    """Count lines in a file."""
+    try:
+        with open(filepath, "r", encoding="utf-8") as f:
+            return sum(1 for _ in f)
+    except Exception:
+        return 0

mdmemory-0.1.2.dist-info/METADATA

@@ -0,0 +1,270 @@
+Metadata-Version: 2.4
+Name: mdmemory
+Version: 0.1.2
+Summary: Markdown-first, LLM-driven memory framework organized into a hierarchical Knowledge Tree
+Project-URL: Homepage, https://github.com/pvkarthikk/MdMemory
+Project-URL: Repository, https://github.com/pvkarthikk/MdMemory.git
+Project-URL: Documentation, https://github.com/pvkarthikk/MdMemory/blob/main/README.md
+Project-URL: Bug Tracker, https://github.com/pvkarthikk/MdMemory/issues
+Project-URL: Changelog, https://github.com/pvkarthikk/MdMemory/blob/main/CHANGELOG.md
+Author-email: Contributors <contributor@example.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,hierarchical,knowledge-management,knowledge-tree,llm,markdown,memory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.9
+Requires-Dist: aiofiles>=23.0.0
+Requires-Dist: litellm>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-frontmatter>=1.0.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MdMemory
+
+A Markdown-first, LLM-driven memory framework that organizes agent knowledge into a hierarchical **Knowledge Tree**.
+
+## Features
+
+- **Human-Readable**: Data stored as standard `.md` files on the filesystem
+- **LLM-Organized**: Uses LLM to automatically determine folder structure and organization
+- **Context-Aware**: Hybrid indexing strategy keeps the root index compact
+- **Efficient Navigation**: Central `index.md` and `.registry.json` Path Map for direct access
+
+## Installation
+
+```bash
+pip install mdmemory
+```
+
+Or with development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from mdmemory import MdMemory
+
+# Define your LLM callback function
+# It receives messages and should return LLM response as a string
+def llm_callback(messages: list) -> str:
+    """
+    LLM callback function that handles LLM provider communication.
+    
+    You can use any LLM provider: OpenAI, Claude, Gemini, Ollama, etc.
+    """
+    # Example with LiteLLM (supports all major providers)
+    from litellm import completion
+    response = completion(model="gpt-3.5-turbo", messages=messages)
+    return response.choices[0].message.content
+    
+    # Or use OpenAI directly
+    # from openai import OpenAI
+    # client = OpenAI()
+    # response = client.chat.completions.create(model="gpt-3.5-turbo", messages=messages)
+    # return response.choices[0].message.content
+
+# Initialize MdMemory with the callback
+memory = MdMemory(
+    llm_callback,
+    storage_path="./knowledge_base",
+    optimize_threshold=20
+)
+
+# Store a memory WITH explicit topic
+topic = memory.store(
+    usr_id="user123",
+    query="Decorators are functions that modify other functions...",
+    topic="python_decorators"  # Optional - provide explicit topic
+)
+
+# Store a memory WITHOUT topic - LLM generates one automatically
+generated_topic = memory.store(
+    usr_id="user123",
+    query="List comprehensions are concise ways to create lists in Python..."
+    # topic parameter omitted - LLM will infer topic from content
+)
+print(f"Generated topic: {generated_topic}")
+
+# Retrieve the knowledge tree
+index = memory.retrieve("user123")
+print(index)
+
+# Get a specific topic
+content = memory.get("user123", "python_decorators")
+print(content)
+
+# Delete a topic
+memory.delete("user123", "python_decorators")
+
+# List all topics
+topics = memory.list_topics()
+print(topics)
+
+# Optimize structure
+memory.optimize("user123")
+```
+
+## Directory Structure
+
+```
+storage_root/
+├── .registry.json           # Global Path Map (Topic ID -> Physical Path)
+├── index.md                 # Root Knowledge Tree
+└── /categories/             # Auto-created folders
+    ├── coding/
+    │   ├── index.md         # Sub-index
+    │   └── python.md        # Knowledge file
+    └── finance/
+        └── taxes.md
+```
+
+## Architecture
+
+### Core Components
+
+- **MdMemory**: Main class providing the public API
+- **PathRegistry**: Manages `.registry.json` for topic ID -> file path mapping
+- **FrontMatter**: Metadata attached to each knowledge file
+- **LLMResponse**: Structured response from LLM decisions
+
+### Key Concepts
+
+#### Hybrid Indexing
+
+- **Root `index.md`**: High-level overview of all knowledge
+- **Sub-folder `index.md`**: Generated when folder exceeds `optimize_threshold`
+- **Compression**: Parent index replaced with link to folder index when compressed
+
+#### LLM Integration
+
+The library queries the LLM for:
+
+1. **Path Recommendation**: Where to store new knowledge
+2. **Frontmatter Generation**: Metadata (summary, tags) for files
+3. **Optimization Suggestions**: When to reorganize structure
+
+### System Prompt
+
+```
+You are the MdMemory Librarian. Your goal is to maintain a clean, hierarchical 
+Markdown Knowledge Tree. When storing data, choose a logical path. When optimizing, 
+group related files into sub-directories to keep the root index under 50 lines.
+```
+
+## API Reference
+
+### `__init__(llm_callback, storage_path, optimize_threshold=20)`
+
+Initialize MdMemory with an LLM callback function.
+
+**Parameters:**
+- `llm_callback`: Callback function that receives messages and returns LLM response
+  - Signature: `(messages: List[Dict[str, str]]) -> str`
+  - Messages format: `[{"role": "user", "content": "prompt"}]`
+  - Should return the LLM response as a string (preferably JSON)
+- `storage_path`: Root directory path for storing markdown files
+- `optimize_threshold` (optional): Line count threshold for triggering auto-optimization (default: 20)
+
+**Example:**
+```python
+# Define a callback for your LLM provider
+def llm_callback(messages):
+    # Use any LLM provider here
+    from litellm import completion
+    response = completion(model="gpt-3.5-turbo", messages=messages)
+    return response.choices[0].message.content
+
+memory = MdMemory(llm_callback, "./knowledge_base")
+
+# Or use built-in callbacks
+from mdmemory import LiteLLMCallback, OpenAICallback, AnthropicCallback
+
+memory = MdMemory(LiteLLMCallback("gpt-3.5-turbo"), "./knowledge_base")
+memory = MdMemory(OpenAICallback("gpt-4"), "./knowledge_base")
+memory = MdMemory(AnthropicCallback("claude-3-sonnet"), "./knowledge_base")
+```
+
+### `store(usr_id, query, topic=None) -> Optional[str]`
+
+Store a new memory item.
+
+**Parameters:**
+- `usr_id`: User identifier
+- `query`: Content to store (Markdown text)
+- `topic` (optional): Topic identifier. If not provided, LLM will generate one from the query content
+
+**Returns:** The topic ID that was used or generated, or None if storage failed
+
+**Example:**
+```python
+# With explicit topic
+topic = memory.store("user1", "Content here", topic="my_topic")
+
+# With LLM-generated topic
+topic = memory.store("user1", "Content here")  # LLM generates topic from content
+```
+
+### `retrieve(usr_id) -> str`
+
+Get the root index (knowledge tree overview).
+
+### `get(usr_id, topic) -> Optional[str]`
+
+Get full content of a specific topic.
+
+### `delete(usr_id, topic) -> bool`
+
+Remove a topic from memory.
+
+### `optimize(usr_id) -> None`
+
+Reorganize knowledge tree structure.
+
+### `list_topics() -> Dict[str, str]`
+
+List all topics in the registry.
+
+## Development
+
+### Running Tests
+
+```bash
+pytest tests/
+```
+
+### Code Quality
+
+```bash
+black src/
+ruff check src/
+mypy src/
+```
+
+## License
+
+MIT
+
+## Specification
+
+See [spec.md](spec.md) for the full implementation specification.

mdmemory-0.1.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+mdmemory/__init__.py,sha256=c8V2oKaxKaavDvLexBbGlEzHkwdtYOmKi3G8eZIupI0,1663
+mdmemory/core.py,sha256=-N-yk8mVpAkoCoQSNUf9hAHLcNjSk1fkhUCB7gcdxfs,16453
+mdmemory/models.py,sha256=3YTEZIOixf4mDmJu37tLSCG2DdtzegfpLjmXGv9MQT4,775
+mdmemory/registry.py,sha256=hY5vT4Qe_aTlTGdGEIHU1Y4ExFZhXuw1cTeV8XeOLpg,2365
+mdmemory/utils.py,sha256=E_gpaOCmXkuBPgRic3UuQn3ylGt3hST9wVnpkQyaAas,2480
+mdmemory-0.1.2.dist-info/METADATA,sha256=Pp4FUm_dDPLwGRDFT2fnoqYfoXR1aRLF5-Win2dWlqo,8128
+mdmemory-0.1.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+mdmemory-0.1.2.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+mdmemory-0.1.2.dist-info/RECORD,,

mdmemory-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mdmemory-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.