Papr Memory 🧠

Predictive memory layer for AI agents. MongoDB + Qdrant + Neo4j with multi-tier caching, custom schema support & GraphQL. 91% Stanford STARK accuracy, <100ms on-device retrieval.

🚀 What is Papr Memory?

Papr Memory is the predictive memory layer for your AI agents that allows you to:

Store Information: Save text, documents, code snippets, and structured data
AI-Powered Search: Find relevant memories using natural language queries
Graph Relationships: Automatically discover and track connections between memories
Vector Embeddings: Semantic search powered by modern embedding models
Multi-Modal Support: Handle text, documents, images, and structured data
User Context: Personal memory spaces with fine-grained access control

💡 Use Cases

Voice Agents for Customer Support: Enable intelligent voice assistants with persistent memory and context
B2B AI Agents: Knowledge management, RAG, and semantic search for enterprise applications
Coding Agents: Use custom ontology + GraphQL for significant improvements to context and search in your codebase
Financial AI Agents: Ingest financial documents using custom ontology + GraphQL for queries
Healthcare AI Agents: Secure, compliant memory management for healthcare applications
Retail AI Agents: Use custom ontology + GraphQL for intelligent product recommendations and customer insights

🏗️ Architecture Overview

graph TB
    Client[Client Applications] --> API[FastAPI Server]
    API --> Parse[Parse Server]
    API --> Mongo[(MongoDB)]
    API --> Neo4j[(Neo4j Graph DB)]
    API --> Qdrant[(Qdrant Vector DB)]
    API --> Redis[(Redis Cache)]

    subgraph "AI Services"
        OpenAI[OpenAI Embeddings]
        LLM[Language Models]
    end

    API --> OpenAI
    API --> LLM

    subgraph "Storage Layer"
        Parse --> Mongo
        Neo4j --> MemGraph[Memory Graph]
        Qdrant --> VectorStore[Vector Embeddings]
    end

    subgraph "Features"
        Search[Semantic Search]
        Graph[Graph Relationships]
        ACL[Access Control]
        Embed[Auto Embeddings]
    end

Predictive memory Architecture

🆚 Open Source vs Cloud

Feature	Open Source	Cloud
Memory Storage	✅	✅
Vector Search	✅	✅
Graph Relationships	✅	✅
API Access	✅	✅
Self-Hosted	✅	❌
Managed Infrastructure	❌	✅
Automatic Backups	❌	✅
Payment/Billing	❌	✅
Enterprise SSO	❌	✅
SLA Guarantees	❌	✅
Priority Support	❌	✅
Advanced Analytics	❌	✅
Document Ingestion with Durable Execution	❌	✅
GraphQL Instance with Custom Ontology	❌	✅
On-Device Predictions (< 100ms retrieval)	❌	✅

🔧 Key Components

FastAPI Server: Main API layer with authentication and routing
Parse Server: User management, ACL, and structured data storage
MongoDB: Primary document storage and user data
Neo4j: Graph database for memory relationships and connections
Qdrant: Vector database for semantic search and embeddings
Redis: Caching layer for performance optimization

🚀 Quick Start

Prerequisites

Python 3.8+
Docker & Docker Compose (recommended)
Git
API Keys: OpenAI API key, Groq API key, and Deep Infra API key
- Note: Hugging Face is also supported, and local Qwen on-device support will be added soon

Option 1: Docker Setup (Recommended)

For Open Source Setup, see the detailed guide: QUICKSTART_OPENSOURCE.md

Quick start:

Clone the repository

git clone https://github.com/Papr-ai/memory-opensource.git
cd memory-opensource

Copy environment configuration

# For open source setup
cp .env.example .env.opensource
# Edit .env.opensource with your API keys (OpenAI, Groq, Deep Infra)
# Note: Hugging Face is also supported, and local Qwen on-device support will be added soon

Start all services

# Open source setup (auto-initializes everything)
docker-compose up -d

