Kiroku Memory

https://github.com/yelban/kiroku-memory
Admin
A tiered retrieval memory system for AI agents with 100% local storage, conflict resolution, and a...
Tokens:23,204
Snippets:286
Trust Score:6.2
Update:5 months ago
Show doc for...
Tokens:
Raw
### Start Kiroku Memory API with SurrealDB

Source: https://github.com/yelban/kiroku-memory/blob/main/README.md

Configure the backend to use SurrealDB in your .env file and start the API server. No Docker is needed for this setup, and data will be stored locally.

```bash
# Configure backend in .env
echo "BACKEND=surrealdb" >> .env

# Start the API server (no Docker needed!)
uv run uvicorn kiroku_memory.api:app --reload

# Data stored in ./data/kiroku/
```

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

### Install Kiroku Memory using install.sh

Source: https://github.com/yelban/kiroku-memory/blob/main/README.md

Installs Kiroku Memory using a one-click script or by cloning the repository and running the install script manually.

```bash
curl -fsSL https://raw.githubusercontent.com/yelban/kiroku-memory/main/skill/assets/install.sh | bash
```

```bash
git clone https://github.com/yelban/kiroku-memory.git
cd kiroku-memory/skill/assets && ./install.sh
```

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

### Start PostgreSQL Backend

Source: https://github.com/yelban/kiroku-memory/blob/main/CLAUDE.md

Use this command to start the PostgreSQL backend with pgvector using Docker Compose. Ensure Docker is installed and running.

```bash
docker compose up -d
```

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

### Create .env file from example

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/installation-guide.md

This command copies the example environment file to a new file named .env, which should then be populated with your actual API keys.

```bash
cp .env.example .env
```

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

### Install Kiroku Memory Skill Files

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/installation-guide.md

Copies the Kiroku Memory skill files to the Claude Code skills directory. This should be run after the API service is started.

```bash
cd ~/projects/kiroku-memory
./skill/assets/install.sh
```

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

### Start API Server

Source: https://github.com/yelban/kiroku-memory/blob/main/CLAUDE.md

Starts the Kiroku Memory API server using uvicorn. This command is used after setting up the backend.

```bash
uv run uvicorn kiroku_memory.api:app --reload
```

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

### Verify launchd Installation

Source: https://github.com/yelban/kiroku-memory/blob/main/README.md

Verifies that the Kiroku memory launchd jobs have been installed correctly by checking the launchctl list.

```bash
launchctl list | grep kiroku
```

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

### Verify uv Installation

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/installation-guide.md

Check if uv has been installed correctly by verifying its version.

```bash
uv --version
```

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

### Start Kiroku Memory Service

Source: https://github.com/yelban/kiroku-memory/blob/main/commands/memory-status.md

If the Kiroku Memory service is not running, navigate to the project directory and use Docker Compose to start the services. Then, use uv to run the Uvicorn server.

```bash
cd ~/path/to/kiroku-memory
docker compose up -d
uv run uvicorn kiroku_memory.api:app --reload
```

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

### Configure Environment Variables

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/installation-guide.md

Copies the example environment file and opens it for editing. Set your OpenAI API key in this file.

```bash
# Copy the example file
cp .env.example .env

# Open in your editor
open -e .env   # Opens in TextEdit
# Or use: nano .env / vim .env / code .env
```

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

### shadcn/ui Installation and Component Addition

Source: https://github.com/yelban/kiroku-memory/blob/main/desktop/design-system/DESIGN.md

Commands to initialize shadcn/ui in a project and add specific UI components. Ensure you have npx available.

```bash
# Initialize shadcn/ui
npx shadcn@latest init

# Install required components
npx shadcn@latest add button input badge card dialog \
  dropdown-menu switch table toast tooltip scroll-area separator
```

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

### Clone Repository and Install Dependencies

Source: https://github.com/yelban/kiroku-memory/blob/main/README.md

Clone the Kiroku Memory repository and install project dependencies using uv. Remember to copy and edit the environment file to set your OpenAI API Key.

```bash
git clone https://github.com/yelban/kiroku-memory.git
cd kiroku-memory

uv sync

cp .env.example .env

# Edit .env and set your OPENAI_API_KEY
```

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

### Install Python Dependencies with uv

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/installation-guide.md

Installs all required Python packages for Kiroku Memory using uv. This command also creates a virtual environment.

```bash
uv sync
```

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

### Install SurrealDB Dependency

Source: https://github.com/yelban/kiroku-memory/blob/main/CLAUDE.md

Installs the SurrealDB dependency for Kiroku Memory. This is part of Option B for using SurrealDB as the backend.

