feat(provider): add Sandra semantic graph provider#42
Open
ShabanShaame wants to merge 1 commit into
Open
Conversation
Adds a `sandra` provider that stores memories in Sandra
(github.com/everdreamsoft/sandra), a semantic graph database
exposing typed refs and entity factories via an MCP HTTP server.
Ingestion is a two-stage pipeline: an LLM extractor emits
entities + facts per session, then one `sandra_batch` call writes
them to the graph scoped by `instance_id = containerTag`.
Extractor supports both Anthropic (default `claude-haiku-4-5-20251001`)
and OpenAI (default `gpt-4o-mini`); preference order is Anthropic if
`ANTHROPIC_API_KEY` is set, otherwise OpenAI. Override either default
via `SANDRA_EXTRACTOR_MODEL`.
Retrieval is single-shot: `sandra_semantic_search` on the
`lme_fact` factory, client-filtered by `instance_id`. No
multi-turn tool-use agent — search results are static, matching
how Mem0 and Zep providers return retrieval results today.
Wiring:
- src/providers/sandra/{index,extractor,mcp-client,prompts,schema}.ts
- providers/index.ts: register `sandra` in factory map
- types/provider.ts: extend `ProviderName` union
- cli/index.ts: document the provider + flag
- utils/config.ts: add `SANDRA_URL`, `SANDRA_TOKEN`; route Sandra's
apiKey slot to `ANTHROPIC_API_KEY`
Required env (one of):
- ANTHROPIC_API_KEY — preferred path, Claude Haiku
- OPENAI_API_KEY — fallback path, gpt-4o-mini
Plus SANDRA_URL (MCP HTTP endpoint, default
http://localhost:8090/mcp) and optional SANDRA_TOKEN bearer.
Sandra is self-hostable (PHP + MySQL, docker-compose in the
Sandra repo); no managed-cloud requirement.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a
sandraprovider that stores memories in Sandra, a semantic graph database exposing typed refs and entity factories via an MCP HTTP server.Architecture
Ingestion — two-stage pipeline matching the existing filesystem/RAG providers:
sandra_batchMCP call writes everything to the graph in a single roundtrip, scoped byinstance_id = containerTag.Retrieval — single-shot
sandra_semantic_searchon thelme_factfactory, client-filtered byinstance_id. No multi-turn tool-use agent — search results are static, matching howmem0andzepproviders return retrieval results today.Cleanup —
clear()is a best-effort no-op likesupermemory's; tests use a dedicated DB (SANDRA_DB=benchmark_mb) so physical isolation comes from the database, not per-containerTagdeletion.Extractor LLM
Provider preference is checked at init time:
ANTHROPIC_API_KEYclaude-haiku-4-5-20251001OPENAI_API_KEYgpt-4o-miniOverride either default via
SANDRA_EXTRACTOR_MODEL. Anthropic wins if both keys are set.Env vars added
SANDRA_URL— MCP HTTP endpoint. Defaulthttp://localhost:8090/mcp.SANDRA_TOKEN— optional bearer for the MCP server.ANTHROPIC_API_KEYorOPENAI_API_KEYfor the extractor.SANDRA_EXTRACTOR_MODELto pin a specific extractor model.Self-hosting
Sandra ships as PHP + MySQL; the Sandra repo includes a
docker-composesetup. No managed-cloud requirement — reviewers can spin up a local instance and runmemorybench -p sandraend-to-end.Wiring
src/providers/sandra/index.tsSandraProviderclasssrc/providers/sandra/extractor.tssrc/providers/sandra/mcp-client.tssandra_batch/sandra_semantic_searchsrc/providers/sandra/prompts.tssrc/providers/sandra/schema.tssrc/providers/index.tssandrain factory mapsrc/types/provider.tsProviderNameunionsrc/cli/index.tssrc/utils/config.tsSANDRA_URL,SANDRA_TOKEN; route apiKey slot toANTHROPIC_API_KEYTest plan
docker compose upin the Sandra repo).SANDRA_URL,ANTHROPIC_API_KEY(orOPENAI_API_KEY).bun run src/cli/index.ts -p sandra --dataset longmemeval --questions 5ingests a small slice and returns answers.