🔥 LLM Hippocampus helping your project for building and experimenting with Context Engineering applications. harness the full power of Redis for lightning-fast vector search, intelligent semantic caching, persistent LLM memory, and **smart context engineering **.

✨ What makes this special?

• 🚀 One-command setup - pip install llm-hippocampus
• ⚡ LLM support - OpenAI
• 🎯 Redis-powered - Vector search, caching, and memory management
• 🐳 Docker ready - Building...
• 🔧 Developer-first - Support to Hot load by installing llm-hippocampus

Table of Contents

• Quick Start
• Prerequisites
• Getting Started
  • Available Commands
  • Development Workflows
  • Environment Configuration
• Using Google VertexAI
• Project Structure
• Connecting to Redis Cloud
• Troubleshooting
• Contributing
• License
• Learn More

Quick Start

Get up and install in your project:

pip install llm-hippocampus
or
uv add llm-hippocampus

Welcome to LLM Hippocampus! 🎉

Prerequisites

1. Make sure you have the following tools available:
   • python 3.11+
   • uv
   • Redis Stack
2. Setup one or more of the following:
   • OpenAI API
     • You will need an API Key

Getting Started

from dotenv import load_dotenv
from llm_hippocampus import env
from llm_hippocampus.core.utils import list2np_array
from llm_hippocampus.core.redis import create_search_index, client, load_data2search_index, vector_query
from llm_hippocampus.session import Session
load_dotenv()
# Load the model
session = Session()
embeddings = session.get_embedding_model()
schema = {
    "index": {
        "name": "data_agent_chain",
        "prefix": "data_agent_chain",
    },
    "fields": [
        {"name": "query", "type": "text"},
        {"name": "scope", "type": "text"},
        {"name": "intent", "type": "text"},
        {
            "name": "query_embedding",
            "type": "vector",
            "attrs": {
                "dims": 768,
                "distance_metric": "cosine",
                "algorithm": "flat",
                "datatype": "float32"
            }
        }
    ]
}

data = [
    {
        'query': 'SAAJ91的管理费率和托管费率是多少？',
        'scope': "产品基本信息",
        'intent': '管理费率、托管费率',
        'query_embedding': list2np_array(embeddings.encode(
            "SAAJ91的管理费率和托管费率是多少？",
            precision=schema["fields"][3]["attrs"]["datatype"],
            truncate_dim=schema["fields"][3]["attrs"]["dims"])).tobytes()
    },
    {
        'query': 'SATP77在于2025年06月01日至2025年06月30日的股票持仓明细',
        'scope': "股票持仓信息",
        'intent': '股票持仓信息',
        'query_embedding': list2np_array(embeddings.encode(
            "SATP77在于2025年06月01日至2025年06月30日的股票持仓明细",
            precision=schema["fields"][3]["attrs"]["datatype"],
            truncate_dim=schema["fields"][3]["attrs"]["dims"])).tobytes()
    },
    {
        'query': '截至于2025年01月01日至2025年12月31日，001120的户均定投金额？',
        'scope': "客户定投情况",
        'intent': '客户定投情况',
        'query_embedding': list2np_array(embeddings.encode(
            "截至于2025年01月01日至2025年12月31日，001120的户均定投金额",
            precision=schema["fields"][3]["attrs"]["datatype"],
            truncate_dim=schema["fields"][3]["attrs"]["dims"])).tobytes()
    }
]

redis_client = client(env.REDIS_URL)
index = create_search_index(redis_client, schema)
keys = load_data2search_index(index, data)

query = "400001的管理费率"
args = {
    "distance_threshold": session.distance_threshold,
    "top_k": session.top_k,
    "vector_field_name": "query_embedding",
    "precision": schema["fields"][3]["attrs"]["datatype"],
    "truncate_dim": schema["fields"][3]["attrs"]["dims"],
    "return_fileds": ["query", "scope", "intent"],
}

results = vector_query(query, index, embeddings, schema, **args)

Development Workflows

• Building

Project Structure

Contributing

🤝 Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Troubleshooting

Learn More