MemoryCore

NeuralSleep-Compatible Memory Consolidation System for Luna

MemoryCore is a production implementation of the NeuralSleep theoretical architecture, providing genuine temporal integration and experience-dependent learning for the Luna Chinese language learning platform.

Overview

MemoryCore implements a three-tier memory system that mirrors biological memory consolidation:

Working Memory (Redis)
  ↓ Consolidation (session end)
Episodic Memory (PostgreSQL)
  ↓ Consolidation (daily/weekly)
Semantic Memory (PostgreSQL)

Core Principle: Memory as structural modification (weight updates), not storage/retrieval. Past experiences shape present processing through integrated structure.

Features

Multi-Timescale Memory: Working (seconds-minutes), Episodic (hours-days), Semantic (persistent)
Consolidation Cycles: Immediate, daily, and weekly consolidation mimicking biological sleep
Temporal Dynamics: Exponential moving averages approximating Liquid Neural Networks
Pattern Extraction: Automatic discovery of learning patterns from experience
Meta-Learning: System learns how users learn, not just what they know
Personalized Teaching: Recommendations based on consolidated user models

Quick Start

Prerequisites

Node.js 18+
Docker and Docker Compose
PostgreSQL 15+ (or use Docker)
Redis 7+ (or use Docker)

Installation

Clone the repository:

cd /opt/memorycore

Install dependencies:

npm install

Configure environment:

cp .env.example .env
# Edit .env with your configuration

Start services with Docker:

docker-compose up -d postgres redis

Run database migrations:

npm run migrate

Start development server:

npm run dev

The API will be available at http://localhost:3002.

Verify Installation

Check the health endpoint:

curl http://localhost:3002/api/health

Expected response:

{
  "status": "healthy",
  "services": {
    "redis": "up",
    "postgres": "up",
    "queue": "up"
  }
}

Development

Available Scripts

npm run dev          # Start development server with hot reload
npm run build        # Build TypeScript to dist/
npm start            # Start production server
npm test             # Run tests
npm run test:watch   # Run tests in watch mode
npm run lint         # Run ESLint
npm run format       # Format code with Prettier
npm run migrate      # Run database migrations

Project Structure

/opt/memorycore/
├── src/
│   ├── memory/          # Memory system implementations
│   │   ├── WorkingMemory.ts
│   │   ├── EpisodicMemory.ts
│   │   └── SemanticMemory.ts
│   ├── consolidation/   # Consolidation engine
│   │   ├── ConsolidationQueue.ts
│   │   ├── ConsolidationEngine.ts
│   │   └── TemporalDynamics.ts
│   ├── api/             # REST API
│   │   ├── server.ts
│   │   └── routes/
│   ├── lib/             # Shared libraries
│   │   ├── db/          # Database connection
│   │   └── logger/      # Logging
│   ├── types/           # TypeScript types
│   └── utils/           # Utilities
├── migrations/          # SQL migrations
├── tests/               # Test suites
├── docker-compose.yml   # Docker services
└── package.json

Running Tests

# Run all tests
npm test

# Run specific test suite
npx jest tests/unit/memory/WorkingMemory.test.ts

# Run with coverage
npm run test:coverage

Database Operations

# Run migrations
npm run migrate

# Create new migration
npm run migrate:create add_new_table

# Connect to database
docker exec -it memorycore-postgres psql -U memorycore -d memorycore

Redis Operations

# Connect to Redis
docker exec -it memorycore-redis redis-cli

# Check working memory
KEYS session:*

# Monitor operations
MONITOR

API Documentation

Memory Operations

Start Session

POST /api/memory/session/start
Authorization: Bearer <JWT>

{
  "userId": "user123",
  "context": {
    "lessonType": "radicals",
    "difficulty": 0.5
  }
}

Record Interaction

POST /api/memory/interaction
Authorization: Bearer <JWT>

{
  "sessionId": "session123",
  "interaction": {
    "type": "practice",
    "characterId": "你",
    "correct": true,
    "timeSpent": 2500,
    "timestamp": "2025-10-29T10:00:00Z"
  }
}

End Session

POST /api/memory/session/end
Authorization: Bearer <JWT>

{
  "sessionId": "session123",
  "summary": {
    "duration": 1200,
    "interactions": 25,
    "successRate": 0.85
  }
}

Get User Model

GET /api/memory/user/:userId/model
Authorization: Bearer <JWT>

Get Recommendations

GET /api/memory/user/:userId/recommendations
Authorization: Bearer <JWT>

Consolidation Management

Trigger Manual Consolidation

POST /api/consolidation/trigger
Authorization: Bearer <JWT>

{
  "type": "immediate",
  "userId": "user123"
}

Check Status

GET /api/consolidation/status/:userId
Authorization: Bearer <JWT>

Architecture

Three-Tier Memory System

1. Working Memory (Redis)

Purpose: Real-time interaction handling
Timescale: Seconds to minutes
Storage: Redis with 30-minute TTL
Plasticity: High (rapid updates)

2. Episodic Memory (PostgreSQL)

Purpose: Recent session history and patterns
Timescale: Hours to days
Storage: Time-series event tables
Retention: 90 days

3. Semantic Memory (PostgreSQL)

Purpose: Long-term user models
Timescale: Persistent
Storage: JSONB models
Updates: Slow, weighted consolidation

Consolidation Cycles

Immediate Consolidation (Working → Episodic):

