Skip to content

Commit 5ce2ad9

Browse files
abrookinsabrookins
committed
Refactor README into separate docs
1 parent 01fe346 commit 5ce2ad9

File tree

9 files changed

+641
-500
lines changed

9 files changed

+641
-500
lines changed

‎README.md

Lines changed: 22 additions & 500 deletions
Large diffs are not rendered by default.

‎docs/README.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Redis Agent Memory Server Documentation
2+
3+
This directory contains comprehensive documentation for the Redis Agent Memory Server.
4+
5+
## Documentation Index
6+
7+
### Core Documentation
8+
9+
- **[Authentication](authentication.md)** - OAuth2/JWT setup, configuration, and security best practices
10+
- **[REST API](api.md)** - Complete API reference with endpoints and examples
11+
- **[MCP Server](mcp.md)** - Model Context Protocol interface and client setup
12+
- **[CLI](cli.md)** - Command-line interface reference and examples
13+
14+
### Setup and Configuration
15+
16+
- **[Getting Started](getting-started.md)** - Installation, running servers, and Docker setup
17+
- **[Configuration](configuration.md)** - Environment variables, background tasks, and memory management
18+
19+
### Development
20+
21+
- **[Development](development.md)** - Testing, contributing, and development setup
22+
23+
### Additional Resources
24+
25+
- **[Manual OAuth Testing](../manual_oauth_qa/README.md)** - Comprehensive Auth0 testing guide
26+
- **[Main README](../README.md)** - Project overview and quick reference
27+
28+
## Quick Links
29+
30+
- **Start here**: [Getting Started](getting-started.md)
31+
- **API Reference**: [REST API](api.md)
32+
- **Authentication Setup**: [Authentication](authentication.md)
33+
- **MCP Integration**: [MCP Server](mcp.md)

