Persistent memory for AI agents. Retain context across conversations, learn from every interaction, and transform stateless systems into context-aware applications that truly remember.
A production-grade memory infrastructure for AI agents built on the Model Context Protocol (MCP). Memron enables persistent, portable, and private memory that works across platforms, providers, and sessions through hardware-backed zero-trust architecture and pointer-based context compression.
Key Innovation: Pointer-based context transfer achieving 89-95% token compression. Instead of sending entire conversation histories, Memron uses smart pointers to relevant memories, reducing inference costs by 10-100x while delivering surgical context injection.
- System Overview
- Architecture
- Memory Pipeline
- Technology Stack
- Installation
- Configuration
- MCP Integration
- API Documentation
- Storage Options
- Monorepo Structure
- Contributing
Memron solves the context amnesia problem in AI systems through a distributed memory backbone. Traditional AI agents suffer from memory loss between sessions, context locked in silos, and no user ownership of conversation data. This results in degraded output quality, massive token waste, and zero portability between platforms.
The system implements a bucketed memory architecture that organizes context into thematic partitions (Conversation, Tools, Preferences, Knowledge), each with cryptographic integrity verification and hardware-backed access control. Memory operations flow through a multi-stage pipeline ensuring input validation, canonical normalization, intelligent routing, and distributed persistence with forensic audit capabilities.
Core Capabilities:
- Cross-platform memory transfer via MCP protocol standard
- AES-256-GCM encryption with identity-based access control
- Persistent storage with immutable verification
- Forensic snapshots for poisoning detection and state rollback
- 89-95% token compression through pointer-based retrieval
- Identity-based access control with RFC3339 timestamp expiration
This architecture enables AI agents to maintain persistent context across sessions, platforms, and providers while ensuring user sovereignty over memory ownership and privacy. The system is designed for production environments with comprehensive observability, error handling, and scalability.
The system implements a layered architecture separating concerns across MCP client interface, memory processing pipeline, and distributed storage backends. Each layer exposes health check endpoints and structured metadata for comprehensive observability and debugging.
┌─────────────────────────────────────────────────────────────┐
│ MCP CLIENT (Agents) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Cursor │ │ Claude │ │ Windsurf │ │
│ │ Desktop App │ │ Desktop App │ │ Desktop App │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
↓ MCP Protocol (JSON-RPC)
┌─────────────────────────────────────────────────────────────┐
│ MEMRON MCP SERVER (Node.js) │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ TOOL ROUTING & ORCHESTRATION │ │
│ │ Tool Registry → Permission Checks → Dispatch │ │
│ └────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ PERCEPTION LAYER (Observable) │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Memory │ │ Query │ │ Access │ │ │
│ │ │ Write │ │ Parse │ │ Verify │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ │ │
│ └────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ NORMALIZATION LAYER (Observable) │ │
│ │ Bucketing → Deduplication → Embedding Generation │ │
│ └────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ MEMORY MANAGEMENT LAYER - Four Buckets │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
│ │ │Conversation│ │ Tools │ │Preferences │ │ │
│ │ └────────────┘ └────────────┘ └────────────┘ │ │
│ │ ┌────────────┐ │ │
│ │ │ Knowledge │ │ │
│ │ └────────────┘ │ │
│ │ Semantic Search · Vector Similarity · Temporal Decay │ │
│ └────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ PERSISTENCE LAYER (Observable) │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Local │ │ Object │ │ AES-256 │ │ │
│ │ │ SQLite │ │ Storage │ │ -GCM │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ │ │
│ │ Forensic Snapshots · Encryption · Integrity Checks │ │
│ └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
The MCP client layer interfaces with AI agents through the standardized Model Context Protocol, exposing memory operations as tools that agents can invoke directly. The server layer orchestrates the full memory pipeline with independent processing stages for input validation, context normalization, intelligent bucketing, and distributed persistence with cryptographic integrity checks.
The memory pipeline implements a four-stage processing workflow that transforms raw agent interactions into structured, retrievable memory artifacts. Each stage executes independently with comprehensive error handling and observability.
The perception stage validates incoming memory writes and queries, ensuring well-formed inputs before processing. This stage implements input sanitization to prevent injection attacks, permission verification through DID-based access control, rate limiting to prevent abuse, and content classification to determine appropriate bucket routing. Outputs include validated memory objects with normalized timestamps, extracted metadata tags, and preliminary confidence scores.
Once perception validates the input, normalization transforms heterogeneous memory formats into a canonical representation. This stage performs bucket classification into one of four thematic categories (Conversation, Tools, Preferences, Knowledge), embedding generation through OpenAI's text-embedding-3-small model for semantic search, deduplication detection through vector similarity comparison to prevent redundant storage, and content chunking for memories exceeding single-chunk limits. The normalized memory includes 1536-dimensional semantic embeddings, bucket assignments, conflict resolution metadata, and dedupe fingerprints.
The memory management stage handles intelligent retrieval and injection of relevant context based on agent queries. This stage employs semantic search across vector embeddings with cosine similarity scoring, temporal decay functions to prioritize recent memories while maintaining access to historical context, cross-bucket fusion to build comprehensive context from multiple memory categories, and relevance ranking with configurable thresholds. Retrieval queries return ranked memory pointers with relevance scores between 0-1, temporal decay factors, original content or summaries, metadata including tags and sources, and storage references for verification.
The final persistence stage commits memories to storage with cryptographic integrity guarantees. This stage executes forensic snapshots before mutations to enable rollback and poisoning detection, AES-256-GCM encryption ensuring only authorized identities can decrypt memories, and local SQLite caching for rapid sub-millisecond access. Each memory write produces a unique storage identifier, encrypted payload reference with access control metadata, snapshot reference for pre-mutation state, and cache entry for performance optimization.
Each pipeline stage exposes health check endpoints through the /health API and emits structured logs with execution metrics for monitoring dashboards. The sequential execution ensures data integrity while the observable design enables granular debugging and performance optimization in production environments.
The system employs modern, production-grade technologies selected for performance, security, and developer experience. The technology choices reflect requirements for reliable storage, cryptographic security, and standards-based integration.
The MCP server runs on Node.js 20+ providing access to the latest language features and performance improvements. TypeScript 5.6 ensures type safety with strict mode enforcement and modern decorators support. The MCP SDK implements the Model Context Protocol specification version 2024-11-05, exposing memory operations as standardized tools accessible to any MCP-compatible AI agent. sqlite3 with better-sqlite3 bindings provides local persistence with WAL mode for concurrent access and full-text search capabilities.
Local SQLite instances serve as performance-optimized storage with LRU eviction policies and JSON support for flexible schema evolution. AES-256-GCM encryption ensures only authorized identities with valid access grants can decrypt memories. The storage architecture supports pluggable backends for flexible deployment options.
OpenAI's text-embedding-3-small model generates 1536-dimensional embeddings optimized for semantic similarity at reduced cost compared to larger embedding models. The system implements cosine similarity search with configurable threshold filtering and optional FAISS acceleration for memory sets exceeding 10,000 entries. Temporal decay functions incorporate recency bias using exponential decay with configurable half-life parameters, ensuring fresh memories receive priority while maintaining access to historical context.
The landing page leverages Next.js 15 with App Router for optimal performance through automatic code splitting, React Server Components, and static generation. Tailwind CSS 4.0 provides utility-first styling with custom design tokens, responsive breakpoints, and dark mode support. The dashboard application uses React 18 with concurrent features, Suspense boundaries for progressive loading, and optimistic UI updates for perceived performance.
The installation process requires setting up the MCP server, configuring storage backends, and optionally deploying frontend applications. The system supports multiple deployment modes from local development to production cloud environments.
Before installation, ensure you have Node.js 20 or later installed along with pnpm 9.15+ for workspace management. Obtain API credentials from OpenAI for embedding generation (platform.openai.com).
Clone the repository and install all workspace dependencies:
git clone https://github.com/memron-ai/memron.git
cd memron
pnpm installBuild all packages in dependency order using Turbo:
pnpm buildThe build process compiles TypeScript packages, generates type definitions, and prepares distribution bundles for all workspace packages.
Navigate to the MCP server package and configure environment variables:
cd packages/mcp-server
cp .env.example .envEdit the .env file with your configuration:
# Storage Configuration
STORAGE_TYPE=local # local | postgres | hybrid
SQLITE_PATH=./data/memron.db # Local database path
# OpenAI Configuration (Required)
OPENAI_API_KEY=sk-... # API key for embeddings
# Server Configuration
MCP_LOG_LEVEL=info # debug | info | warn | errorStart the MCP server in development mode:
pnpm devThe server initializes the MCP protocol, logs available tools and health check results, and begins listening for agent connections.
Configuration is managed through environment variables for security and deployment flexibility. Advanced scenarios support JSON configuration files for complex memory routing rules and access policies.
The STORAGE_TYPE variable determines the persistence strategy. Setting it to local uses SQLite only, providing rapid development iteration and single-user deployments with no external dependencies. Setting it to postgres enables PostgreSQL-backed storage for production multi-user deployments. Setting it to hybrid combines local SQLite caching with PostgreSQL persistence, optimizing for both performance through local reads and durability through database distribution.
AES-256-GCM encryption is enabled by default for all memory records. The system supports granular access control with time-limited grants specified in RFC3339 format, allowing temporary access delegation that automatically expires. Access policies can be configured per memory bucket, enabling different security models for conversation history versus sensitive preferences.
The default embedding model is OpenAI's text-embedding-3-small generating 1536-dimensional vectors. Alternative models can be configured through the server configuration file, including local embedding models for air-gapped environments or specialized domain embedding models for improved semantic search in technical domains. The system supports embedding dimension adaptation through PCA projection for compatibility across different model dimensions.
Memron exposes memory operations through standardized MCP tools that AI agents can invoke directly without client-side integration code. Integration requires adding Memron to the MCP client configuration file.
Edit the Claude Desktop configuration located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows:
{
"mcpServers": {
"memron": {
"command": "node",
"args": ["/absolute/path/to/memron/packages/mcp-server/dist/index.js"],
"env": {
"OPENAI_API_KEY": "sk-...",
"STORAGE_TYPE": "local",
"SQLITE_PATH": "/absolute/path/to/memron.db"
}
}
}
}Restart Claude Desktop to activate the integration. Memron tools will appear in the tool selection panel, allowing Claude to read and write memories during conversations.
The MCP server exposes five primary tools following the Model Context Protocol specification:
memron_write: Write a new memory to a specific bucket with optional metadata, tags, and access control grants. Accepts content string, bucket name, metadata object, and optional expiration timestamp.
memron_query: Retrieve relevant memories using semantic search across specified buckets. Accepts query string, bucket array, result limit, and minimum relevance score threshold.
memron_list_buckets: List all available memory buckets with statistics including entry counts, total storage size, and last update timestamps.
memron_snapshot Create a forensic snapshot of current memory state for rollback capability. Returns snapshot CID and timestamp.
memron_rollback: Rollback memory state to a previous snapshot identified by CID. Validates snapshot integrity before restoration.
Each tool returns structured JSON responses with success status, data payload, and comprehensive error details including error codes and troubleshooting suggestions.
The MCP server implements the Model Context Protocol specification with memory-specific tool definitions and error handling. All API responses follow consistent JSON structures for interoperability.
The memron_write tool accepts a memory object with required content and bucket fields:
{
"content": "User prefers TypeScript over JavaScript for type safety and tooling",
"bucket": "preferences",
"metadata": {
"source": "conversation",
"confidence": 0.95,
"tags": ["language", "typescript", "coding-style"]
},
"access": {
"readers": ["did:key:z6Mk..."],
"expiresAt": "2027-02-13T23:59:59Z"
}
}Response includes the assigned memory ID (UUID v4), storage identifier for verification, embedding vector summary with dimension and norm information, snapshot reference capturing pre-mutation state, and success boolean with optional error details.
The memron_query tool performs semantic search across specified memory buckets:
{
"query": "What are the user's coding preferences and style guidelines?",
"buckets": ["preferences", "tools", "conversation"],
"limit": 10,
"minScore": 0.7,
"includeMetadata": true
}Response returns an array of ranked memories sorted by combined relevance and temporal scores. Each result includes the relevance score (0-1) from cosine similarity, temporal decay factor based on memory age, original content string or summary for large memories, metadata object with tags and source information, storage reference for content verification, and creation timestamp in ISO 8601 format.
The server exposes health monitoring endpoints for operational visibility:
GET /health → Overall system health with status and component checks
GET /health/storage → Storage backend connectivity and capacity
GET /health/embeddings → Embedding service status and model info
GET /health/encryption → Encryption service status
Health responses include status enum (operational | degraded | offline), component-specific metrics, recent error counts, and timestamp of last successful operation.
Memron provides flexible storage backends optimized for different deployment scenarios, privacy requirements, and performance characteristics.
The local storage backend uses SQLite with Write-Ahead Logging (WAL) mode for concurrent access and improved write performance. Ideal for development environments, testing scenarios, and single-user deployments requiring rapid iteration. Memories persist in a single database file with automatic checkpointing, full-text search indexes, and JSON column support for flexible schema evolution. No external dependencies or network access required. Backup strategy involves simple file-level replication or continuous archival.
The PostgreSQL backend provides production-grade relational storage with full ACID compliance, connection pooling, and horizontal read scaling. Memories are stored with structured indexes for efficient semantic and temporal queries. Supports pgvector extension for native vector similarity search at scale.
The hybrid backend combines local SQLite caching with PostgreSQL persistence, optimizing for both performance and durability. Frequently accessed memories populate the local cache for sub-millisecond retrieval while all memories persist to PostgreSQL for reliability. Cache eviction uses LRU (Least Recently Used) policy with configurable size limits. Cache misses trigger database fetch with automatic cache population. Write operations commit to both local cache and database concurrently.
The project uses a pnpm workspace monorepo with Turbo for incremental builds and caching. This structure enables code sharing, unified dependency management, and optimized build performance.
memron/
├── apps/
│ ├── landing/ # Next.js landing page
│ └── platform/ # React dashboard (coming soon)
├── packages/
│ ├── mcp-server/ # MCP server implementation
│ ├── shared-types/ # TypeScript type definitions
│ ├── memory-core/ # Core memory orchestration
│ └── trust-registry/ # Trust scoring engine
├── docs/ # Architecture documentation
├── package.json # Root workspace configuration
├── pnpm-workspace.yaml # Workspace package definitions
└── turbo.json # Turbo build pipeline config
Each package exposes a clean API through TypeScript exports, enabling modular consumption and independent testing. The shared-types package provides canonical type definitions used across all packages, ensuring type consistency. Build outputs are cached by Turbo based on input file hashes, dramatically reducing rebuild times during development.
Memron is open source under the Business Source License 1.1 (BUSL-1.1), automatically converting to Apache 2.0 four years after publication. We welcome contributions from the community including bug fixes, feature implementations, documentation improvements, and testing enhancements.
Fork the repository on GitHub and clone your fork locally. Install all workspace dependencies with pnpm install and build packages with pnpm build. Run the test suite with pnpm test to verify correct setup. The development workflow uses Turbo for fast incremental builds and hot module replacement during active development.
Submit pull requests to the main branch with clear descriptions of changes, motivations, and any breaking changes. Include tests for new features and bug fixes, ensuring coverage metrics remain above 80% for core packages. Follow existing TypeScript conventions enforced by ESLint and Prettier, running pnpm lint and pnpm format before committing. Update documentation for user-facing changes including tool APIs, configuration options, and deployment guides.
Report bugs through GitHub Issues using the provided templates for bug reports, feature requests, and documentation issues. Include minimal reproduction cases with steps to reproduce, expected versus actual behavior, system information (OS, Node version, package versions), and relevant error logs or stack traces. For security vulnerabilities, email security@memron.ai directly with encrypted messages to our PGP key rather than filing public issues.
This project is licensed under the Business Source License 1.1 (BUSL-1.1). The licensed work automatically converts to Apache License 2.0 four years after each version's publication date. See LICENSE for complete details.
Additional Use Grant: You may use the licensed work for production purposes in non-commercial open source projects and during development/testing for commercial projects without waiting for the conversion date. Commercial production use requires a commercial license agreement.
Building the memory layer for the Internet of Agents
Website · Documentation · GitHub · Discord · Twitter