Skip to content

feat: add Valkey support (storage db + vector db)#8141

Merged
harshsinha03 merged 15 commits into
agno-agi:mainfrom
atao2004:feat/valkey-client-setname
Jul 13, 2026
Merged

feat: add Valkey support (storage db + vector db)#8141
harshsinha03 merged 15 commits into
agno-agi:mainfrom
atao2004:feat/valkey-client-setname

Conversation

@atao2004

@atao2004 atao2004 commented May 28, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds full Valkey support to Agno: a ValkeyDb storage adapter, a ValkeyDB vector database, cookbooks, and unit/integration tests. Both clients set a client_name so connections are identifiable via CLIENT LIST on the server.

Closes #8117, closes #7795

Storage adapter (agno/db/valkey)

  • ValkeyDb implementing the full BaseDb interface: sessions, user memories, metrics, evals, knowledge, cultural knowledge, traces, and spans.
  • Built on valkey-glide-sync (GlideClient / GlideClusterClient), with support for host/port, username/password auth, TLS, logical database selection, or a pre-configured client instance.
  • Secondary index sets per record type (e.g. user_id, agent_id, session_type, trace_id) for filtered lookups without full scans.
  • Bulk operations (upsert_sessions, upsert_memories, delete_sessions, create_spans, delete_eval_runs) batched through GLIDE pipelines, with per-record write verification.
  • Optional key TTL via expire.
  • Connections are named agno_db_client (CLIENT SETNAME).

Vector database (agno/vectordb/valkey)

  • ValkeyDB (exported alias ValkeyVectorDb) implementing the VectorDb interface using the valkey-search module (FT.* commands).
  • Vector search (KNN over HNSW or FLAT index; cosine, L2, and inner-product distance) and keyword search, plus reranker support.
  • Sync and async variants for all interface methods.
  • Insert, upsert (replace by content hash), delete by id/name/metadata/content_id, metadata updates, and existence checks (id, name, content hash).
  • Connections are named agno_vectordb_client.

Cookbooks

  • cookbook/06_storage/valkey/ — agent, team, and workflow storage examples with README.
  • cookbook/05_agent_os/dbs/valkey_db.py — AgentOS backed by Valkey.
  • cookbook/07_knowledge/05_integrations/vector_dbs/05_valkey.py — knowledge base with Valkey as the vector store.

Tests

  • Unit tests for the storage adapter and vector database (run without a server via a stubbed GLIDE client).
  • Integration tests for bulk operations, trace/span stats, and vector database operations against a live Valkey instance.

Dependencies

  • New valkey extra: valkey-glide-sync>=2.1.0, included in the storage and vectordbs extras.

Run Valkey locally with:

docker run --name my-valkey -p 6379:6379 -d valkey/valkey-bundle

Type of change

  • Bug fix
  • New feature
  • Breaking change
  • Improvement
  • Model update
  • Other:

Checklist

  • Code complies with style guidelines
  • Ran format/validation scripts (./scripts/format.sh and ./scripts/validate.sh)
  • Self-review completed
  • Documentation updated (comments, docstrings)
  • Examples and guides: Relevant cookbook examples have been included or updated (if applicable)
  • Tested in clean environment
  • Tests added/updated (if applicable)

Duplicate and AI-Generated PR Check

  • I have searched existing open pull requests and confirmed that no other PR already addresses this issue
  • If a similar PR exists, I have explained below why this PR is a better approach
  • Check if this PR was entirely AI-generated (by Copilot, Claude Code, Cursor, etc.)

Additional Notes

  • Hybrid search is not supported by the Valkey vector database; supported search types are vector and keyword.
  • The valkey/valkey-bundle Docker image is required for vector search (it ships the valkey-search module); plain valkey/valkey is sufficient for the storage adapter.
  • Learning methods are not implemented, matching the Redis adapter.

edlng and others added 3 commits May 4, 2026 11:23
Signed-off-by: Edward Liang <edward.liang@improving.com>
…ntification

