Document Store¶

Berry includes a document store for managing markdown documents alongside memories. While memories are short-form vector-indexed snippets, documents are longer-form markdown files stored on the filesystem with sidecar metadata. This gives AI agents a consistent, configure-once interface for document CRUD without needing to know filesystem paths.

How It Works¶

Documents are stored as plain markdown files at a configured directory path. Metadata (title, tags, creator, timestamps) lives in sidecar JSON files within a hidden .berry/ subdirectory.

<documents_path>/
  architecture-decisions.md        # markdown content
  onboarding-guide.md
  .berry/
    architecture-decisions.json    # metadata (title, tags, timestamps)
    onboarding-guide.json

Each document gets a slug ID generated from its title (e.g. "Architecture Decisions" becomes architecture-decisions). If a slug already exists, Berry appends -2, -3, etc.

Configuration¶

Document management is enabled by default. Configure it in your config file or with environment variables.

Configuration File¶

{
  "documents": {
    // Path to the documents directory
    "path": "/path/to/documents",

    // Set to false to disable document management
    "enabled": true
  }
}

Environment Variables¶

Default Path¶

The default documents directory is platform-specific:

CLI Usage¶

All document operations are under the berry doc subcommand.

Create a Document¶

berry doc create "Architecture Decisions" --content "# Architecture Decisions\n\nThis document tracks key decisions." --by architect

Arguments:

Options:

Examples:

# With tags
berry doc create "API Reference" --content "# API Reference" --tags "api,reference"

# Interactive mode (prompts for content)
berry doc create "Meeting Notes"

Read a Document¶

berry doc read <ID>

Examples:

berry doc read architecture-decisions

# JSON output
berry --format json doc read architecture-decisions

Update a Document¶

berry doc update <ID> [OPTIONS]

All fields are optional — only provided fields are updated.

Options:

Examples:

# Update content only
berry doc update architecture-decisions --content "# Updated content"

# Update tags
berry doc update architecture-decisions --tags "architecture,decisions,adr"

# Update title (ID remains the same)
berry doc update architecture-decisions --title "Architecture Decision Records"

Delete a Document¶

berry doc delete <ID> [OPTIONS]

Options:

Examples:

# With confirmation
berry doc delete architecture-decisions

# Skip confirmation
berry doc delete -f architecture-decisions

List Documents¶

berry doc list [OPTIONS]

Options:

Examples:

# List all documents
berry doc list

# Filter by tag
berry doc list --tags architecture

# Filter by creator
berry doc list --by architect

# JSON output
berry --format json doc list

HTTP API¶

The Berry server exposes document endpoints when the document store is enabled. All endpoints return JSON.

Create Document¶

POST /v1/documents
Content-Type: application/json

{
  "title": "Architecture Decisions",
  "content": "# Architecture Decisions\n\nKey decisions...",
  "tags": ["architecture"],
  "created_by": "user"
}

Response:

{
  "success": true,
  "document": {
    "id": "architecture-decisions",
    "title": "Architecture Decisions",
    "content": "# Architecture Decisions\n\nKey decisions...",
    "tags": ["architecture"],
    "created_by": "user",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Get Document¶

GET /v1/documents/{id}

Returns 404 if the document does not exist.

Update Document¶

PATCH /v1/documents/{id}
Content-Type: application/json

{
  "content": "# Updated content"
}

All fields are optional. Only provided fields are updated.

Delete Document¶

DELETE /v1/documents/{id}

Response:

{
  "success": true,
  "deleted": true
}

List Documents¶

GET /v1/documents
GET /v1/documents?tags=architecture&created_by=user

Response:

{
  "success": true,
  "documents": [...],
  "total": 2
}

MCP Tools¶

When using Berry as an MCP server (berry mcp), the following document tools are available:

doc_create¶

doc_read¶

doc_update¶

doc_delete¶

doc_list¶

Document vs Memory¶

Disabling Documents¶

If you don't need document management, disable it to skip directory creation and route registration:

export BERRY_DOCUMENTS_ENABLED=false

Or in the config file:

{
  "documents": {
    "enabled": false
  }
}

When disabled, the document API endpoints return 501 Not Implemented.

See Also¶

• CLI Reference - Full CLI documentation
• Configuration - All configuration options
• Getting Started - Installation and setup