```bash
uv sync --extra surrealdb
```

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

### Start Kiroku Memory API with PostgreSQL

Source: https://github.com/yelban/kiroku-memory/blob/main/README.md

Start the PostgreSQL service with pgvector enabled using Docker Compose, then run the API server. The API will be accessible at http://localhost:8000.

```bash
# Start PostgreSQL with pgvector
docker compose up -d

# Start the API server
uv run uvicorn kiroku_memory.api:app --reload

# The API will be available at http://localhost:8000
```

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

### Install uv Python Package Manager

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/installation-guide.md

Installs uv, a fast Python package manager, using a curl script. Restart your terminal or source your shell configuration after installation.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

```bash
source ~/.zshrc
```

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

### Install launchd Jobs (macOS)

Source: https://github.com/yelban/kiroku-memory/blob/main/README.md

Installs scheduled jobs for automatic maintenance on macOS using launchd.

```bash
bash launchd/install.sh
```

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

### Lucide React Icon Installation

Source: https://github.com/yelban/kiroku-memory/blob/main/desktop/design-system/DESIGN.md

Command to install the Lucide React icon library. This library provides a wide range of SVG icons.

```bash
npm install lucide-react
```

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

### Install SurrealDB Dependency

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/surrealdb-setup.md

Add the SurrealDB optional dependency to your project using uv sync.

```bash
# Add surrealdb optional dependency
uv sync --extra surrealdb
```

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

### Environment Variables Configuration

Source: https://github.com/yelban/kiroku-memory/blob/main/CLAUDE.md

Example of environment variables to configure Kiroku Memory. Copy from .env.example and adjust settings for your chosen backend (PostgreSQL or SurrealDB) and optional features like semantic search.

```bash
# Backend selection (postgres or surrealdb)
BACKEND=postgres

# PostgreSQL settings (when BACKEND=postgres)
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/memory

# SurrealDB settings (when BACKEND=surrealdb)
SURREAL_URL=file://./data/kiroku
SURREAL_NAMESPACE=kiroku
SURREAL_DATABASE=memory

# Optional - only needed for semantic search (embeddings)
OPENAI_API_KEY=sk-xxx
```

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

### Load launchd service

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/installation-guide.md

This command loads the configured launchd service, enabling it to start automatically.

```bash
launchctl load ~/Library/LaunchAgents/com.kiroku-memory.api.plist
```

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

### SurrealDB Graph Edge Example

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/surrealdb-migration-plan.md

Example of how to create a graph edge between two 'item' records using the RELATE statement in SurrealQL.

```surql
-- Graph edges using native RELATE
-- Example: RELATE item:uuid("...") -> knows -> item:uuid("...") SET weight = 0.8, created_at = time::now();
```

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

### Integrate Kiroku Memory Context into Agent Prompt

Source: https://github.com/yelban/kiroku-memory/blob/main/CLAUDE.md

Example of how to fetch memory context from the Kiroku Memory API and prepend it to an original prompt. This is useful for providing AI agents with relevant background information.

```javascript
// Get memory context
const context = await fetch("http://localhost:8000/context").then(r => r.json());

// Add to system prompt
const enhancedPrompt = `${context.context}\n\n${originalPrompt}`;

// Save important info after conversation
await fetch("http://localhost:8000/ingest", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ content: "User likes...", source: "my-agent" })
});
```

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

### Verify Kiroku Memory Installation

Source: https://github.com/yelban/kiroku-memory/blob/main/README.md

Perform a health check on the Kiroku Memory API to ensure it is running correctly. A detailed status check is also available.

```bash
# Health check
curl http://localhost:8000/health
# Expected: {"status":"ok","version":"0.1.0"}

# Detailed health status
curl http://localhost:8000/health/detailed
```

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

### Get Resource Repository Factory

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/surrealdb-migration-plan.md

Factory function to get the appropriate resource repository based on the configured backend.

```python
from .base import ResourceRepository
from .postgres.resource import PostgresResourceRepository
from .surrealdb.resource import SurrealResourceRepository
from ..config import settings

def get_resource_repo() -> ResourceRepository:
    if settings.backend == "surrealdb":
        return SurrealResourceRepository()
    return PostgresResourceRepository()
```

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

### SurrealDB Connection URL Formats

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/surrealdb-setup.md

Examples of different SurrealDB connection URL formats for embedded, absolute path, and remote server configurations.

```bash
# Embedded (SurrealKV) - recommended for desktop
SURREAL_URL=file://./data/kiroku
```

```bash
# Absolute path
SURREAL_URL=file:///Users/me/kiroku-data
```

