### Install and Login CLI Command

Source: https://github.com/aristoapp/hermes-membase/blob/main/README.md

Use this command for a one-shot installation and OAuth login process. It initiates the OAuth flow by opening a browser.

```bash
hermes-membase install              # One-shot install and OAuth login
```

```bash
hermes-membase login                # OAuth login (PKCE): opens browser
```

--------------------------------

### Membase Configuration Example

Source: https://github.com/aristoapp/hermes-membase/blob/main/README.md

An example JSON configuration file for Membase, showing settings for auto-recall, auto-capture, mirror-builtin, and max-recall-chars.

```json
{
  "autoRecall": true,
  "autoCapture": true,
  "mirrorBuiltin": true,
  "maxRecallChars": 4000
}
```

--------------------------------

### Install and Test Membase Plugin

Source: https://github.com/aristoapp/hermes-membase/blob/main/CONTRIBUTING.md

Install the hermes-membase plugin and run it with a Hermes installation to test its functionality.

```bash
pip install hermes-membase
hermes-membase install
hermes
```

--------------------------------

### Clone and Install Development Dependencies

Source: https://github.com/aristoapp/hermes-membase/blob/main/README.md

Steps to clone the Hermes Membase repository and install development dependencies using `uv sync --dev`. Requires Python 3.11+.

```bash
git clone https://github.com/aristoapp/hermes-membase.git
cd hermes-membase
uv sync --dev
```

--------------------------------

### Clone Repository and Set Up Development Environment

Source: https://github.com/aristoapp/hermes-membase/blob/main/CONTRIBUTING.md

Clone the repository, create a virtual environment, and install the project and development dependencies using pip.

```bash
git clone https://github.com/aristoapp/hermes-membase.git
cd hermes-membase
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/pip install ruff
```

--------------------------------

### Install Membase Plugin

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Installs the hermes-membase plugin and configures Hermes to use it. Supports installation via uv/pip and includes options to skip OAuth login or specify a custom API URL.

```bash
# Full installation with OAuth login
uv tool install hermes-membase && hermes-membase install
```

```bash
# Installation without pip/uv
pip install hermes-membase && hermes-membase install
```

```bash
# Skip OAuth login (authenticate later)
hermes-membase install --skip-login
```

```bash
# Custom API URL
hermes-membase install --api-url https://custom-api.membase.so
```

--------------------------------

### Membase Configuration File Structure

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Example structure of the Membase configuration file located at ~/.hermes/membase.json. All keys are optional with sensible defaults provided.

```json
{
  "apiUrl": "https://api.membase.so",
  "tokenFile": "~/.hermes/credentials/membase.json",
  "autoRecall": false,
  "autoWikiRecall": false,
  "autoCapture": true,
  "mirrorBuiltin": true,
  "maxRecallChars": 4000,
  "debug": false
}
```

--------------------------------

### Install Membase Plugin

Source: https://github.com/aristoapp/hermes-membase/blob/main/README.md

Installs the Membase plugin for Hermes Agent and configures it. This command handles copying the plugin, setting the memory provider, writing default configuration, and initiating OAuth login.

```bash
uv tool install hermes-membase && hermes-membase install
```

```bash
pip install hermes-membase && hermes-membase install
```

--------------------------------

### Get System Prompt Block

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Retrieves the system prompt content to guide AI tool usage and memory routing.

```APIDOC
## GET /provider/system_prompt

### Description
Fetches the system prompt content that provides guidance on tool usage and routing between different memory types.

### Method
GET

### Endpoint
/provider/system_prompt

### Response
#### Success Response (200)
- **prompt_block** (string) - The system prompt content.

#### Response Example
```json
{
  "prompt_block": "# System Prompt\nUse memory.add for general memories, membase_store for long-term storage, and membase_add_wiki for wiki entries."
}
```
```

--------------------------------

### Get System Prompt Block

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Retrieve the system prompt content that guides the AI on tool usage and routing between different memory types.

```python
prompt_block = provider.system_prompt_block()
# Returns routing guidance for memory.add vs membase_store vs membase_add_wiki
```

--------------------------------

### Queue and Get Prefetch

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Queue a prefetch for upcoming AI turns and retrieve cached prefetch results. Ensure the provider is initialized before use.

