### Manually Install Engram Binary and Dependencies

Source: https://github.com/hyperengineering/engram/blob/main/docs/systemd-setup-guide.md

Installs Engram manually by downloading the binary, creating necessary users, groups, and directories, and setting up the systemd service file. Requires manual configuration file creation.

```bash
# Download and extract
curl -LO https://github.com/hyperengineering/engram/releases/download/v1.0.0/engram_linux_amd64.tar.gz
tar -xzf engram_linux_amd64.tar.gz

# Install binary
sudo mv engram /usr/bin/engram
sudo chmod +x /usr/bin/engram

# Create user and group
sudo groupadd --system engram
sudo useradd --system --gid engram --home-dir /var/lib/engram --shell /usr/sbin/nologin engram

# Create directories
sudo mkdir -p /etc/engram /var/lib/engram
sudo chown engram:engram /var/lib/engram
sudo chmod 750 /var/lib/engram

# Download service file
sudo curl -o /usr/lib/systemd/system/engram.service \
  https://raw.githubusercontent.com/hyperengineering/engram/main/packaging/engram.service

# Reload systemd
sudo systemctl daemon-reload
```

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

### Install and Start Engram (bash)

Source: https://context7.com/hyperengineering/engram/llms.txt

Provides instructions for installing and starting the Engram service using various methods including Homebrew, Docker, binary download, and building from source. It also shows how to set up the necessary environment variables before starting the service.

```bash
# Homebrew (macOS/Linux)
brew install hyperengineering/tap/engram

# Docker
docker run -p 8080:8080 \
  -e OPENAI_API_KEY="sk-..." \
  -e ENGRAM_API_KEY="your-secret-key" \
  -v engram_data:/data \
  ghcr.io/hyperengineering/engram:latest

# Binary download (Linux amd64)
curl -LO https://github.com/hyperengineering/engram/releases/latest/download/engram_linux_amd64.tar.gz
tar -xzf engram_linux_amd64.tar.gz
sudo mv engram /usr/local/bin/

# Build from source (requires Go 1.23+)
git clone https://github.com/hyperengineering/engram.git
cd engram && make build
./dist/engram

# Start the service
export OPENAI_API_KEY="sk-..." && export ENGRAM_API_KEY="your-key"
engram
```

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

### Download and Install Engram Binary (macOS Intel)

Source: https://github.com/hyperengineering/engram/blob/main/docs/getting-started.md

Downloads the pre-built Engram binary for macOS (Intel architecture), extracts it, and moves it to a system-wide executable path. Requires `curl` and `tar`.

```bash
curl -LO https://github.com/hyperengineering/engram/releases/latest/download/engram_darwin_amd64.tar.gz
tar -xzf engram_darwin_amd64.tar.gz
sudo mv engram /usr/local/bin/
```

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

### Start Engram Service

Source: https://github.com/hyperengineering/engram/blob/main/docs/getting-started.md

Starts the Engram service using the `engram` command. Assumes necessary environment variables are set and dependencies are met. This command initiates the server process.

```bash
engram
```

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

### Download and Install Engram Binary (Linux amd64)

Source: https://github.com/hyperengineering/engram/blob/main/docs/getting-started.md

Downloads the pre-built Engram binary for Linux (amd64 architecture), extracts it, and moves it to a system-wide executable path. Requires `curl` and `tar`.

```bash
curl -LO https://github.com/hyperengineering/engram/releases/latest/download/engram_linux_amd64.tar.gz
tar -xzf engram_linux_amd64.tar.gz
sudo mv engram /usr/local/bin/
```

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

### Minimal Engram Setup (Bash)

Source: https://github.com/hyperengineering/engram/blob/main/docs/configuration.md

Sets the required API keys as environment variables and starts the Engram service. This is the most basic configuration to get Engram running.

```bash
export OPENAI_API_API_KEY="sk-your-openai-api-key"
export ENGRAM_API_KEY="your-secret-api-key"
engram
```

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

### Download and Install Engram Binary (macOS Apple Silicon)

Source: https://github.com/hyperengineering/engram/blob/main/docs/getting-started.md

Downloads the pre-built Engram binary for macOS (Apple Silicon architecture), extracts it, and moves it to a system-wide executable path. Requires `curl` and `tar`.

```bash
curl -LO https://github.com/hyperengineering/engram/releases/latest/download/engram_darwin_arm64.tar.gz
tar -xzf engram_darwin_arm64.tar.gz
sudo mv engram /usr/local/bin/
```

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

### Download and Install Engram Binary (Linux arm64)

Source: https://github.com/hyperengineering/engram/blob/main/docs/getting-started.md

Downloads the pre-built Engram binary for Linux (arm64 architecture), extracts it, and moves it to a system-wide executable path. Requires `curl` and `tar`.

```bash
curl -LO https://github.com/hyperengineering/engram/releases/latest/download/engram_linux_arm64.tar.gz
tar -xzf engram_linux_arm64.tar.gz
sudo mv engram /usr/local/bin/
```

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

### Verify Engram Installation

Source: https://github.com/hyperengineering/engram/blob/main/docs/getting-started.md

Checks if the Engram command-line tool has been installed correctly by querying its version. This command is used after installation to confirm the tool is accessible.

```bash
engram version
```

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

### Install Engram via Debian/Ubuntu Package

Source: https://github.com/hyperengineering/engram/blob/main/docs/systemd-setup-guide.md

Installs the Engram package on Debian-based systems using dpkg. This method automatically handles user, group, configuration, and data directory setup.

