memharness 0.1.0__tar.gz

memharness-0.1.0/.gitignore

@@ -0,0 +1,74 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# mypy
+.mypy_cache/
+
+# Ruff
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# SQLite databases
+*.db
+*.sqlite
+*.sqlite3
+
+# Docusaurus
+docs/node_modules/
+docs/.docusaurus/
+docs/build/
+dist/
+dist/

memharness-0.1.0/LICENSE

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

memharness-0.1.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: memharness
+Version: 0.1.0
+Summary: Framework-agnostic memory infrastructure for AI agents
+Project-URL: Homepage, https://github.com/AyushSonuu/memharness
+Project-URL: Documentation, https://ayushsonuu.github.io/memharness
+Project-URL: Repository, https://github.com/AyushSonuu/memharness
+Project-URL: Issues, https://github.com/AyushSonuu/memharness/issues
+Author-email: Ayush Sonuu <sonuayush55@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,langchain,llm,memory,rag,vector-database
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <4.0,>=3.13
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyyaml>=6.0.2
+Provides-Extra: all
+Requires-Dist: anthropic>=0.86.0; extra == 'all'
+Requires-Dist: asyncpg>=0.31.0; extra == 'all'
+Requires-Dist: langchain-core>=0.3.0; extra == 'all'
+Requires-Dist: langchain>=1.2.13; extra == 'all'
+Requires-Dist: openai>=2.29.0; extra == 'all'
+Requires-Dist: pgvector>=0.4.2; extra == 'all'
+Requires-Dist: sentence-transformers>=5.3.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.86.0; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.15.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers>=5.3.0; extra == 'embeddings'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3.0; extra == 'langchain'
+Requires-Dist: langchain>=1.2.13; extra == 'langchain'
+Provides-Extra: openai
+Requires-Dist: openai>=2.29.0; extra == 'openai'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.31.0; extra == 'postgres'
+Requires-Dist: pgvector>=0.4.2; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# memharness
+
+> Framework-agnostic memory infrastructure for AI agents
+
+[![PyPI version](https://badge.fury.io/py/memharness.svg)](https://badge.fury.io/py/memharness)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://github.com/AyushSonuu/memharness/actions/workflows/test.yml/badge.svg)](https://github.com/AyushSonuu/memharness/actions/workflows/test.yml)
+
+## Overview
+
+**memharness** is a complete memory infrastructure layer for AI agents. It provides:
+
+- **10 Memory Types**: Conversational, Knowledge Base, Entity, Workflow, Toolbox, Summary, Tool Log, Skills, File, Persona
+- **Multiple Backends**: PostgreSQL + pgvector, SQLite + sqlite-vss, In-memory
+- **Framework Agnostic**: Works with LangChain, LangGraph, CrewAI, or any custom agent
+- **Deterministic + AI Operations**: Simple ops are deterministic, complex ops use embedded agents
+- **Self-Exploration Tools**: Agents can explore and manage their own memory
+- **Fully Configurable**: All thresholds, schedules, TTLs configurable via YAML or code
+
+## Installation
+
+```bash
+# Core (SQLite backend)
+pip install memharness
+
+# With PostgreSQL support
+pip install memharness[postgres]
+
+# With embedding support
+pip install memharness[embeddings]
+
+# Everything
+pip install memharness[all]
+```
+
+## Quick Start
+
+```python
+from memharness import MemoryHarness
+
+# Initialize with SQLite (development)
+memory = MemoryHarness("sqlite:///memory.db")
+
+# Or PostgreSQL (production)
+memory = MemoryHarness("postgresql://user:pass@localhost/db")
+
+# Write conversational memory (deterministic)
+await memory.add_conversational(
+    thread_id="chat_001",
+    role="user",
+    content="How do I deploy to Kubernetes?"
+)
+
+# Write knowledge base (deterministic)
+await memory.add_knowledge(
+    content="Kubernetes deployment guide...",
+    source="k8s-docs",
+    metadata={"category": "devops"}
+)
+
+# Search knowledge base (semantic search)
+results = await memory.search_knowledge(
+    query="container orchestration",
+    k=5
+)
+
+# Get curated context for LLM
+context = await memory.assemble_context(
+    query="deploy my app",
+    thread_id="chat_001",
+    max_tokens=4000
+)
+```
+
+## Memory Types
+
+| Type | Storage | Purpose |
+|------|---------|---------|
+| **Conversational** | SQL | Chat history per thread |
+| **Knowledge Base** | Vector | Documents, facts, reference material |
+| **Entity** | Vector | People, organizations, systems, concepts |
+| **Workflow** | Vector | Reusable step-by-step patterns |
+| **Toolbox** | Vector | Tool definitions with VFS discovery |
+| **Summary** | Vector | Compressed conversations (expandable) |
+| **Tool Log** | SQL | Tool execution audit trail |
+| **Skills** | Vector | Learned agent capabilities |
+| **File** | Hybrid | Document references |
+| **Persona** | Vector | Agent identity blocks |
+
+## Embedded Agents
+
+memharness includes specialized agents for complex memory operations:
+
+```python
+from memharness import MemoryHarness
+from memharness.agents import AgentConfig
+
+memory = MemoryHarness(
+    backend="postgresql://...",
+    llm=your_llm,  # Optional: for AI-powered operations
+    agents=AgentConfig(
+        summarizer={"enabled": True, "triggers": [{"condition": "age > 7d"}]},
+        entity_extractor={"enabled": True, "on_write": True},
+        consolidator={"enabled": True, "schedule": "0 3 * * *"},
+        gc={"enabled": True, "schedule": "0 4 * * 0"},
+    )
+)
+```
+
+## Memory Tools (Self-Exploration)
+
+Agents can explore their own memory using built-in tools:
+
+```python
+# Get tools for your agent
+tools = memory.get_memory_tools()
+
+# Tools include:
+# - memory_search: Search across memory types
+# - memory_read: Read specific memory by ID
+# - memory_write: Write new memory
+# - memory_stats: Get memory statistics
+# - toolbox_tree: Explore tool VFS
+# - toolbox_grep: Search tools by pattern
+```
+
+## Configuration
+
+```yaml
+# memharness.yaml
+backend: postgresql://localhost/memharness
+
+summarization:
+  enabled: true
+  triggers:
+    - condition: "age > 7d"
+      memory_type: conversational
+  keep_originals: true
+  originals_ttl: 365d
+
+consolidation:
+  enabled: true
+  schedule: "0 3 * * *"
+  similarity_threshold: 0.9
+
+gc:
+  enabled: true
+  schedule: "0 4 * * 0"
+  archive_after: 90d
+  delete_after: 365d
+```
+
+```python
+memory = MemoryHarness.from_config("memharness.yaml")
+```
+
+## Framework Integrations
+
+### LangChain
+
+```python
+from memharness.integrations.langchain import MemharnessMemory
+
+memory = MemharnessMemory(backend="postgresql://...")
+chain = ConversationChain(llm=llm, memory=memory)
+```
+
+### LangGraph
+
+```python
+from memharness.integrations.langgraph import MemharnessCheckpointer
+
+checkpointer = MemharnessCheckpointer(backend="postgresql://...")
+graph = builder.compile(checkpointer=checkpointer)
+```
+
+## Documentation
+
+Full documentation: [https://ayushsonuu.github.io/memharness](https://ayushsonuu.github.io/memharness)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions welcome! Please read our [Contributing Guide](CONTRIBUTING.md).

memharness-0.1.0/README.md

@@ -0,0 +1,188 @@
+# memharness
+
+> Framework-agnostic memory infrastructure for AI agents
+
+[![PyPI version](https://badge.fury.io/py/memharness.svg)](https://badge.fury.io/py/memharness)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://github.com/AyushSonuu/memharness/actions/workflows/test.yml/badge.svg)](https://github.com/AyushSonuu/memharness/actions/workflows/test.yml)
+
+## Overview
+
+**memharness** is a complete memory infrastructure layer for AI agents. It provides:
+
+- **10 Memory Types**: Conversational, Knowledge Base, Entity, Workflow, Toolbox, Summary, Tool Log, Skills, File, Persona
+- **Multiple Backends**: PostgreSQL + pgvector, SQLite + sqlite-vss, In-memory
+- **Framework Agnostic**: Works with LangChain, LangGraph, CrewAI, or any custom agent
+- **Deterministic + AI Operations**: Simple ops are deterministic, complex ops use embedded agents
+- **Self-Exploration Tools**: Agents can explore and manage their own memory
+- **Fully Configurable**: All thresholds, schedules, TTLs configurable via YAML or code
+
+## Installation
+
+```bash
+# Core (SQLite backend)
+pip install memharness
+
+# With PostgreSQL support
+pip install memharness[postgres]
+
+# With embedding support
+pip install memharness[embeddings]
+
+# Everything
+pip install memharness[all]
+```
+
+## Quick Start
+
+```python
+from memharness import MemoryHarness
+
+# Initialize with SQLite (development)
+memory = MemoryHarness("sqlite:///memory.db")
+
+# Or PostgreSQL (production)
+memory = MemoryHarness("postgresql://user:pass@localhost/db")
+
+# Write conversational memory (deterministic)
+await memory.add_conversational(
+    thread_id="chat_001",
+    role="user",
+    content="How do I deploy to Kubernetes?"
+)
+
+# Write knowledge base (deterministic)
+await memory.add_knowledge(
+    content="Kubernetes deployment guide...",
+    source="k8s-docs",
+    metadata={"category": "devops"}
+)
+
+# Search knowledge base (semantic search)
+results = await memory.search_knowledge(
+    query="container orchestration",
+    k=5
+)
+
+# Get curated context for LLM
+context = await memory.assemble_context(
+    query="deploy my app",
+    thread_id="chat_001",
+    max_tokens=4000
+)
+```
+
+## Memory Types
+
+| Type | Storage | Purpose |
+|------|---------|---------|
+| **Conversational** | SQL | Chat history per thread |
+| **Knowledge Base** | Vector | Documents, facts, reference material |
+| **Entity** | Vector | People, organizations, systems, concepts |
+| **Workflow** | Vector | Reusable step-by-step patterns |
+| **Toolbox** | Vector | Tool definitions with VFS discovery |
+| **Summary** | Vector | Compressed conversations (expandable) |
+| **Tool Log** | SQL | Tool execution audit trail |
+| **Skills** | Vector | Learned agent capabilities |
+| **File** | Hybrid | Document references |
+| **Persona** | Vector | Agent identity blocks |
+
+## Embedded Agents
+
+memharness includes specialized agents for complex memory operations:
+
+```python
+from memharness import MemoryHarness
+from memharness.agents import AgentConfig
+
+memory = MemoryHarness(
+    backend="postgresql://...",
+    llm=your_llm,  # Optional: for AI-powered operations
+    agents=AgentConfig(
+        summarizer={"enabled": True, "triggers": [{"condition": "age > 7d"}]},
+        entity_extractor={"enabled": True, "on_write": True},
+        consolidator={"enabled": True, "schedule": "0 3 * * *"},
+        gc={"enabled": True, "schedule": "0 4 * * 0"},
+    )
+)
+```
+
+## Memory Tools (Self-Exploration)
+
+Agents can explore their own memory using built-in tools:
+
+```python
+# Get tools for your agent
+tools = memory.get_memory_tools()
+
+# Tools include:
+# - memory_search: Search across memory types
+# - memory_read: Read specific memory by ID
+# - memory_write: Write new memory
+# - memory_stats: Get memory statistics
+# - toolbox_tree: Explore tool VFS
+# - toolbox_grep: Search tools by pattern
+```
+
+## Configuration
+
+```yaml
+# memharness.yaml
+backend: postgresql://localhost/memharness
+
+summarization:
+  enabled: true
+  triggers:
+    - condition: "age > 7d"
+      memory_type: conversational
+  keep_originals: true
+  originals_ttl: 365d
+
+consolidation:
+  enabled: true
+  schedule: "0 3 * * *"
+  similarity_threshold: 0.9
+
+gc:
+  enabled: true
+  schedule: "0 4 * * 0"
+  archive_after: 90d
+  delete_after: 365d
+```
+
+```python
+memory = MemoryHarness.from_config("memharness.yaml")
+```
+
+## Framework Integrations
+
+### LangChain
+
+```python
+from memharness.integrations.langchain import MemharnessMemory
+
+memory = MemharnessMemory(backend="postgresql://...")
+chain = ConversationChain(llm=llm, memory=memory)
+```
+
+### LangGraph
+
+```python
+from memharness.integrations.langgraph import MemharnessCheckpointer
+
+checkpointer = MemharnessCheckpointer(backend="postgresql://...")
+graph = builder.compile(checkpointer=checkpointer)
+```
+
+## Documentation
+
+Full documentation: [https://ayushsonuu.github.io/memharness](https://ayushsonuu.github.io/memharness)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions welcome! Please read our [Contributing Guide](CONTRIBUTING.md).

memharness-0.1.0/pyproject.toml

@@ -0,0 +1,125 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "memharness"
+version = "0.1.0"
+description = "Framework-agnostic memory infrastructure for AI agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.13,<4.0"
+authors = [
+    { name = "Ayush Sonuu", email = "sonuayush55@gmail.com" }
+]
+keywords = [
+    "ai",
+    "agents",
+    "memory",
+    "llm",
+    "langchain",
+    "vector-database",
+    "rag",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "pydantic>=2.10.0",
+    "aiosqlite>=0.20.0",
+    "numpy>=2.0.0",
+    "pyyaml>=6.0.2",
+]
+
+[project.optional-dependencies]
+postgres = [
+    "asyncpg>=0.31.0",
+    "pgvector>=0.4.2",
+]
+embeddings = [
+    "sentence-transformers>=5.3.0",
+]
+openai = [
+    "openai>=2.29.0",
+]
+anthropic = [
+    "anthropic>=0.86.0",
+]
+langchain = [
+    "langchain>=1.2.13",
+    "langchain-core>=0.3.0",
+]
+all = [
+    "asyncpg>=0.31.0",
+    "pgvector>=0.4.2",
+    "sentence-transformers>=5.3.0",
+    "openai>=2.29.0",
+    "anthropic>=0.86.0",
+    "langchain>=1.2.13",
+    "langchain-core>=0.3.0",
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "pytest-cov>=6.0.0",
+    "ruff>=0.9.0",
+    "mypy>=1.15.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/AyushSonuu/memharness"
+Documentation = "https://ayushsonuu.github.io/memharness"
+Repository = "https://github.com/AyushSonuu/memharness"
+Issues = "https://github.com/AyushSonuu/memharness/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/memharness"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+addopts = "-v --cov=memharness --cov-report=term-missing"
+
+[tool.ruff]
+target-version = "py313"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+]
+ignore = [
+    "E501",   # line too long
+    "B008",   # do not perform function calls in argument defaults
+    "B017",   # do not assert blind exception
+    "UP042",  # prefer StrEnum (keep str, Enum for 3.10 compat docs)
+]
+
+[tool.mypy]
+python_version = "3.13"
+warn_return_any = true
+warn_unused_ignores = true
+disallow_untyped_defs = true
+
+[tool.black]
+line-length = 100
+target-version = ["py313"]

memharness-0.1.0/src/memharness/__init__.py

@@ -0,0 +1,39 @@
+# memharness - Framework-agnostic memory infrastructure for AI agents
+# Copyright (c) 2026 Ayush Sonuu
+# Licensed under MIT License
+
+"""
+memharness - Framework-agnostic memory infrastructure for AI agents.
+
+This package provides a complete memory layer for AI agents with:
+- 10 memory types (Conversational, KB, Entity, Workflow, Toolbox, Summary, ToolLog, Skills, File, Persona)
+- Multiple backends (PostgreSQL, SQLite, In-memory)
+- Embedded AI agents for complex operations
+- Self-exploration tools for agents
+- Full configurability
+
+Quick Start:
+    from memharness import MemoryHarness
+
+    memory = MemoryHarness("sqlite:///memory.db")
+    await memory.add_conversational(thread_id="t1", role="user", content="Hello")
+"""
+
+from memharness.config import Config, MemharnessConfig
+from memharness.core.harness import MemoryHarness
+from memharness.registry import MemoryTypeRegistry
+from memharness.types import MemoryType, MemoryUnit
+
+__version__ = "0.1.0"
+__author__ = "Ayush Sonuu"
+__license__ = "MIT"
+
+__all__ = [
+    "MemoryHarness",
+    "MemoryUnit",
+    "MemoryType",
+    "Config",
+    "MemharnessConfig",
+    "MemoryTypeRegistry",
+    "__version__",
+]