‎docs/api.md

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# REST API Endpoints
2+
3+
The following endpoints are available:
4+
5+
- **GET /health**
6+
A simple health check endpoint returning the current server time.
7+
Example Response:
8+
9+
```json
10+
{ "now": 1616173200 }
11+
```
12+
13+
- **GET /sessions/**
14+
Retrieves a paginated list of session IDs.
15+
_Query Parameters:_
16+
17+
- `limit` (int): Number of sessions per page (default: 10)
18+
- `offset` (int): Number of sessions to skip (default: 0)
19+
- `namespace` (string, optional): Filter sessions by namespace.
20+
21+
- **GET /sessions/{session_id}/memory**
22+
Retrieves working memory for a session, including messages, structured memories,
23+
context, and metadata.
24+
_Query Parameters:_
25+
26+
- `namespace` (string, optional): The namespace to use for the session
27+
- `window_size` (int, optional): Number of messages to include in the response (default from config)
28+
- `model_name` (string, optional): The client's LLM model name to determine appropriate context window size
29+
- `context_window_max` (int, optional): Direct specification of max context window tokens (overrides model_name)
30+
31+
- **PUT /sessions/{session_id}/memory**
32+
Sets working memory for a session, replacing any existing memory.
33+
Automatically summarizes conversations that exceed the window size.
34+
_Request Body Example:_
35+
36+
```json
37+
{
38+
"messages": [
39+
{ "role": "user", "content": "Hello" },
40+
{ "role": "assistant", "content": "Hi there" }
41+
],
42+
"memories": [
43+
{
44+
"id": "mem-123",
45+
"text": "User prefers direct communication",
46+
"memory_type": "semantic"
47+
}
48+
],
49+
"context": "Previous conversation summary...",
50+
"session_id": "session-123",
51+
"namespace": "default"
52+
}
53+
```
54+
55+
- **DELETE /sessions/{session_id}/memory**
56+
Deletes all working memory (messages, context, structured memories, metadata) for a session.
57+
58+
- **POST /long-term-memory**
59+
Creates long-term memories directly, bypassing working memory.
60+
_Request Body Example:_
61+
62+
```json
63+
{
64+
"memories": [
65+
{
66+
"id": "mem-456",
67+
"text": "User is interested in AI and machine learning",
68+
"memory_type": "semantic",
69+
"session_id": "session-123",
70+
"namespace": "default"
71+
}
72+
]
73+
}
74+
```
75+
76+
- **POST /long-term-memory/search**
77+
Performs vector search on long-term memories with advanced filtering options.
78+
_Request Body Example:_
79+
80+
```json
81+
{
82+
"text": "Search query text",
83+
"limit": 10,
84+
"offset": 0,
85+
"session_id": { "eq": "session-123" },
86+
"namespace": { "eq": "default" },
87+
"topics": { "any": ["AI", "Machine Learning"] },
88+
"entities": { "all": ["OpenAI", "Claude"] },
89+
"created_at": { "gte": 1672527600, "lte": 1704063599 },
90+
"last_accessed": { "gt": 1704063600 },
91+
"user_id": { "eq": "user-456" }
92+
}
93+
```
94+
95+
- **POST /memory-prompt**
96+
Generates prompts enriched with relevant memory context from both working
97+
memory and long-term memory. Useful for retrieving context before answering questions.
98+
_Request Body Example:_
99+
100+
```json
101+
{
102+
"query": "What did we discuss about AI?",
103+
"session": {
104+
"session_id": "session-123",
105+
"namespace": "default",
106+
"window_size": 10
107+
},
108+
"long_term_search": {
109+
"text": "AI discussion",
110+
"limit": 5,
111+
"namespace": { "eq": "default" }
112+
}
113+
}
114+
```
115+
116+
## Filter Options
117+
118+
_Filter options for search endpoints:_
119+
120+
- Tag filters (session_id, namespace, topics, entities, user_id):
121+
122+
- `eq`: Equals this value
123+
- `ne`: Not equals this value
124+
- `any`: Contains any of these values
125+
- `all`: Contains all of these values
126+
127+
- Numeric filters (created_at, last_accessed):
128+
- `gt`: Greater than
129+
- `lt`: Less than
130+
- `gte`: Greater than or equal
131+
- `lte`: Less than or equal
132+
- `eq`: Equals
133+
- `ne`: Not equals
134+
- `between`: Between two values

‎docs/authentication.md

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Authentication
2+
3+
The Redis Agent Memory Server supports OAuth2/JWT Bearer token authentication for secure API access. All API endpoints (except `/health`, `/docs`, and `/openapi.json`) require valid JWT authentication unless disabled for development.
4+
5+
## Features
6+
7+
- **OAuth2/JWT Bearer Token Authentication**: Industry-standard authentication using JWT access tokens
8+
- **JWKS Public Key Validation**: Automatic fetching and caching of public keys for token signature verification
9+
- **Multi-Provider Support**: Compatible with Auth0, AWS Cognito, Okta, Azure AD, and any standard OAuth2 provider
10+
- **Flexible Configuration**: Environment variable-based configuration for different deployment scenarios
11+
- **Development Mode**: `DISABLE_AUTH` setting for local development and testing
12+
- **Role and Scope Support**: Fine-grained access control using JWT claims
13+
14+
## Configuration
15+
16+
Authentication is configured using environment variables:
17+
18+
```bash
19+
# OAuth2 Provider Configuration
20+
OAUTH2_ISSUER_URL=https://your-auth-provider.com
21+
OAUTH2_AUDIENCE=your-api-audience
22+
OAUTH2_JWKS_URL=https://your-auth-provider.com/.well-known/jwks.json # Optional, auto-derived from issuer
23+
OAUTH2_ALGORITHMS=["RS256"] # Supported signing algorithms
24+
25+
# Development Mode (DISABLE AUTHENTICATION - USE ONLY FOR DEVELOPMENT)
26+
DISABLE_AUTH=true # Set to true to bypass all authentication (development only)
27+
```
28+
29+
## Provider Examples
30+
31+
### Auth0
32+
33+
```bash
34+
OAUTH2_ISSUER_URL=https://your-domain.auth0.com/
35+
OAUTH2_AUDIENCE=https://your-api.com
36+
```
37+
38+
### AWS Cognito
39+
40+
```bash
41+
OAUTH2_ISSUER_URL=https://cognito-idp.region.amazonaws.com/your-user-pool-id
42+
OAUTH2_AUDIENCE=your-app-client-id
43+
```
44+
45+
### Okta
46+
47+
```bash
48+
OAUTH2_ISSUER_URL=https://your-domain.okta.com/oauth2/default
49+
OAUTH2_AUDIENCE=api://default
50+
```
51+
52+
### Azure AD
53+
54+
```bash
55+
OAUTH2_ISSUER_URL=https://login.microsoftonline.com/your-tenant-id/v2.0
56+
OAUTH2_AUDIENCE=your-application-id
57+
```
58+
59+
## Usage Examples
60+
61+
### With Authentication (Production)
62+
63+
```bash
64+
# Make authenticated API request
65+
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
66+
-H "Content-Type: application/json" \
67+
http://localhost:8000/sessions/
68+
69+
# Python example
70+
import httpx
71+
72+
headers = {
73+
"Authorization": "Bearer YOUR_JWT_TOKEN",
74+
"Content-Type": "application/json"
75+
}
76+
77+
response = httpx.get("http://localhost:8000/sessions/", headers=headers)
78+
```
79+
80+
### Development Mode (Local Testing)
81+
82+
```bash
83+
# Set environment variable to disable auth
84+
export DISABLE_AUTH=true
85+
86+
# Now you can make requests without tokens
87+
curl -H "Content-Type: application/json" \
88+
http://localhost:8000/sessions/
89+
```
90+
91+
## Token Requirements
92+
93+
JWT tokens must include:
94+
95+
- **Valid signature**: Verified using JWKS public keys from the issuer
96+
- **Not expired**: `exp` claim must be in the future
97+
- **Valid audience**: `aud` claim must match `OAUTH2_AUDIENCE` (if configured)
98+
- **Valid issuer**: `iss` claim must match `OAUTH2_ISSUER_URL`
99+
- **Subject**: `sub` claim identifying the user/client
100+
101+
## Error Responses
102+
103+
Authentication failures return HTTP 401 with details:
104+
105+
```json
106+
{
107+
"detail": "Invalid JWT: Token has expired",
108+
"status_code": 401
109+
}
110+
```
111+
112+
Common error scenarios:
113+
114+
- `Missing authorization header`: No `Authorization: Bearer` header provided
115+
- `Missing bearer token`: Empty or malformed authorization header
116+
- `Invalid token header`: Malformed JWT structure
117+
- `Token has expired`: JWT `exp` claim is in the past
118+
- `Invalid audience`: JWT `aud` claim doesn't match expected audience
119+
- `Unable to find matching public key`: JWKS doesn't contain key for token's `kid`
120+
121+
## Security Best Practices
122+
123+
1. **Never use `DISABLE_AUTH=true` in production**
124+
2. **Use HTTPS in production** to protect tokens in transit
125+
3. **Implement token refresh** in your clients for long-running applications
126+
4. **Monitor token expiration** and handle 401 responses appropriately
127+
5. **Validate tokens server-side** - never trust client-side validation alone
128+
6. **Use appropriate scopes/roles** for fine-grained access control
129+
130+
## Manual Testing
131+
132+
For comprehensive Auth0 testing instructions, see the [manual OAuth testing guide](../manual_oauth_qa/README.md).

0 commit comments

Comments
 (0)