Hashgrid DNA (local) MCP server

hashgrid

The Python client for Hashgrid DNA, a search engine that learns from feedback. You add items and search them; you score the results; DNA learns from the scores, so the next searches rank better.

DNA works on embeddings only and never sees your content. This package embeds text and images on your machine, sends DNA only the vectors, and keeps the content with you, in a local index.

<!-- mcp-name: ai.hashgrid/sdk -->

pip install 'hashgrid[local]'

[local] adds the local embedders, which run on your CPU with no account. To embed with OpenAI or Voyage instead, install plain hashgrid and use your own key.

Each grid has its own API key (hg-…). Creating a grid needs no key:

from hashgrid.dna import Grid

grid, api_key = Grid.create("mine")
print(api_key)   # shown only now: keep it, e.g. as $HASHGRID_API_KEY

A grid created this way holds up to 1024 items and queries (grid.dna.getgrid().maxnodes), and each address can create a few grids a day. Need more? Write to office@hashgrid.ai.

Add, search, score

from hashgrid.dna import Grid

grid = Grid()  # Index() and DNA(), from the environment: the key from $HASHGRID_API_KEY

grid.add_many({
    "/cities/lisbon": "Lisbon, a hilly coastal capital",
    "/cities/oslo": "Oslo, between fjords and forest",
})

query, results = grid.ask("a capital by the sea", k=2, prefix="/cities/")
results[0].content                    # "Lisbon, a hilly coastal capital"
grid.score(query, results[0], 1.0)    # a good result
grid.score(query, results[1], -0.5)   # a poor one

narrows a search to keys that start with it. Without a key, an item is keyed by a hash of its content, so adding the same content again returns the same item.

• Items have a key, a path unique in the grid. Only items are found by searches, and prefix

is good or bad. Only scores train DNA.

• Queries have no key. grid.search(query, k) gives the next k results not shown before.
• Scores run from -1 (wrong) to 1 (perfect). You can score a result, or any pair you already know

Each Result has the item's id, key, content (from the index) and your score. grid.results(query) lists a query's results so far, and grid.get and grid.delete take an item or its id. grid.delete_grid() deletes the whole grid, for good, and its content in the index. AsyncGrid does the same with await.

Images

Content is text or an Image, from a file or from bytes. Images need an embedder that takes them:

from hashgrid.dna import Grid
from hashgrid.index import Image, Index

grid = Grid(Index("fastembed:Qdrant/clip-ViT-B-32"))
grid.add(Image("photos/beach.jpg"), key="/photos/beach")
query, results = grid.ask("a sunny beach", k=5)      # text finds images
query, results = grid.ask(Image("another.jpg"))      # and so do images

The index

Index is the local half of a grid. It embeds content, and keeps it in sqlite by DNA id, so results come back with their content. Index() uses the default embedder and ~/.hashgrid/index.sqlite; $HASHGRIDEMBEDDER and $HASHGRIDINDEX change them, and so do its arguments:

Index("voyage:voyage-multimodal-3")
Index(OpenAI("text-embedding-3-small", dimensions=512), path="my-index.sqlite")
Index(path=":memory:")   # keeps nothing

Use one embedder per grid. Vectors from different models do not compare. The index records each grid's embedder and refuses another, and a grid refuses vectors whose length differs from its own.

Shortened. The full README is on GitHub.