```bash
# Download the .deb package
curl -LO https://github.com/hyperengineering/engram/releases/download/v1.0.0/engram_1.0.0_linux_amd64.deb

# Install
sudo dpkg -i engram_1.0.0_linux_amd64.deb
```

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

### Troubleshoot Engram Service Startup Failures

Source: https://github.com/hyperengineering/engram/blob/main/docs/systemd-setup-guide.md

Provides steps to diagnose and resolve issues when the Engram service fails to start. Involves checking logs, verifying API key configuration, and inspecting file permissions.

```bash
# 1. Check the logs:
sudo journalctl -u engram -n 100 --no-pager

# 2. Verify API keys are set:
sudo grep -v '^#' /etc/engram/environment | grep -v '^$'

# 3. Check file permissions:
ls -la /etc/engram/
ls -la /var/lib/engram/
```

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

### Build Engram from Source

Source: https://github.com/hyperengineering/engram/blob/main/docs/getting-started.md

Clones the Engram repository from GitHub and builds the binary using `make`. This method is for users who need to build from the latest source code or customize the build.

```bash
git clone https://github.com/hyperengineering/engram.git
cd engram
make build
```

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

### Install Engram using Homebrew

Source: https://github.com/hyperengineering/engram/blob/main/docs/macos-launchagent-setup.md

Installs the Engram binary, wrapper script, configuration directories, and environment template using the custom Homebrew tap. This is the initial step for setting up Engram on macOS.

```bash
brew install hyperengineering/tap/engram
```

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

### Install Engram via RHEL/Fedora/CentOS Package

Source: https://github.com/hyperengineering/engram/blob/main/docs/systemd-setup-guide.md

Installs the Engram package on RHEL-based systems using rpm. This method automatically handles user, group, configuration, and data directory setup.

```bash
# Download the .rpm package
curl -LO https://github.com/hyperengineering/engram/releases/download/v1.0.0/engram-1.0.0.x86_64.rpm

# Install
sudo rpm -i engram-1.0.0.x86_64.rpm
```

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

### Upgrade Engram Package

Source: https://github.com/hyperengineering/engram/blob/main/docs/systemd-setup-guide.md

Demonstrates how to upgrade the Engram application using package managers for Debian/Ubuntu and RHEL/Fedora systems.

```bash
# Debian/Ubuntu
sudo dpkg -i engram_NEW_VERSION_linux_amd64.deb

# RHEL/Fedora
sudo rpm -U engram-NEW_VERSION.x86_64.rpm
```

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

### Troubleshoot Missing API Key Error

Source: https://github.com/hyperengineering/engram/blob/main/docs/getting-started.md

Provides the solution for `OPENAI_API_KEY` or `ENGRAM_API_KEY` errors by showing how to set these essential environment variables. Correctly setting these is critical for Engram to function.

```bash
export OPENAI_API_KEY="sk-..."
export ENGRAM_API_KEY="your-secret-key"
```

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

### Troubleshoot Engram Service Startup

Source: https://github.com/hyperengineering/engram/blob/main/docs/macos-launchagent-setup.md

Provides steps to troubleshoot issues when the Engram service fails to start. This involves checking log files, verifying API key configuration, and testing the service manually.

```bash
cat "$(brew --prefix)/var/log/engram/engram.log"

grep -v '^#' "$(brew --prefix)/etc/engram/environment" | grep -v '^$'

"$(brew --prefix)/bin/engram-wrapper"
```

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

### Configure Optional Engram Settings

Source: https://github.com/hyperengineering/engram/blob/main/docs/getting-started.md

Demonstrates setting optional environment variables to customize Engram's behavior, such as changing the server port, database path, or log level. These allow for fine-tuning the service.

```bash
# Change the server port (default: 8080)
export ENGRAM_PORT=3000

# Change the database location (default: ./data/engram.db)
export ENGRAM_DB_PATH=/var/lib/engram/lore.db

# Set log level (default: info)
export ENGRAM_LOG_LEVEL=debug
```

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

### Perform Manual Engram Upgrade

Source: https://github.com/hyperengineering/engram/blob/main/docs/systemd-setup-guide.md

Outlines the steps for a manual upgrade of Engram, involving stopping the service, downloading the new binary, making it executable, and restarting the service.

```bash
sudo systemctl stop engram
sudo curl -L -o /usr/bin/engram \
  https://github.com/hyperengineering/engram/releases/download/vNEW/engram_linux_amd64
sudo chmod +x /usr/bin/engram
sudo systemctl start engram
```

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

### Run Engram using Docker

Source: https://github.com/hyperengineering/engram/blob/main/docs/getting-started.md

Pulls the latest Engram Docker image and runs it as a container, exposing the API port and setting necessary environment variables for OpenAI and Engram API keys. It also mounts a volume for data persistence.

```bash
docker pull ghcr.io/hyperengineering/engram:latest

docker run -p 8080:8080 \
  -e OPENAI_API_KEY="sk-your-openai-api-key" \
  -e ENGRAM_API_KEY="your-secret-api-key" \
  -v engram_data:/data \
  ghcr.io/hyperengineering/engram:latest
```

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

### Set Database Permissions (Bash)

Source: https://github.com/hyperengineering/engram/blob/main/docs/getting-started.md

This snippet shows how to create a data directory and set appropriate permissions for it, resolving 'permission denied' errors when Engram tries to access its database. It ensures the directory exists and is writable.

```bash
mkdir -p data
chmod 755 data
```

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

### Configure Engram API Keys

Source: https://github.com/hyperengineering/engram/blob/main/docs/systemd-setup-guide.md

