MemoryBear

---

Overview

MemoryBear is a next-generation AI memory system developed by RedBear AI. Its core breakthrough lies in moving beyond the limitations of traditional “static knowledge storage”. Inspired by the cognitive mechanisms of biological brains, MemoryBear builds an intelligent knowledge-processing framework that spans the full lifecycle of perception → extraction → association → forgetting.

Unlike traditional memory tools that treat knowledge as static data to be retrieved, MemoryBear emulates the hippocampus’s memory encoding, the neocortex’s knowledge consolidation, and synaptic pruning-based forgetting — enabling knowledge to dynamically evolve with life-like properties. This shifts the relationship between AI and users from passive lookup to proactive cognitive assistance.

Papers

Paper	Description
📄 Memory Bear AI: A Breakthrough from Memory to Cognition	MemoryBear core technical report
📄 Memory Bear AI Memory Science Engine for Multimodal Affective Intelligence	Technical report on multimodal affective intelligence memory engine
📄 A-MBER: Affective Memory Benchmark for Emotion Recognition	Affective memory benchmark dataset

Why MemoryBear

Knowledge Forgetting in Single Models

• Context window limits: Mainstream LLMs have 8k–32k token windows. In long conversations, early messages are pushed out, causing responses to lose historical context
• Static knowledge gap: Training data is a static snapshot — it cannot absorb personalized information (preferences, history) from live interactions
• Recency bias: Transformer self-attention weakens on long-range dependencies, overweighting recent input and ignoring earlier critical information

Memory Gaps in Multi-Agent Collaboration

• Data silos: Different agents (consulting, after-sales, recommendation) maintain isolated memories, forcing users to repeat information
• Inconsistent dialogue state: When switching agents, user intent and history labels are not fully passed along, causing service discontinuities
• Decision conflicts: Agents with partial memory can produce contradictory responses (e.g., recommending products a user is allergic to)

Semantic Ambiguity in Reasoning

• Domain jargon, colloquial expressions, and context-dependent references are not accurately encoded, leading to semantic drift in memory interpretation
• Cross-language memory associations fail in multilingual or dialect-rich scenarios

---

Core Features

Memory Extraction Engine

Performs semantic-level parsing of unstructured conversations and documents to extract:

• Core declarative information: Strips redundant modifiers, preserving subject-action-object logic
• Structured triples: Automatically extracts entity relationships (e.g., MemoryBear → core function → knowledge extraction) as atomic units for graph storage
• Temporal anchoring: Automatically extracts and tags timestamps, enabling time-based knowledge tracing
• Intelligent summarization: Customizable length (50–500 words) and focus; generates concise summaries of 10-page documents in under 3 seconds

Graph Storage (Neo4j)

Graph-first architecture integrated with Neo4j, overcoming the weak relational modeling of traditional databases:

• Supports millions of entities and tens of millions of relational edges
• Covers 12 core relationship types: hierarchical, causal, temporal, logical, and more
• Extracted triples sync directly to Neo4j, automatically building the initial knowledge graph
• Interactive graph visualization with “machine-generated + human-optimized” collaborative management

Hybrid Search

Keyword retrieval + semantic vector retrieval dual-engine fusion:

• Keyword search powered by Elasticsearch for millisecond-level exact matching of structured information
• Semantic vector search via BERT embeddings, recognizing synonyms, near-synonyms, and implicit intent
• Semantic retrieval expands the candidate space; keyword retrieval then performs precise filtering
• Retrieval accuracy reaches 92%, improving 35% over single-mode retrieval

Memory Forgetting Engine

Inspired by the brain’s synaptic pruning mechanism, using a dual-dimension model of memory strength and time decay:

• Each knowledge item is assigned an initial memory strength, updated dynamically by usage frequency and association activity
• When strength falls below threshold, knowledge enters a dormancy → decay → clearance three-stage lifecycle
• Redundant knowledge maintained below 8%, reducing waste by over 60% compared to systems without forgetting

Self-Reflection Engine

Scheduled daily reflection process, mimicking human review and retrospection:

• Consistency checks: Detects logical conflicts across related knowledge, flags suspicious records for human review
• Value assessment: Evaluates invocation frequency and association contribution; reinforces high-value knowledge, accelerates decay of low-value knowledge
• Association optimization: Adjusts relationship weights based on recent usage, strengthening high-frequency association paths