```bash
# Remote SurrealDB server (if needed)
SURREAL_URL=ws://localhost:8000
```

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

### Install Kiroku Memory Claude Code Skill

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/installation-guide.md

Use this command to add the Kiroku Memory skill to Claude Code. This is part of the Desktop App installation.

```bash
npx skills add yelban/kiroku-memory
```

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

### Clone Kiroku Memory Repository

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/installation-guide.md

Clones the Kiroku Memory project from GitHub into a specified directory. Ensure you have git installed.

```bash
# Create projects directory if it doesn't exist
mkdir -p ~/projects
cd ~/projects

# Clone the repository
git clone https://github.com/yelban/kiroku-memory.git
cd kiroku-memory
```

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

### Verify Code Signing Identity

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/macos-code-signing.md

Lists all valid code signing identities available in the default keychain. Use this to confirm your Developer ID certificate has been installed correctly.

```bash
security find-identity -v -p codesigning
```

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

### Retrieve Memories

Source: https://github.com/yelban/kiroku-memory/blob/main/README.md

Use the /retrieve endpoint with a query parameter for tiered retrieval, combining summaries and items. The /context endpoint can be used to get context for agent prompts.

```bash
# Tiered retrieval (summaries + items)
curl "http://localhost:8000/retrieve?query=What%20does%20John%20do"

# Get context for agent prompt
curl "http://localhost:8000/context"
```

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

### Interact with Kiroku Memory in Claude Code

Source: https://github.com/yelban/kiroku-memory/blob/main/README.md

Commands to save memory, recall information, and check memory status within Claude Code after installation.

```bash
/remember 用戶偏好深色模式          # Save memory
```

```bash
/recall 編輯器偏好                  # Search memories
```

```bash
/memory-status                      # Check status
```

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

### Clone Repository and Build Desktop App

Source: https://github.com/yelban/kiroku-memory/blob/main/desktop/README.md

Steps to clone the Kiroku Memory repository, build the Python runtime, and then build the desktop application using npm. Ensure you are in the 'desktop' directory before running npm commands.

```bash
git clone https://github.com/yelban/kiroku-memory.git
cd kiroku-memory

bash tools/packaging/build-python.sh

cd desktop
npm install
npm run tauri build
```

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

### Configure SurrealDB Backend

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/surrealdb-setup.md

Set the BACKEND environment variable to 'surrealdb' and configure SurrealDB connection details in the .env file.

```bash
# Switch to SurrealDB backend
BACKEND=surrealdb

# SurrealDB settings (optional, defaults shown)
SURREAL_URL=file://./data/kiroku
SURREAL_NAMESPACE=kiroku
SURREAL_DATABASE=memory
```

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

### File Structure Overview

Source: https://github.com/yelban/kiroku-memory/blob/main/desktop/design-system/DESIGN.md

Illustrates the directory structure for the Kiroku Memory project. Highlights key directories like src/components, src/pages, and src/lib.

```plaintext
desktop/
├── src/
│   ├── components/
│   │   ├── ui/                  # shadcn/ui (auto-generated)
│   │   ├── layout/
│   │   │   ├── Sidebar.tsx
│   │   │   └── Titlebar.tsx
│   │   ├── dashboard/
│   │   │   ├── StatCard.tsx
│   │   │   └── RecentMemories.tsx
│   │   ├── memories/
│   │   │   ├── MemoryList.tsx
│   │   │   ├── MemoryItem.tsx
│   │   │   └── SearchBar.tsx
│   │   └── settings/
│   │       └── ApiKeyInput.tsx
│   ├── pages/
│   │   ├── Status.tsx
│   │   ├── Memories.tsx
│   │   ├── Settings.tsx
│   │   └── Maintenance.tsx
│   ├── lib/
│   │   ├── api.ts
│   │   ├── tauri.ts
│   │   └── utils.ts
│   ├── styles/
│   │   └── globals.css
│   ├── App.tsx
│   └── main.tsx
└── index.html
```

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

### Tiered Retrieval

Source: https://github.com/yelban/kiroku-memory/blob/main/CLAUDE.md

Performs tiered retrieval of memories, starting with summaries and drilling down as needed.

```APIDOC
## GET /retrieve

### Description
Performs tiered retrieval of memories. The system first retrieves summaries and then allows for drilling down into more specific details as needed.

### Method
GET

### Endpoint
/retrieve

### Query Parameters
- **query** (string) - Optional - The query to use for retrieval.
- **limit** (integer) - Optional - The maximum number of results to return.
```

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

### Create launchd plist file for Kiroku Memory API

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/installation-guide.md

