Memind Memory

Self-evolving cognitive memory for AI agents — not just storage, but understanding.

---

memind is a hierarchical cognitive memory system for AI agents, built natively in Java. It goes beyond simple key-value memory — memind automatically extracts, organizes, and evolves knowledge from conversations into a structured Insight Tree, enabling agents to truly understand and remember.

It tackles the core problems of agent memory: flat, unstructured storage (memories are isolated facts with no relationships) and no knowledge evolution (memories never grow or consolidate).

---

Why memind?

Traditional Memory Systems	memind
🗄️ Flat key-value storage	🌳 Hierarchical Insight Tree (Leaf → Branch → Root)
📝 Store raw facts only	🧠 Self-evolving cognition — items are analyzed into multi-level insights
🔍 Single-level retrieval	🎯 Multi-granularity retrieval (detail → summary → profile)
💰 Requires expensive models	🏆 SOTA performance with gpt-4o-mini
🔧 Manual memory management	⚡ Fully automatic extraction pipeline

---

Highlights

🌳 Insight Tree — Hierarchical Knowledge, Not Flat Storage

The Insight Tree is memind's core innovation. Unlike traditional memory systems that store isolated facts, memind progressively distills knowledge through three tiers — each tier sees patterns the previous one cannot:

Tier	Input	What it produces
🍃 Leaf	Grouped memory items	Insights within a single semantic group
🌿 Branch	Multiple leaves	Cross-group patterns within one dimension
🌳 Root	Multiple branches	Cross-dimensional insights invisible at lower levels

Example — understanding a user named Li Wei through conversations:

🍃 Leaf (from career_background group): "Li Wei has 8 years of backend experience — 3 years at Alibaba, then led an 8-person team at a fintech company, designing a core trading system with Java 17 + Spring Cloud + Kafka."

🌿 Branch (integrating career + education + certifications): "Li Wei is a senior backend architect with deep distributed systems expertise, combining Zhejiang University CS training, large-scale Alibaba experience, and hands-on fintech system design — a well-rounded technical profile with both depth and breadth."

🌳 Root (cross-dimensional — identity × preferences × behavior): "Li Wei's preference for functional programming and high code quality (80% test coverage), combined with conservative tech adoption (requires 2+ years production validation), reveals a personality oriented toward long-term code maintainability over rapid innovation — suggesting recommendations should emphasize stability and proven patterns over cutting-edge tools."

Each tier reveals something the previous one couldn't see. Leaves know facts. Branches see patterns. Roots understand the person.

🏆 SOTA with Lightweight Model

Achieved 86.88% overall on the LoCoMo benchmark using only gpt-4o-mini — a lightweight, cost-effective model. This proves that intelligent memory architecture matters more than brute-force model power.

☕ Java-Native — First SOTA Memory for the Java Ecosystem

The first Java-based AI memory system to achieve SOTA-level performance. Built with Spring Boot 4.0 and Spring AI 2.0, memind integrates naturally into Java/Kotlin enterprise stacks with a one-line Maven dependency.

---

Architecture

memind processes conversations through a multi-stage pipeline, from raw dialogue to structured knowledge:

Two-Scope Memory

memind maintains separate memory scopes for comprehensive agent cognition:

Scope	Categories	Purpose
USER	Profile, Behavior, Event	User identity, preferences, relationships, experiences
AGENT	Tool, Procedural	Tool usage patterns, reusable procedures, learned workflows

Dual Retrieval Strategies

Strategy	How it works	Best for
Simple	Vector search + BM25 keyword matching, merged via RRF (Reciprocal Rank Fusion), with adaptive truncation	Low-latency, cost-sensitive scenarios
Deep	LLM-assisted query expansion, sufficiency checking, and reranking	Complex queries requiring reasoning

---

Benchmark

LoCoMo

Evaluation on the LoCoMo benchmark using gpt-4o-mini:

Method	Single Hop	Multi Hop	Temporal	Open Domain	Overall
memind (gpt-4o-mini)	91.56	83.33	82.24	71.88	86.88

memind achieves SOTA-level performance using only gpt-4o-mini — a lightweight, cost-effective model.

---

Quick Start

Installation

Build and install locally:

git clone https://github.com/openmemind-ai/memind.git
cd memind
mvn clean install

Then add the runtime modules you need to your project's pom.xml:

<dependency>
  <groupId>com.openmemind.ai</groupId>
  <artifactId>memind-core</artifactId>
  <version>0.1.0-SNAPSHOT</version>
</dependency>
<dependency>
  <groupId>com.openmemind.ai</groupId>
  <artifactId>memind-plugin-ai-spring-ai</artifactId>
  <version>0.1.0-SNAPSHOT</version>
</dependency>
<dependency>
  <groupId>com.openmemind.ai</groupId>
  <artifactId>memind-plugin-jdbc</artifactId>
  <version>0.1.0-SNAPSHOT</version>
</dependency>

Memind supports two primary integration styles:

• Pure Java: memind-core plus the plugins you need
• Spring Boot infrastructure wiring: plugin starters such as memind-plugin-ai-spring-ai-starter and memind-plugin-jdbc-starter

Usage

// Assemble the runtime once in your application
Memory memory = ...;

// Create a memory identity (user + agent)
MemoryId memoryId = DefaultMemoryId.of("user-1", "my-agent");

// Extract knowledge from conversations
memory.addMessages(memoryId, messages).block();