FastAPI Service Layer

Unified service architecture exposing two API surfaces:

API Type	Path Prefix	Auth	Purpose
Management API	/api	JWT	System config, permissions, log queries
Service API	/v1	API Key	Knowledge extraction, graph ops, search, forgetting control

• Average response latency below 50ms, single instance sustaining 1000 QPS
• Auto-generated Swagger documentation
• Docker-ready, compatible with enterprise microservice ecosystems (CRM, OA, R&D management)

---

Architecture

Celery Multi-Queue Async Architecture (7 worker types in docker-compose):

Queue	Worker Type	Concurrency	Purpose
memory_tasks	threads	100	Memory read/write (asyncio-friendly)
memory_fast_tasks	threads	32	High-frequency fast writes + RAG memory index writes (dedicated queue to avoid mutual blocking)
document_tasks	prefork	4	Document parsing (CPU-bound)
periodic_tasks	prefork	2	Scheduled tasks, reflection engine, various scanners
workflow_trigger_tasks	prefork	2	Workflow scheduled triggers
subscription_state_tasks	prefork	4	Subscription state transitions (Enterprise)
subscription_email_tasks	prefork	4	Subscription expiry reminder emails (Enterprise)

Additional task queues such as graphrag_tasks, reflection_tasks, and memory_heavy_tasks (GraphRAG construction, second-layer reflection/deduplication, forgetting and insight generation, and other heavy-compute tasks) work together with the standalone task scheduler celery_task_scheduler and Celery Beat.

---

Benchmarks

We evaluate MemoryBear on two widely used long-term memory benchmarks: LongMemEval (ICLR 2025) and LoCoMo (ACL 2024). Evaluation metrics include LLM-as-a-Judge accuracy (J) and token-level F1 (F1) — higher values indicate better performance.

MemoryBear achieves state-of-the-art overall performance on both benchmarks, reaching 95.00% LLM-judge accuracy on LongMemEval and 91.54% LLM-judge accuracy with 67.49 token-F1 on LoCoMo. It demonstrates particularly strong long-term memory capabilities in single-hop retrieval, multi-hop reasoning, temporal reasoning, knowledge updates, and adversarial robustness.

LoCoMo overall metrics: Overall Judge is 91.54%, and Overall F1 is 67.49.

Evaluation scope: MemoryBear is evaluated on 446 adversarial questions, achieving 94.39% accuracy. The other baselines cover 1,540 non-adversarial questions, so their overall scores are calculated over the four non-adversarial categories.

Evaluation Setup and Reproduction

Item	LongMemEval	LoCoMo
Dataset size	500 questions	1,986 questions across 10 conversations
Reader model	qwen3.7-plus	qwen3.7-plus
Judge model	qwen3.7-plus	qwen3.7-plus
Temperature	0	0
Primary metric	LLM-judge accuracy	LLM-judge accuracy
Additional metric	—	Token-level F1
Memory retrieval	Memory Search API	Two-speaker memory retrieval with reranking

For LoCoMo, MemoryBear queries both speakers’ memory stores, retrieves the top 50 candidates from each store, reranks them to the top 10 with gte-rerank-v2, and merges the results. Per-question retrieved memories, generated answers, LLM-judge decisions, and aggregate metrics are available in MemoryBear Evaluation Results. Evaluation code and reproduction instructions are available in MemoryBear Memory Benchmarks.

Data note: The original LoCoMo dataset contains several mislabeled golden answers. The results above use corrected golden answers. LLM judges are not perfectly deterministic; even at temperature 0, a small number of borderline decisions may vary slightly between reproduction runs.

---

Quick Start

Docker Compose (Recommended)

Prerequisites: Docker Desktop installed.

# 1. Clone the repository
git clone https://github.com/SuanmoSuanyangTechnology/MemoryBear.git
cd MemoryBear/api

# 2. Start base services (PostgreSQL / Neo4j / Redis / Elasticsearch)
# Pull and start these images via Docker Desktop first (see Installation section 3.2)

# 3. Configure environment variables
cp env.example .env
# Edit .env with your database connections and LLM API keys

# 4. Initialize the database
pip install uv && uv sync
alembic upgrade head