This bash script creates a plist file to configure the Kiroku Memory API to auto-start using launchd. Remember to replace YOUR_USERNAME with your actual macOS username.

```bash
cat > ~/Library/LaunchAgents/com.kiroku-memory.api.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.kiroku-memory.api</string>

    <key>ProgramArguments</key>
    <array>
        <string>/Users/YOUR_USERNAME/.local/bin/uv</string>
        <string>run</string>
        <string>uvicorn</string>
        <string>kiroku_memory.api:app</string>
        <string>--host</string>
        <string>127.0.0.1</string>
        <string>--port</string>
        <string>8000</string>
    </array>

    <key>WorkingDirectory</key>
    <string>/Users/YOUR_USERNAME/projects/kiroku-memory</string>

    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/Users/YOUR_USERNAME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
    </dict>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>StandardOutPath</key>
    <string>/tmp/kiroku-api.log</string>

    <key>StandardErrorPath</key>
    <string>/tmp/kiroku-api.err</string>
</dict>
</plist>
EOF
```

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

### Get current username

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/installation-guide.md

This command retrieves your current macOS username, which is needed to correctly configure the launchd plist file.

```bash
whoami
```

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

### Configure SurrealDB Backend

Source: https://github.com/yelban/kiroku-memory/blob/main/CLAUDE.md

Sets the BACKEND environment variable to 'surrealdb' in the .env file. This is required when using SurrealDB.

```bash
echo "BACKEND=surrealdb" >> .env
```

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

### Lint launchd plist file

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/installation-guide.md

This command checks the syntax of the launchd plist file for errors, helping to troubleshoot service startup issues.

```bash
plutil -lint ~/Library/LaunchAgents/com.kiroku-memory.api.plist
```

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

### Basic /remember command

Source: https://github.com/yelban/kiroku-memory/blob/main/commands/remember.md

Stores a simple piece of information in Kiroku Memory.

```bash
/remember 用戶偏好深色模式
```

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

### Import Developer ID Certificate

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/macos-code-signing.md

Imports a downloaded Developer ID application certificate into the login keychain database. Ensure the path to the `.cer` file is correct.

```bash
security import ~/Downloads/developerID_application.cer -k ~/Library/Keychains/login.keychain-db
```

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

### View Kiroku Memory API error log

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/installation-guide.md

This command displays the content of the API's error log file, which is crucial for diagnosing startup failures.

```bash
cat /tmp/kiroku-api.err
```

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

### Get Embedding Provider Factory

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/surrealdb-migration-plan.md

Factory function to retrieve the appropriate embedding provider based on configuration settings. It supports 'local' and other providers (defaulting to OpenAI).

```python
from .base import EmbeddingProvider
from .openai import OpenAIEmbeddingProvider
from .local import LocalEmbeddingProvider
from .config import embedding_settings

def get_embedding_provider() -> EmbeddingProvider:
    if embedding_settings.provider == "local":
        return LocalEmbeddingProvider(model_name=embedding_settings.model)
    return OpenAIEmbeddingProvider(model_name=embedding_settings.model)
```

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

### Add Kiroku Memory Plugin Marketplace

Source: https://github.com/yelban/kiroku-memory/blob/main/README.md

Adds Kiroku Memory via the plugin marketplace. Requires adding the marketplace URL first.

```bash
/plugin marketplace add https://github.com/yelban/kiroku-memory.git
```

```bash
/plugin install kiroku-memory
```

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

### Verify SessionStart Hook Success

Source: https://github.com/yelban/kiroku-memory/blob/main/README.md

Confirms that the SessionStart hook executed successfully, the API service is connected, and memory context has been injected.

```text
SessionStart:startup hook success: <kiroku-memory>
## User Memory Context

### Preferences
...
</kiroku-memory>
```

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

### Recall Search with Context

Source: https://github.com/yelban/kiroku-memory/blob/main/commands/recall.md

Display the full tiered context of search results instead of just the summary. Use the --context flag.

```bash
/recall --context
```

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

### View Kiroku Memory API logs

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/installation-guide.md

These commands allow you to monitor the standard output and error logs of the Kiroku Memory API service in real-time.

```bash
# Standard output
tail -f /tmp/kiroku-api.log
```

```bash
# Error log
tail -f /tmp/kiroku-api.err
```

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

### Verify paths for launchd service

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/installation-guide.md

These commands check if the executable and project directories specified in the launchd plist file actually exist on your system.

```bash
ls -la ~/.local/bin/uv
```

```bash
ls -la ~/projects/kiroku-memory
```

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

### Executing the remember script

Source: https://github.com/yelban/kiroku-memory/blob/main/commands/remember.md

