Skip to main content

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:

  1. 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.
  2. No learning loop. SemanticCache returns 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 set PERCEPT_VECTORIZER=openai + OPENAI_API_KEY to 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. .env is git-ignored; use .env.example as 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:

  • graph omitted → 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)

Source distribution for percept-context-plugin 0.1.0
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)

Table of built distributions (wheels) for percept-context-plugin 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page