Sets the required API keys for Engram by editing the `/etc/engram/environment` file. Includes generating a secure API key for client authentication and obtaining an OpenAI API key.

```bash
sudo nano /etc/engram/environment

# Required: Generate a secure key for client authentication
# Run: openssl rand -hex 32
ENGRAM_API_KEY=your-generated-api-key

# Required: OpenAI API key for embedding generation
# Get from: https://platform.openai.com/api-keys
OPENAI_API_KEY=sk-your-openai-api-key

sudo chmod 640 /etc/engram/environment
sudo chown root:engram /etc/engram/environment
```

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

### Initialize and Use Recall Client (Go)

Source: https://github.com/hyperengineering/engram/blob/main/README.md

Demonstrates initializing the Recall client with configuration, querying for relevant lore, recording new learnings, and providing feedback on recalled knowledge. Requires Engram URL and API key.

```go
import (
	"os"
	"github.com/hyperengineering/recall"
)

// Initialize Recall client
client, _ := recall.New(recall.Config{
    EngramURL: "https://engram.example.com",
    APIKey:    os.Getenv("ENGRAM_API_KEY"),
    SourceID:  "devcontainer-abc123",
})

// Query for relevant lore
results, _ := client.Query(recall.QueryParams{
    Query: "handling race conditions in message queues",
    Limit: 5,
})

// Record new learning
client.Record(recall.RecordParams{
    Content:    "Consumer acknowledgments should use transactions",
    Context:    "Debugging message loss in production",
    Category:   "DEPENDENCY_BEHAVIOR",
    Confidence: 0.85,
})

// Provide feedback on recalled lore
client.Feedback(recall.FeedbackParams{
    Helpful:     []string{"L1", "L2"},
    NotRelevant: []string{"L3"},
})
```

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

### Initialize Recall Go Module and Dependencies

Source: https://github.com/hyperengineering/engram/blob/main/docs/engram.md

Commands to create the Recall project directory, initialize a Go module, and add essential dependencies like SQLite, ULID generation, and Cobra for the CLI. It concludes with downloading and tidying the module dependencies.

```bash
# Create repository
mkdir recall && cd recall

# Initialize Go module
go mod init github.com/hyperengineering/recall

# Add minimal dependencies
go get modernc.org/sqlite
go get github.com/oklog/ulid/v2
go get github.com/spf13/cobra  # For CLI

# Download and tidy
go mod download
go mod tidy
```

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

### Go Server Integration Test Example

Source: https://github.com/hyperengineering/engram/blob/main/docs/sync-integration-e2e-test-plan.md

Example Go code snippet demonstrating server integration tests using httptest and SQLiteStore. This approach allows for fast, in-process validation of endpoint interplay without requiring external binaries.

```go
package e2e

import (
	"net/http/httptest"
	"testing"

	"github.com/hyperengineering/engram/server"
	"github.com/hyperengineering/engram/store/sqlite"
)

func TestSync_PushThenDelta(t *testing.T) {
	// Setup: In-process httptest server with a real SQLiteStore
	store := sqlite.NewTestStore(t)
	router := server.NewRouter(server.Config{Store: store})
	sserver := httptest.NewServer(router)
	defer server.Close()

	// Test Steps: Push 5 entries, then GET delta after=0
	// ... (code to push entries)
	// ... (code to GET delta)

	// Assertion: All 5 returned with server-assigned sequences
	// ... (code to assert results)
}

// Other test functions like TestSync_PushThenDelta_Pagination, TestSync_PushIdempotent_NoDoubleSideEffects, etc. would follow a similar pattern.
```

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

### GET /api/v1/stores/{store_id}/sync/delta

Source: https://github.com/hyperengineering/engram/blob/main/docs/recall-client-sync-integration.md

Retrieves a delta of change log entries from the server starting after a specific sequence number.

```APIDOC
## GET /api/v1/stores/{store_id}/sync/delta

### Description
Fetches change log entries that occurred after a specific sequence number. Clients are responsible for filtering out their own entries using the `source_id`.

### Method
GET

### Endpoint
/api/v1/stores/{store_id}/sync/delta

### Parameters
#### Path Parameters
- **store_id** (string) - Required - The unique identifier of the store.

#### Query Parameters
- **after** (int64) - Required - Exclusive lower bound sequence number.
- **limit** (int) - Optional - Max number of entries to return (default 500, max 1000).

### Response
#### Success Response (200)
- **entries** (array) - List of change log entries.
- **last_sequence** (int64) - Highest sequence in this response.
- **latest_sequence** (int64) - Highest sequence on the server.
- **has_more** (boolean) - Indicates if more pages are available.

### Response Example
{
  "entries": [],
  "last_sequence": 1500,
  "latest_sequence": 2042,
  "has_more": true
}
```

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

### Write Path: Create Record and Log Change (Go)

Source: https://github.com/hyperengineering/engram/blob/main/docs/engram-changelog-sync-design.md

Demonstrates the write path in Go, where creating a 'Goal' record also appends an entry to the 'change_log' table within the same database transaction. This implements the outbox pattern, ensuring data consistency between the domain table and the change log.

```go
func (s *Store) CreateGoal(goal *Goal) error {
    return s.db.Transaction(func(tx *gorm.DB) error {
        if err := tx.Create(goal).Error; err != nil {
            return err
        }
        return tx.Create(&ChangeLogEntry{
            TableName: "goals",
            EntityID:  goal.ID,
            Operation: "upsert",
            Payload:   marshalJSON(goal),
            SourceID:  s.sourceID,
        }).Error
    })
}
```

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

### Verify Engram Installation

Source: https://github.com/hyperengineering/engram/blob/main/docs/systemd-setup-guide.md