This command executes the remember script with user-provided arguments. Ensure the Kiroku Memory service is running.

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/remember.py <user_args>
```

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

### Run Memory Status Script

Source: https://github.com/yelban/kiroku-memory/blob/main/commands/memory-status.md

Execute the memory-status script to check the Kiroku Memory system's health and statistics. This script should be run from the project directory.

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/memory-status.py
```

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

### Uninstall Kiroku Memory launchd service and files

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/installation-guide.md

This script performs a complete uninstallation by stopping and removing the launchd service, deleting the Claude Code skill, stopping and removing Docker containers, and finally removing the project directory.

```bash
# Stop launchd service (if installed)
launchctl unload ~/Library/LaunchAgents/com.kiroku-memory.api.plist 2>/dev/null
rm ~/Library/LaunchAgents/com.kiroku-memory.api.plist

# Remove Claude Code skill
rm -rf ~/.claude/skills/kiroku-memory

# Stop and remove Docker container
cd ~/projects/kiroku-memory
docker compose down -v

# Remove project directory
rm -rf ~/projects/kiroku-memory
```

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

### Run Unit Tests for SurrealDB Repositories

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/surrealdb-setup.md

Execute unit tests specifically for the SurrealDB repository implementations using Uvicorn and Pytest.

```bash
# Unit tests
uv run pytest tests/repositories/test_surrealdb_repos.py -v
```

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

### shadcn/ui Theme Configuration (globals.css)

Source: https://github.com/yelban/kiroku-memory/blob/main/desktop/design-system/DESIGN.md

Configures the theme for shadcn/ui components using HSL color values and Tailwind CSS. Includes Inter font import and base styles.

```css
@import url('https://rsms.me/inter/inter.css');

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    /* shadcn/ui HSL format */
    --background: 222 47% 11%;      /* #0F172A */
    --foreground: 210 40% 98%;      /* #F8FAFC */

    /* 改善層級對比 (Guillermo Rauch 建議) */
    --card: 220 30% 12%;            /* #151921 */
    --card-foreground: 210 40% 98%;

    --popover: 217 33% 17%;         /* #1E293B */
    --popover-foreground: 210 40% 98%;

    --primary: 142 71% 45%;         /* #22C55E */
    --primary-foreground: 0 0% 100%;

    --secondary: 217 19% 27%;       /* #334155 */
    --secondary-foreground: 210 40% 98%;

    --muted: 215 16% 47%;           /* #64748B */
    --muted-foreground: 215 16% 47%;

    --accent: 211 100% 50%;         /* #0A84FF fallback */
    --accent-foreground: 0 0% 100%;

    --destructive: 0 84% 60%;       /* #EF4444 */
    --destructive-foreground: 0 0% 100%;

    /* 提高邊框可見度 (Guillermo Rauch 建議：12%) */
    --border: 0 0% 100% / 0.12;
    --input: 0 0% 100% / 0.12;
    --ring: 211 100% 50%;

    --radius: 0.75rem;
  }
}

@layer base {
  * {
    @apply border-border;
  }

  body {
    @apply bg-background text-foreground;
    font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
    font-feature-settings: 'ss01' on, 'ss02' on, 'cv01' on;
  }

  /* Focus ring (Guillermo Rauch 建議) */
  :focus-visible {
    @apply outline-2 outline-offset-2 outline-ring;
  }

  /* Tabular nums for numbers */
  .tabular-nums {
    font-variant-numeric: tabular-nums;
  }
}

/* Vibrancy support */
@supports (backdrop-filter: blur(20px)) {
  .vibrancy {
    background: rgba(21, 25, 33, 0.8);
    backdrop-filter: blur(20px) saturate(180%);
    -webkit-backdrop-filter: blur(20px) saturate(180%);
  }
}
```

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

### Import Apple Certificate in GitHub Actions

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/macos-code-signing.md

This step configures a temporary keychain, decodes the Base64-encoded certificate from GitHub secrets, imports it into the keychain, and sets it as the default for code signing. It also verifies the certificate's presence.