Access the API
- API Documentation: http://localhost:5001/docs
- Health Check: http://localhost:5001/health
- Parse Dashboard: http://localhost:4040 (optional, use --profile dashboard for open source)

Note: The open-source setup automatically initializes schemas, creates a default user, and generates an API key on first run. Check container logs for your API key.

Option 2: Manual Setup

Clone and setup Python environment

git clone https://github.com/Papr-ai/memory-opensource.git
cd memory-opensource
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Start required services

# Recommended: Use docker-compose for open source setup
docker-compose up -d mongodb neo4j qdrant redis parse-server

# Or start individually (for development):
# MongoDB
docker run -d -p 27017:27017 --name mongo mongo:8.0.12

# Neo4j
docker run -d -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  --name neo4j neo4j:2025.10.1

# Qdrant
docker run -d -p 6333:6333 --name qdrant qdrant/qdrant:v1.16.0

# Redis
docker run -d -p 6379:6379 --name redis redis:7-alpine

# Parse Server
docker run -d -p 1337:1337 \
  -e PARSE_SERVER_APPLICATION_ID=papr-oss-app-id \
  -e PARSE_SERVER_MASTER_KEY=papr-oss-master-key \
  -e PARSE_SERVER_DATABASE_URI=mongodb://localhost:27017/papr_memory \
  --name parse parseplatform/parse-server:8.4.0

Configure environment

# For open source
cp .env.example .env.opensource
# Edit .env.opensource with your service URLs and API keys

# For cloud/development
cp .env.example .env
# Edit .env with your service URLs and API keys

Run the application

python main.py

📖 API Documentation

Authentication

The API supports multiple authentication methods:

# API Key
curl -H "X-API-Key: your-api-key" http://localhost:5001/v1/memory

# Session Token
curl -H "X-Session-Token: your-session-token" http://localhost:5001/v1/memory

# Bearer Token (OAuth)
curl -H "Authorization: Bearer your-jwt-token" http://localhost:5001/v1/memory

Core Endpoints

Memory Management

# Add a memory
POST /v1/memory
{
  "content": "Your memory content",
  "type": "text",
  "metadata": {
    "tags": ["important", "work"],
    "location": "office"
  }
}

# Search memories
POST /v1/memory/search
{
  "query": "find relevant information",
  "max_memories": 10
}

# Get specific memory
GET /v1/memory/{memory_id}

# Update memory
PUT /v1/memory/{memory_id}

# Delete memory
DELETE /v1/memory/{memory_id}

Document Upload

# Upload document
POST /v1/documents
Content-Type: multipart/form-data
File: document.pdf

User Management

# Get user info
GET /v1/users/me

# Update user settings
PUT /v1/users/me

Interactive API Documentation

Once running, visit:

Swagger UI: http://localhost:5001/docs
ReDoc: http://localhost:5001/redoc
OpenAPI Schema: http://localhost:5001/openapi.json

🔧 Configuration

Environment Variables

Key environment variables (see .env.example for complete list):

# Server Configuration
PORT=5001
DEBUG=true
ENVIRONMENT=development

# Database URLs
MONGODB_URL=mongodb://localhost:27017/papr_memory
NEO4J_URL=bolt://localhost:7687
QDRANT_URL=http://localhost:6333
REDIS_URL=redis://localhost:6379

# Parse Server
PARSE_SERVER_URL=http://localhost:1337
PARSE_SERVER_APP_ID=your-app-id
PARSE_SERVER_MASTER_KEY=your-master-key

# AI Services
OPENAI_API_KEY=your-openai-key
OPENAI_ORGANIZATION=your-org-id
GROQ_API_KEY=your-groq-key
DEEPINFRA_API_KEY=your-deepinfra-key
# Note: Hugging Face is also supported, and local Qwen on-device support will be added soon

Advanced Configuration

Vector Search: Configure embedding models and search parameters
Graph Relationships: Customize relationship extraction and graph building
Access Control: Setup user roles and permissions
Caching: Configure Redis caching strategies
Monitoring: Setup logging and health checks

