1
1
Fork
You've already forked holocene
0
Persistent memory and artifact storage for LLM and agent interactions
  • Go 84.8%
  • Shell 12.4%
  • Just 2.8%
Find a file
2026年01月11日 13:50:41 -05:00
internal chore: massive update 2026年01月11日 13:44:06 -05:00
.gitignore chore: massive update 2026年01月11日 13:44:06 -05:00
CLAUDE-DESKTOP.md chore: Justfile 2026年01月11日 13:50:05 -05:00
config.example.json chore: initial commit 2026年01月11日 12:34:23 -05:00
go.mod chore: massive update 2026年01月11日 13:44:06 -05:00
go.sum chore: initial commit 2026年01月11日 12:34:23 -05:00
init.go chore: initial commit 2026年01月11日 12:34:23 -05:00
INSTALL.md chore: Justfile 2026年01月11日 13:50:05 -05:00
justfile chore: Justfile 2026年01月11日 13:50:05 -05:00
main.go chore: massive update 2026年01月11日 13:44:06 -05:00
README.md chore: Justfile 2026年01月11日 13:50:05 -05:00
SYSTEM_PROMPT.md chore: massive update 2026年01月11日 13:44:06 -05:00
test_complete.sh chore: Justfile 2026年01月11日 13:50:05 -05:00

Holocene

Persistent memory and artifact storage for Claude conversations. Local-first with S3-compatible sync for durability.

Installation

go install github.com/hrbrmstr/holocene@latest

Or build from source:

git clone https://github.com/hrbrmstr/holocene
cd holocene
just build

Note: Requires CGO for SQLite FTS5 support. The justfile handles the necessary flags.

Setup

Run the init command to configure S3 credentials:

holocene init

This creates ~/.holocene/config.json with your S3 endpoint and credentials.

Usage

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
 "mcpServers": {
 "holocene": {
 "command": "/path/to/holocene"
 }
 }
}

Features

Memory Tools

Store and retrieve persistent context across conversations.

Tool Description
memory_add Store facts, preferences, context with tags and priority
memory_get Retrieve by ID
memory_list Browse with filtering by tags/project
memory_search Full-text search
memory_update Update (creates new version)
memory_forget Remove

Artifact Tools

Store code, documents, data with versioning.

Tool Description
artifact_save Store with content type, filename, metadata
artifact_get Retrieve (optionally at specific version)
artifact_list Browse with filtering
artifact_search Full-text search
artifact_versions View version history
artifact_update Update (creates new version)
artifact_delete Remove

Sync Tools

Bidirectional sync with S3-compatible storage.

Tool Description
sync_status Check sync state, pending writes, conflicts
sync_now Force immediate bidirectional sync
sync_pull Pull remote changes without pushing
sync_resolve_conflict Resolve conflicts with local_wins or remote_wins
storage_stats Counts, sizes, usage

Prompts

Built-in prompts for context loading.

Prompt Description
context_load Load recent memories and artifacts at session start
project_context Load all context for a specific project
search_context Search across everything

Resources

URI Description
holocene://about Usage documentation

Storage Architecture

Local (source of truth for reads):

  • SQLite with FTS5 for fast full-text search
  • WAL mode for concurrent access
  • Located at ~/.holocene/db/index.db

Remote (durability):

  • S3-compatible object storage
  • Bidirectional sync with conflict detection
  • Pull on startup, periodic push
  • Last-write-wins with version archiving
~/.holocene/
├── config.json
└── db/
 └── index.db
s3://bucket/
├── entries/{id}.json
└── versions/{id}/v{n}.json

Sync Behavior

  1. Startup: Pulls all remote entries, merges with local
  2. Periodic: Every 5 minutes (configurable), syncs pending changes
  3. On demand: sync_now forces immediate sync
  4. Conflict resolution: When local and remote both modified, tracks conflicts for manual resolution
  5. Shutdown: Final push of pending changes

Configuration

Environment variable HOLOCENE_CONFIG overrides the default config path.

{
 "data_dir": "~/.holocene",
 "s3": {
 "endpoint": "https://your-s3-endpoint.com",
 "bucket": "holocene",
 "access_key_id": "...",
 "secret_access_key": "...",
 "region": "auto"
 },
 "sync": {
 "enabled": true,
 "interval_secs": 300,
 "on_write_delay_ms": 5000
 }
}

S3-Compatible Services

Tested with:

  • iDrive e2
  • Wasabi
  • Backblaze B2
  • MinIO
  • AWS S3

Set endpoint to the service's S3-compatible URL. Use region: "auto" for most providers.

Building

# Development build
just build
# Run tests
just test
# Clean
just clean
# Release builds
make release-darwin-arm64
make release-darwin-amd64

License

MIT