```yaml
- name: Import Apple certificate
  if: matrix.platform == 'darwin'
  env:
    APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
    APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
  run: |
    # Create temporary keychain
    KEYCHAIN_PATH=$RUNNER_TEMP/app-signing.keychain-db
    KEYCHAIN_PASSWORD=$(openssl rand -base64 32)

    # Decode certificate
    echo -n "$APPLE_CERTIFICATE" | base64 --decode -o $RUNNER_TEMP/certificate.p12

    # Create and configure keychain
    security create-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH
    security set-keychain-settings -lut 21600 $KEYCHAIN_PATH
    security unlock-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH

    # Import certificate
    security import $RUNNER_TEMP/certificate.p12 -P "$APPLE_CERTIFICATE_PASSWORD" -A -t cert -f pkcs12 -k $KEYCHAIN_PATH
    security set-key-partition-list -S apple-tool:,apple: -s -k "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH
    security list-keychain -d user -s $KEYCHAIN_PATH

    # Verify certificate
    security find-identity -v -p codesigning $KEYCHAIN_PATH
```

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

### Configure Tauri macOS Signing Settings

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/macos-code-signing.md

Set up the `tauri.conf.json` file to specify macOS signing parameters, including the minimum system version, signing identity, and provider short name.

```json
{
  "bundle": {
    "macOS": {
      "minimumSystemVersion": "10.15",
      "signingIdentity": "-",
      "providerShortName": "YOUR_TEAM_ID",
      "infoPlist": "Info.plist"
    }
  }
}
```

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

### /remember command with category

Source: https://github.com/yelban/kiroku-memory/blob/main/commands/remember.md

Stores information with a category hint to aid organization. Supported categories include preferences, facts, events, relationships, skills, and goals.

```bash
/remember --category preferences 喜歡用 Neovim
```

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

### Migrate Data from PostgreSQL to SurrealDB

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/surrealdb-setup.md

Commands for performing full or step-by-step data migration from PostgreSQL to SurrealDB, including export, import, and verification steps.

```bash
# Full migration
python scripts/migrate_backend.py migrate --from postgres --to surrealdb
```

```bash
# Or step by step:
# 1. Export from PostgreSQL
python scripts/migrate_backend.py export --backend postgres

# 2. Import to SurrealDB
python scripts/migrate_backend.py import --backend surrealdb

# 3. Verify
python scripts/migrate_backend.py verify
```

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

### Repository Factory for Backend Switching

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/surrealdb-migration-plan.md

Factory function to return repository implementations based on the configured backend. This allows for dynamic switching between different database backends.

```python
# kiroku_memory/db/repositories/factory.py
from .resource import ResourceRepository
from .item import ItemRepository
from .category import CategoryRepository
from .graph import GraphRepository
from .embedding import EmbeddingRepository
from .category_access import CategoryAccessRepository
from ..config import settings

def get_repository(name: str):
    if settings.backend == "surrealdb":
        if name == "resource":
            return ResourceRepository()
        if name == "item":
            return ItemRepository()
        if name == "category":
            return CategoryRepository()
        if name == "graph":
            return GraphRepository()
        if name == "embedding":
            return EmbeddingRepository()
        if name == "category_access":
            return CategoryAccessRepository()
    # Default to PostgreSQL repositories if backend is not SurrealDB
    # (Implementation for PostgreSQL repositories would be here)
    raise ValueError(f"Unknown repository name: {name}")
```

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

### Intelligent Truncation Process

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/architecture.md

Illustrates the step-by-step process for truncating context when it exceeds character limits, prioritizing complete categories.

```text
┌─────────────────────────────────────────┐
│ 1. 按優先級排序所有分類                   │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 2. 逐一加入完整分類區塊                   │
│    (永不在分類中間截斷)                   │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 3. 超過上限時停止                         │
│    (低優先級分類被捨棄)                   │
└─────────────────────────────────────────┘
```

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

### Restart Kiroku Memory launchd service

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/installation-guide.md

These commands first unload and then reload the Kiroku Memory API service, useful after making changes to its configuration.

```bash
# To restart after changes
launchctl unload ~/Library/LaunchAgents/com.kiroku-memory.api.plist
launchctl load ~/Library/LaunchAgents/com.kiroku-memory.api.plist
```

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

### Recall Search within Current Project

Source: https://github.com/yelban/kiroku-memory/blob/main/commands/recall.md

Limit the search to memories within the current project. Use the --project or -p flag followed by the project name.

```bash
/recall --project 資料庫設計
```

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

### Force Reinitialize SurrealDB Schema

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/surrealdb-setup.md

Python script to force reinitialize the SurrealDB schema, useful if issues persist after startup.

```python
python -c "
import asyncio
from kiroku_memory.db.surrealdb import init_surreal_db
asyncio.run(init_surreal_db(force=True))
"
```

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

### Observability Endpoints

Source: https://github.com/yelban/kiroku-memory/blob/main/README.md

Endpoints for monitoring the health and performance of the Kiroku Memory system.

```APIDOC
## GET /health

### Description
Basic health check.

### Method
GET

### Endpoint
/health
```