Confirms the Engram service is running correctly by checking its status and testing the health endpoint. Requires the service to be running and accessible on localhost.

```bash
# Check service status
sudo systemctl status engram

# Test the health endpoint (no authentication required)
curl http://localhost:8080/api/v1/health

# Expected response:
# {"status":"healthy","version":"1.0.0","embedding_model":"text-embedding-3-small","lore_count":0,"last_snapshot":null}
```

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

### Discover Test Binaries in Go

Source: https://github.com/hyperengineering/engram/blob/main/docs/sync-integration-e2e-test-plan.md

Initializes paths for Engram, Recall, and Tract binaries using environment variables or system PATH lookup. This setup is performed in TestMain to ensure all required tools are available before executing tests.

```go
//go:build e2e

package e2e

import (
	"os"
	"os/exec"
	"testing"
)

var (
	engramBin string
	recallBin string
	tractBin  string
)

func TestMain(m *testing.M) {
	engramBin = os.Getenv("ENGRAM_BIN")
	if engramBin == "" {
		engramBin = lookPath("engram")
	}
	recallBin = os.Getenv("RECALL_BIN")
	if recallBin == "" {
		recallBin = lookPath("recall")
	}
	tractBin = os.Getenv("TRACT_BIN")
	if tractBin == "" {
		tractBin = lookPath("tract")
	}
	os.Exit(m.Run())
}

func lookPath(name string) string {
	p, _ := exec.LookPath(name)
	return p
}
```

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

### Manage Engram Systemd Service

Source: https://github.com/hyperengineering/engram/blob/main/docs/systemd-setup-guide.md

Provides essential systemd commands for managing the Engram service, including starting, enabling on boot, checking status, viewing logs, restarting, and stopping the service.

```bash
# Start the Service
sudo systemctl start engram

# Enable on Boot
sudo systemctl enable engram

# Check Status
sudo systemctl status engram

# View Logs (Recent)
sudo journalctl -u engram -n 50

# View Logs (Follow)
sudo journalctl -u engram -f

# View Logs (Since last boot)
sudo journalctl -u engram -b

# Restart After Configuration Changes
sudo systemctl restart engram

# Stop the Service
sudo systemctl stop engram
```

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

### GET /api/v1/stores/{store_id}/sync/snapshot

Source: https://github.com/hyperengineering/engram/blob/main/docs/recall-client-sync-integration.md

Initiates a full data synchronization by providing a complete snapshot of the store's data. Used for initial setup or full data resets.

```APIDOC
## GET /api/v1/stores/{store_id}/sync/snapshot

### Description
Initiates a full data synchronization by providing a complete snapshot of the store's data. Used for initial setup or full data resets.

### Method
GET

### Endpoint
`/api/v1/stores/{store_id}/sync/snapshot`

### Headers
- **Authorization**: Bearer <token>

### Response
#### Success Response (200)
- **Body**: Binary SQLite database file (`application/octet-stream`).

#### Error Response (503)
- **Headers**: `Retry-After: <seconds>` (indicates when the snapshot will be ready).

### Snapshot Contents
The downloaded snapshot includes the following tables:
- `lore_entries`: All lore data.
- `store_metadata`: Store configuration.
- `change_log`: Server-side change history.
- `push_idempotency`: Server push cache (can be ignored client-side).
- `sync_meta`: Sync protocol state.

### Bootstrap Flow
1. Request the snapshot using `GET /stores/{store_id}/sync/snapshot`.
2. If a `503` error is received, wait for the duration specified in the `Retry-After` header and retry.
3. Upon receiving a `200` response, save the binary body to a temporary file.
4. Verify the integrity of the downloaded SQLite database using `PRAGMA integrity_check`.
5. Read the `MAX(sequence)` from the `change_log` table to determine the starting point for delta pulls.
6. Atomically replace the existing local database with the downloaded snapshot.
7. Initialize `sync_meta` with the `last_pull_seq` from the snapshot, `last_push_seq` as '0', and a new `source_id`.
```

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

### Initialize Engram Go Module and Dependencies

Source: https://github.com/hyperengineering/engram/blob/main/docs/engram.md

Initializes a new Go module for the Engram project and fetches necessary dependencies using 'go mod'. This includes chi for routing, go-openai for OpenAI integration, modernc.org/sqlite for database access, ulid for unique IDs, and cobra for CLI commands. Finally, 'go mod tidy' cleans up the module dependencies.

```bash
mkdir engram && cd engram

go mod init github.com/hyperengineering/engram

go get github.com/go-chi/chi/v5
go get github.com/sashabaranov/go-openai
go get modernc.org/sqlite
go get github.com/oklog/ulid/v2
go get github.com/spf13/cobra

go mod tidy
```

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

### Forge Configuration Example (YAML)

Source: https://github.com/hyperengineering/engram/blob/main/docs/engram.md

Example configuration file for Forge, specifying settings for recall, engram service, and synchronization. Uses environment variable interpolation for sensitive information like API keys.

```yaml
# .forge/config.yaml (in devcontainer)
recall:
  enabled: true
  lore_path: "${FORGE_DATA_DIR}/lore.db"
  engram:
    url: "https://engram.forge.dev"
    api_key: "${ENGRAM_API_KEY}"
  sync:
    interval: "5m"
    on_boot: true
    on_shutdown: true
  passive_injection:
    enabled: true
    k: 5
    min_confidence: 0.6
```

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

### Recall CLI Root Command (Go)

Source: https://github.com/hyperengineering/engram/blob/main/docs/engram.md

