archiledger

# Archiledger

Archiledger combines Greek *arkhē* (origin, first principle) with "Ledger" - a foundational record serving as the source of truth for AI memory.

**Give your AI assistant a persistent memory and the power to build knowledge graphs.**

Archiledger is a specialized **Knowledge Graph** that serves as a **RAG (Retrieval-Augmented Generation)** system with **vector search**. It is exposed as a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server to enable LLM-based assistants to store, connect, and recall information using a graph database. Whether you need a personal memory bank that persists across conversations or want to analyze codebases and documents into structured knowledge graphs, Archiledger provides the infrastructure to make your AI truly remember.

> **⚠️ Disclaimer:** This server implements **no authentication** and uses an **embedded graph database** designed for **local development only**. Not recommended for production.

## Why Archiledger?

LLMs are powerful, but they forget everything when a conversation ends:

- **Repeating yourself** — Telling your assistant the same preferences over and over
- **Lost insights** — Valuable analysis from one session isn't available in the next
- **No connected thinking** — Information lives in silos without relationships

Archiledger solves this with a **graph-based memory**:

| Problem | Solution |
|---------|----------|
| Context resets every conversation | Persistent notes that survive restarts |
| Flat, disconnected notes | Typed links between atomic notes (Zettelkasten) |
| No categorization | Tags and keywords on every note |
| No temporal awareness | ISO-8601 timestamps on every note |
| Keyword search limits | Vector search finds semantically similar notes |
| Hard to explore large graphs | Graph traversal via `LINKED_TO` relationships |

---

## Four Ways to Use Archiledger

```
┌────────────────────────────────────────────────────────────────────────────┐
│   LOW-LEVEL (Manual Control)              HIGH-LEVEL (AI-Powered)          │
│                                                                            │
│   ┌──────────────────┐                    ┌──────────────────┐             │
│   │  Core Module     │                    │ Agentic Memory   │             │
│   │  (Maven Dep)     │                    │ (Embabel)        │             │
│   │                  │                    │                  │             │
│   │ MemoryNoteService│                    │ • Agent          │             │
│   │ Direct Java API  │                    │ • RAG / Vector   │             │
│   └────────┬─────────┘                    │ • Auto-evolution │             │
│            │                              └────────┬─────────┘             │
│            ▼                                       ▼                       │
│   ┌──────────────────┐                    ┌──────────────────┐             │
│   │  MCP Server      │                    │ Agentic Memory   │             │
│   │  (LLM Tools)     │                    │ MCP              │             │
│   └──────────────────┘                    └──────────────────┘             │
│                                                                            │
│   No LLM Required ◄──────────────────────► LLM Required                    │
└────────────────────────────────────────────────────────────────────────────┘
```

### Quick Decision Guide

| Requirement | Recommended Approach |
|-------------|---------------------|
| Pure Java, no LLM | Core Module (Maven) |
| LLM with full manual control | MCP Server |
| AI classification in Java app | Agentic Memory (Embabel) |
| LLM with automatic memory management | Agentic Memory MCP |
| Full control over tags/links | Core Module or MCP Server |
| Automatic knowledge evolution | Agentic Memory (either) |

---

### 1. Core Module (Maven Dependency)

**Best for:** Java applications that need direct, programmatic control over memory operations without AI involvement.

```xml
<dependency>
    <groupId>com.thecookiezen</groupId>
    <artifactId>archiledger-core</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>
```

The `MemoryNoteService` interface provides full control over note creation, linking, similarity search, and graph traversal. No external LLM dependency required.

### 2. MCP Server (Low-Level Tools)

**Best for:** LLM-based assistants that need direct access to memory operations with full manual control.

The `mcp` module exposes all core operations as MCP tools. The LLM decides how to create notes, add tags, and establish links.

| Category | Tools |
|----------|-------|
| **Note Management** | `create_notes`, `get_note`, `get_notes_by_tag`, `delete_notes` |
| **Link Management** | `add_links`, `delete_links` |
| **Graph Exploration** | `read_graph`, `get_linked_notes`, `get_all_tags`, `search_notes` |

### 3. Agentic Memory (Embabel Module)

**Best for:** Java applications that want AI-powered memory management with automatic classification and evolution.

The `agentic-memory` module provides higher-level abstraction built on the [Embabel framework](https://github.com/embabel/embabel):

- **AgenticMemoryAgent**: Automatically analyzes content and suggests classifications
- **Vector Search**: Semantic similarity search across memory notes
- **Zoom Out Search**: Traverse upward in the knowledge graph to find related context
- **Memory Evolution**: AI evaluates whether new memories should link to existing ones
- **RAG Integration**: Built-in retrieval-augmented generation support

### 4. Agentic Memory MCP

**Best for:** LLM-based assistants that want AI-powered memory with minimal manual management.

The `agentic-memory-mcp` module exposes agentic memory capabilities as MCP tools. The AI handles classification, tagging, and linking automatically.

| Tool | Description |
|------|-------------|
| `memory_vector_search` | Perform semantic similarity search across memory notes |
| `memory_broaden_search` | Given a note ID, expand to find connected/linked notes |
| `memory_zoom_out` | Traverse upward in the knowledge graph to find parent/related notes |
| `agentic_memory_write` | Store content with automatic AI classification, tagging, and link generation |

---

## MCP Tools Reference

### Low-Level MCP Tools

#### Note Management

| Tool | Description |
|------|-------------|
| `create_notes` | Create one or more memory notes with content, keywords, tags, and optional links |
| `get_note` | Retrieve a specific note by ID (increments retrieval counter) |
| `get_notes_by_tag` | Find all notes with a given tag (e.g., `architecture`, `decision`, `bug`) |
| `delete_notes` | Delete notes by their IDs, including associated links and embeddings |

#### Link Management

| Tool | Description |
|------|-------------|
| `add_links` | Add typed links between notes with context (e.g., `DEPENDS_ON`, `RELATED_TO`, `CONTRADICTS`) |
| `delete_links` | Remove typed links between notes |

#### Graph Exploration

| Tool | Description |
|------|-------------|
| `read_graph` | Read the entire knowledge graph (all notes and links) |
| `get_linked_notes` | Find all notes directly connected to a given note |
| `get_all_tags` | List all unique tags currently used across notes |
| `search_notes` | Semantic similarity search with temperature scaling and threshold filtering |

### Agentic Memory MCP Tools

| Tool | Description |
|------|-------------|
| `memory_vector_search` | Semantic similarity search. Params: `query`, `topK` (default: 10), `threshold` (default: 0.5) |
| `memory_broaden_search` | Expand from a note to find connected notes. Params: `noteId`, `limit` (default: 10) |
| `memory_zoom_out` | Traverse upward in graph. Params: `noteId`, `limit` (default: 10) |
| `agentic_memory_write` | Store content with automatic classification. Params: `content` |

---

## Prerequisites

- Java 21 or higher
- Maven

## Building

```bash
mvn clean package
```

Builds all modules:
- `core/targe

[truncated…]