solohq-memory 0.1.0__tar.gz

solohq_memory-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+*.swp
+*.swo
+*~
+.env
+*.db
+.pytest_cache/
+.venv/

solohq_memory-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 SoloHQ
+
+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.

solohq_memory-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: solohq-memory
+Version: 0.1.0
+Summary: Context memory system for AI agents — persistent context graph with episodes, artifacts, relationships, and staleness tracking
+Project-URL: Repository, https://github.com/whaleventure13/solohq-agent
+Author: SoloHQ
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: apsw>=3.46
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-ulid>=3.0
+Requires-Dist: sqlite-vec>=0.1.6
+Provides-Extra: all
+Requires-Dist: anthropic>=0.40; extra == 'all'
+Requires-Dist: google-genai>=1.0; extra == 'all'
+Requires-Dist: openai>=1.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: google
+Requires-Dist: google-genai>=1.0; extra == 'google'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# solohq-memory
+
+Core context memory library for AI agents. Persistent context graph with episodes, artifacts, relationships, and staleness tracking.
+
+## Installation
+
+```bash
+pip install solohq-memory
+
+# With LLM provider extras
+pip install solohq-memory[anthropic]
+pip install solohq-memory[openai]
+pip install solohq-memory[google]
+pip install solohq-memory[all]
+```
+
+## Quick Start
+
+```python
+from solohq_memory import (
+    ContextMemoryManager,
+    SqliteVecStorage,
+)
+
+# You need to provide LLM and embedding implementations
+# that satisfy LLMProvider and EmbeddingProvider protocols
+
+storage = SqliteVecStorage("memory.db", dimensions=1536)
+manager = ContextMemoryManager(
+    storage=storage,
+    llm=your_llm_provider,
+    embedder=your_embedding_provider,
+)
+
+# Classify a message to find or create a context
+result = await manager.classify("Tell me about Python decorators")
+context = result.context
+
+# Record an episode
+await manager.record_episode(
+    context_id=context.id,
+    user_message="Tell me about Python decorators",
+    assistant_message="Decorators are a way to modify functions...",
+)
+
+# Search across all contexts
+results = await manager.search("decorators", limit=5)
+```
+
+## Key Components
+
+- **ContextMemoryManager** — main orchestrator for context operations
+- **SqliteVecStorage** — SQLite + sqlite-vec storage with vector search
+- **LLMClassifier** — 3-tier context routing: stable shortcut, embedding similarity, LLM fallback
+- **ArtifactManager** — versioned content objects with rollback support
+- **EpisodeRecorder** — conversation recording
+- **BoundaryDetector** — topic shift detection (heuristics + LLM)
+- **FileIndexer** — file indexing (on-disk references) and upload (full content)
+
+## Interfaces
+
+All providers are protocol-based and pluggable:
+
+- `StorageProvider` — CRUD + vector search
+- `LLMProvider` — `complete()` and `complete_json()`
+- `EmbeddingProvider` — `embed()`, `embed_batch()`, `dimensions`
+- `BlockStorageProvider` — session block persistence
+
+## License
+
+MIT

solohq_memory-0.1.0/README.md

@@ -0,0 +1,71 @@
+# solohq-memory
+
+Core context memory library for AI agents. Persistent context graph with episodes, artifacts, relationships, and staleness tracking.
+
+## Installation
+
+```bash
+pip install solohq-memory
+
+# With LLM provider extras
+pip install solohq-memory[anthropic]
+pip install solohq-memory[openai]
+pip install solohq-memory[google]
+pip install solohq-memory[all]
+```
+
+## Quick Start
+
+```python
+from solohq_memory import (
+    ContextMemoryManager,
+    SqliteVecStorage,
+)
+
+# You need to provide LLM and embedding implementations
+# that satisfy LLMProvider and EmbeddingProvider protocols
+
+storage = SqliteVecStorage("memory.db", dimensions=1536)
+manager = ContextMemoryManager(
+    storage=storage,
+    llm=your_llm_provider,
+    embedder=your_embedding_provider,
+)
+
+# Classify a message to find or create a context
+result = await manager.classify("Tell me about Python decorators")
+context = result.context
+
+# Record an episode
+await manager.record_episode(
+    context_id=context.id,
+    user_message="Tell me about Python decorators",
+    assistant_message="Decorators are a way to modify functions...",
+)
+
+# Search across all contexts
+results = await manager.search("decorators", limit=5)
+```
+
+## Key Components
+
+- **ContextMemoryManager** — main orchestrator for context operations
+- **SqliteVecStorage** — SQLite + sqlite-vec storage with vector search
+- **LLMClassifier** — 3-tier context routing: stable shortcut, embedding similarity, LLM fallback
+- **ArtifactManager** — versioned content objects with rollback support
+- **EpisodeRecorder** — conversation recording
+- **BoundaryDetector** — topic shift detection (heuristics + LLM)
+- **FileIndexer** — file indexing (on-disk references) and upload (full content)
+
+## Interfaces
+
+All providers are protocol-based and pluggable:
+
+- `StorageProvider` — CRUD + vector search
+- `LLMProvider` — `complete()` and `complete_json()`
+- `EmbeddingProvider` — `embed()`, `embed_batch()`, `dimensions`
+- `BlockStorageProvider` — session block persistence
+
+## License
+
+MIT