```APIDOC
## GET /health/detailed

### Description
Detailed health status.

### Method
GET

### Endpoint
/health/detailed
```

```APIDOC
## GET /metrics

### Description
Application metrics.

### Method
GET

### Endpoint
/metrics
```

```APIDOC
## POST /metrics/reset

### Description
Reset metrics.

### Method
POST

### Endpoint
/metrics/reset
```

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

### Check Kiroku Memory service status

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/installation-guide.md

This command verifies if the Kiroku Memory service is running by filtering the launchctl list output.

```bash
# Check service status
launchctl list | grep kiroku
```

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

### Repository Pattern Architecture Diagram

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/architecture.md

Visual representation of the Kiroku Memory system's layered architecture, emphasizing the separation of concerns with the Repository Pattern.

```text
┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                         │
│  (api.py, jobs/nightly.py, jobs/weekly.py, jobs/monthly.py) │
└────────────────────────────┬────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                      Domain Entities                         │
│  (ResourceEntity, ItemEntity, CategoryEntity, ...)          │
└────────────────────────────┬────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                   Repository Interfaces                      │
│  (ResourceRepository, ItemRepository, CategoryRepository)    │
└────────────────────────────┬────────────────────────────────┘
                             │
              ┌──────────────┴──────────────┐
              ▼                             ▼
┌─────────────────────────┐   ┌─────────────────────────┐
│     PostgreSQL          │   │      SurrealDB          │
│   Implementation        │   │    Implementation       │
│  (SQLAlchemy 2.x)       │   │   (surrealdb.py)        │
└─────────────────────────┘   └─────────────────────────┘
```

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

### Build Tauri App with macOS Signing

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/macos-code-signing.md

Configure your CI/CD pipeline to build the Tauri application for macOS, ensuring all necessary signing environment variables are set.

```yaml
- name: Build Tauri app (macOS with signing)
  if: matrix.platform == 'darwin'
  working-directory: desktop
  env:
    APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
    APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
    APPLE_SIGNING_IDENTITY: "Developer ID Application: Your Name (TEAMID)"
    APPLE_ID: ${{ secrets.APPLE_ID }}
    APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
    APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
  run: npm run tauri build -- --target ${{ matrix.target }}
```

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

### Application Metrics

Source: https://github.com/yelban/kiroku-memory/blob/main/CLAUDE.md

Retrieves application metrics for observability.

```APIDOC
## GET /metrics

### Description
Retrieves application metrics for observability purposes.

### Method
GET

### Endpoint
/metrics
```

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

### Open Keychain Access

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/macos-code-signing.md

Opens the Keychain Access application on macOS. This is the first step in managing certificates and keys.

```bash
open -a "Keychain Access"
```

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

### Ingestion Pipeline Stages

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/architecture.md

Visualizes the steps involved in processing a user message into structured data for storage.

```text
User Message
     │
     ▼
┌─────────────────┐
│ 1. Store Raw    │  → resources table (immutable)
│    Resource     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 2. Extract      │  → LLM 抽取 subject-predicate-object
│    Facts        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 3. Classify     │  → 分配到 6 個預設分類之一
│    Category     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 4. Resolve      │  → 檢測並解決衝突
│    Conflicts    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 5. Generate     │  → OpenAI embeddings
│    Embedding    │
└────────┬────────┘
         │
         ▼
     items table
```

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

### Convert .p12 Certificate to Base64

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/macos-code-signing.md

Converts a PKCS#12 certificate file (`.p12`) to Base64 encoding and copies it to the clipboard. This is necessary for storing the certificate as a GitHub secret.

```bash
base64 -i ~/Desktop/Certificates.p12 | pbcopy
```

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

### Basic Recall Search

Source: https://github.com/yelban/kiroku-memory/blob/main/commands/recall.md

Perform a basic search for memories. This is the simplest way to query the system.

```bash
/recall 編輯器偏好
```

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

### SurrealDB Connection Manager

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/surrealdb-migration-plan.md

Provides an asynchronous context manager for establishing and closing SurrealDB connections. It handles connection details and namespace/database usage.

```python
from contextlib import asynccontextmanager
from surrealdb import Surreal
from .config import surreal_settings

@asynccontextmanager
async def get_surreal() -> Surreal:
    db = Surreal()
    await db.connect(surreal_settings.url)  # e.g. "file://./data/kiroku"
    await db.use(surreal_settings.namespace, surreal_settings.database)
    try:
        yield db
    finally:
        await db.close()
```

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

### Generate Summaries

Source: https://github.com/yelban/kiroku-memory/blob/main/README.md