Signed-off-by: Anna Tao <annatao2004@gmail.com>
@atao2004 atao2004 requested a review from a team as a code owner May 28, 2026 15:41
@harshsinha03 harshsinha03 mentioned this pull request Jun 24, 2026
13 tasks
@harshsinha03 harshsinha03 changed the title feat(valkey): add CLIENT SETNAME to Valkey adapter feat: add Valkey support (storage db + vector db) Jul 3, 2026
Comment thread libs/agno/agno/db/valkey/valkey.py Outdated
Comment thread cookbook/05_agent_os/dbs/valkey_db.py Outdated
@kausmeows kausmeows added the docs-needed The official Agno docs should be updated label Jul 3, 2026
@harshsinha03 harshsinha03 force-pushed the feat/valkey-client-setname branch from 9f56cdd to db9a83f Compare July 3, 2026 12:25

@kausmeows kausmeows left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

traces filtering from FE filter bar is not working-

Image

Comment thread libs/agno/agno/db/valkey/valkey.py Outdated
Comment thread libs/agno/agno/db/valkey/valkey.py
Comment thread libs/agno/agno/db/valkey/valkey.py Outdated
Comment thread libs/agno/agno/vectordb/valkey/valkeydb.py Outdated
@harshsinha03

Copy link
Copy Markdown
Contributor

Hi @atao2004, thanks for this addition! We'll get this merged soon.

Would you also be open to adding the docs for this here: https://github.com/agno-agi/docs?

- Remove culture_table support (deprecated); add learnings_table
- Make client_name configurable with sensible defaults
- Fix ServerCredentials: raise ValueError on username-without-password
- Add docker instructions to cookbook
- Expand table_exists() docstring (schemaless DB explanation)
- Add dict-based metadata filtering for indexed tag fields in vectordb

Signed-off-by: Anna Tao <annatao2004@gmail.com>
@atao2004

atao2004 commented Jul 7, 2026

Copy link
Copy Markdown
Contributor Author

 Thanks for the review @kausmeows all feedback addressed in commit 3c659af:

@atao2004

atao2004 commented Jul 7, 2026

Copy link
Copy Markdown
Contributor Author

Hi @harshsinha03 added docs here agno-agi/docs#700 :)

@harshsinha03 harshsinha03 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, thanks @atao2004 and @edlng for the great work here, really appreciate the contribution! 🙌

@harshsinha03 harshsinha03 merged commit e0dd351 into agno-agi:main Jul 13, 2026
7 checks passed
harshsinha03 added a commit to agno-agi/docs that referenced this pull request Jul 14, 2026
## Summary

Adds documentation for the Valkey integration (storage adapter + vector
database), companion to
[agno-agi/agno#8141](agno-agi/agno#8141).

### Storage adapter (`database/providers/valkey/`)

- Overview with Docker setup, basic usage, and configuration params
- Usage examples: agent, team, workflow storage

### Vector database (`knowledge/vector-stores/valkey/`)

- Overview with setup (requires `valkey/valkey-bundle` for search
module)
- Code example with Knowledge + Agent
- Metadata filtering documentation (dict-based on indexed TAG fields)
- Configuration params table

### Notes

- `database/valkey.mdx` is a leftover from an incorrect initial
placement — should be deleted (the correct file is at
`database/providers/valkey/overview.mdx`)
- `docs.json` navigation entries need to be added for the Valkey pages
(happy to do this if you point me to the right section structure)
- No `<Snippet>` param files created yet — used inline tables instead.
Happy to refactor to snippets if preferred.

## Checklist

- [x] Follows existing doc structure (mirrors Redis docs)
- [x] Code examples use correct imports from the Valkey adapter
- [x] Docker instructions included
- [x] Configuration parameters documented

---------

Co-authored-by: Harsh Sinha <sinha03harsh@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs-needed The official Agno docs should be updated first-time-contributor

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add CLIENT SETNAME to Valkey adapter for connection identification [Feature Request] Add Valkey as a database and vector database option

4 participants