// Retrieve relevant memories
var result = memory.retrieve(memoryId, "What does the user prefer?",
        RetrievalConfig.Strategy.SIMPLE).block();

Pure Java Bootstrap

Outside Spring Boot, assemble the runtime objects directly and pass them into Memory.builder():

OpenAiApi openAiApi = OpenAiApi.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .baseUrl(System.getenv().getOrDefault("OPENAI_BASE_URL", "https://api.openai.com"))
        .build();

OpenAiChatModel chatModel = OpenAiChatModel.builder()
        .openAiApi(openAiApi)
        .defaultOptions(OpenAiChatOptions.builder().model("gpt-4o-mini").build())
        .observationRegistry(ObservationRegistry.NOOP)
        .build();

EmbeddingModel embeddingModel = new OpenAiEmbeddingModel(
        openAiApi,
        MetadataMode.NONE,
        OpenAiEmbeddingOptions.builder().model("text-embedding-3-small").build());

JdbcMemoryAccess jdbc = JdbcStore.sqlite("./data/memind.db");

Memory memory = Memory.builder()
        .chatClient(new SpringAiStructuredChatClient(ChatClient.builder(chatModel).build()))
        .store(jdbc.store())
        .buffer(jdbc.buffer())
        .textSearch(jdbc.textSearch())
        .vector(SpringAiFileVector.file("./data/vector-store.json", embeddingModel))
        .options(MemoryBuildOptions.builder()
                .extraction(new ExtractionOptions(
                        ExtractionCommonOptions.defaults(),
                        RawDataExtractionOptions.defaults(),
                        ItemExtractionOptions.defaults(),
                        new InsightExtractionOptions(true, new InsightBuildConfig(2, 2, 8, 2))))
                .retrieval(RetrievalOptions.defaults())
                .build())
        .build();

The maintained Java examples wrap this assembly behind a small shared support layer. Start with memind-examples/memind-example-java/README.md and memind-examples/memind-example-java/src/main/java/com/openmemind/ai/memory/example/java/support/ExampleSettings.java if you want the runnable version with centralized configuration defaults.

---

Examples

Clone and run examples to see memind in action:

git clone https://github.com/openmemind-ai/memind.git
cd memind

Maintained Java examples now live in memind-examples/memind-example-java.

They still read shared input data from memind-examples/data, while each scenario writes its own runtime artifacts under target/example-runtime/<scenario> by default.

Configuration is centralized in memind-examples/memind-example-java/src/main/java/com/openmemind/ai/memory/example/java/support/ExampleSettings.java. Set OPENAI_API_KEY first, then optionally enable rerank with MEMIND_EXAMPLES_RERANK_ENABLED=true plus RERANK_API_KEY.

Then run one of the pure Java examples:

# Basic extract + retrieve
mvn -pl memind-examples/memind-example-java -am \
  -Dexec.mainClass=com.openmemind.ai.memory.example.java.quickstart.QuickStartExample \
  exec:java

Run them from your IDE, or invoke them with Maven Exec Plugin using the fully qualified class names below. They all share the same support layer for settings, runtime assembly, and example output formatting.

Runtime	Example	Main Class	Description
Pure Java	QuickStart	com.openmemind.ai.memory.example.java.quickstart.QuickStartExample	Shared runtime bootstrap plus basic addMessages and retrieve
Pure Java	Agent Scope	com.openmemind.ai.memory.example.java.agent.AgentScopeMemoryExample	Shared runtime bootstrap plus agent-scope extraction, insight flush, and targeted retrieval
Pure Java	Insight	com.openmemind.ai.memory.example.java.insight.InsightTreeExample	Shared runtime bootstrap plus lower-threshold insight-tree options
Pure Java	Foresight	com.openmemind.ai.memory.example.java.foresight.ForesightExample	Pure Java foresight extraction and retrieval
Pure Java	Tool	com.openmemind.ai.memory.example.java.tool.ToolMemoryExample	Pure Java tool call tracking and aggregated statistics

---

Core Capabilities

Category	Capability	Description
Extraction	Conversation Segmentation	Automatic boundary detection and segmentation for streaming messages
	Memory Item Extraction	Extract structured facts with deduplication across 5 categories
	Insight Tree Construction	Hierarchical knowledge building: Leaf → Branch → Root
	Foresight Prediction	Predict future user needs based on conversation patterns
	Tool Call Statistics	Track tool usage patterns and success rates
Retrieval	Simple Strategy	Vector + BM25 hybrid search with RRF fusion and adaptive truncation
	Deep Strategy	LLM-assisted query expansion, sufficiency checking, and reranking
	Intent Routing	Automatically determine whether retrieval is needed
	Multi-granularity	Retrieve from any Insight Tree tier based on query needs
Integration	Pure Java Runtime	memind-core plus plugins assembled through Memory.builder()
	Spring Boot Infrastructure Starters	Optional infrastructure wiring with memind-plugin-ai-spring-ai-starter and memind-plugin-jdbc-starter
	Plugin Architecture	Pluggable store (SQLite, MySQL) and tracing (OpenTelemetry)

---

Tech Stack

Component	Technology
Language	Java 21
Framework	Spring Boot 4.0, Spring AI 2.0
Data Store	SQLite (default), MySQL (plugin)
Vector Store	Qdrant, JSON file (for examples)
Observability	OpenTelemetry, Micrometer
Build	Maven

---

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

License

Apache License 2.0