Sets up the root command for the Recall CLI using Cobra. It initializes the CLI and adds subcommands for various operations like recording, querying, and syncing lore.

```go
package main

import (
    "os"

    "github.com/spf13/cobra"
)

func main() {
    if err := rootCmd.Execute(); err != nil {
        os.Exit(1)
    }
}

var rootCmd = &cobra.Command{
    Use:   "recall",
    Short: "Recall - Lore management CLI",
}

func init() {
    rootCmd.AddCommand(recordCmd)
    rootCmd.AddCommand(queryCmd)
    rootCmd.AddCommand(syncCmd)
}

```

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

### GET /api/v1/lore/snapshot

Source: https://github.com/hyperengineering/engram/blob/main/docs/api-usage.md

Get a complete database snapshot for initial bootstrap. The response is a binary SQLite database file.

```APIDOC
## GET /api/v1/lore/snapshot

### Description
Get a complete database snapshot for initial bootstrap. The response is a binary SQLite database file containing all active lore with embeddings.

### Method
GET

### Endpoint
/api/v1/lore/snapshot

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://engram.example.com/api/v1/lore/snapshot \
  -o engram-snapshot.db
```

### Response
#### Success Response (200)
- **Content-Type**: `application/octet-stream`
- **Body**: Binary SQLite database file

#### Error Response (503 Service Unavailable)
Returned if no snapshot is available yet. Includes a `Retry-After` header indicating when to retry.

#### Response Example (Headers Only Check)
```bash
curl -I -H "Authorization: Bearer YOUR_API_KEY" \
  https://engram.example.com/api/v1/lore/snapshot
```
```

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

### Recall CLI Examples for Engram

Source: https://github.com/hyperengineering/engram/blob/main/docs/e2e-test-plan.md

Provides examples of how to use the Recall command-line interface for various operations within the Engram project. These include recording lore, querying data, providing feedback, performing sync operations, and retrieving statistics. These commands are essential for interacting with and testing the Engram system.

```bash
# Record lore
/workspaces/engram/tmp/recall record \
  --content "ORM generates N+1 queries for polymorphic associations" \
  --category DEPENDENCY_BEHAVIOR \
  --confidence 0.70 \
  --context "E2E test scenario"

# Query with JSON output
/workspaces/engram/tmp/recall query "ORM queries" --json --top 5

# Feedback using session refs (L1, L2, etc.)
/workspaces/engram/tmp/recall feedback --id L1 --type helpful
/workspaces/engram/tmp/recall feedback --helpful L1,L2 --incorrect L3

# Sync operations
/workspaces/engram/tmp/recall sync bootstrap
/workspaces/engram/tmp/recall sync push

# Stats
/workspaces/engram/tmp/recall stats
```

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

### Perform Manual Engram Removal

Source: https://github.com/hyperengineering/engram/blob/main/docs/systemd-setup-guide.md

Guides through the manual uninstallation of Engram, including stopping and disabling the service, removing binaries and configuration files, and optionally removing data and user/group.

```bash
sudo systemctl stop engram
sudo systemctl disable engram
sudo rm /usr/lib/systemd/system/engram.service
sudo rm /usr/bin/engram
sudo rm -rf /etc/engram
# Optionally remove data:
# sudo rm -rf /var/lib/engram
sudo userdel engram
sudo groupdel engram
sudo systemctl daemon-reload
```

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

### Initial Bootstrap: Download Full Engram Snapshot

Source: https://github.com/hyperengineering/engram/blob/main/docs/api-usage.md

This workflow shows how to perform an initial bootstrap for a new client environment by downloading the full Engram lore database snapshot. It includes steps to verify service health and check model compatibility before downloading.

```bash
# 1. Verify service is healthy and check embedding model
curl https://engram.example.com/api/v1/health

# 2. Check if models match (important for semantic search compatibility)
# Response includes: "embedding_model": "text-embedding-3-small"

# 3. Download full snapshot
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://engram.example.com/api/v1/lore/snapshot \
  -o lore-snapshot.db

# 4. Replace local database with snapshot
# (Implementation-specific to your client)
```

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

### Load Test Fixtures with Go Helpers

Source: https://github.com/hyperengineering/engram/blob/main/docs/sync-integration-e2e-test-plan.md

Offers Go functions for loading various test fixture files used in Engram's testing suite. These include fixtures for Recall, Tract, and multi-client scenarios. A helper function to get the absolute path to the test fixtures directory is also provided.

```go
// loadRecallFixture loads a Recall fixture file and returns parsed entries.
func loadRecallFixture(t *testing.T, name string) []recallFixtureEntry

// loadTractFixture loads a Tract fixture file and returns entity graph.
func loadTractFixture(t *testing.T, name string) tractFixtureGraph

// loadScenario loads a multi-client scenario fixture.
func loadScenario(t *testing.T, name string) scenarioFixture

// fixturesDir returns the absolute path to test/fixtures/.
func fixturesDir() string
```

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

### GET /api/v1/health

Source: https://github.com/hyperengineering/engram/blob/main/docs/api-usage.md

Retrieves health information about the Engram service, including the embedding model in use.

```APIDOC
## GET /api/v1/health

### Description
This endpoint provides health status information for the Engram service, including details about the currently active embedding model.

### Method
GET

### Endpoint
`/api/v1/health`

### Response
#### Success Response (200)
- **embedding_model** (string) - The name of the embedding model currently in use.

#### Response Example
```json
{
  "embedding_model": "text-embedding-3-small"
}
```
```

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

### Get Full Lore Snapshot

Source: https://github.com/hyperengineering/engram/blob/main/docs/api-usage.md

Downloads the full database snapshot for bootstrapping a new Recall client environment.

```APIDOC
## Get Full Lore Snapshot