```python
# Queue a prefetch for upcoming turn
provider.queue_prefetch(
    query="What were the project requirements?",
    session_id="session-123"
)

# Get cached prefetch results
context = provider.prefetch(
    query="What were the project requirements?",
    session_id="session-123"
)
print(context)  # Returns <membase-context>...</membase-context> block
```

--------------------------------

### Get AI Tool Schemas

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Retrieve all available tool schemas exposed by the provider for AI agents. This includes tool names, descriptions, and parameter lists.

```python
# Get all tool schemas
schemas = provider.get_tool_schemas()

for schema in schemas:
    print(f"Tool: {schema['name']}")
    print(f"Description: {schema['description'][:100]}...")
    print(f"Parameters: {list(schema['parameters']['properties'].keys())}")
```

--------------------------------

### Get User Profile

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Retrieves the authenticated user's profile information and settings.

```APIDOC
## GET /api/profile

### Description
Fetches the profile details of the currently authenticated user.

### Method
GET

### Endpoint
/api/profile

### Response
#### Success Response (200)
- **display_name** (string) - The user's display name.
- **email** (string) - The user's email address.

#### Response Example
```json
{
  "display_name": "John Doe",
  "email": "john.doe@example.com"
}
```
```

--------------------------------

### Get User Profile Memory

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Retrieves the user's profile memory bundle, containing biographical information.

```APIDOC
## GET /api/user_profile_memory

### Description
Retrieves the memory bundle associated with the user's profile, which includes biographical data.

### Method
GET

### Endpoint
/api/user_profile_memory

### Response
#### Success Response (200)
- **episode** (object) - An object containing the profile memory episode details.
  - **content** (string) - The biographical content of the profile memory.

#### Response Example
```json
{
  "episode": {
    "content": "User is a software engineer working on backend systems..."
  }
}
```
```

--------------------------------

### Retrieve User Profile Memory

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Get the user's profile memory bundle, which contains biographical information. Check if `profile_memory` exists before accessing episode content.

```python
profile_memory = client.get_user_profile_memory()
if profile_memory:
    episode = profile_memory.get("episode", {})
    print(f"Profile content: {episode.get('content', '')}")
```

--------------------------------

### Initialize MembaseClient

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Creates a MembaseClient instance for API interaction, handling automatic token refresh. Requires API URL and authentication details. Includes an option to set a callback for token refreshes.

```python
from membase_hermes.client import AuthState, MembaseClient

# Create client with authentication
client = MembaseClient(
    api_url="https://api.membase.so",
    auth=AuthState(
        access_token="your_access_token",
        refresh_token="your_refresh_token",
        client_id="your_client_id"
    ),
    source="hermes",
    timeout_s=15.0,
    debug=False,
    on_token_refresh=lambda access, refresh: print(f"Tokens refreshed")
)

# Check authentication status
if client.is_authenticated():
    print("Client is authenticated")

# Always close client when done
client.close()
```

--------------------------------

### Initialize MembaseMemoryProvider

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Integrate with Hermes Agent's memory system. Requires `config_path`, `session_id`, `hermes_home`, and `agent_context` for initialization.

```python
from pathlib import Path
from membase_hermes.provider import MembaseMemoryProvider

# Create provider instance
provider = MembaseMemoryProvider(
    config_path=Path("~/.hermes/membase.json").expanduser()
)

# Initialize with session
provider.initialize(
    session_id="session-123",
    hermes_home="/home/user/.hermes",
    agent_context="primary"
)

# Check availability
if provider.is_available():
    print(f"Provider '{provider.name}' is ready")
```

--------------------------------

### Create a Wiki Document

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Add a new document to the knowledge wiki. Requires `title`, `content`, and `collection`. `summarize` defaults to true.

```python
# Create a wiki document
doc = client.create_wiki_document(
    title="REST API Authentication Guide",
    content="""# Authentication Methods

## OAuth 2.0
The recommended authentication method for production applications.

## API Keys
Suitable for server-to-server communication.

See also: [[Security Best Practices]]
""",
    collection="api-docs",
    summarize=False
)

print(f"Created document: {doc.get('title')} (ID: {doc.get('id')})")
```

--------------------------------

### Run Full Local Verification Suite