# 5. Start API + Celery Workers + Beat scheduler
docker-compose up -d

# 6. Initialize the system and get the admin account
curl -X POST http://127.0.0.1:8002/api/setup

Note: docker-compose.yml includes the API service, Celery Workers, the standalone task scheduler (celery_task_scheduler), and the sandbox service. Base services (PostgreSQL, Neo4j, Redis, Elasticsearch) must be started separately.

Port info: Docker Compose defaults to port 8002; manual startup defaults to port 8000. The installation guide below uses manual startup (8000) as the example.

After startup:

• API docs: http://localhost:8002/docs
• Frontend: http://localhost:5175 (after starting the web app)

Default admin credentials:

• Account: [email protected]
• Password: admin_password

Manual Start

Quick commands below — see Installation for detailed steps.

# Backend
cd api
pip install uv && uv sync
alembic upgrade head
uv run -m app.main

# Frontend (new terminal)
cd web
npm install && npm run dev

---

Installation

1. Environment Requirements

Component	Version	Purpose
Python	3.12 (3.13+ not supported)	Backend runtime
Node.js	20.19+ or 22.12+	Frontend runtime
PostgreSQL	13+	Primary database
Neo4j	4.4+	Knowledge graph storage
Redis	6.0+	Cache and message queue
Elasticsearch	8.x	Hybrid search engine

2. Get the Project

git clone https://github.com/SuanmoSuanyangTechnology/MemoryBear.git

3. Backend API Service

3.1 Install Python Dependencies

# Install uv package manager
pip install uv

# Switch to the API directory
cd api

# Install dependencies
uv sync

# Activate virtual environment
# Windows (PowerShell, inside /api)
.venv\Scripts\Activate.ps1
# Windows (cmd, inside /api)
.venv\Scripts\activate.bat
# macOS / Linux
source .venv/bin/activate

3.2 Install Base Services (Docker Images)

Download Docker Desktop and pull the required images.

PostgreSQL — search → select → pull

Neo4j — pull the same way. When creating the container, map two required ports and set an initial password:

• 7474: Neo4j Browser
• 7687: Bolt protocol

Important: You must also add the environment variable NEO4J_PLUGINS=["apoc"] to install the APOC plugin (a hard dependency of the backend graph engine; not included in the official image by default). If configuring this via the Docker Desktop GUI is inconvenient, create the container from the command line instead:

docker run -d --name memorybear-neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/<initial password, at least 8 chars> \
  -e NEO4J_PLUGINS='["apoc"]' \
  neo4j:5

Redis — same steps as above.

Elasticsearch

Pull the Elasticsearch 8.x image and create a container, mapping ports 9200 (HTTP API) and 9300 (cluster communication). For initial setup, disable security to simplify configuration:

docker run -d --name elasticsearch \
  -p 9200:9200 -p 9300:9300 \
  -e "discovery.type=single-node" \
  -e "xpack.security.enabled=false" \
  elasticsearch:8.15.0

3.3 Configure Environment Variables

cp env.example .env

Fill in the core configuration in .env:

# Neo4j Graph Database
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password

# PostgreSQL Database
DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your-password
DB_NAME=redbear-mem

# Set to true on first startup to auto-migrate the database
DB_AUTO_UPGRADE=true

# Redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_DB=1
REDIS_PASSWORD=

# Celery
REDIS_DB_CELERY_BROKER=1
REDIS_DB_CELERY_BACKEND=2

# Elasticsearch
ELASTICSEARCH_HOST=127.0.0.1
ELASTICSEARCH_PORT=9200

# JWT Secret Key (generate with: openssl rand -hex 32)
SECRET_KEY=your-secret-key-here

3.4 Initialize the PostgreSQL Database

The database connection is read automatically from the DB_* environment variables in .env (migrations/env.py builds the connection string dynamically) — no need to modify alembic.ini.

Apply all migrations to create the full schema:

alembic upgrade head

Tip: When DB_AUTO_UPGRADE=true is set in .env, the API service automatically runs alembic upgrade head on startup. Migration scripts are located in api/migrations/versions/ — make sure that directory contains migration files before running the command.

3.5 Start the API Service

uv run -m app.main

Access API documentation at http://localhost:8000/docs