### Description

Downloads the full database snapshot for bootstrapping a new Recall client environment.

### Method

GET

### Endpoint

`/api/v1/lore/snapshot`

### Parameters

#### Query Parameters

- **Authorization** (string) - Bearer token for authentication.

### Request Example

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://engram.example.com/api/v1/lore/snapshot \
  -o lore-snapshot.db
```

### Notes

After downloading, replace the local database with this snapshot. (Implementation-specific to your client).
```

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

### Wrap Recall CLI for Testing

Source: https://github.com/hyperengineering/engram/blob/main/docs/sync-integration-e2e-test-plan.md

Provides a wrapper for the Recall CLI binary to simplify test interactions. It enables recording, querying, feedback submission, and direct SQLite database inspection for verification.

```go
type recallCLI struct {
	bin      string
	dbPath   string
	storeID  string
	sourceID string
	env      []string
}

func newRecallCLI(t *testing.T, server *engramServer, storeID string) *recallCLI
func (r *recallCLI) record(t *testing.T, content, category string, confidence float64) string
func (r *recallCLI) feedback(t *testing.T, helpful, incorrect, notRelevant []string)
func (r *recallCLI) query(t *testing.T, queryStr string, k int) []loreResult
func (r *recallCLI) sync(t *testing.T) syncResult
func (r *recallCLI) exec(t *testing.T, args ...string) (string, string, error)
func (r *recallCLI) db(t *testing.T) *sql.DB
func (r *recallCLI) loreCount(t *testing.T) int
func (r *recallCLI) loreEntry(t *testing.T, id string) *loreEntry
```

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

### Uninstall Engram Package

Source: https://github.com/hyperengineering/engram/blob/main/docs/systemd-setup-guide.md

Details the process for uninstalling Engram using package managers for Debian/Ubuntu and RHEL/Fedora systems.

```bash
# Debian/Ubuntu
sudo apt remove engram

# RHEL/Fedora
sudo dnf remove engram
```

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

### GET /api/v1/lore/delta

Source: https://github.com/hyperengineering/engram/blob/main/docs/api-usage.md

Retrieve incremental changes since a given timestamp. The response includes lore changes and deleted IDs.

```APIDOC
## GET /api/v1/lore/delta

### Description
Retrieve incremental changes since a given timestamp. The response includes lore changes and deleted IDs, along with a timestamp for the next delta request.

### Method
GET

### Endpoint
/api/v1/lore/delta

### Parameters
#### Path Parameters
None

#### Query Parameters
- **since** (string) - Required - Timestamp in RFC 3339 format (e.g., `2026-01-28T10:00:00Z`) to retrieve changes after.

### Request Example
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://engram.example.com/api/v1/lore/delta?since=2026-01-28T10:00:00Z"
```

### Response
#### Success Response (200)
- **lore** (array) - List of lore entries that have changed since the `since` timestamp.
  - **id** (string) - Unique identifier for the lore entry.
  - **content** (string) - The content of the lore entry.
  - **context** (string) - Additional context for the lore entry.
  - **category** (string) - The category of the lore entry.
  - **confidence** (number) - The confidence score of the lore entry.
  - **embedding** (array) - The embedding vector for the lore entry.
  - **source_id** (string) - The original source ID.
  - **sources** (array) - List of source IDs associated with this lore.
  - **validation_count** (integer) - Number of times this lore has been validated.
  - **created_at** (string) - Timestamp when the lore was created.
  - **updated_at** (string) - Timestamp when the lore was last updated.
  - **last_validated_at** (string) - Timestamp when the lore was last validated.
  - **embedding_status** (string) - Status of the embedding generation.
- **deleted_ids** (array) - List of IDs of lore entries that have been deleted.
- **as_of** (string) - Timestamp indicating the point in time for this delta. Use this for the `since` parameter in the next request.

#### Response Example
```json
{
  "lore": [
    {
      "id": "01ARYZ6S41TSV4RRFFQ69G5FAV",
      "content": "Event sourcing adds unnecessary complexity for simple CRUD operations",
      "context": "Architecture review for inventory service",
      "category": "ARCHITECTURAL_DECISION",
      "confidence": 0.85,
      "embedding": [0.123, -0.456, 0.789, ...],
      "source_id": "devcontainer-xyz789",
      "sources": ["devcontainer-xyz789", "devcontainer-abc123"],
      "validation_count": 3,
      "created_at": "2026-01-27T08:30:00Z",
      "updated_at": "2026-01-28T11:15:00Z",
      "last_validated_at": "2026-01-28T11:15:00Z",
      "embedding_status": "complete"
    }
  ],
  "deleted_ids": [
    "01ARYZ6S41TSV4RRFFQ69G5ABC"
  ],
  "as_of": "2026-01-28T14:30:00Z"
}
```
```

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

### Recall Devcontainer Post-Create Script (post-create.sh)

Source: https://github.com/hyperengineering/engram/blob/main/docs/engram.md

This bash script is executed after the devcontainer is created. It ensures Go modules are downloaded, creates a data directory for the database, installs the golangci-lint tool, and prints a confirmation message.

```bash
#!/bin/bash
set -e

go mod download
mkdir -p /workspaces/recall/data
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

echo "=== Recall dev environment ready ==="
```

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

### Initialize Recall Client in Forge

Source: https://github.com/hyperengineering/engram/blob/main/docs/engram.md

This Go code demonstrates how to initialize the Recall client within the Forge application. It configures the client with local database path, Engram service URL, API key, and a source ID. It also shows optional registration of MCP tools and an initial sync operation.

```go
import (
    "github.com/hyperengineering/recall"
    recallmcp "github.com/hyperengineering/recall/mcp"
)

