RecallGraph 🧠

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

pip install recallgraph

Install with optional dependencies:

# 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

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:

recallgraph --vault ~/my-vault ingest

Force re-indexing all files:

recallgraph --vault ~/my-vault ingest --force

Remember

Quickly add a memory from the command line:

recallgraph --vault ~/my-vault remember \
    --title "Team Sync" \
    --content "Discussed Q3 goals." \
    --tags planning q3

Context Window

Generate context for a query:

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:

recallgraph --vault ~/my-vault ask --chat --provider ollama --model llama3

Or ask a single question:

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:

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:

# 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:

---
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 for details.

Development Setup

1. Clone the repository:

   git clone https://github.com/Indhar01/RecallGraph.git
   cd RecallGraph
   

2. Install in development mode:

   pip install -e ".[all,dev]"
   

3. Install pre-commit hooks:

   pre-commit install
   

4. Run tests:

   pytest
   

📚 Documentation

• Contributing Guide - How to contribute to the project
• Code of Conduct - Community guidelines
• Security Policy - Security reporting and best practices
• Changelog - Version history and changes

🔒 Security

See our Security Policy for reporting vulnerabilities.

📄 License

This project is licensed under the MIT License - see the 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
• Discussions: GitHub 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