archiledger (Thecookiezen)

档案分类账

Archiledger结合了希腊语 *方舟子* （起源，第一原则）与“Ledger”-作为人工智能记忆真理来源的基础记录。

给你的人工智能助手一个持久的记忆和构建知识图的能力。

Archiledger是一个专业 知识图谱 它作为一个 RAG（检索增强生成） 系统与 向量搜索。它被暴露为 模型上下文协议（MCP） 服务器，使基于LLM的助手能够使用图形数据库存储、连接和调用信息。无论你是需要一个在对话中持续存在的个人记忆库，还是想将代码库和文档分析成结构化的知识图，Archiledger都能提供基础设施，让你的人工智能真正记住。

⚠️ 免责声明： 此服务器实现 无需认证 并使用 嵌入式图形数据库 设计用于 仅限于本地开发不建议用于生产。

为什么是Archiledger？

LLMs很强大，但当谈话结束时，他们会忘记一切：

• 重复自己 --一遍又一遍地告诉你的助手同样的偏好
• 失去洞察力 --一次会议的有价值的分析在下一次会议中不可用
• 无关联思维 --信息存在于没有关系的孤岛中

Archiledger通过一个 基于图形的存储器:

______________________________________________________________________

使用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                    │
└────────────────────────────────────────────────────────────────────────────┘

快速决策指南

______________________________________________________________________

1.核心模块（Maven依赖）

最适合： 需要在没有人工智能参与的情况下对内存操作进行直接编程控制的Java应用程序。

    com.thecookiezen
    archiledger-core
    1.0.0-SNAPSHOT

这 MemoryNoteService 该界面提供了对笔记创建、链接、相似性搜索和图遍历的完全控制。不需要外部LLM依赖关系。

2.MCP服务器（低级工具）

最适合： 基于LLM的助手，需要通过完全手动控制直接访问内存操作。

这 mcp 该模块将所有核心操作作为MCP工具公开。LLM决定如何创建注释、添加标签和建立链接。

3.代理记忆（Embabel模块）

最适合： 需要具有自动分类和进化功能的AI驱动内存管理的Java应用程序。

这 agentic-memory 模块提供基于 Embabel框架:

• Agent内存代理：自动分析内容并建议分类
• 向量搜索：跨记忆笔记的语义相似性搜索
• 缩小搜索：在知识图中向上遍历以查找相关上下文
• 记忆进化：AI评估新记忆是否应该链接到现有记忆
• RAG集成：内置检索增强生成支持

4.代理记忆MCP

最适合： 基于LLM的助手需要人工智能驱动的内存，只需要最少的手动管理。

这 agentic-memory-mcp 该模块将代理内存功能作为MCP工具公开。AI自动处理分类、标记和链接。

______________________________________________________________________

MCP工具参考

低级MCP工具

笔记管理

链路管理

图形探索

代理记忆MCP工具

______________________________________________________________________

先决条件

• Java 21或更高版本
• 梅文

建筑

mvn clean package

构建所有模块：

• core/target/archiledger-core-*.jar -核心库
• mcp/target/archiledger-server-*.jar -低级MCP服务器
• agentic-memory/target/agentic-memory-*.jar -代理记忆库
• agentic-memory-mcp/target/agentic-memory-mcp-*.jar -代理内存MCP服务器

跑步

低级MCP服务器

服务器在端口上使用流式HTTP传输 8080.

瞬态（内存中）：

java -jar mcp/target/archiledger-server-1.0.0-SNAPSHOT.jar

持久性：

java -Dladybugdb.data-path=./archiledger.lbdb \
     -jar mcp/target/archiledger-server-1.0.0-SNAPSHOT.jar

代理内存MCP服务器

AI功能需要LLM配置。

瞬态：

java -jar agentic-memory-mcp/target/agentic-memory-mcp-1.0.0-SNAPSHOT.jar

持久性：

java -Dladybugdb.data-path=./archiledger.lbdb \
     -jar agentic-memory-mcp/target/agentic-memory-mcp-1.0.0-SNAPSHOT.jar