// Initialize Recall client
client, err := recall.New(recall.Config{
    LocalPath: os.Getenv("FORGE_DATA_DIR") + "/lore.db",
    EngramURL: os.Getenv("ENGRAM_URL"),
    APIKey:    os.Getenv("ENGRAM_API_KEY"),
    SourceID:  hostname(),
})
if err != nil {
    return err
}
defer client.Close()

// Register MCP tools (optional)
recallmcp.RegisterTools(mcpRegistry, client)

// Sync on startup
if err := client.Sync(ctx); err != nil {
    slog.Warn("Initial sync failed", "error", err)
}
```

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

### GET /api/v1/health

Source: https://github.com/hyperengineering/engram/blob/main/docs/api-usage.md

Checks the health and status of the Engram service. This endpoint does not require authentication and is useful for verifying service availability.

```APIDOC
## GET /api/v1/health

### Description
Checks the health and status of the Engram service. This endpoint does not require authentication and is useful for verifying service availability.

### Method
GET

### Endpoint
/api/v1/health

### Parameters
No parameters required.

### Response
#### Success Response (200)
- **status** (string) - The current status of the service (e.g., 'healthy').
- **version** (string) - The version of the Engram service.
- **embedding_model** (string) - The embedding model currently in use.
- **lore_count** (integer) - The total number of lore entries.
- **last_snapshot** (string) - Timestamp of the last snapshot.

#### Response Example
```json
{
  "status": "healthy",
  "version": "1.0.0",
  "embedding_model": "text-embedding-3-small",
  "lore_count": 1234,
  "last_snapshot": "2026-01-28T12:00:00Z"
}
```
```

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

### Extended Stats Response Example (JSON)

Source: https://github.com/hyperengineering/engram/blob/main/docs/api-usage.md

Example JSON response for the extended stats endpoint, providing in-depth metrics about the Engram system. It details lore counts, embedding and category statistics, quality indicators, and timing information for snapshots and decay processes.

```json
{
  "total_lore": 1234,
  "active_lore": 1200,
  "deleted_lore": 34,
  "embedding_stats": {
    "complete": 1195,
    "pending": 3,
    "failed": 2
  },
  "category_stats": {
    "ARCHITECTURAL_DECISION": 156,
    "PATTERN_OUTCOME": 234,
    "INTERFACE_LESSON": 89,
    "EDGE_CASE_DISCOVERY": 178,
    "IMPLEMENTATION_FRICTION": 145,
    "TESTING_STRATEGY": 201,
    "DEPENDENCY_BEHAVIOR": 112,
    "PERFORMANCE_INSIGHT": 85
  },
  "quality_stats": {
    "average_confidence": 0.72,
    "validated_count": 456,
    "high_confidence_count": 890,
    "low_confidence_count": 78
  },
  "unique_source_count": 12,
  "last_snapshot": "2026-01-28T12:00:00Z",
  "last_decay": "2026-01-28T00:00:00Z",
  "stats_as_of": "2026-01-30T14:30:00Z"
}
```

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

### Health Check Response Example (JSON)

Source: https://github.com/hyperengineering/engram/blob/main/docs/api-usage.md

Example JSON response for the health check endpoint, indicating the service is operational. It includes the current status, software version, active embedding model, total lore count, and the timestamp of the last data snapshot.

```json
{
  "status": "healthy",
  "version": "1.0.0",
  "embedding_model": "text-embedding-3-small",
  "lore_count": 1234,
  "last_snapshot": "2026-01-28T12:00:00Z"
}
```

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

### Recall Client Library: Register MCP Tools (Go)

Source: https://github.com/hyperengineering/engram/blob/main/docs/engram.md

Provides Go functions to register Recall tools with an MCP registry. This integration is optional and allows Recall's functionalities (querying, recording, feedback) to be exposed as tools within an MCP framework. It requires a Recall client instance and a registry object.

```go
package mcp

import "github.com/hyperengineering/recall"

// RegisterTools registers Recall tools with an MCP registry.
// This is optional — Recall can be used without MCP.
func RegisterTools(registry Registry, client *recall.Client) {
    registry.Register(Tool{
        Name:        "recall_query",
        Description: "Retrieve relevant lore based on semantic similarity",
        Parameters: Schema{
            "query":          {Type: "string", Required: true},
            "k":              {Type: "integer", Default: 5},
            "min_confidence": {Type: "number", Default: 0.5},
            "categories":     {Type: "array", Items: "string"},
        },
        Handler: makeQueryHandler(client),
    })

    registry.Register(Tool{
        Name:        "recall_record",
        Description: "Capture lore from current experience",
        Parameters: Schema{
            "content":    {Type: "string", Required: true},
            "category":   {Type: "string", Required: true},
            "context":    {Type: "string"},
            "confidence": {Type: "number", Default: 0.7},
        },
        Handler: makeRecordHandler(client),
    })

    registry.Register(Tool{
        Name:        "recall_feedback",
        Description: "Provide feedback on lore recalled this session",
        Parameters: Schema{
            "helpful":      {Type: "array", Items: "string"},
            "not_relevant": {Type: "array", Items: "string"},
            "incorrect":    {Type: "array", Items: "string"},
        },
        Handler: makeFeedbackHandler(client),
    })
}
```

```go
import (
    "github.com/hyperengineering/recall"
    recallmcp "github.com/hyperengineering/recall/mcp"
)