3.6 Start Celery Workers (Optional, for async tasks)

# Memory worker (thread pool, asyncio-friendly, high concurrency)
celery -A app.celery_worker.celery_app worker -E --loglevel=info --pool=threads --concurrency=100 --queues=memory_tasks -n memory_worker@%h

# Fast-write worker (thread pool, dedicated queue to avoid blocking normal writes; also consumes memory_rag_tasks)
celery -A app.celery_worker.celery_app worker -E --loglevel=info --pool=threads --concurrency=32 --queues=memory_fast_tasks,memory_rag_tasks -n memory_fast_worker@%h

# Document parsing worker (prefork, CPU-bound)
celery -A app.celery_worker.celery_app worker -E --loglevel=info --pool=prefork --concurrency=4 --queues=document_tasks --max-tasks-per-child=100 -n document_worker@%h

# Periodic tasks worker (reflection engine, various scanners)
celery -A app.celery_worker.celery_app worker -E --loglevel=info --pool=prefork --concurrency=2 --queues=periodic_tasks --max-tasks-per-child=50 -n periodic_worker@%h

# Workflow trigger worker
celery -A app.celery_worker.celery_app worker -E --loglevel=info --pool=prefork --concurrency=2 --queues=workflow_trigger_tasks --max-tasks-per-child=50 -n workflow_trigger_worker@%h

# Beat scheduler
celery -A app.celery_worker.celery_app beat --loglevel=info

# Task scheduler service (enqueue rate limiting and admission control)
python -m app.celery_task_scheduler

Tip: The above are the core workers. For a full deployment (including GraphRAG, subscription/notification, and other Enterprise-edition queue workers), docker-compose up -d is recommended.

4. Frontend Web Application

4.1 Install Dependencies

cd web
npm install

Note: In a corporate intranet, run npm run install:private to install the private component @redbear/memory-brick (use npm run install:private:dev in development). On the public internet, the script auto-detects the environment and skips silently, without affecting startup.

4.2 Update API Proxy Configuration

Edit web/vite.config.ts and point the /api proxy target to the backend API service (the frontend dev server runs on port 5175 by default):

proxy: {
  '/api': {
    target: 'http://127.0.0.1:8000',  // Backend API address — change to your actual deployment address
    changeOrigin: true,
  },
}

4.3 Start the Frontend Service

npm run dev

5. Initialize the System

# Initialize the database and obtain the super admin account
curl -X POST http://127.0.0.1:8000/api/setup

Super admin credentials:

• Account: [email protected]
• Password: admin_password

6. Full Startup Checklist

Step 1  Clone the repository
Step 2  Start base services (PostgreSQL / Neo4j / Redis / Elasticsearch)
Step 3  Configure .env environment variables
Step 4  Run alembic upgrade head to initialize the database
Step 5  uv run -m app.main to start the backend API
Step 6  npm run dev to start the frontend
Step 7  curl -X POST http://127.0.0.1:8000/api/setup to initialize the system
Step 8  Log in to the frontend with the admin account

---

Tech Stack

Layer	Technology
Backend Framework	FastAPI + Uvicorn
Async Tasks	Celery (multi-queue: memory / document / periodic / graphrag, etc.)
Primary Database	PostgreSQL 13+
Graph Database	Neo4j 5.13+ (5.26 LTS recommended, APOC plugin required)
Search Engine	Elasticsearch 8.x (keyword + semantic vector hybrid)
Cache / Queue	Redis 6.0+
ORM	SQLAlchemy 2.0 + Alembic
LLM Integration	LangChain / OpenAI / DashScope / AWS Bedrock
MCP Integration	fastmcp + langchain-mcp-adapters
Frontend Framework	React 18 + TypeScript + Vite (rolldown-vite)
UI Components	Ant Design 5.x
Graph Visualization	AntV X6 + ECharts + D3.js
Package Manager	uv (backend) / npm (frontend)

---

License

This project is licensed under the Apache License 2.0.

---

Community & Support

• Bug Reports & Feature Requests: GitHub Issues
• Contribute: Please read our Contributing Guide. Submit Pull Requests on a feature branch following Conventional Commits format
• Discussions: GitHub Discussions
• WeChat Community: Scan the QR code below to join our WeChat group

• Star History:

• Contact: [email protected]