使用Docker运行

瞬态（容器停止时数据丢失）：

docker run -p 8080:8080 registry.hub.docker.com/thecookiezen/archiledger:latest

持久（数据保存到主机文件系统）：

docker run -p 8080:8080 -v /path/to/local/data:/data registry.hub.docker.com/thecookiezen/archiledger:latest

自定义数据目录：

docker run -p 8080:8080 \
  -e LADYBUGDB_DATA_PATH=/custom/data/archiledger.lbdb \
  -v /path/to/local/data:/custom/data \
  registry.hub.docker.com/thecookiezen/archiledger:latest

注： 这 /data 卷必须可由UID 1000写入(spring 用户）。

用Docker运行代理内存MCP

代理内存mcp服务器需要LLM配置才能实现AI功能。

瞬态（容器停止时数据丢失）：

docker run -p 8080:8080 \
  -e OPENAI_CUSTOM_BASE_URL=https://api.example.com \
  -e OPENAI_CUSTOM_MODELS=model-name \
  -e OPENAI_CUSTOM_API_KEY=your_api_key \
  registry.hub.docker.com/thecookiezen/archiledger-agentic-memory:latest

持久（数据保存到主机文件系统）：

docker run -p 8080:8080 \
  -v /path/to/local/data:/data \
  -e OPENAI_CUSTOM_BASE_URL=https://api.example.com \
  -e OPENAI_CUSTOM_MODELS=model-name \
  -e OPENAI_CUSTOM_API_KEY=your_api_key \
  registry.hub.docker.com/thecookiezen/archiledger-agentic-memory:latest

LLM配置环境变量

代理内存Docker环境变量

注： 这 /data 卷必须可由UID 1000写入(spring 用户）。

图形可视化

使用 Ladybug检测仪 要可视化您的图形：

1. 打开BugScope并使用Ladybug数据目录URI进行连接
2. 运行Cypher查询，如下所示 MATCH (n) RETURN n 探索你的知识图谱

______________________________________________________________________

配置

服务器属性

spring.ai.mcp.server.name=archiledger-server
spring.ai.mcp.server.version=1.0.0
spring.ai.mcp.server.protocol=STREAMABLE
server.port=8080

CORS配置

开发（许可）：

cors.enabled=true
cors.allow-any-origin=true

生产（受限）：

cors.enabled=true
cors.origins=https://my-secure-frontend.internal
cors.allow-credentials=true

动态子域：

cors.enabled=true
cors.match-origins=^http://localhost:\\d+$,^https://.*\\.my-company\\.com$

\[！重要\] 对于经过认证的请求，使用显式的起源或正则表达式模式。 cors.allow-any-origin 对于经过认证的请求，浏览器将拒绝。

向量存储

嵌入使用LadybugDB的原生向量扩展和HNSW索引进行存储。

HNSW索引配置

调整HNSW（分层导航小世界）索引参数以获得最佳性能：

资源估算（10k条记录，384个暗矢量）：

嵌入模型配置

默认情况下，Archiledger使用本地ONNX模型(all-MiniLM-L6-v2384个尺寸），其不需要外部API。您可以使用环境变量自定义嵌入模型。

模型比较

选项1：自定义拥抱面ONNX型号

使用HuggingFace的任何ONNX兼容型号：

export SPRING_AI_EMBEDDING_TRANSFORMER_ONNX_MODELURI=https://huggingface.co/BAAI/bge-small-en-v1.5/resolve/main/onnx/model.onnx
export SPRING_AI_EMBEDDING_TRANSFORMER_TOKENIZER_URI=https://huggingface.co/BAAI/bge-small-en-v1.5/resolve/main/tokenizer.json
export LADYBUGDB_EMBEDDING_DIMENSIONS=384

java -jar mcp/target/archiledger-server-1.0.0-SNAPSHOT.jar

选项2:OpenAI兼容API（OpenAI、智普AI、Mistral等）

# OpenAI
export SPRING_AI_OPENAI_BASE_URL=https://api.openai.com
export SPRING_AI_OPENAI_API_KEY=sk-your-api-key
export SPRING_AI_OPENAI_EMBEDDING_OPTIONS_MODEL=text-embedding-3-small
export LADYBUGDB_EMBEDDING_DIMENSIONS=1536

# ZhiPu AI
export SPRING_AI_OPENAI_BASE_URL=https://open.bigmodel.cn/api/paas/v4
export SPRING_AI_OPENAI_API_KEY=your-zhipu-api-key
export SPRING_AI_OPENAI_EMBEDDING_OPTIONS_MODEL=embedding-3
export LADYBUGDB_EMBEDDING_DIMENSIONS=2048

java -jar mcp/target/archiledger-server-1.0.0-SNAPSHOT.jar

选项3：Olama本地模型

# Ensure Ollama is running: ollama pull nomic-embed-text
export SPRING_AI_OPENAI_BASE_URL=http://localhost:11434
export SPRING_AI_OPENAI_EMBEDDING_OPTIONS_MODEL=nomic-embed-text
export LADYBUGDB_EMBEDDING_DIMENSIONS=768

java -jar mcp/target/archiledger-server-1.0.0-SNAPSHOT.jar

带有自定义嵌入的Docker

# Ollama
docker run -p 8080:8080 \
  --add-host=host.docker.internal:host-gateway \
  -e SPRING_AI_OPENAI_BASE_URL=http://host.docker.internal:11434 \
  -e SPRING_AI_OPENAI_EMBEDDING_OPTIONS_MODEL=nomic-embed-text \
  -e LADYBUGDB_EMBEDDING_DIMENSIONS=768 \
  registry.hub.docker.com/thecookiezen/archiledger:latest

嵌入环境变量

重要提示： 更改嵌入模型时，尺寸必须与模型的输出相匹配。常见尺寸：全MiniLM-L6-v2（384），nomic嵌入文本（768），文本嵌入3-small（1536）。

______________________________________________________________________

MCP客户端连接

连接方式： 可流式传输HTTP端点: http://localhost:8080/mcp

客户端配置示例

Gemini CLI(settings.json):

{
  "mcpServers": {
    "archiledger": {
      "httpUrl": "http://localhost:8080/mcp"
    }
  }
}

VSCode/GitHubCopilot(settings.json):

{
  "servers": {
    "archiledger": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

反重力：

{
  "mcpServers": {
    "archiledger": {
      "serverUrl": "http://localhost:8080/mcp"
    }
  }
}

MCP客户端的Docker技巧

1. 持久化数据：始终装载卷(-v)保存你的知识图谱
2. 容器生命周期：跑步 -d （分离模式）
3. 端口冲突：映射到不同的端口（例如。， -p 9090:8080)并更新URL
4. 命名容器：使用 --name archiledger 便于管理
5. 除错记录: docker logs archiledger

______________________________________________________________________

用法示例

用例1：内存库

将知识图用作持久记忆库。LLM将原子知识片段存储为笔记，对其进行标记，并链接相关笔记。

# Memory Bank Instructions

You have access to a knowledge graph MCP server. Use it to store and retrieve atomic notes across conversations.

## Core Behaviors

### Proactive Memory Storage
When the user shares important information, store it as an atomic note:
- **Preferences**: User's coding style, preferred tools, naming conventions
- **Decisions**: Architecture decisions, technology choices, rejected alternatives
- **Context**: Project goals, constraints, team information
- **Tasks**: Ongoing work, blockers, next steps

### Tagging Notes
Use tags for categorization:
- `preference` - User preferences and settings
- `decision` - Important decisions with rationale
- `context` - Project or domain context
- `task` - Work items and their status
- `observation` - General notes and observations
- `person` - Team members and stakeholders

### Creating Notes
1. Give the note a descriptive ID (e.g., `java-naming-convention`)
2. Write focused content (one idea per note — Zettelkasten atomicity)
3. Add relevant keywords for search
4. Set appropriate tags
5. Link to related notes with context

### Recalling Notes
At the start of each conversation:
1. Use `read_graph` to get an overview
2. Use `search_notes` to find semantically relevant notes
3. Use `get_notes_by_tag` to retrieve by category
4. Reference stored decisions and preferences in responses

### Linking Notes
Use typed links with context:
- `RELATES_TO` - General relationship
- `DEPENDS_ON` - Dependency relationship
- `AFFECTS` - One thing impacts another
- `PART_OF` - Component/container relationship
- `SUPERSEDES` - Replaces previous decision/approach
- `CONTRADICTS` - Conflicts with another note

> **Note:** Each link requires a `context` field explaining why the relationship exists.

______________________________________________________________________

用例2：代码库/文档分析

从代码库或文档语料库构建结构化知识库。

# Codebase Knowledge Graph Builder

Use the memory MCP server to create atomic knowledge notes from the codebase.

## Analysis Workflow

### Phase 1: High-Level Structure
1. Identify major modules, packages, or services
2. Create a note for each architectural component
3. Link notes with `DEPENDS_ON`, `CONTAINS`, or `USES` links

### Phase 2: Deep Dive
For each component:
1. Key classes, interfaces, and their responsibilities
2. Important functions and their purposes
3. Data models and their relationships
4. External integrations and APIs

### Phase 3: Cross-Cutting Concerns
1. Design patterns in use
2. Shared utilities and helpers
3. Configuration and environment handling
4. Error handling strategies

## Tags for Code Analysis
- `module` - Top-level packages, services, or bounded contexts
- `component` - Major classes, interfaces, or subsystems
- `function` - Important functions or methods
- `model` - Data models, DTOs, entities
- `pattern` - Design patterns in use
- `config` - Configuration classes or files
- `api` - External or internal API endpoints
- `dependency` - External libraries or services

## Link Types for Code
- `DEPENDS_ON` - Class/module depends on another
- `IMPLEMENTS` - Implements an interface or contract
- `EXTENDS` - Inherits from another class
- `USES` - Utilizes another component
- `CALLS` - Function calls another function
- `CONTAINS` - Package contains class, class contains method
- `PRODUCES` - Creates or emits events/messages
- `CONSUMES` - Handles events/messages

## Querying for Investigation
1. **Find dependencies**: Get a note and examine its links
2. **Impact analysis**: Follow `DEPENDS_ON` links to find affected components
3. **Understand data flow**: Trace `CALLS`, `PRODUCES`, `CONSUMES` links
4. **Onboarding**: Search by `module` tag, then explore linked `component` notes

## Best Practices
1. **One idea per note** — Zettelkasten atomicity
2. **Include file paths** in content or keywords
3. **Document "why"** not just "what"
4. **Update incrementally** as you explore
5. **Link with context** — explanatory context makes the graph valuable

______________________________________________________________________

建筑

• 域层：核心域模型(MemoryNote, MemoryNoteId, NoteLink).定义存储库端口(MemoryNoteRepository).
• 应用层：使用编排域逻辑 MemoryNoteService.处理检索计数跟踪和嵌入生成。
• 基础设施层:

- 坚持: LadybugMemoryNoteRepository -LadybugDB图形数据库。笔记存储为节点，链接存储为 LINKED_TO 关系。 - 向量搜索: LadybugEmbeddingsService 使用LadybugDB的原生向量扩展和HNSW索引。 - 主控程序：通过以下方式显示记忆工具 McpToolAdapter.

代理存储模块

这 agentic-memory 模块提供AI驱动的内存进化：

• Agent内存代理：分析笔记，并根据语义关系建议新的链接
• 上下文感知链接：自动评估是否添加、更新或删除链接
• 进化提示：使用Jinja模板进行内容分析和演变评估
• 内存注释搜索操作：实现用于矢量搜索和结果扩展的RAG接口

______________________________________________________________________

限制和性能

⚠️ 重要提示： 专为本地开发、个人使用和中小型数据集而设计。