solohq_memory-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "solohq-memory"
+version = "0.1.0"
+description = "Context memory system for AI agents — persistent context graph with episodes, artifacts, relationships, and staleness tracking"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    {name = "SoloHQ"},
+]
+readme = "README.md"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.0",
+    "sqlite-vec>=0.1.6",
+    "apsw>=3.46",
+    "python-ulid>=3.0",
+]
+
+[project.optional-dependencies]
+openai = ["openai>=1.0"]
+anthropic = ["anthropic>=0.40"]
+google = ["google-genai>=1.0"]
+all = ["solohq-memory[openai,anthropic,google]"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.24"]
+
+[project.urls]
+Repository = "https://github.com/whaleventure13/solohq-agent"

solohq_memory-0.1.0/src/solohq_memory/__init__.py

@@ -0,0 +1,90 @@
+from .indexing import FileIndexer
+from .interfaces import BlockStorageProvider, EmbeddingProvider, LLMProvider, StorageProvider
+from .memory.artifact_manager import ArtifactManager, CascadeResult, VersionDiff
+from .memory.block_contradiction import BlockConflict, BlockConflictResult, BlockContradictionDetector
+from .memory.block_summarizer import BlockSummarizer
+from .memory.boundary_detector import BoundaryDetector
+from .memory.classifier import ClassificationResult, Confidence, LLMClassifier
+from .memory.context_graph import ContextGraphManager
+from .memory.contradiction import (
+    Contradiction,
+    ContradictionDetector,
+    ContradictionResult,
+    Severity,
+)
+from .memory.episode_recorder import EpisodeRecorder
+from .memory.manager import ContextLoad, ContextMemoryManager, SearchResult
+from .memory.staleness import StalenessTracker, StalenessType
+from .models import (
+    Artifact,
+    ArtifactContext,
+    ArtifactFreshness,
+    ArtifactVersion,
+    SourceMeta,
+    Context,
+    ContextRelationship,
+    ContextState,
+    ContextStatus,
+    Episode,
+    Message,
+    RelationType,
+    Role,
+    SessionBlock,
+    SignalType,
+)
+from .storage.sqlite import SqliteVecStorage
+from .utils.cache import EmbeddingCache
+
+__all__ = [
+    # Core manager
+    "ContextMemoryManager",
+    "ContextLoad",
+    "SearchResult",
+    # Memory components
+    "ArtifactManager",
+    "BlockConflict",
+    "BlockConflictResult",
+    "BlockContradictionDetector",
+    "BlockSummarizer",
+    "BoundaryDetector",
+    "CascadeResult",
+    "ClassificationResult",
+    "Confidence",
+    "ContextGraphManager",
+    "ContradictionDetector",
+    "Contradiction",
+    "ContradictionResult",
+    "EpisodeRecorder",
+    "LLMClassifier",
+    "Severity",
+    "StalenessTracker",
+    "StalenessType",
+    "VersionDiff",
+    # Models
+    "Artifact",
+    "ArtifactContext",
+    "ArtifactFreshness",
+    "ArtifactVersion",
+    "SourceMeta",
+    "Context",
+    "ContextRelationship",
+    "ContextState",
+    "ContextStatus",
+    "Episode",
+    "Message",
+    "RelationType",
+    "Role",
+    "SessionBlock",
+    "SignalType",
+    # Interfaces
+    "BlockStorageProvider",
+    "EmbeddingProvider",
+    "LLMProvider",
+    "StorageProvider",
+    # Indexing
+    "FileIndexer",
+    # Storage
+    "SqliteVecStorage",
+    # Utils
+    "EmbeddingCache",
+]

solohq_memory-0.1.0/src/solohq_memory/indexing/__init__.py

@@ -0,0 +1,12 @@
+from .file_indexer import FileIndexer
+from .processors import BinaryProcessor, CodeProcessor, FileProcessor, TextProcessor
+from .registry import get_processor
+
+__all__ = [
+    "FileIndexer",
+    "FileProcessor",
+    "CodeProcessor",
+    "TextProcessor",
+    "BinaryProcessor",
+    "get_processor",
+]

solohq_memory-0.1.0/src/solohq_memory/indexing/file_indexer.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import mimetypes
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from solohq_memory.interfaces import EmbeddingProvider, LLMProvider, StorageProvider
+from solohq_memory.models import Artifact, ArtifactContext, ArtifactVersion
+from solohq_memory.models.artifact import SourceMeta
+
+from .registry import get_processor
+
+DEFAULT_IGNORE = {".git", "node_modules", "__pycache__", ".venv", ".env", ".tox", ".mypy_cache"}
+
+
+class FileIndexer:
+    """Core engine for indexing and uploading files as artifacts."""
+
+    def __init__(
+        self,
+        storage: StorageProvider,
+        embedder: EmbeddingProvider,
+        llm: LLMProvider,
+    ) -> None:
+        self._storage = storage
+        self._embedder = embedder
+        self._llm = llm
+
+    async def index_file(
+        self, path: str, context_id: str | None = None,
+    ) -> Artifact:
+        """Index a single file: summary + embedding + save.
+
+        Content stays on disk, read on-demand.
+        """
+        abs_path = os.path.abspath(os.path.expanduser(path))
+        if not os.path.isfile(abs_path):
+            raise FileNotFoundError(f"File not found: {abs_path}")
+
+        # Check if already indexed and unchanged
+        existing = await self._storage.find_by_source_path(abs_path)
+        if existing and existing.source_meta:
+            current_mtime = os.path.getmtime(abs_path)
+            if existing.source_meta.mtime == current_mtime:
+                return existing
+
+        # Determine processor
+        mime_type = mimetypes.guess_type(abs_path)[0] or "application/octet-stream"
+        processor = get_processor(mime_type, abs_path)
+
+        # Extract text for embedding
+        text = processor.extract_text(abs_path)
+        embedding = await self._embedder.embed(text) if text else []
+
+        # LLM summary for artifact content
+        summary = await processor.extract_summary(abs_path, self._llm)
+
+        # Build source meta
+        stat = os.stat(abs_path)
+        source_meta = SourceMeta(
+            source_path=abs_path,
+            mime_type=mime_type,
+            size_bytes=stat.st_size,
+            mtime=stat.st_mtime,
+            processor=type(processor).__name__,
+        )
+
+        filename = os.path.basename(abs_path)
+
+        contexts = []
+        if context_id:
+            contexts.append(ArtifactContext(context_id=context_id, role="primary", relevance=1.0))
+
+        if existing:
+            # Update existing artifact
+            existing.content = summary
+            existing.embedding = embedding
+            existing.source_meta = source_meta
+            existing.updated_at = datetime.now(timezone.utc)
+            await self._storage.save_artifact(existing)
+            return existing
+
+        artifact = Artifact(
+            type="indexed_file",
+            title=filename,
+            content=summary,
+            embedding=embedding,
+            source_path=abs_path,
+            source_meta=source_meta,
+            contexts=contexts,
+            current_version=1,
+            versions=[ArtifactVersion(version=1, content=summary, change_reason="indexed")],
+        )
+        await self._storage.save_artifact(artifact)
+        return artifact
+
+    async def index_directory(
+        self,
+        path: str,
+        context_id: str | None = None,
+        patterns: list[str] | None = None,
+        ignore_patterns: list[str] | None = None,
+        max_files: int = 100,
+    ) -> list[Artifact]:
+        """Recursively index files in a directory."""
+        abs_path = os.path.abspath(os.path.expanduser(path))
+        if not os.path.isdir(abs_path):
+            raise NotADirectoryError(f"Directory not found: {abs_path}")
+
+        ignore = DEFAULT_IGNORE | set(ignore_patterns or [])
+        root = Path(abs_path)
+
+        # Collect files matching patterns
+        files: list[Path] = []
+        if patterns:
+            for pattern in patterns:
+                for match in root.rglob(pattern):
+                    if match.is_file() and not _should_ignore(match, root, ignore):
+                        files.append(match)
+        else:
+            for match in root.rglob("*"):
+                if match.is_file() and not _should_ignore(match, root, ignore):
+                    files.append(match)
+
+        # Deduplicate and limit
+        seen: set[str] = set()
+        unique_files: list[Path] = []
+        for f in files:
+            resolved = str(f.resolve())
+            if resolved not in seen:
+                seen.add(resolved)
+                unique_files.append(f)
+
+        unique_files = unique_files[:max_files]
+
+        results = []
+        for file_path in unique_files:
+            artifact = await self.index_file(str(file_path), context_id)
+            results.append(artifact)
+
+        return results
+
+    async def refresh_file(self, artifact: Artifact) -> Artifact | None:
+        """Re-index if the file has changed (mtime check).
+
+        Returns updated artifact if changed, None if unchanged.
+        """
+        if not artifact.source_meta or not artifact.source_path:
+            return None
+
+        if not os.path.isfile(artifact.source_path):
+            return None
+
+        current_mtime = os.path.getmtime(artifact.source_path)
+        if artifact.source_meta.mtime == current_mtime:
+            return None
+
+        # File changed — re-index
+        mime_type = artifact.source_meta.mime_type
+        processor = get_processor(mime_type, artifact.source_path)
+
+        text = processor.extract_text(artifact.source_path)
+        embedding = await self._embedder.embed(text) if text else []
+        summary = await processor.extract_summary(artifact.source_path, self._llm)
+
+        stat = os.stat(artifact.source_path)
+        artifact.source_meta.mtime = stat.st_mtime
+        artifact.source_meta.size_bytes = stat.st_size
+        artifact.source_meta.indexed_at = datetime.now(timezone.utc)
+        artifact.content = summary
+        artifact.embedding = embedding
+        artifact.updated_at = datetime.now(timezone.utc)
+        await self._storage.save_artifact(artifact)
+        return artifact
+
+    async def read_file_content(self, artifact: Artifact, max_chars: int = 50000) -> str:
+        """Read current file content from disk."""
+        if artifact.type == "uploaded_file":
+            return artifact.content
+
+        if not artifact.source_path:
+            return "Error: No source path for this artifact."
+
+        if not os.path.isfile(artifact.source_path):
+            return f"Error: File not found: {artifact.source_path}"
+
+        mime_type = "application/octet-stream"
+        if artifact.source_meta:
+            mime_type = artifact.source_meta.mime_type
+
+        processor = get_processor(mime_type, artifact.source_path)
+        return processor.extract_text(artifact.source_path, max_chars=max_chars)
+
+    async def upload_file(
+        self, path: str, context_id: str | None = None,
+    ) -> Artifact:
+        """Upload a file — full content saved in the artifact."""
+        abs_path = os.path.abspath(os.path.expanduser(path))
+        if not os.path.isfile(abs_path):
+            raise FileNotFoundError(f"File not found: {abs_path}")
+
+        mime_type = mimetypes.guess_type(abs_path)[0] or "application/octet-stream"
+        processor = get_processor(mime_type, abs_path)
+
+        # Full text content stored in artifact
+        full_text = processor.extract_text(abs_path, max_chars=100000)
+        embedding = await self._embedder.embed(full_text) if full_text else []
+
+        stat = os.stat(abs_path)
+        source_meta = SourceMeta(
+            source_path=abs_path,
+            mime_type=mime_type,
+            size_bytes=stat.st_size,
+            mtime=stat.st_mtime,
+            processor=type(processor).__name__,
+        )
+
+        filename = os.path.basename(abs_path)
+
+        contexts = []
+        if context_id:
+            contexts.append(ArtifactContext(context_id=context_id, role="primary", relevance=1.0))
+
+        artifact = Artifact(
+            type="uploaded_file",
+            title=filename,
+            content=full_text,
+            embedding=embedding,
+            source_path=abs_path,
+            source_meta=source_meta,
+            contexts=contexts,
+            current_version=1,
+            versions=[ArtifactVersion(version=1, content=full_text, change_reason="uploaded")],
+        )
+        await self._storage.save_artifact(artifact)
+        return artifact
+
+
+def _should_ignore(path: Path, root: Path, ignore: set[str]) -> bool:
+    """Check if a file should be ignored based on directory names."""
+    rel = path.relative_to(root)
+    for part in rel.parts:
+        if part in ignore:
+            return True
+    return False