recallgraph 0.0.2__tar.gz

recallgraph-0.0.2/LICENSE

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

recallgraph-0.0.2/MANIFEST.in

@@ -0,0 +1,4 @@
+include requirements.txt
+include README.md
+include LICENSE
+recursive-include mnemo *.py

recallgraph-0.0.2/PKG-INFO

@@ -0,0 +1,330 @@
+Metadata-Version: 2.4
+Name: recallgraph
+Version: 0.0.2
+Summary: A graph-based memory system for LLMs with intelligent retrieval using knowledge graphs, hybrid search, and semantic embeddings
+Author-email: RecallGraph Contributors <author@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Indhar01/RecallGraph
+Project-URL: Documentation, https://github.com/Indhar01/RecallGraph#readme
+Project-URL: Repository, https://github.com/Indhar01/RecallGraph
+Project-URL: Issues, https://github.com/Indhar01/RecallGraph/issues
+Project-URL: Changelog, https://github.com/Indhar01/RecallGraph/blob/main/CHANGELOG.md
+Keywords: llm,memory,knowledge-graph,rag,retrieval,ai,machine-learning,graph-database,semantic-search,vector-embeddings,chatgpt,claude,ollama,langchain,llamaindex,markdown,note-taking,personal-knowledge-management,pkm,second-brain
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Information Technology
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Topic :: Database
+Classifier: Topic :: Office/Business
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Requires-Dist: tiktoken>=0.5.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.39.0; extra == "anthropic"
+Provides-Extra: ollama
+Requires-Dist: ollama>=0.3.0; extra == "ollama"
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers>=2.2.0; extra == "embeddings"
+Requires-Dist: numpy>=1.24.0; extra == "embeddings"
+Provides-Extra: all
+Requires-Dist: recallgraph[anthropic,embeddings,ollama,openai]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: ruff>=0.7.0; extra == "dev"
+Requires-Dist: mypy>=1.7.0; extra == "dev"
+Requires-Dist: pre-commit>=3.5.0; extra == "dev"
+Requires-Dist: black>=23.11.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Requires-Dist: types-requests>=2.31.0; extra == "dev"
+Dynamic: license-file
+
+# RecallGraph 🧠
+
+[![PyPI version](https://img.shields.io/pypi/v/recallgraph)](https://pypi.org/project/recallgraph/)
+[![Python Version](https://img.shields.io/pypi/pyversions/recallgraph)](https://pypi.org/project/recallgraph/)
+[![License](https://img.shields.io/github/license/Indhar01/RecallGraph)](https://github.com/Indhar01/RecallGraph/blob/main/LICENSE)
+[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+
+A graph-based memory system for LLMs with intelligent retrieval. RecallGraph provides a powerful solution to the LLM memory problem by combining knowledge graphs, hybrid retrieval, and semantic search.
+
+## ✨ Features
+
+- **Graph-Based Memory**: Navigate knowledge using bidirectional wikilinks and backlinks
+- **Hybrid Retrieval**: Combines keyword matching, graph traversal, and optional vector embeddings
+- **Markdown-Native**: Human-readable markdown files with YAML frontmatter
+- **Memory Types**: Support for episodic, semantic, procedural, and fact-based memories
+- **Smart Indexing**: Efficient caching system that only re-indexes changed files
+- **CLI & Python API**: Use via command line or integrate into your Python applications
+- **Multiple LLM Providers**: Works with Ollama, Claude, and OpenAI
+- **Context Compression**: Intelligent token budgeting for optimal context windows
+- **Salience Scoring**: Memory importance ranking for better retrieval
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install recallgraph
+```
+
+Install with optional dependencies:
+
+```bash
+# For OpenAI support
+pip install recallgraph[openai]
+
+# For Anthropic Claude support
+pip install recallgraph[anthropic]
+
+# For Ollama support
+pip install recallgraph[ollama]
+
+# For embedding support
+pip install recallgraph[embeddings]
+
+# Install everything
+pip install recallgraph[all]
+```
+
+### Python Usage
+
+```python
+from recallgraph import MemoryKernel, MemoryType
+
+# Initialize the kernel attached to your vault path
+kernel = MemoryKernel("~/my-vault")
+
+# Ingest all notes in the vault
+stats = kernel.ingest()
+print(f"Indexed {stats['indexed']} memories.")
+
+# Programmatically add a new memory
+kernel.remember(
+    title="Meeting Note",
+    content="Decided to use BFS graph traversal for retrieval.",
+    memory_type=MemoryType.EPISODIC,
+    tags=["design", "retrieval"]
+)
+
+# Retrieve context for an LLM query
+context = kernel.context_window(
+    query="how does retrieval work?",
+    tags=["retrieval"],
+    depth=2,
+    top_k=8
+)
+
+print(context)
+```
+
+## 🎯 CLI Usage
+
+RecallGraph comes with a powerful CLI for managing your vault and chatting with it.
+
+### Ingest
+
+Index your markdown files into the graph database:
+
+```bash
+recallgraph --vault ~/my-vault ingest
+```
+
+Force re-indexing all files:
+
+```bash
+recallgraph --vault ~/my-vault ingest --force
+```
+
+### Remember
+
+Quickly add a memory from the command line:
+
+```bash
+recallgraph --vault ~/my-vault remember \
+    --title "Team Sync" \
+    --content "Discussed Q3 goals." \
+    --tags planning q3
+```
+
+### Context Window
+
+Generate context for a query:
+
+```bash
+recallgraph --vault ~/my-vault context \
+    --query "What did we decide about the database?" \
+    --tags architecture \
+    --depth 2 \
+    --top-k 5
+```
+
+### Ask (Interactive Chat)
+
+Start an interactive chat session with your vault context:
+
+```bash
+recallgraph --vault ~/my-vault ask --chat --provider ollama --model llama3
+```
+
+Or ask a single question:
+
+```bash
+recallgraph --vault ~/my-vault ask \
+    --query "Summarize our design decisions" \
+    --provider claude \
+    --model claude-3-5-sonnet-20240620
+```
+
+### Diagnostics
+
+Check your environment and connection to LLM providers:
+
+```bash
+recallgraph --vault ~/my-vault doctor
+```
+
+## 📖 Core Concepts
+
+### Memory Types
+
+RecallGraph supports different types of memories inspired by cognitive science:
+
+- **Episodic**: Personal experiences and events (e.g., meeting notes)
+- **Semantic**: Facts and general knowledge (e.g., documentation)
+- **Procedural**: How-to knowledge and processes (e.g., tutorials)
+- **Fact**: Discrete factual information (e.g., configuration values)
+
+### Graph Traversal
+
+The library uses BFS (Breadth-First Search) to traverse your knowledge graph:
+
+```python
+# Retrieve nodes with depth=2 (2 hops from seed nodes)
+nodes = kernel.retrieve_nodes(
+    query="graph algorithms",
+    depth=2,  # Traverse up to 2 levels deep
+    top_k=10  # Return top 10 relevant memories
+)
+```
+
+### Salience Scoring
+
+Each memory has a salience score (0.0-1.0) that represents its importance:
+
+```yaml
+---
+title: "Critical Architecture Decision"
+salience: 0.9
+memory_type: semantic
+---
+
+We decided to use PostgreSQL for better ACID guarantees...
+```
+
+## 🏗️ Project Structure
+
+```
+RecallGraph/
+├── recallgraph/        # Main package
+│   ├── core/           # Core functionality
+│   │   ├── kernel.py   # Memory kernel
+│   │   ├── graph.py    # Graph implementation
+│   │   ├── retriever.py # Hybrid retrieval
+│   │   ├── indexer.py  # File indexing
+│   │   └── parser.py   # Markdown parsing
+│   ├── adapters/       # LLM and embedding adapters
+│   │   ├── embeddings/ # Embedding providers
+│   │   ├── frameworks/ # Framework integrations
+│   │   └── llm/        # LLM providers
+│   ├── storage/        # Storage and caching
+│   └── cli.py          # CLI implementation
+├── tests/              # Test suite
+└── examples/           # Example usage
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/Indhar01/RecallGraph.git
+   cd RecallGraph
+   ```
+
+2. Install in development mode:
+   ```bash
+   pip install -e ".[all,dev]"
+   ```
+
+3. Install pre-commit hooks:
+   ```bash
+   pre-commit install
+   ```
+
+4. Run tests:
+   ```bash
+   pytest
+   ```
+
+## 📚 Documentation
+
+- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute to the project
+- **[Code of Conduct](CODE_OF_CONDUCT.md)** - Community guidelines
+- **[Security Policy](SECURITY.md)** - Security reporting and best practices
+- **[Changelog](CHANGELOG.md)** - Version history and changes
+
+## 🔒 Security
+
+See our [Security Policy](SECURITY.md) for reporting vulnerabilities.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🌟 Acknowledgments
+
+Inspired by the need for better memory management in LLM applications. Built with:
+
+- Graph-based knowledge representation
+- Hybrid retrieval strategies
+- Cognitive science principles
+
+## 📬 Contact & Support
+
+- **Issues**: [GitHub Issues](https://github.com/Indhar01/RecallGraph/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/Indhar01/RecallGraph/discussions)
+
+## 🚦 Status
+
+This project is in active development. While the core functionality is stable, the API may change in minor versions until we reach v1.0.0.
+
+---
+
+Made with ❤️ for better LLM memory management

recallgraph-0.0.2/README.md

@@ -0,0 +1,267 @@
+# RecallGraph 🧠
+
+[![PyPI version](https://img.shields.io/pypi/v/recallgraph)](https://pypi.org/project/recallgraph/)
+[![Python Version](https://img.shields.io/pypi/pyversions/recallgraph)](https://pypi.org/project/recallgraph/)
+[![License](https://img.shields.io/github/license/Indhar01/RecallGraph)](https://github.com/Indhar01/RecallGraph/blob/main/LICENSE)
+[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+
+A graph-based memory system for LLMs with intelligent retrieval. RecallGraph provides a powerful solution to the LLM memory problem by combining knowledge graphs, hybrid retrieval, and semantic search.
+
+## ✨ Features
+
+- **Graph-Based Memory**: Navigate knowledge using bidirectional wikilinks and backlinks
+- **Hybrid Retrieval**: Combines keyword matching, graph traversal, and optional vector embeddings
+- **Markdown-Native**: Human-readable markdown files with YAML frontmatter
+- **Memory Types**: Support for episodic, semantic, procedural, and fact-based memories
+- **Smart Indexing**: Efficient caching system that only re-indexes changed files
+- **CLI & Python API**: Use via command line or integrate into your Python applications
+- **Multiple LLM Providers**: Works with Ollama, Claude, and OpenAI
+- **Context Compression**: Intelligent token budgeting for optimal context windows
+- **Salience Scoring**: Memory importance ranking for better retrieval
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install recallgraph
+```
+
+Install with optional dependencies:
+
+```bash
+# For OpenAI support
+pip install recallgraph[openai]
+
+# For Anthropic Claude support
+pip install recallgraph[anthropic]
+
+# For Ollama support
+pip install recallgraph[ollama]
+
+# For embedding support
+pip install recallgraph[embeddings]
+
+# Install everything
+pip install recallgraph[all]
+```
+
+### Python Usage
+
+```python
+from recallgraph import MemoryKernel, MemoryType
+
+# Initialize the kernel attached to your vault path
+kernel = MemoryKernel("~/my-vault")
+
+# Ingest all notes in the vault
+stats = kernel.ingest()
+print(f"Indexed {stats['indexed']} memories.")
+
+# Programmatically add a new memory
+kernel.remember(
+    title="Meeting Note",
+    content="Decided to use BFS graph traversal for retrieval.",
+    memory_type=MemoryType.EPISODIC,
+    tags=["design", "retrieval"]
+)
+
+# Retrieve context for an LLM query
+context = kernel.context_window(
+    query="how does retrieval work?",
+    tags=["retrieval"],
+    depth=2,
+    top_k=8
+)
+
+print(context)
+```
+
+## 🎯 CLI Usage
+
+RecallGraph comes with a powerful CLI for managing your vault and chatting with it.
+
+### Ingest
+
+Index your markdown files into the graph database:
+
+```bash
+recallgraph --vault ~/my-vault ingest
+```
+
+Force re-indexing all files:
+
+```bash
+recallgraph --vault ~/my-vault ingest --force
+```
+
+### Remember
+
+Quickly add a memory from the command line:
+
+```bash
+recallgraph --vault ~/my-vault remember \
+    --title "Team Sync" \
+    --content "Discussed Q3 goals." \
+    --tags planning q3
+```
+
+### Context Window
+
+Generate context for a query:
+
+```bash
+recallgraph --vault ~/my-vault context \
+    --query "What did we decide about the database?" \
+    --tags architecture \
+    --depth 2 \
+    --top-k 5
+```
+
+### Ask (Interactive Chat)
+
+Start an interactive chat session with your vault context:
+
+```bash
+recallgraph --vault ~/my-vault ask --chat --provider ollama --model llama3
+```
+
+Or ask a single question:
+
+```bash
+recallgraph --vault ~/my-vault ask \
+    --query "Summarize our design decisions" \
+    --provider claude \
+    --model claude-3-5-sonnet-20240620
+```
+
+### Diagnostics
+
+Check your environment and connection to LLM providers:
+
+```bash
+recallgraph --vault ~/my-vault doctor
+```
+
+## 📖 Core Concepts
+
+### Memory Types
+
+RecallGraph supports different types of memories inspired by cognitive science:
+
+- **Episodic**: Personal experiences and events (e.g., meeting notes)
+- **Semantic**: Facts and general knowledge (e.g., documentation)
+- **Procedural**: How-to knowledge and processes (e.g., tutorials)
+- **Fact**: Discrete factual information (e.g., configuration values)
+
+### Graph Traversal
+
+The library uses BFS (Breadth-First Search) to traverse your knowledge graph:
+
+```python
+# Retrieve nodes with depth=2 (2 hops from seed nodes)
+nodes = kernel.retrieve_nodes(
+    query="graph algorithms",
+    depth=2,  # Traverse up to 2 levels deep
+    top_k=10  # Return top 10 relevant memories
+)
+```
+
+### Salience Scoring
+
+Each memory has a salience score (0.0-1.0) that represents its importance:
+
+```yaml
+---
+title: "Critical Architecture Decision"
+salience: 0.9
+memory_type: semantic
+---
+
+We decided to use PostgreSQL for better ACID guarantees...
+```
+
+## 🏗️ Project Structure
+
+```
+RecallGraph/
+├── recallgraph/        # Main package
+│   ├── core/           # Core functionality
+│   │   ├── kernel.py   # Memory kernel
+│   │   ├── graph.py    # Graph implementation
+│   │   ├── retriever.py # Hybrid retrieval
+│   │   ├── indexer.py  # File indexing
+│   │   └── parser.py   # Markdown parsing
+│   ├── adapters/       # LLM and embedding adapters
+│   │   ├── embeddings/ # Embedding providers
+│   │   ├── frameworks/ # Framework integrations
+│   │   └── llm/        # LLM providers
+│   ├── storage/        # Storage and caching
+│   └── cli.py          # CLI implementation
+├── tests/              # Test suite
+└── examples/           # Example usage
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/Indhar01/RecallGraph.git
+   cd RecallGraph
+   ```
+
+2. Install in development mode:
+   ```bash
+   pip install -e ".[all,dev]"
+   ```
+
+3. Install pre-commit hooks:
+   ```bash
+   pre-commit install
+   ```
+
+4. Run tests:
+   ```bash
+   pytest
+   ```
+
+## 📚 Documentation
+
+- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute to the project
+- **[Code of Conduct](CODE_OF_CONDUCT.md)** - Community guidelines
+- **[Security Policy](SECURITY.md)** - Security reporting and best practices
+- **[Changelog](CHANGELOG.md)** - Version history and changes
+
+## 🔒 Security
+
+See our [Security Policy](SECURITY.md) for reporting vulnerabilities.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🌟 Acknowledgments
+
+Inspired by the need for better memory management in LLM applications. Built with:
+
+- Graph-based knowledge representation
+- Hybrid retrieval strategies
+- Cognitive science principles
+
+## 📬 Contact & Support
+
+- **Issues**: [GitHub Issues](https://github.com/Indhar01/RecallGraph/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/Indhar01/RecallGraph/discussions)
+
+## 🚦 Status
+
+This project is in active development. While the core functionality is stable, the API may change in minor versions until we reach v1.0.0.
+
+---
+
+Made with ❤️ for better LLM memory management