Source: https://github.com/aristoapp/hermes-membase/blob/main/README.md

Execute the `make check` command to run the complete suite of local verification tests before submitting a pull request.

```bash
make check
```

--------------------------------

### Perform Basic Wiki Search

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Search the knowledge wiki using hybrid semantic and keyword matching. Specify query and limit for results.

```python
# Basic wiki search
result = client.search_wiki(
    query="API authentication methods",
    limit=10
)

documents = result.get("documents", [])
for doc in documents:
    print(f"Title: {doc.get('title')}")
    print(f"Content: {doc.get('content', '')[:200]}...")
    print(f"ID: {doc.get('id')}")
```

--------------------------------

### Initialize Memory Provider

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Initializes the MembaseMemoryProvider with session and context information.

```APIDOC
## POST /provider/initialize

### Description
Initializes the MembaseMemoryProvider, setting up the connection to the memory system.

### Method
POST

### Endpoint
/provider/initialize

### Parameters
#### Request Body
- **session_id** (string) - Required - The ID of the current session.
- **hermes_home** (string) - Required - The path to the Hermes home directory.
- **agent_context** (string) - Required - The context for the agent.
- **config_path** (string) - Required - The path to the provider configuration file.

### Request Example
```json
{
  "session_id": "session-123",
  "hermes_home": "/home/user/.hermes",
  "agent_context": "primary",
  "config_path": "~/.hermes/membase.json"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating successful initialization.

#### Response Example
```json
{
  "message": "MembaseMemoryProvider initialized successfully."
}
```
```

--------------------------------

### Individual Make Targets for Development

Source: https://github.com/aristoapp/hermes-membase/blob/main/README.md

Useful individual `make` targets for development, including type checking, linting, formatting, testing, and building.

```bash
make typecheck      # mypy static type checks
```

```bash
make lint           # Ruff lint checks
```

```bash
make format         # Apply Ruff formatting
```

```bash
make format-check   # Verify formatting without writing
```

```bash
make test           # Unit tests
```

```bash
make build          # Build sdist and wheel
```

```bash
make verify-dist    # Build and validate package metadata
```

--------------------------------

### Login to Membase

Source: https://github.com/aristoapp/hermes-membase/blob/main/README.md

Initiates the OAuth authentication process for Membase. This command opens a browser window for login, and authentication tokens are saved automatically.

```bash
hermes-membase login
```

--------------------------------

### Resync CLI Commands

Source: https://github.com/aristoapp/hermes-membase/blob/main/README.md

Commands for rebuilding the mirror index. The `--dry-run` option allows previewing the resync process without making changes.

```bash
hermes-membase resync               # Rebuild mirror index from MEMORY.md
```

```bash
hermes-membase resync --dry-run     # Preview resync without writing
```

--------------------------------

### Search with Source and Project Filters

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Narrow down search results by specifying allowed sources and the project context. Use `sources` and `project` parameters.

```python
results = client.search(
    query="code reviews",
    sources=["slack", "gmail"],
    project="backend-api"
)
```

--------------------------------

### OAuth PKCE Flow Implementation

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Implement the OAuth 2.0 PKCE flow for secure authentication. This involves creating PKCE pairs, registering the client dynamically, building the authorization URL, and setting up a callback listener.

```python
from membase_hermes.oauth import (
    create_pkce_pair,
    create_state,
    dynamic_register_client,
    build_authorize_url,
    exchange_code_for_token,
    OAuthCallbackListener
)

# Create PKCE verifier and challenge
verifier, challenge = create_pkce_pair()
state = create_state()

# Register OAuth client dynamically
api_url = "https://api.membase.so"
redirect_uri = "http://127.0.0.1:8765/oauth/callback"
client_id = dynamic_register_client(api_url, redirect_uri)

# Build authorization URL
auth_url = build_authorize_url(
    api_url,
    client_id=client_id,
    redirect_uri=redirect_uri,
    state=state,
    code_challenge=challenge
)

# Start callback listener
listener = OAuthCallbackListener(
    preferred_port=8765,
    expected_state=state
)
```

--------------------------------

### Logout and Status CLI Commands

Source: https://github.com/aristoapp/hermes-membase/blob/main/README.md

Commands to manage authentication and check the status of the Membase API connection and profile.

```bash
hermes-membase logout               # Remove stored tokens
```

```bash
hermes-membase status               # Check API connectivity and profile
```

--------------------------------

### Create Wiki Document

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Adds a new document to the knowledge wiki.

```APIDOC
## POST /api/wiki/documents

### Description
Creates a new document in the knowledge wiki.

### Method
POST

### Endpoint
/api/wiki/documents

### Parameters
#### Request Body
- **title** (string) - Required - The title of the new document.
- **content** (string) - Required - The content of the document.
- **collection** (string) - Optional - The collection to which the document belongs.
- **summarize** (boolean) - Optional - Whether to automatically summarize the content.

### Request Example
```json
{
  "title": "REST API Authentication Guide",
  "content": "# Authentication Methods\n\n## OAuth 2.0\nThe recommended authentication method for production applications.\n\n## API Keys\nSuitable for server-to-server communication.\n\nSee also: [[Security Best Practices]]",
  "collection": "api-docs",
  "summarize": false
}
```

### Response
#### Success Response (200)
- **title** (string) - The title of the created document.
- **id** (string) - The unique identifier of the created document.

#### Response Example
```json
{
  "title": "REST API Authentication Guide",
  "id": "doc-xyz789"
}
```
```

--------------------------------

### Run Linting and Formatting Checks

Source: https://github.com/aristoapp/hermes-membase/blob/main/CONTRIBUTING.md

Execute Ruff to check for code style violations and ensure code is properly formatted according to project standards.

```bash
.venv/bin/ruff check src/
.venv/bin/ruff format --check src/
```

--------------------------------

### Search Bundles

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Retrieves complete bundle objects including episodes and knowledge graph edges.

```APIDOC
## POST /api/search_bundles

### Description
Searches for bundles, returning complete objects with episodes and related knowledge graph edges.

### Method
POST

### Endpoint
/api/search_bundles

### Parameters
#### Request Body
- **query** (string) - Required - The search query string.
- **limit** (integer) - Optional - The maximum number of bundles to return.
- **offset** (integer) - Optional - The number of bundles to skip.

### Request Example
```json
{
  "query": "user preferences",
  "limit": 10,
  "offset": 0
}
```

### Response
#### Success Response (200)
- **bundles** (array) - A list of bundle objects, each containing an episode and edges.

#### Response Example
```json
{
  "bundles": [
    {
      "episode": {
        "display_title": "...",
        "content": "..."
      },
      "edges": [
        { ... }
      ]
    }
  ]
}
```
```

--------------------------------

### Search for Full Bundles with Entities

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Retrieve complete bundle objects, including episodes and related knowledge graph edges, for richer context. Use `search_bundles` with `query`, `limit`, and `offset`.

```python
# Get full bundles with related entities
bundles = client.search_bundles(
    query="user preferences",
    limit=10,
    offset=0
)

for bundle in bundles:
    episode = bundle.get("episode", {})
    edges = bundle.get("edges", [])
    print(f"Episode: {episode.get('display_title', 'Untitled')}")
    print(f"Related edges: {len(edges)}")
```

--------------------------------

### Search Wiki Documents

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Searches the knowledge wiki using hybrid semantic and keyword matching.

```APIDOC
## POST /api/wiki/search

### Description
Searches the knowledge wiki for documents using a combination of semantic and keyword matching.

### Method
POST

### Endpoint
/api/wiki/search

### Parameters
#### Request Body
- **query** (string) - Required - The search query.
- **limit** (integer) - Optional - The maximum number of documents to return.
- **collection** (string) - Optional - The specific collection within the wiki to search.

### Request Example
```json
{
  "query": "API authentication methods",
  "limit": 10
}
```

### Response
#### Success Response (200)
- **documents** (array) - A list of documents matching the search query.
  - **title** (string) - The title of the document.
  - **content** (string) - The content of the document.
  - **id** (string) - The unique identifier of the document.

#### Response Example
```json
{
  "documents": [
    {
      "title": "Authentication Methods",
      "content": "...",
      "id": "doc-123"
    }
  ]
}
```
```

--------------------------------

### Handle Tool Calls for Memory Operations

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Process AI tool calls for various memory operations including search, store, profile retrieval, forget, wiki search, and wiki document addition. Note that 'membase_forget' requires a two-step confirmation.

```python
# Search memories
result = provider.handle_tool_call(
    tool_name="membase_search",
    args={
        "query": "project deadlines",
        "limit": 10,
        "date_from": "2024-01-01"
    }
)

# Store a memory
result = provider.handle_tool_call(
    tool_name="membase_store",
    args={
        "content": "User prefers morning standup meetings at 9am",
        "display_summary": "Meeting time preference"
    }
)

# Get user profile
result = provider.handle_tool_call(
    tool_name="membase_profile",
    args={}
)

# Forget a memory (two-step: search then confirm)
result = provider.handle_tool_call(
    tool_name="membase_forget",
    args={"query": "old project notes", "confirm": False}
)
# Returns candidates, then call again with:
result = provider.handle_tool_call(
    tool_name="membase_forget",
    args={"uuid": "memory-uuid-here", "confirm": True}
)

# Search wiki
result = provider.handle_tool_call(
    tool_name="membase_search_wiki",
    args={"query": "API documentation", "limit": 5}
)

# Add wiki document
result = provider.handle_tool_call(
    tool_name="membase_add_wiki",
    args={
        "title": "Project Architecture",
        "content": "# Overview\n\nThe system uses...",
        "collection": "technical-docs"
    }
)
```

--------------------------------

### Session Lifecycle Management

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Manage the provider lifecycle, including handling session end events and performing cleanup. The `on_session_end` method accepts a list of messages.

```python
# Called when session ends
provider.on_session_end(messages=[
    {"role": "user", "content": "Hello"},
    {"role": "assistant", "content": "Hi there!"}
])

# Shutdown and cleanup
provider.shutdown()
```

--------------------------------

### Perform Basic Semantic Search

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Use for general text-based searches. Specify query and limit for results.

```python
results = client.search(
    query="project deadlines and meetings",
    limit=20
)
```

--------------------------------

### Resync Membase Index

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Rebuilds the Membase mirror index from an existing MEMORY.md file. Useful for synchronizing memories. Supports dry-run previews, custom memory file paths, and custom output paths for the mirror index.

```bash
# Standard resync
hermes-membase resync
```

```bash
# Preview without writing changes
hermes-membase resync --dry-run
```

```bash
# Custom MEMORY.md path
hermes-membase resync --memory-file /path/to/MEMORY.md
```

```bash
# Custom mirror index output path
hermes-membase resync --mirror-index /path/to/mirror_index.json
```

--------------------------------

### Retrieve User Profile

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Fetch the authenticated user's profile information, including display name and email.

```python
profile = client.get_profile()
print(f"Display Name: {profile.get('display_name')}")
print(f"Email: {profile.get('email')}")
```

--------------------------------

### Check Membase Status

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Verifies connectivity to the Membase API and displays the authenticated user's profile. Shows connection status and user details or indicates if not logged in.

```bash
hermes-membase status

# Expected output when connected:
# Membase connection: OK
# {
#   "display_name": "John Doe",
#   "email": "john@example.com"
# }

# Expected output when not connected:
# Not logged in. Run: hermes-membase login
```

--------------------------------

### Sync Conversation Turn

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Synchronize a conversation turn by providing both user and assistant content. This is used for automatic memory storage.

```python
# Sync a conversation turn
provider.sync_turn(
    user_content="Can you help me understand the authentication flow?",
    assistant_content="The authentication uses OAuth 2.0 with PKCE...",
    session_id="session-123"
)
```

--------------------------------

### Ingest New Content to Memory

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Store new information into long-term memory with automatic entity and relationship extraction. Requires `content`, `display_summary`, and `project`.

```python
# Store a memory with display summary
result = client.ingest(
    content="User prefers dark mode interfaces and uses VS Code as their primary editor. They work on Python and TypeScript projects primarily.",
    display_summary="User's development environment preferences",
    project="user-preferences"
)

print(f"Ingestion status: {result.get('status')}")
# Expected output: Ingestion status: accepted
```

--------------------------------

### Update Wiki Document

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Updates an existing wiki document's title, content, or collection.

```APIDOC
## PUT /api/wiki/documents/{doc_id}

### Description
Updates an existing document in the knowledge wiki.

### Method
PUT

### Endpoint
/api/wiki/documents/{doc_id}

### Parameters
#### Path Parameters
- **doc_id** (string) - Required - The ID of the document to update.

#### Request Body
- **updates** (object) - Required - An object containing the fields to update.
  - **title** (string) - Optional - The new title for the document.
  - **content** (string) - Optional - The new content for the document.
  - **collection** (string) - Optional - The new collection for the document.

### Request Example
```json
{
  "updates": {
    "title": "Updated Authentication Guide",
    "content": "New content here...",
    "collection": "security-docs"
  }
}
```

### Response
#### Success Response (200)
- **title** (string) - The title of the updated document.

#### Response Example
```json
{
  "title": "Updated Authentication Guide"
}
```
```

--------------------------------

### Process Search Results

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Iterate through search results to extract and display content, summary, and UUID. Access episode data using dictionary-like methods.

```python
# Process results
for episode in results:
    print(f"Content: {episode.get('content', '')[:100]}")
    print(f"Summary: {episode.get('summary', '')}")
    print(f"UUID: {episode.get('uuid', '')}")
```

--------------------------------

### Search with Date Range

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Searches for content within a specified date range.

```APIDOC
## POST /api/search

### Description
Performs a semantic search within a specified date range.

### Method
POST

### Endpoint
/api/search

### Parameters
#### Request Body
- **query** (string) - Required - The search query string.
- **limit** (integer) - Optional - The maximum number of results to return.
- **date_from** (string) - Optional - The start date for the search range (YYYY-MM-DD).
- **date_to** (string) - Optional - The end date for the search range (YYYY-MM-DD).
- **timezone** (string) - Optional - The timezone for interpreting the date range.

### Request Example
```json
{
  "query": "team discussions",
  "limit": 10,
  "date_from": "2024-01-01",
  "date_to": "2024-01-31",
  "timezone": "America/New_York"
}
```

### Response
#### Success Response (200)
- **results** (array) - A list of search results within the specified date range.

#### Response Example
```json
{
  "results": [
    {
      "content": "...",
      "summary": "...",
      "uuid": "..."
    }
  ]
}
```
```

--------------------------------

### Exchange Authorization Code for Tokens

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

After a user authorizes in the browser, this code exchanges the received authorization code for access and refresh tokens. Ensure the listener is closed after use.

```python
code = listener.wait_for_code(timeout_s=180.0)
tokens = exchange_code_for_token(
    api_url,
    code=code,
    client_id=client_id,
    redirect_uri=redirect_uri,
    code_verifier=verifier
)

print(f"Access Token: {tokens['access_token'][:20]}...")
print(f"Refresh Token: {tokens['refresh_token'][:20]}...")

listener.close()
```

--------------------------------

### Search with Date Range and Timezone

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Filter search results by a specific date range and timezone. Requires `date_from`, `date_to`, and `timezone` parameters.

```python
results = client.search(
    query="team discussions",
    limit=10,
    date_from="2024-01-01",
    date_to="2024-01-31",
    timezone="America/New_York"
)
```

--------------------------------

### Basic Search

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Performs a basic semantic search for a given query.

```APIDOC
## POST /api/search

### Description
Performs a semantic search using the provided query and returns relevant results.

### Method
POST

### Endpoint
/api/search

### Parameters
#### Request Body
- **query** (string) - Required - The search query string.
- **limit** (integer) - Optional - The maximum number of results to return.

### Request Example
```json
{
  "query": "project deadlines and meetings",
  "limit": 20
}
```

### Response
#### Success Response (200)
- **results** (array) - A list of search results.

#### Response Example
```json
{
  "results": [
    {
      "content": "...",
      "summary": "...",
      "uuid": "..."
    }
  ]
}
```
```

--------------------------------

### Memory Write Hook

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Automatically mirror Hermes's built-in memory writes to Membase. This hook is triggered by 'add', 'remove', or 'replace' actions on a target file.

```python
# Called automatically when Hermes writes to MEMORY.md
provider.on_memory_write(
    action="add",  # "add", "remove", or "replace"
    target="MEMORY.md",
    content="Important fact to remember"
)
```

--------------------------------

### Search with Source Filter

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Filters search results by specified sources.

```APIDOC
## POST /api/search

### Description
Performs a semantic search and filters results by specified sources.

### Method
POST

### Endpoint
/api/search

### Parameters
#### Request Body
- **query** (string) - Required - The search query string.
- **sources** (array of strings) - Optional - A list of sources to filter results by (e.g., ["slack", "gmail"]).
- **project** (string) - Optional - The project to filter results by.

### Request Example
```json
{
  "query": "code reviews",
  "sources": ["slack", "gmail"],
  "project": "backend-api"
}
```

### Response
#### Success Response (200)
- **results** (array) - A list of search results filtered by the specified sources and project.

#### Response Example
```json
{
  "results": [
    {
      "content": "...",
      "summary": "...",
      "uuid": "..."
    }
  ]
}
```
```

--------------------------------

### Ingest Memory

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Stores new content into long-term memory with automatic entity and relationship extraction.

```APIDOC
## POST /api/ingest

### Description
Ingests new content into the memory system, extracting entities and relationships.

### Method
POST

### Endpoint
/api/ingest

### Parameters
#### Request Body
- **content** (string) - Required - The content to ingest.
- **display_summary** (string) - Optional - A summary to display for the ingested content.
- **project** (string) - Optional - The project associated with the content.

### Request Example
```json
{
  "content": "User prefers dark mode interfaces and uses VS Code as their primary editor. They work on Python and TypeScript projects primarily.",
  "display_summary": "User's development environment preferences",
  "project": "user-preferences"
}
```

### Response
#### Success Response (200)
- **status** (string) - The status of the ingestion operation (e.g., "accepted").

#### Response Example
```json
{
  "status": "accepted"
}
```
```

--------------------------------

### Logout from Membase

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Removes stored OAuth tokens and clears the authentication state from the local machine. This command logs the user out of the Membase service.

```bash
hermes-membase logout

# Expected output:
# Membase tokens removed.
```

--------------------------------

### Search Wiki within a Specific Collection

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Filter wiki search results to a particular collection. Use the `collection` parameter.

```python
# Search within a specific collection
result = client.search_wiki(
    query="database schemas",
    collection="technical-docs"
)
```

--------------------------------

### Update Wiki Document

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Modify an existing wiki document's title, content, or collection using its ID. Pass updates as a dictionary to the `updates` parameter.

```python
# Update document content
updated_doc = client.update_wiki_document(
    doc_id="doc-abc123",
    updates={
        "title": "Updated Authentication Guide",
        "content": "New content here...",
        "collection": "security-docs"
    }
)

print(f"Updated: {updated_doc.get('title')}")
```

--------------------------------

### Delete Memory by UUID

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Remove a specific memory episode using its unique identifier (UUID).

```python
# Delete a memory by UUID
client.delete_memory(episode_uuid="abc123-def456-ghi789")
```

--------------------------------

### Delete Wiki Document by ID

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Remove a wiki document from the knowledge base using its unique document ID.

```python
# Delete a wiki document
client.delete_wiki_document(doc_id="doc-abc123")
```

--------------------------------

### Delete Wiki Document

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Removes a wiki document by its ID.

```APIDOC
## DELETE /api/wiki/documents/{doc_id}

### Description
Deletes a specific document from the knowledge wiki.

### Method
DELETE

### Endpoint
/api/wiki/documents/{doc_id}

### Parameters
#### Path Parameters
- **doc_id** (string) - Required - The ID of the document to delete.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the document was deleted.

#### Response Example
```json
{
  "message": "Document doc-abc123 deleted successfully."
}
```
```

--------------------------------

### Delete Memory

Source: https://context7.com/aristoapp/hermes-membase/llms.txt

Removes a specific memory episode by its UUID.

```APIDOC
## DELETE /api/memories/{episode_uuid}

### Description
Deletes a specific memory episode using its unique identifier.

### Method
DELETE

### Endpoint
/api/memories/{episode_uuid}

### Parameters
#### Path Parameters
- **episode_uuid** (string) - Required - The UUID of the memory episode to delete.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the memory was deleted.

#### Response Example
```json
{
  "message": "Memory episode abc123-def456-ghi789 deleted successfully."
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.