Triggered: After session end
Duration: ~2 seconds
Process: Extract session summary, identify significant events, store in episodic memory

Daily Consolidation (Episodic → Semantic):

Triggered: 2 AM (configurable)
Duration: ~30 seconds per user
Process: Extract patterns from 24h events, update proficiency models

Weekly Consolidation (Deep Semantic):

Triggered: 3 AM Sunday (configurable)
Duration: ~60 seconds per user
Process: Compute meta-patterns, update learning styles, prune old data

Temporal Dynamics

MemoryCore approximates Liquid Neural Networks using exponential moving averages:

newValue = oldValue * (1 - alpha) + evidence * alpha
alpha = 1 - exp(-timeSinceUpdate / timeConstant)

Time constants:

Working Memory: 100ms - 1s
Episodic Memory: 1s - 10min
Semantic Memory: 10min - days

Integration with Luna

MemoryCore integrates with Luna (/opt/luna-app/) to provide personalized learning.

Luna Configuration

Add to Luna's .env.production:

MEMORYCORE_URL=http://memorycore:3002
MEMORYCORE_ENABLED=true
JWT_SECRET=<same-as-memorycore>

Luna Integration Example

import { startMemorySession, recordInteraction, endMemorySession } from '@/lib/session/memorycore';

// Start session
const sessionId = await startMemorySession(userId, 'radicals');

// Record interactions
await recordInteraction(sessionId, {
  type: 'practice',
  characterId: '你',
  correct: true,
  timeSpent: 2500,
  timestamp: new Date()
});

// End session
await endMemorySession(sessionId, {
  duration: 1200,
  interactions: 25,
  successRate: 0.85
});

Configuration

Environment Variables

See .env.example for all available configuration options.

Key variables:

POSTGRES_*: Database connection
REDIS_*: Redis connection
JWT_SECRET: Shared with Luna for authentication
CONSOLIDATION_ENABLED: Enable/disable consolidation
*_CONSOLIDATION_CRON: Scheduling for consolidation jobs

Time Constants

Adjust temporal dynamics in .env:

WORKING_MEMORY_TTL=1800           # 30 minutes
EPISODIC_RETENTION_DAYS=90        # 90 days
SEMANTIC_LEARNING_RATE=0.01       # Slow updates

Monitoring

Health Check

curl http://localhost:3002/api/health

Metrics

curl http://localhost:3002/api/metrics

Logs

# Docker logs
docker-compose logs -f api

# Specific service
docker-compose logs postgres
docker-compose logs redis

Bull Queue Dashboard

Access at http://localhost:3002/admin/queues (if enabled).

Deployment

Production Build

# Build TypeScript
npm run build

# Start production server
NODE_ENV=production npm start

Docker Production

docker-compose -f docker-compose.prod.yml up -d

Environment Setup

Copy .env.example to .env.production
Update with production values (strong JWT_SECRET, secure passwords)
Configure PostgreSQL with SSL
Enable Redis persistence (AOF)
Set up monitoring (Prometheus + Grafana)

Testing

Unit Tests

npm test

Integration Tests

npm run test:integration

Research Validation

MemoryCore includes tests for validating NeuralSleep principles:

Memory consolidation effects
Pattern emergence
Meta-learning indicators
Temporal continuity

Performance Targets

Session start: < 100ms (P95)
Interaction recording: < 50ms (P95)
Session consolidation: < 2s
Daily consolidation: < 30s per user
API uptime: 99.9%

Troubleshooting

Database Connection Failed

# Check PostgreSQL is running
docker ps | grep postgres

# Check connection
docker exec -it memorycore-postgres pg_isready -U memorycore

Redis Connection Failed

# Check Redis is running
docker ps | grep redis

# Test connection
docker exec -it memorycore-redis redis-cli ping

Consolidation Jobs Stuck

# Check Bull queue
redis-cli LLEN bull:memory-consolidation:waiting

# Clear stuck jobs (use with caution)
redis-cli DEL bull:memory-consolidation:stalled

Contributing

See planning.md for the 14-week implementation roadmap.

Current phase: Phase 1 - Foundation (Weeks 1-2)

Next steps:

Implement Working Memory service
Implement Episodic Memory service
Implement Semantic Memory service

Documentation

CLAUDE.md: Claude Code guidance
MemoryCore.md: Complete technical specification
planning.md: Implementation roadmap
NeuralSleep.md (/opt/neuralsleep/): Theoretical foundation

Research Context

MemoryCore is a testbed for machine consciousness, not just a personalization engine.

Research questions:

Does consolidation create genuine temporal continuity?
Do teaching strategies evolve through structural modification?
Is meta-learning emergent (not programmed)?
Are adaptations persistent across time?

License

MIT License

Contact

Research Site: bitwarelabs.com
Luna Platform: studywithluna.com
Email: research@bitwarelabs.com

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
migrations		migrations
src		src
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierrc		.prettierrc
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
MemoryCore.md		MemoryCore.md
OPENWEBUI_QUICKSTART.md		OPENWEBUI_QUICKSTART.md
README.md		README.md
docker-compose.yml		docker-compose.yml
git_instructions.md		git_instructions.md
jest.config.js		jest.config.js
package.json		package.json
planning.md		planning.md
tsconfig.json		tsconfig.json

Bitwarelabscom/memorycore

Folders and files

Latest commit

History

Repository files navigation