Heare Memory Global Service

A RESTful memory service that provides persistent storage for agents with automatic git versioning. The service exposes a tree-structured filesystem interface backed by markdown files and git commits.

Overview

The Heare Memory Global Service implements the "global" tier of a three-tier memory architecture:

• Session: Task-specific, may not persist beyond session
• Project: Curated by humans/agents, project-specific
• Global: Cross-project concepts, multi-agent accessible, implicit interaction model

This service provides:

• RESTful API for memory node CRUD operations
• Git-backed storage with full audit trail
• Search capabilities across memory content
• Batch operations for efficient updates
• Authentication and read-only mode support

Quick Start

Requirements

• Python 3.12+
• UV package manager
• Git
• GitHub CLI (gh) for git operations (optional, for push functionality)

Installation

1. Clone the repository:

git clone https://github.com/heare-ai/heare-memory.git
cd heare-memory

2. Install dependencies:

uv sync

3. Run the service:

uv run heare-memory

The service will be available at http://localhost:8000.

Development

1. Install development dependencies:

uv sync --dev

2. Set up pre-commit hooks:

uv run pre-commit install

3. Run tests:

uv run pytest

4. Run code quality checks:

# Run all pre-commit hooks manually
uv run pre-commit run --all-files

# Run specific tools
uv run ruff check                # Linting
uv run ruff format              # Formatting
uv run pytest                   # Tests with coverage

5. Run the service in development mode:

uv run python -m heare_memory.main

Pre-commit Hooks

The project uses pre-commit hooks to ensure code quality:

• ruff: Python linting and formatting
• autoflake: Remove unused imports and variables
• trailing-whitespace: Remove trailing whitespace
• end-of-file-fixer: Ensure files end with newline
• check-yaml/toml/json: Validate configuration files
• check-merge-conflict: Prevent committing merge conflicts
• debug-statements: Prevent committing debug statements

Hooks run automatically on git commit. To run manually:

uv run pre-commit run --all-files

Configuration

The service is configured via environment variables:

• GITHUB_TOKEN (required for write operations and git push)
• MEMORY_ROOT (default: ./memory)
• GIT_REMOTE_URL (required, e.g. https://github.com/org/memory-repo.git)
• SERVICE_PORT (default: 8000)
• SERVICE_HOST (default: 0.0.0.0)

API Documentation

Once running, visit:

• API documentation: http://localhost:8000/docs
• Alternative docs: http://localhost:8000/redoc
• Health check: http://localhost:8000/health

Development Status

This project is currently in active development. See the implementation plan for detailed progress and roadmap.

Contributing

This project uses:

• Package Manager: UV
• Code Quality: Ruff, autoflake, pre-commit hooks
• Testing: pytest with asyncio support
• Web Framework: FastAPI
• Git Integration: GitPython

Please ensure all tests pass and code quality checks are met before submitting pull requests.

License

MIT License - see LICENSE file for details.