client, _ := recall.New(cfg)
recallmcp.RegisterTools(mcpRegistry, client)
```

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

### GET /api/v1/stores/{store_id}/sync/snapshot

Source: https://github.com/hyperengineering/engram/blob/main/docs/recall-client-sync-integration.md

Retrieves a binary SQLite snapshot for a specific store to facilitate data synchronization.

```APIDOC
## GET /api/v1/stores/{store_id}/sync/snapshot

### Description
Retrieves a binary SQLite snapshot for the specified store. This endpoint is used for initial data synchronization.

### Method
GET

### Endpoint
/api/v1/stores/{store_id}/sync/snapshot

### Parameters
#### Path Parameters
- **store_id** (string) - Required - The unique identifier of the store.

### Response
#### Success Response (200)
- **body** (binary) - Returns a binary SQLite database file.

#### Pending Response (503)
- **Retry-After** (header) - Indicates the number of seconds to wait before retrying the request.
```

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

### Install and Configure Engram as Systemd Service (Bash)

Source: https://github.com/hyperengineering/engram/blob/main/README.md

Provides bash commands to install Engram via a Debian package, configure API keys by editing a file, and start/enable the Engram systemd service. Assumes a Debian-based Linux system.

```bash
# Install via package (recommended)
sudo dpkg -i engram_1.0.0_linux_amd64.deb

# Configure API keys
sudo nano /etc/engram/environment

# Start and enable
sudo systemctl enable --now engram
```

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

### GET /api/v1/stats

Source: https://github.com/hyperengineering/engram/blob/main/docs/api-usage.md

Retrieves detailed system metrics for monitoring dashboards. This endpoint does not require authentication and provides insights into lore, embeddings, categories, and quality.

```APIDOC
## GET /api/v1/stats

### Description
Retrieves detailed system metrics for monitoring dashboards. This endpoint does not require authentication and provides insights into lore, embeddings, categories, and quality.

### Method
GET

### Endpoint
/api/v1/stats

### Parameters
No parameters required.

### Response
#### Success Response (200)
- **total_lore** (integer) - All lore entries including deleted.
- **active_lore** (integer) - Non-deleted lore entries.
- **deleted_lore** (integer) - Soft-deleted entries.
- **embedding_stats** (object) - Statistics related to embedding generation.
  - **complete** (integer) - Entries with generated embeddings.
  - **pending** (integer) - Entries awaiting embedding generation.
  - **failed** (integer) - Entries that failed embedding after max retries.
- **category_stats** (object) - Count of entries per category.
- **quality_stats** (object) - Statistics related to lore quality.
  - **average_confidence** (number) - Mean confidence score.
  - **validated_count** (integer) - Entries with at least one "helpful" feedback.
  - **high_confidence_count** (integer) - Entries with confidence >= 0.7.
  - **low_confidence_count** (integer) - Entries with confidence < 0.3.
- **unique_source_count** (integer) - Number of distinct source environments.
- **last_snapshot** (string) - Timestamp of the last snapshot.
- **last_decay** (string) - Timestamp when confidence decay last ran.
- **stats_as_of** (string) - Timestamp when these statistics were generated.

#### Response Example
```json
{
  "total_lore": 1234,
  "active_lore": 1200,
  "deleted_lore": 34,
  "embedding_stats": {
    "complete": 1195,
    "pending": 3,
    "failed": 2
  },
  "category_stats": {
    "ARCHITECTURAL_DECISION": 156,
    "PATTERN_OUTCOME": 234,
    "INTERFACE_LESSON": 89,
    "EDGE_CASE_DISCOVERY": 178,
    "IMPLEMENTATION_FRICTION": 145,
    "TESTING_STRATEGY": 201,
    "DEPENDENCY_BEHAVIOR": 112,
    "PERFORMANCE_INSIGHT": 85
  },
  "quality_stats": {
    "average_confidence": 0.72,
    "validated_count": 456,
    "high_confidence_count": 890,
    "low_confidence_count": 78
  },
  "unique_source_count": 12,
  "last_snapshot": "2026-01-28T12:00:00Z",
  "last_decay": "2026-01-28T00:00:00Z",
  "stats_as_of": "2026-01-30T14:30:00Z"
}
```
```

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

### Build Engram from Source

Source: https://github.com/hyperengineering/engram/blob/main/README.md

Compiles the Engram project from its source code using Go 1.23+. It involves cloning the repository, navigating into the directory, running the build command, and then executing the compiled binary.

```bash
git clone https://github.com/hyperengineering/engram.git
cd engram
make build
./dist/engram
```

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

### System Statistics API

Source: https://github.com/hyperengineering/engram/blob/main/docs/getting-started.md

This endpoint provides detailed statistics about the Engram system, including lore counts, embedding pipeline status, category distribution, and quality metrics.

```APIDOC
## GET /api/v1/stats

### Description
Retrieves detailed statistics about the Engram system.

### Method
GET

### Endpoint
/api/v1/stats

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl http://localhost:8080/api/v1/stats
```

### Response
#### Success Response (200)
- **lore_count** (integer) - Total number of lore entries.
- **embedding_pipeline_status** (string) - Status of the embedding pipeline.
- **category_distribution** (object) - Distribution of lore entries by category.
- **quality_metrics** (object) - Metrics related to the quality of stored lore.

#### Response Example
```json
{
  "lore_count": 1,
  "embedding_pipeline_status": "idle",
  "category_distribution": {
    "DEPENDENCY_BEHAVIOR": 1
  },
  "quality_metrics": {
    "average_confidence": 0.85
  }
}
```
```