Percept Context 🧠 — a Redis-native Context Graph + GraphRAG engine (MCP)
A queryable context graph for video-ad generation that lives entirely inside Redis — and learns from outcomes.
pip install percept-context-plugin gives any agent (Claude Code, Claude Desktop, your own)
direct access to a reward-weighted property graph on Redis, exposed over the
Model Context Protocol (MCP). Store creative knowledge, run GraphRAG retrieval, and
close the loop by reinforcing what actually performed. Ships with a curated video-ad
knowledge graph; the engine itself is domain-agnostic.
Why this exists
Redis is the obvious substrate for AI memory — but two things are missing from the stack today:
- No graph. Redis retired RedisGraph (end-of-support Jan 31, 2025) and shipped no replacement; the official AI recipes are all flat vector RAG. There's no first-class way to model entities + relationships and do GraphRAG on Redis.
- No learning loop.
SemanticCachereturns a prior answer, never the best-performing one — there's no notion of a reward signal feeding back into retrieval.
Percept Context fills both, natively on Redis primitives:
| Concern | How it's done |
|---|---|
| Nodes + embeddings | Redis hashes indexed by RedisVL (SearchIndex, cosine vector field) |
| Edges + weights | Redis sorted sets (member=neighbor, score=weight) → O(log n) "best neighbors first" |
| Semantic retrieval | RedisVL VectorQuery finds entry nodes |
| GraphRAG | vector entry → beam traversal of highest-weight edges → connected subgraph |
| Learning | record_outcome(path, reward) → ZINCRBY edge weights + bump node scores |
| Multi-tenant | every key namespaced by a graph id → a shared graph and per-user personal graphs |
Architecture
add_node / link_nodes record_outcome(path, reward)
│ ▲
▼ │ (e.g. a TRIBE engagement score)
┌──────────────────────────────────────────────────────────────────┐
│ R E D I S │
│ │
│ Nodes (hash + vector, RedisVL SearchIndex) Edges (sorted sets) │
│ percept:node:{graph}:{uuid} percept:adj:{graph}:… │
└──────────────────────────────────────────────────────────────────┘
▲ │
│ 1. VectorQuery → entry nodes │ 2. ZREVRANGE → top-weight
│ ▼ neighbors (beam traversal)
graph_rag_query(brief) ───────────────► grounded subgraph + context
Retrieval is semantic + structural: vectors find where to enter the graph; weighted edges decide what proven context to pull in. Outcomes reinforce the edges, so the graph gets better at retrieval over time.
Install
Requires Python ≥ 3.10 and a Redis with the Search/Query module (Redis Cloud, Redis Stack, or Redis 8). First run downloads a small local embedding model (MiniLM, 384-dim) — no API key needed.
pip install percept-context-plugin
Configure your connection (or pass env vars at registration):
export REDIS_URL=redis://localhost:6379
export REDIS_PROTOCOL=2
Torch-free install:
pip install percept-context-plugin[openai]and setPERCEPT_VECTORIZER=openai+OPENAI_API_KEYto skip the local model.
Register with Claude Code
claude mcp add percept-context --scope local \
--env REDIS_URL=redis://localhost:6379 \
--env REDIS_PROTOCOL=2 \
-- percept-context
Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"percept-context": {
"command": "percept-context",
"env": {
"REDIS_URL": "redis://localhost:6379",
"REDIS_PROTOCOL": "2"
}
}
}
}
🔒 Never commit your real
REDIS_URL..envis git-ignored; use.env.exampleas the template.
Tools
| Tool | What it does |
|---|---|
graph_rag_query(query, graph?, types?, k?, hops?) |
The core. Vector-entry + weighted traversal → grounded subgraph + context. |
search_nodes(query, graph?, types?, k?) |
Pure semantic vector search (no traversal). |
add_node(type, label, content?, props?, graph?) |
Add + embed + index a node. |
link_nodes(src_id, dst_id, type, weight?, props?, graph?) |
Create a weighted directed edge. |
neighbors(node_id, edge_type?, direction?, graph?, limit?) |
Highest-weight neighbors of a node. |
record_outcome(path, reward, graph?) |
Close the loop: reinforce a winning path. |
top_performers(graph?, types?, limit?) |
Most-reinforced nodes. |
graph_stats(graph?) |
Ping, index, node count, endpoint. |
seed_demo_graph(graph?) |
Load the bundled video-ad knowledge graph. |
compose_brief(brief, graph?, k?, hops?) |
Full RAG: retrieve context, then (optional LLM) compose an optimized ad prompt. |
Shared vs. personal graphs
Every tool takes an optional graph namespace:
graphomitted → the shared graph (PERCEPT_DEFAULT_GRAPH, default"shared").graph="user:dean"→ that user's personal graph, isolated by key prefix.
Query the shared graph for curated, proven knowledge; query a personal graph for what that user's own outcomes have taught the system. They live side-by-side in one Redis.
Quickstart (from source)
git clone <this-repo> && cd percept-context
python -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env # set REDIS_URL
python examples/quickstart.py # seeds, queries, reinforces, prints top performers
Example agent session:
seed_demo_graph()
graph_rag_query("energy drink ad that stops the scroll", k=3, hops=1)
→ entry: [technique] Pattern interrupt, [principle] Hook in the first second …
→ edges: Hook in the first second —[ENABLES w=2.00]→ Pattern interrupt …
record_outcome(path=[<hook_id>, <pattern_interrupt_id>], reward=8.5) # a TRIBE score
graph_rag_query("energy drink ad that stops the scroll") # now biased to the winner
Configuration reference
| Env var | Default | Purpose |
|---|---|---|
REDIS_URL |
– (required) | Redis connection string. |
REDIS_PROTOCOL |
2 |
Use 3 for Redis Cloud / RESP3. |
PERCEPT_INDEX |
percept_nodes |
RediSearch index name. |
PERCEPT_PREFIX |
percept:node |
Node key prefix. |
PERCEPT_DEFAULT_GRAPH |
shared |
Default namespace. |
PERCEPT_VECTORIZER |
hf |
hf (local) or openai. |
PERCEPT_EMBED_MODEL |
…all-MiniLM-L6-v2 |
Embedding model. |
ANTHROPIC_API_KEY |
– | Enables LLM composition in compose_brief. |
PERCEPT_LLM_MODEL |
claude-opus-4-8 |
Model for compose_brief. |
Roadmap
- Plugin 2 — multimodal video nodes: store videos in Redis, run computer vision to understand their content, and query them semantically — folding video understanding into this same graph as first-class nodes.
License
MIT
Metadata
Release files for percept-context-plugin 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| percept_context_plugin-0.1.0.tar.gz | 14.4 kB | Without provenance | Details for percept_context_plugin-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| percept_context_plugin-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for percept_context_plugin-0.1.0-py3-none-any.whl |
Total release size: 30.6 kB
Release files / percept_context_plugin-0.1.0.tar.gz
| Download URL | percept_context_plugin-0.1.0.tar.gz |
|---|---|
| Size | 14.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ef218988d8b287346b4fe0d8f93d54457356b9c546227d7ac68379a08349fd5b
|
|
BLAKE2b-256 checksum How to use checksums |
1d47cd92bd17290ec4e39372f70c6b60ff597ac323016253a5c6c692819d0ee2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
Release files / percept_context_plugin-0.1.0-py3-none-any.whl
| Download URL | percept_context_plugin-0.1.0-py3-none-any.whl |
|---|---|
| Size | 16.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
15ff7fbd179a72cd55e2a126993673424970e535b4de636906778572d4d117b6
|
|
BLAKE2b-256 checksum How to use checksums |
9d7a0cdbebf87de38caf434ab5740aeda40a6b2703eccffe34e562b6fd321528
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
Security for percept-context-plugin 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.