Send a POST request to the /summarize endpoint to generate summaries for the ingested data. This is part of the tiered retrieval system.

```bash
curl -X POST http://localhost:8000/summarize
```

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

### SurrealDB Python SDK: RecordID for Parameterized IDs

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/surrealdb-setup.md

Demonstrates the correct usage of `RecordID` objects for parameterized IDs in SurrealDB Python SDK queries to avoid errors.

```python
from surrealdb import RecordID

# ❌ Wrong - string ID causes "Can not execute UPDATE statement" error
await client.query(
    "UPDATE item SET status = $status WHERE id = $id",
    {"id": f"item:{item_id}", "status": "archived"}
)

# ✅ Correct - RecordID object
record_id = RecordID("item", str(item_id))
await client.query(
    "UPDATE $id SET status = $status",
    {"id": record_id, "status": "archived"}
)
```

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

### Generate Summaries

Source: https://github.com/yelban/kiroku-memory/blob/main/CLAUDE.md

Generates summaries from provided text, requires OpenAI API key.

```APIDOC
## POST /summarize

### Description
Generates summaries from provided text. This operation requires an OpenAI API key to be configured.

### Method
POST

### Endpoint
/summarize

### Request Body
- **text** (string) - Required - The text to summarize.
```

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

### Sign Embedded Binaries for macOS

Source: https://github.com/yelban/kiroku-memory/blob/main/docs/macos-code-signing.md

Sign all .so, .dylib, and executable files within your Python bundle before building the Tauri app. This is crucial for macOS code signing compliance.

```yaml
- name: Sign Python bundle binaries
  if: matrix.platform == 'darwin'
  env:
    APPLE_SIGNING_IDENTITY: "Developer ID Application: Your Name (TEAMID)"
  run: |
    PYTHON_BUNDLE="tools/packaging/dist/current/python"

    # Sign all .so files
    find "$PYTHON_BUNDLE" -name "*.so" -type f | while read -r file; do
      codesign --force --options runtime --timestamp --sign "$APPLE_SIGNING_IDENTITY" "$file"
    done

    # Sign all .dylib files
    find "$PYTHON_BUNDLE" -name "*.dylib" -type f | while read -r file; do
      codesign --force --options runtime --timestamp --sign "$APPLE_SIGNING_IDENTITY" "$file"
    done

    # Sign executables
    if [ -f "$PYTHON_BUNDLE/bin/python3.11" ]; then
      codesign --force --options runtime --timestamp --sign "$APPLE_SIGNING_IDENTITY" "$PYTHON_BUNDLE/bin/python3.11"
    fi
```

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

### Check Port Usage

Source: https://github.com/yelban/kiroku-memory/blob/main/desktop/README.md

Use this command to check if port 8000 is currently in use by any process, which can help diagnose service startup issues.

```bash
lsof -i :8000
```

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

### Agent Prompt Context

Source: https://github.com/yelban/kiroku-memory/blob/main/CLAUDE.md

Retrieves context for an agent's prompt.

```APIDOC
## GET /context

### Description
Retrieves context that can be used to enhance an agent's prompt.

### Method
GET

### Endpoint
/context

### Response
#### Success Response (200)
- **context** (string) - The retrieved context string.
```

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

### Extract Facts from a Resource

Source: https://github.com/yelban/kiroku-memory/blob/main/README.md

Send a POST request to the /extract endpoint with a resource_id to trigger LLM-powered fact extraction. This process categorizes information into 'facts' and 'preferences'.

```bash
curl -X POST http://localhost:8000/extract \
  -H "Content-Type: application/json" \
  -d '{"resource_id": "YOUR_RESOURCE_ID"}'
```

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

### /remember command for global memory

Source: https://github.com/yelban/kiroku-memory/blob/main/commands/remember.md

Stores information as global memory, making it accessible across projects. Use the --global or -g flag for this purpose.

```bash
/remember --global 暱稱叫吹吹
```

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

### MCP Server Integration with Kiroku Memory

Source: https://github.com/yelban/kiroku-memory/blob/main/README.md

Python code for integrating Kiroku Memory with a custom MCP server. It defines a tool endpoint to retrieve tiered context from the database.

```python
from mcp.server import Server
from kiroku_memory.db.database import get_session
from kiroku_memory.summarize import get_tiered_context

app = Server("memory-system")

@app.tool("memory_context")
async def memory_context():
    async with get_session() as session:
        return await get_tiered_context(session)
```

```json
{
  "mcpServers": {
    "memory": {
      "command": "uv",
      "args": ["run", "python", "memory_mcp.py"]
    }
  }
}
```
Tokens:
Raw