🧪 Testing

Run Tests

# All tests
pytest

# Specific test categories
pytest tests/unit/
pytest tests/integration/
pytest tests/api/

# With coverage
pytest --cov=./ --cov-report=html

API Testing

# Health check
curl http://localhost:5001/health

# Test authentication
curl -H "X-API-Key: test-key" http://localhost:5001/v1/memory

# Test memory creation
curl -X POST -H "Content-Type: application/json" \
  -H "X-API-Key: test-key" \
  -d '{"content":"Test memory","type":"text"}' \
  http://localhost:5001/v1/memory

📚 Examples

Python Client

import requests

# Initialize client
base_url = "http://localhost:5001"
headers = {"X-API-Key": "your-api-key"}

# Add memory
response = requests.post(
    f"{base_url}/v1/memory",
    json={
        "content": "Important meeting notes from today",
        "type": "text",
        "metadata": {
            "tags": ["meeting", "work"],
            "date": "2024-01-15"
        }
    },
    headers=headers
)
memory = response.json()

# Search memories
response = requests.post(
    f"{base_url}/v1/memory/search",
    json={"query": "meeting notes", "max_memories": 10},
    headers=headers
)
results = response.json()

JavaScript Client

const baseUrl = 'http://localhost:5001';
const headers = { 'X-API-Key': 'your-api-key' };

// Add memory
const addMemory = async (content, metadata = {}) => {
  const response = await fetch(`${baseUrl}/v1/memory`, {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({ content, type: 'text', metadata })
  });
  return response.json();
};

// Search memories
const searchMemories = async (query) => {
  const response = await fetch(`${baseUrl}/v1/memory/search`, {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({ query, max_memories: 10 })
  });
  return response.json();
};

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick Contribution Steps

Fork the repository
Create a feature branch: git checkout -b feature/your-feature
Make your changes and add tests
Run tests: pytest
Commit your changes: git commit -am 'Add some feature'
Push to the branch: git push origin feature/your-feature
Submit a pull request

📄 License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.

🆘 Support

Documentation: Check the API docs and this README
Issues: GitHub Issues
Discussions: GitHub Discussions
Discord: Join our community for real-time support: https://discord.gg/sWpR5a3H

Built with ❤️ by the Papr team

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.vscode		.vscode
.well-known		.well-known
api_handlers		api_handlers
background_tasks		background_tasks
config		config
connectors		connectors
core		core
datastore		datastore
docs		docs
examples		examples
memory		memory
models		models
routers/v1		routers/v1
routes		routes
scripts		scripts
services		services
tasks		tasks
tests		tests
utils		utils
.coverage		.coverage
.gitignore		.gitignore
.python-version		.python-version
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
QUICKSTART_OPENSOURCE.md		QUICKSTART_OPENSOURCE.md
README.md		README.md
SECURITY.md		SECURITY.md
agent.md		agent.md
app_factory.py		app_factory.py
docker-compose.yaml		docker-compose.yaml
main.py		main.py
monitor_batch_processing.sh		monitor_batch_processing.sh
openapi-stainless.json		openapi-stainless.json
openapi.json		openapi.json
openapi.stainless.yml		openapi.stainless.yml
openapi.yaml		openapi.yaml
openapi_with_schemas.json		openapi_with_schemas.json
parse-server-config.json		parse-server-config.json
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements.txt		requirements.txt
setup_neo4j.sh		setup_neo4j.sh
start_all_services.py		start_all_services.py
start_all_services.sh		start_all_services.sh
start_all_workers.py		start_all_workers.py
start_document_worker.py		start_document_worker.py
start_temporal_worker.py		start_temporal_worker.py
start_worker.py		start_worker.py
test_memory.json		test_memory.json
version.py		version.py

License

Papr-ai/memory-opensource

Folders and files

Latest commit

History

Repository files navigation