hgcachemem 0.1.0

HGCacheMem: A robust architectural approach to improve contextual coherence and retrieval speed in agentic systems.

HGCacheMem

A robust architectural approach to improve contextual coherence and retrieval speed in agentic systems.

LLM agents often encounter a significant trade-off between retrieval speed and contextual coherence. Semantic caching systems offer sub-millisecond retrieval speeds but are plagued by "context ignorance," resulting in inaccurate cache hits. Graph-based and other complex memory systems yield high contextual accuracy but come with latency drawbacks that impact real-time user experience.

HGCacheMem is a robust architecture that merges vector similarity searches with a topological Graph Validator. The Graph Validator checks potential cache hits against the user's active context within a knowledge graph prior to delivery.

Experimental tests on the RGB Noise Robustness benchmark testbed show that HGCacheMem achieves a contextual coherence accuracy of 97.7%, significantly surpassing other caching alternatives and complex memory systems, with a mean retrieval latency of 23.66 ms — proving that structural validation can be achieved within real-time interaction thresholds.

How It Works

User Query
    │
    ▼
┌──────────────┐     ┌──────────────────┐     ┌──────────────┐
│ Vector Cache  │────▶│ Graph Validator   │────▶│   Response   │
│ (Chroma)      │     │ (Neo4j path check │     │              │
│ similarity    │     │  weight > 0.6)    │     │ Cache hit OR │
│ search        │     │                   │     │ LLM fallback │
└──────────────┘     └───────────────────┘     └──────────────┘

1. A user query hits the vector cache (Chroma) via similarity search.
2. The Graph Validator runs a Cypher shortest-path query on a Neo4j knowledge graph to verify that the candidate answer is structurally connected to the user's current context anchor, with every edge weight exceeding a configurable threshold (default 0.6).
3. If the graph validation passes → return the cached answer (fast path).
4. If it fails → fall back to LLM generation grounded in graph context (safe path).

Benchmark Results

Evaluated on the RGB Noise Robustness benchmark (300 cases):

Metric	Value
Contextual Coherence Accuracy	97.7%
Trapped (cross-context hallucination)	0.0%
Mean Retrieval Latency	23.66 ms
p50 Latency	17.02 ms
p90 Latency	34.27 ms
p95 Latency	50.16 ms

Installation

pip install hgcachemem

Quick Start

from hgcachemem import GraphValidator, connect_graph, connect_cache

# Connect to your stores
graph = connect_graph(url="bolt://localhost:7687", username="neo4j", password="secret")
cache = connect_cache(persist_directory="./chroma_db")

# Create the Graph Validator
graph_validator = GraphValidator(graph=graph, weight_threshold=0.6)

# Validate a cache hit before returning it
results = cache.similarity_search("What is the budget?", k=1)
candidate_entity = results[0].metadata["linked_entity"]

if graph_validator.validate(active_entity="Project Alpha", candidate_entity=candidate_entity):
    print("Cache hit is valid for this context!")
    print(results[0].metadata["answer"])
else:
    print("Blocked — answer belongs to a different context.")

Full Pipeline Example

See examples/langchain_example.py for a complete LangChain integration with anchor resolution, vector search, Graph Validator validation, and LLM fallback.

API Reference

GraphValidator(graph, weight_threshold=0.6, max_hops=2)

The core validation class.

• graph — A LangChain Neo4jGraph instance.
• weight_threshold — Minimum edge weight required on every relationship in the path (default 0.6).
• max_hops — Maximum path length for the shortest path check (default 2).

graph_validator.validate(active_entity, candidate_entity) -> bool

Returns True if the candidate is contextually valid for the current anchor.

connect_graph(url, username, password) -> Neo4jGraph

Factory for a connected Neo4j graph instance.

connect_cache(collection_name, persist_directory, embedding_model) -> Chroma

Factory for a Chroma vector store with HuggingFace embeddings.

SessionState(user_id)

Tracks the user's current context anchor across a conversation.

• update_anchor(entity_id) — Move focus to a new entity.
• active_entity_id — The current anchor (or None).

resolve_anchor(user_query, known_entities, llm=None) -> str | None

Uses an LLM to extract the entity from a query and match it against known graph nodes.

generate_response(user_query, context, llm=None) -> str

Fallback LLM generation grounded in graph-retrieved context.

get_context_neighbors(graph, active_entity, limit=10) -> str

Retrieves neighbours of the active entity from the graph as formatted context.

get_known_entities(graph) -> list[str]

Returns all entity names present in the graph.

Requirements

• Python >= 3.10
• Neo4j >= 5.0 (running instance)
• An OpenAI API key (for anchor resolution and fallback generation)

License

MIT