### Setup Ollama Models and Server

Source: https://github.com/memtensor/text2mem/blob/main/docs/CONFIGURATION.md

Instructions for installing Ollama, pulling necessary models (nomic-embed-text, qwen2:0.5b), and starting the Ollama server.

```bash
# Install Ollama from https://ollama.ai
ollama pull nomic-embed-text
ollama pull qwen2:0.5b

# Start Ollama server
ollama serve
```

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

### Quick Setup: Copy Environment File

Source: https://github.com/memtensor/text2mem/blob/main/docs/README.md

Copies the example environment file to a new file for customization. This is the first step in setting up Text2Mem.

```bash
# 1. Copy template
cp .env.example .env
```

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

### Install and Run Ollama

Source: https://github.com/memtensor/text2mem/blob/main/docs/CONFIGURATION.md

Commands to install Ollama, pull necessary models, and start the Ollama server.

```bash
# Install Ollama from https://ollama.ai
ollama pull nomic-embed-text
ollama pull qwen2:0.5b

# Start Ollama server
ollama serve

```

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

### Install and Configure Ollama

Source: https://github.com/memtensor/text2mem/blob/main/docs/CONFIGURATION.md

Steps to install Ollama, pull necessary models, and verify the installation. This setup is for local LLM inference.

```bash
# 1. Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# 2. Pull models
ollama pull nomic-embed-text
ollama pull qwen2:0.5b

# 3. Verify models
ollama list

# 4. Start server (if not running)
ollama serve

# 5. Test connection
curl http://localhost:11434/api/version
```

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

### Copy Example .env.local

Source: https://github.com/memtensor/text2mem/blob/main/docs/CONFIGURATION.md

Copy the example .env.local file to start configuring local development settings. This file is automatically ignored by git.

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

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

### Configure Mock Provider

Source: https://github.com/memtensor/text2mem/blob/main/README.md

Set up the environment for testing by copying the example .env file and setting the provider to mock.

```bash
cp .env.example .env
# .env content:
# TEXT2MEM_PROVIDER=mock
```

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

### Quick Start Commands

Source: https://github.com/memtensor/text2mem/blob/main/bench/README.md

Basic commands to view benchmark information, run tests, and check results.

```bash
./bench-cli info

# 2. Run tests
./bench-cli run --mode mock -v

# 3. View results
./bench-cli show-result latest
```

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

### Install Dependencies

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/QUICK_REFERENCE.md

Install the necessary Python dependencies for asynchronous generation.

```bash
pip install aiohttp
```

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

### Clone Repository and Install Package

Source: https://github.com/memtensor/text2mem/blob/main/README.md

Clone the Text2Mem repository and install the package in a virtual environment.

```bash
git clone https://github.com/your-username/Text2Mem.git
cd Text2Mem

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

pip install -e .
```

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

### Configuration Options

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/QUICK_REFERENCE.md

Examples of how to configure concurrency, checkpoint batch size, and maximum retries for the benchmark generation process.

```bash
# Concurrency (default: 5)
--max-concurrent 10
```

```bash
# Checkpoint batch size (default: 10)
export TEXT2MEM_BENCH_GEN_CHECKPOINT_BATCH=20
```

```bash
# Max retries (default: 3)
export TEXT2MEM_BENCH_GEN_RETRY_MAX=5
```

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

### Quick Setup: Choose Provider

Source: https://github.com/memtensor/text2mem/blob/main/docs/README.md

Selects the backend provider for Text2Mem by editing the .env file. Options include mock, ollama, and openai.

```bash
# 2. Choose provider (edit .env)
TEXT2MEM_PROVIDER=mock          # Testing
TEXT2MEM_PROVIDER=ollama        # Local models
TEXT2MEM_PROVIDER=openai        # Cloud API
```

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

### Copy Environment Template

Source: https://github.com/memtensor/text2mem/blob/main/docs/CONFIGURATION.md

Copies the example environment file to a new file for customization. This is the first step in setting up your configuration.

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

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

### Install Ollama

Source: https://github.com/memtensor/text2mem/blob/main/docs/CONFIGURATION.md

Steps to install Ollama on your system. This involves downloading and executing an installation script.

```bash
# 1. Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh
```

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

### Verify Environment Setup

Source: https://github.com/memtensor/text2mem/blob/main/README.md

Check the status of the Text2Mem environment configuration, including provider and model loading.

```bash
# Check environment status
python manage.py status

# Expected output:
# ✅ Environment configured
# ✅ Provider: mock/ollama/openai
# ✅ Models loaded
```

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

### First Time Use: Run Quick Test

Source: https://github.com/memtensor/text2mem/blob/main/bench/GUIDE.md

Run a quick test that takes only a few seconds. Useful for verifying the system setup.

```bash
# 2. Run quick test (few seconds)
./bench-cli run --mode mock -v
```

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

### Basic Usage

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/QUICK_REFERENCE.md

Run the benchmark generation script with asynchronous mode and a specified concurrency level. This is the recommended starting point.

```bash
python bench/generate/generate.py --async --max-concurrent 5
```

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

### Serve Ollama

Source: https://github.com/memtensor/text2mem/blob/main/docs/CONFIGURATION.md

Start the Ollama server if it is not already running. This command is used to make local models accessible.

```bash
# 4. Start server (if not running)
ollama serve
```

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

### Stage 2 Input Format Example

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/en_stage3_expected_generation.md

An example of a single test sample in the Stage 2 output JSONL format. This serves as the input for Stage 3.

```jsonl
{"id": "t2m-en-direct-single-enc-001", "class":{...} , "nl":{...} , "prerequisites":[], "schema_list":[...] , "init_db":null, "notes":"..."}
```

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

### Copy and Edit .env.local for Local Development

Source: https://github.com/memtensor/text2mem/blob/main/docs/CONFIGURATION.md

Copy the example .env file and edit it with your local credentials. This file is ignored by git and takes precedence over .env.

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

# Edit with your real credentials
nano .env.local
```

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

### Configuration Using a Proxy

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/config/README.md

Example configuration for using a proxy service with OpenAI, specifying the custom base URL for the API.

```yaml
llm:
  provider: openai
  model: gpt-4-turbo-preview
  base_url: "https://your-openai-proxy.com/v1"
```

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

### Verify Text2Mem Configuration

Source: https://github.com/memtensor/text2mem/blob/main/docs/CONFIGURATION.md

Runs the manage.py status command to verify the Text2Mem configuration after setup.

```bash
python manage.py status

```

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

### Correct Promote Operation Arguments

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/en_stage2_ir_generation.md

These examples demonstrate correct usage of the 'Promote' operation, showing how to use 'weight_delta' for relative increment, 'weight' for absolute weight, and 'remind' to set a reminder rule.

```json
{"op": "Promote", "args": {"weight_delta": 0.3, "reason": "提升优先级"}}
```

```json
{"op": "Promote", "args": {"weight": 0.8}}
```

```json
{"op": "Promote", "args": {"remind": {"rrule":"FREQ=WEEKLY;BYDAY=FR"}}}
```

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

### Metadata Extraction Examples

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/en_stage2_ir_generation.md

Examples of structured metadata fields for filtering. These fields should be placed in 'facets' to support querying.

```json
{"amount":2000000,"currency":"CNY"}
```

```json
{"duration_months":2}
```

```json
{"window":{"start":"2025-11-01","end":"2025-11-11"}}
```

```json
{"certainty":"confirmed"}
```

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

### Stage and Op Mapping Example

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/stage2_ir_generation.md

Shows a correct mapping between 'stage' and 'op' values as per the defined rules, ensuring consistency in IR generation.

```json
{"stage": "STO", "op": "Label"}
```

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

### Stage 3 Output Format Example

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/en_stage3_expected_generation.md

An example of a single test sample in the Stage 3 output JSONL format. It includes the new 'expected' field with assertions, ranking, triggers, and metadata.

```jsonl
{"id": "t2m-en-direct-single-enc-001", "class":{...} , "nl":{...} , "prerequisites":[], "schema_list":[...] , "init_db":null, "expected":{"assertions":[...] , "ranking":null, "triggers":[], "meta":{"dialect": "sqlite", "eval_time_utc": "2025-10-21T00:00:00Z", "step_index":0}}, "notes":"..."}
```

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

### Filtering Benchmark Samples

Source: https://github.com/memtensor/text2mem/blob/main/bench/GUIDE.md

Examples of using filter parameters to select specific samples for testing, such as by language or operation schema.

```bash
--filter "lang:zh"              # Chinese only
```

```bash
--schema-filter Encode,Retrieve # Specific operations only
```

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

### Pull Ollama Models

Source: https://github.com/memtensor/text2mem/blob/main/docs/CONFIGURATION.md

Download necessary language models for Ollama. This example pulls 'nomic-embed-text' and 'qwen2:0.5b'.

```bash
# 2. Pull models
ollama pull nomic-embed-text
ollama pull qwen2:0.5b
```

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

### Start Interactive REPL Session

Source: https://github.com/memtensor/text2mem/blob/main/examples/README.md

Initiates an interactive REPL session for Text2Mem. Paste IR JSON snippets line by line for testing.

```bash
python manage.py session --db ./text2mem.db
# Paste content from ir_operations/*.json and press Enter
```

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

### Configure Ollama Provider

Source: https://github.com/memtensor/text2mem/blob/main/README.md

Set up the environment to use local Ollama models. This involves installing Ollama, pulling models, and configuring the .env file with model names and base URL.

```bash
# Install Ollama: https://ollama.ai
# Pull models
ollama pull nomic-embed-text
ollama pull qwen2:0.5b

# Configure .env
cp .env.example .env
# Edit .env:
# TEXT2MEM_PROVIDER=ollama
# TEXT2MEM_EMBEDDING_MODEL=nomic-embed-text
# TEXT2MEM_GENERATION_MODEL=qwen2:0.5b
# OLLAMA_BASE_URL=http://localhost:11434
```

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

### Resolve '.env' Not Found Error

Source: https://github.com/memtensor/text2mem/blob/main/docs/README.md

Provides commands to copy the example environment file and run the configuration command. This is typically used when the application cannot find its configuration.

```bash
cp .env.example .env
python manage.py config
```

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

### Troubleshoot Ollama Connection Failure

Source: https://github.com/memtensor/text2mem/blob/main/docs/README.md

Includes commands to check if Ollama is running by querying its API and instructions to start the Ollama server. Use this when the application fails to connect to Ollama.

```bash
# Check Ollama is running
curl http://localhost:11434/api/version

# Start Ollama
ollama serve
```

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

### Retrieve Operation Example

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/en_stage2_ir_generation.md

Shows how to retrieve specific knowledge units, such as meeting minutes related to a project budget from the last week. This requires specifying filters for tags and time range.

```json
{
  "instruction": "Finds the minutes of last week's meeting about the project budget.",
  "context": "The user is ready to report on the budget progress",
  
  "scenario_info":{"scenario": "meeting_notes", "operation": "retrieve", "style": "concise", "topic": "project_budget"}
}
```

```json
{"id": "t2m-en-direct-single-ret-001", "class":{"instruction_type": "direct", "structure": "single", "lang": "en"}, "nl":{"en": "Finding minutes from last week's meeting about the project budget. "}, "context": "User ready to report on budget progress", "prerequisites":[{"stage": "ENC", "op": "Encode", "args":{"payload":{"text": "Budget Review Meeting: Confirmed Q4 Budget Goal of 2 Million CNY", "knowledge_type": "fact", "source": "Finance Department Meeting", "context": "Q4 Budget Discussion"}, "type": "knowledge", "tags":["meeting", "budget"], "time": "2025-10-18T10:00:00Z", "facets":{"amount":2000000, "currency": "CNY"}}},{
```

```json
{"stage": "ENC", "op": "Encode", "args":{"payload":{"text": "Budgeted expenditures need to be kept within the upper limit of 2 million", "knowledge_type": "constraint", "source": "finance director", "context": "budget constraints"}, "type": "knowledge", "tags":["budget", "constraints"], "time": "2025-10-18T10:05:00Z", "facets" :{"amount_limit":2000000, "currency": "CNY"}}},{
```

```json
{"stage": "ENC", "op": "Encode", "args":{"payload":{"text": "The R&D department is requesting an increase of 10% in the budget for performance optimization.", "knowledge_type": "request", "source": "R&D Manager", "context": "Budget Request"}, "type": "knowledge", "tags":["budget", "R&D"], "time": "2025-10-17T14:00:00Z", "facets":{"increase_ratio":0.1}}], "schema_list":[{"stage": "RET", "op": "Retrieve", "target":{"filter":{"has_tags":["meeting", "budget"], "time_range":{"relative": "last", "amount":7, "unit": "days"}}}, "args":{"include":["id", "text", "tags"]}}], "init_db":null, "notes": "Retrieve minutes of budget-related meetings "}
```

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

### Encode-Only Operation Example

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/en_stage2_ir_generation.md

Demonstrates encoding a simple instruction and context without any prepended information. This is used for recording new information directly.

```json
{
  "instruction": "Record the content of this morning's team meeting.",
  "context": "The user has just finished their daily station meeting. திரும்பு",
  
  "scenario_info":{"scenario": "meeting_notes", "operation": "encode", "style": "formal", "topic": "daily_meeting"}
}
```

```json
{"id": "t2m-en-direct-single-enc-001", "class":{"instruction_type": "direct", "structure": "single", "lang": "en"}, "nl":{"en": "Recording this morning's team meeting"}, "context": "Users just finished the daily station meeting", "prerequisites":[], "schema_list":[{"stage": "ENC", "op": "Encode", "args":{"payload":{"text": {"text": "Today's morning meeting discussed the current version of testing progress and task planning for next week", "knowledge_type": "fact", "source": "meeting_minutes", "context": "team_day_meeting"}, "type": "note", "tags":["meeting", "daily", "project_progress"], "time": "2025-10- 21T09:00:00Z", "facets":{"certainty": "confirmed"}}}], "init_db":null, "notes": "No predecessor operations"}
```

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

### Troubleshoot Ollama Connection Issues

Source: https://github.com/memtensor/text2mem/blob/main/docs/CONFIGURATION.md

Verify Ollama server status and URL. Use curl to check the API version and 'ollama serve' to start the server if needed.

```bash
# Check if Ollama is running
curl http://localhost:11434/api/version

# If not, start Ollama
ollama serve

# If using custom host, check URL in .env
echo $OLLAMA_BASE_URL
```

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

### Valid Facets Examples

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/stage2_ir_generation.md

Demonstrates correct usage of the 'facets' field within arguments, ensuring it contains business-related fields and is not empty or solely time-based.

```json
{"args": {"payload": {...}, "facets": {"certainty": "confirmed"}}}
```

```json
{"args": {"payload": {...}, "facets": {"amount": 2000000, "currency": "CNY"}}}
```

```json
{"args": {"payload": {...}, "facets": {"priority": "high", "status": "active"}}}
```

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

### Process Complete Pipeline from Latest Raw Data

Source: https://github.com/memtensor/text2mem/blob/main/bench/tools/README.md

Execute the entire data processing pipeline, starting from the latest raw data and building a benchmark of the specified version. This includes testing, cleaning, and building steps.

```bash
python -m bench.tools.pipeline --raw latest --version v2
```

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

### First Run with Mock Provider

Source: https://github.com/memtensor/text2mem/blob/main/README.md

Configure and run the initial demo using the mock provider, which does not require an LLM.

```bash
# Copy environment template
cp .env.example .env

# Use mock provider (no LLM required)
# Edit .env and ensure: TEXT2MEM_PROVIDER=mock

# Run demo
python manage.py demo
```

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

### Correct Time Range Formats

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/en_stage2_ir_generation.md

These examples show the correct ways to format 'time_range', including relative time with 'relative', 'amount', and 'unit', and absolute time with 'start' and 'end' fields.

```json
{'time_range': {'relative':'last', 'amount' :7, 'unit':'days'}}
```

```json
{'time_range' :{'start':'2025 -10 -01 T00 :00 :00 Z','end':'2025 -10 -21 T00 :00 :00 Z'}}
```

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

### Incorrect Time Range Formats

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/en_stage2_ir_generation.md

These examples illustrate common errors in 'time_range' formatting, including nested objects for absolute time, missing units for relative time, and providing only a start or end time.

```json
{"time_range': {'absolute': {'start': '...', 'end': '...'}}}
```

```json
{"time_range': {'relative': 'last', 'amount': 7}}
```

```json
{"time_range': {'start': '2025-10-01T00:00:00Z'}}
```

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

### First Time Use: View Benchmark Info

Source: https://github.com/memtensor/text2mem/blob/main/bench/GUIDE.md

View benchmark information before running tests. This is the first step for new users.

```bash
# 1. View benchmark information
./bench-cli info
```

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

### Create Text2Mem Services and Adapters

Source: https://github.com/memtensor/text2mem/blob/main/docs/README.md

Demonstrates how to initialize the Text2Mem service in mock mode and set up a SQLite adapter for database operations. Ensure necessary imports are present.

```python
from text2mem.services.service_factory import create_models_service
from text2mem.adapters.sqlite_adapter import SQLiteAdapter

# Create service
service = create_models_service(mode="mock")

# Create adapter
adapter = SQLiteAdapter(db_path="./text2mem.db")
```

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

### Empty or Time-Only Facets Error Example

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/en_stage2_ir_generation.md

These examples show incorrect usage where the 'facets' object is either empty or contains only the 'time' field, which is not allowed. The 'facets' must include at least one business field.

```json
{"args": {"payload": {...}, "facets": {}}}
```

```json
{"args": {"payload": {...}, "facets": {"time": "..."}}}
```

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

### Complete Workflow: Generate New Benchmark - Test New Benchmark

Source: https://github.com/memtensor/text2mem/blob/main/bench/GUIDE.md

Run tests against the newly promoted official benchmark. Verifies the benchmark is ready for use.

```bash
# Step 5: Test new benchmark
./bench-cli run --mode ollama -v
```

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

### Meeting Minutes Retrieval IR Example

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/en_stage2_ir_generation.md

This JSON structure defines an example for retrieving meeting minutes related to product design from the last week. It includes natural language queries, context, classification, scenario information, prerequisites for encoding knowledge, and the retrieval schema.

```json
[{"nl":{"en": "Find the minutes of last week\'s meeting on product design"},"context": "The user is advancing the design review of the new version","classification":{"instruction_type":"direct","structure":"single","lang":"en"},"scenario_info": {"scenario": "meeting_notes", "operation": "retrieve", "style": "concise", "topic": "product design"},"prerequisites":[{"stage": "ENC", "op":"Encode","args":{"workload":{"text":"Product design review meeting: confirm the new version of the interaction plan","knowledge_type": "fact", "source":"meeting minutes", "context":"Design review-second time"}, "type": "knowledge", "tags":["Meeting", "Product Design","Review"], "time":" 2025-10-18T10:00:00Z","facets":{"phase":"review"}}},{"stage": "ENC", "op":"Encode","args":{"workload":{"text":"Interactive changes need to be released before October 25th in high fidelity","knowledge_type": "restriction", "source": "product manager", "context":"Design schedule"}, "type": "knowledge", "tags":["Meeting","Product Design", "deadline"], "time":" 2025-10-15T14:00:00Z","facets":{"deadline":"2025-10-25T00:00:00Z"}}},{"stage": "ENC", "op": "Encode","args":{"workload":{"text":"Availability test sample size needs to be ≥20","knowledge_type": "requirement", "source": "user research", "context":"availability test"}, "type": "knowledge", "tags":["Conference", "Product Design", "availability"], "time":" 2025-10-14T09:30:00Z","facets":{"sample_size":20}}}],"schema_list":[{"stage":"RET","op": "Retrieve","target":{"filter":{"has_tags":["Conference","product design"],"time_range":{"relative": "last","amount":7, "unit":"days"}}}}]}
```

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

### All Available Commands

Source: https://github.com/memtensor/text2mem/blob/main/bench/README.md

A comprehensive list of all commands supported by the bench-cli tool, with brief descriptions.

```bash
./bench-cli run              # Run tests
./bench-cli generate         # Generate new benchmark
./bench-cli validate <id>    # Validate quality
./bench-cli promote <id>     # Promote to benchmark
./bench-cli list-results     # List history
./bench-cli show-result <id> # View details
./bench-cli compare <id1> <id2>  # Compare
./bench-cli info             # Benchmark information
```

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

### Postgres JSON Access for Tags

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/en_stage3_expected_generation.md

Example of checking if a tag exists within the 'tags' JSON array in PostgreSQL.

```sql
EXISTS (SELECT 1 FROM json_array_elements_text(tags) t(value) WHERE t.value LIKE :tag) 
```

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

### CLI: Demo, Workflows, and Session

Source: https://github.com/memtensor/text2mem/blob/main/docs/README.md

Commands for running demos, multi-step workflows, and entering the interactive REPL mode.

```bash
# Demo & Examples
python manage.py demo            # Run demo workflow

# Workflows
python manage.py workflow <file> # Run multi-step workflow

# Interactive
python manage.py session         # Enter REPL mode
```

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

### Complete Workflow: Generate New Benchmark - Promote Benchmark

Source: https://github.com/memtensor/text2mem/blob/main/bench/GUIDE.md

Promote a validated generation to become an official benchmark. This makes it available for regular testing.

```bash
# Step 4: If quality is good, promote to official benchmark
./bench-cli promote <generation_id>
```

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

### Build Benchmark from Latest Run with Version

Source: https://github.com/memtensor/text2mem/blob/main/bench/tools/README.md

Construct the final benchmark dataset from the latest cleaned run data. Specify the desired version for the benchmark output.

```bash
python -m bench.tools.build --run latest --version v2
```

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

### Postgres JSON Access for Facets Time

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/en_stage3_expected_generation.md

Example of accessing the 'time' field within the 'facets' JSON object in PostgreSQL.

```sql
facets->>"time" 
```

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

### SQLite JSON Access for Facets Time

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/en_stage3_expected_generation.md

Example of accessing the 'time' field within the 'facets' JSON object in SQLite.

```sql
JSON_EXTRACT(facets,"$.time") 
```

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

### Demo and Workflow Execution Commands

Source: https://github.com/memtensor/text2mem/blob/main/README.md

Commands to run a demo workflow or a multi-step workflow from a file.

```bash
python manage.py demo                 # Run demo workflow
```

```bash
python manage.py workflow <file>      # Run multi-step workflow
```

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

### PostgreSQL JSON Array Check Example

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/stage3_expected_generation.md

Demonstrates how to check for a value within a JSON array in PostgreSQL using `json_array_elements_text`.

```sql
EXISTS (SELECT 1 FROM json_array_elements_text(tags) t(value) WHERE t.value LIKE :tag)
```

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

### Local Ollama Configuration (Free)

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/config/README.md

Configuration for running benchmarks using a local Ollama instance, specifying the model, base URL, and a potentially longer timeout.

```yaml
llm:
  provider: ollama
  model: qwen2:7b
  base_url: http://localhost:11434
  timeout: 120
```

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

### List Ollama Models

Source: https://github.com/memtensor/text2mem/blob/main/docs/CONFIGURATION.md

Verify that the Ollama models have been successfully downloaded and are available.

```bash
# 3. Verify models
ollama list
```

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

### Complete Workflow: Generate New Benchmark - Generate Data

Source: https://github.com/memtensor/text2mem/blob/main/bench/GUIDE.md

Generate new benchmark data based on the configuration. This is a core step in creating new benchmarks.

```bash
# Step 2: Generate data
./bench-cli generate
```

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

### Benchmark System: View Results and Generate

Source: https://github.com/memtensor/text2mem/blob/main/docs/README.md

Commands to view the latest benchmark results and generate new benchmarks.

```bash
# View results
./bench-cli show-result latest

# Generate new benchmark
./bench-cli generate
```

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

### Set Ollama Provider

Source: https://github.com/memtensor/text2mem/blob/main/docs/CONFIGURATION.md

Configures Text2Mem to use the Ollama provider for local LLM inference. Requires Ollama to be installed and models to be pulled.

```bash
TEXT2MEM_PROVIDER=ollama
TEXT2MEM_EMBEDDING_MODEL=nomic-embed-text
TEXT2MEM_GENERATION_MODEL=qwen2:0.5b
OLLAMA_BASE_URL=http://localhost:11434

```

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

### Benchmark System: Validate, Run Tests, and Promote

Source: https://github.com/memtensor/text2mem/blob/main/docs/README.md

Commands for validating a benchmark by ID, running tests against it, and promoting a benchmark.

```bash
./bench-cli validate <id> --run-tests
./bench-cli promote <id>
```

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

### Benchmark System: Quick Test

Source: https://github.com/memtensor/text2mem/blob/main/docs/README.md

Runs a quick benchmark test using the mock mode. The -v flag enables verbose output.

```bash
# Quick test
./bench-cli run --mode mock -v
```

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

### Complete Workflow: Generate New Benchmark - Edit Config

Source: https://github.com/memtensor/text2mem/blob/main/bench/GUIDE.md

Edit the configuration file for generating new benchmark data. This step is optional.

```bash
# Step 1: Edit configuration (optional)
nano bench/generate/config/generation_plan.yaml
```

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

### Build Benchmark from Specific Run with Version

Source: https://github.com/memtensor/text2mem/blob/main/bench/tools/README.md

Construct the final benchmark dataset from a specific cleaned run directory. This allows for building benchmarks from historical data.

```bash
python -m bench.tools.build --run 20251022_184604 --version v2
```

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

### PostgreSQL JSON Extraction Example

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/stage3_expected_generation.md

Provides the syntax for extracting JSON data from a column in PostgreSQL, specifically using the '->>' operator for string values.

```sql
facets->>'time'
```

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

### Run Demo for All Operations

Source: https://github.com/memtensor/text2mem/blob/main/examples/README.md

Automatically runs all minimal operation workflows in demo mode. Specify the database and operations set.

```bash
# Automatically run all minimal operation workflows
python manage.py demo --mode mock --db ./text2mem.db --set ops
```

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

### SQLite Lineage Array Check Example

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/stage3_expected_generation.md

Illustrates checking for the existence of a child ID within a JSON array in the 'lineage_children' column using SQLite.

```sql
EXISTS (SELECT 1 FROM json_each(lineage_children) WHERE value = :child_id)
```

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

### SQLite JSON Extraction Example

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/stage3_expected_generation.md

Demonstrates how to extract JSON data from the 'facets' column in SQLite. This is used for accessing nested fields like 'time'.

```sql
JSON_EXTRACT(facets,'$.time')
```

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

### Operation Schema IR Example

Source: https://github.com/memtensor/text2mem/blob/main/docs/README.md

Defines the typed JSON contract for memory operations in Text2Mem. This schema is central to how memory operations are defined and executed.

```json
{
  "stage": "ENC|RET|STR",
  "op": "Encode|Retrieve|...",
  "target": {...},
  "args": {...},
  "meta": {...}
}
```

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

### Verify Environment Configuration

Source: https://github.com/memtensor/text2mem/blob/main/docs/CONFIGURATION.md

Runs a status check to confirm that the environment and provider configurations are set up correctly and models are loaded.

```bash
python manage.py status
```

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

### Run Configuration Tests

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/config/README.md

Commands to execute Python scripts for testing LLM configuration and system integration.

```bash
# Run config test
python bench/generate/tests/test_llm_config.py

# Run system test
python bench/generate/tests/test_system.py
```

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

### Benchmark System: Full Test

Source: https://github.com/memtensor/text2mem/blob/main/docs/README.md

Executes a full benchmark test using the ollama provider. Verbose output is enabled with -v.

```bash
# Full test
./bench-cli run --mode ollama -v
```

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

### Check Ollama Performance Stats

Source: https://github.com/memtensor/text2mem/blob/main/docs/CONFIGURATION.md

Monitor Ollama server statistics to help tune performance. This command may vary depending on the Ollama version and setup.

```bash
ollama ps
```

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

### Configure OpenAI Provider

Source: https://github.com/memtensor/text2mem/blob/main/README.md

Set up the environment to use OpenAI's cloud API. This requires configuring the .env file with the provider, model names, and your OpenAI API key.

```bash
cp .env.example .env
# Edit .env:
# TEXT2MEM_PROVIDER=openai
# TEXT2MEM_EMBEDDING_MODEL=text-embedding-3-small
# TEXT2MEM_GENERATION_MODEL=gpt-4o-mini
# OPENAI_API_KEY=your-api-key-here
```

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

### Time Range Format Specification - Absolute Time

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/en_stage2_ir_generation.md

Correct format for specifying absolute time ranges in a flat structure. Includes 'start' and 'end' fields.

```json
{"time_range": {"start": "2025-10-01T00:00:00Z", "end": "2025-10-21T00:00:00Z"}}
```

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

### Run Tests with Options

Source: https://github.com/memtensor/text2mem/blob/main/bench/GUIDE.md

Executes benchmark tests with various filtering and mode options. Use verbose flag for detailed output.

```bash
./bench-cli run [OPTIONS]

Options:
  --mode MODE              Test mode: auto/mock/ollama/openai
  --filter EXPR            Sample filter: "lang:zh" or "lang:en"
  --schema-filter OPS      Operation filter: "Encode,Retrieve"
  --schema-indices IDS     Index filter: "0,2"
  --timeout SECONDS        Timeout setting
  --output-id ID           Result ID
  --verbose, -v            Verbose output
```

```bash
./bench-cli run --mode mock -v              # Mock quick test
```

```bash
./bench-cli run --mode ollama -v            # Ollama full test
```

```bash
./bench-cli run --filter "lang:zh" -v       # Chinese only
```

```bash
./bench-cli run --schema-filter Encode -v   # Encode only
```

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

### Valid Promote Operation Arguments

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/stage2_ir_generation.md

Shows correct ways to use the 'Promote' operation by providing one of the required arguments: 'weight_delta', 'weight', or 'remind'.

```json
{"op": "Promote", "args": {"weight_delta": 0.3, "reason": "提升优先级"}}
```

```json
{"op": "Promote", "args": {"weight": 0.8}}
```

```json
{"op": "Promote", "args": {"remind": {"rrule": "FREQ=WEEKLY;BYDAY=FR"}}}
```

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

### Interactive Session Commands

Source: https://github.com/memtensor/text2mem/blob/main/README.md

Start an interactive session using `python manage.py session` and use commands like encode, retrieve, status, help, and exit.

```bash
python manage.py session

# Commands:
> encode "Another important meeting"
> retrieve "meeting" limit=5
> status
> help
> exit
```

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

### Step-by-Step Benchmark Processing

Source: https://github.com/memtensor/text2mem/blob/main/bench/tools/README.md

Manually execute individual stages of the benchmark data processing pipeline. This includes testing, cleaning, building, and statistical analysis.

```bash
python -m bench.tools.test --raw latest
```

```bash
python -m bench.tools.clean --run latest
```

```bash
python -m bench.tools.build --run latest --version v2
```

```bash
python -m bench.tools.stats --run latest
```

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

### SQLite JSON Array Check Example

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/stage3_expected_generation.md

Shows how to check if a JSON array in the 'tags' column contains a specific value in SQLite. This is useful for verifying tag presence.

```sql
EXISTS (SELECT 1 FROM json_each(tags) WHERE value LIKE :tag)
```

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

### Benchmarking CLI Commands

Source: https://github.com/memtensor/text2mem/blob/main/bench/GUIDE.md

Commands to generate, validate, and promote a new benchmark.

```bash
./bench-cli generate
./bench-cli validate <id> --run-tests
./bench-cli promote <id>
```

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

### Incorrect Promote Operation Arguments

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/en_stage2_ir_generation.md

These examples show incorrect arguments for the 'Promote' operation, such as using 'priority' instead of valid parameters or providing only a 'reason' without a weight or reminder.

```json
{"op": "Promote", "args": {"priority": "high"}}
```

```json
{"op": "Promote", "args": {"reason": "重要"}}
```

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

### Configure SQLite Database Path

Source: https://github.com/memtensor/text2mem/blob/main/docs/CONFIGURATION.md

Set the path for the SQLite database. Use ':memory:' for testing purposes only to use an in-memory database.

```bash
# SQLite database path
TEXT2MEM_DB_PATH=./text2mem.db

# Use in-memory database (testing only)
TEXT2MEM_DB_PATH=:memory:
```

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

### Troubleshoot: Ollama Connection Failed

Source: https://github.com/memtensor/text2mem/blob/main/docs/CONFIGURATION.md

To resolve 'Ollama connection failed', verify that the Ollama server is running and the URL is correct. Use curl to check its status and start it if necessary.

```bash
curl http://localhost:11434/api/version
```

```bash
ollama serve
```

```bash
echo $OLLAMA_BASE_URL
```

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

### Complete Workflow: Daily Testing Sequence

Source: https://github.com/memtensor/text2mem/blob/main/bench/GUIDE.md

A sequence of commands for daily testing: view info, run tests, show results, and list history.

```bash
# 1. View benchmark
./bench-cli info

# 2. Run tests
./bench-cli run --mode ollama -v

# 3. View results
./bench-cli show-result latest

# 4. View historical trends
./bench-cli list-results
```

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

### Process Complete Pipeline from Specific Raw Data

Source: https://github.com/memtensor/text2mem/blob/main/bench/tools/README.md

Execute the data processing pipeline starting from a specific raw data identifier. This ensures the pipeline runs on a chosen dataset.

```bash
python -m bench.tools.pipeline --raw 20251022_184604 --version v2
```

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

### Complete Workflow: Generate New Benchmark - Validate Quality

Source: https://github.com/memtensor/text2mem/blob/main/bench/GUIDE.md

Validate the quality of the generated benchmark data. Optionally run tests during validation.

```bash
# Step 3: Validate quality
./bench-cli validate <generation_id>
./bench-cli validate <generation_id> --run-tests
```

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

### Generate New Benchmark

Source: https://github.com/memtensor/text2mem/blob/main/bench/tools/README.md

Use this command to generate raw data and then run the full benchmark pipeline.

```bash
# 1. 生成原始数据
python bench/generate/generate.py

# 2. 运行完整流程
python -m bench.tools.pipeline --raw latest --version v2
```

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

### Example of Inauthentic Context - Too Short

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/en_stage1_nl_generation.md

This JSON snippet illustrates an incorrect context that fails to meet the minimum length requirement. It is too brief and lacks the necessary detail and authenticity for the Text2Mem system.

```json
{
  "context": "The meeting discussed the product planning and budget for Q4."
}
```

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

### Direct YAML Configuration (Not Recommended)

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/config/README.md

Directly embedding API keys and base URLs in the configuration file is not recommended due to security risks, as it exposes sensitive information.

```yaml
llm:
  provider: openai
  model: gpt-4-turbo-preview
  api_key: "sk-your-actual-key"       # ⚠️ Will expose
  base_url: "https://api.openai.com/v1"
```

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

### Example of Authentic Context - Audio Transcription

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/en_stage1_nl_generation.md

This JSON snippet demonstrates an authentic context derived from an audio transcription, meeting the specified length and content feature requirements. It includes colloquialisms and details relevant to a project discussion.

```json
{
  "context": "[Audio Transcription] Manager Wang: Uh... for Q4 we need to focus on the payment system reconstruction. The budget is about two million yuan? Timeline—two months? Technical Director: Right. But we need to assess interface compatibility first; especially with the old system. Operations Department: The launch needs to align with the new activity schedule; it can't affect the Double Eleven promotion. Manager Wang: Understood. Let's start with a technical assessment and get me a detailed plan by next Wednesday. By the way, the security team also needs to be involved; this time we have to pass PCI DSS certification. Technical Director: No problem; I'll arrange for an architect to produce a design document this week. Hmm… one more thing—can our current database handle it? DBA: Currently around QPS is about 8000; after reconstruction it's estimated to double so I recommend doing capacity planning in advance."
}
```

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

### Encode Operation Example

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/prompts/en_stage2_ir_generation.md

This JSON object demonstrates the structure for the 'Encode' operation. It includes the main text payload, record type, optional tags, and structured facets for metadata. Ensure the payload text is standardized and not structured JSON.

```json
{
  "stage": "ENC",
  "op": "Encode",
  "args": {
    "payload": {"text": "Meeting content..."},
    "type": "note",
    "tags": ["meeting", "product"],
    "facets": {
      "subject": "Product Discussion",
      "time": "2024-11-15T10:00:00Z"
    }
  }
}
```

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

### Running Benchmarks with Ollama Mode

Source: https://github.com/memtensor/text2mem/blob/main/bench/GUIDE.md

Command to execute benchmarks using the Ollama mode with verbose output.

```bash
./bench-cli run --mode ollama -v
```

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

### Configure OpenAI Provider

Source: https://github.com/memtensor/text2mem/blob/main/docs/CONFIGURATION.md

Set up text2mem to use OpenAI's cloud-based LLM services. Requires an OpenAI API key and billing account. Configure provider, models, and API endpoint.

```bash
TEXT2MEM_PROVIDER=openai
TEXT2MEM_EMBEDDING_MODEL=text-embedding-3-small
TEXT2MEM_GENERATION_MODEL=gpt-4o-mini
OPENAI_API_KEY=sk-你的实际密钥
OPENAI_API_BASE=https://api.openai.com/v1
```

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

### Display Benchmark Information

Source: https://github.com/memtensor/text2mem/blob/main/bench/GUIDE.md

Shows statistics of the current benchmark.

```bash
./bench-cli info
```

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

### Benchmark CLI Promote Command

Source: https://github.com/memtensor/text2mem/blob/main/README.md

Command to promote a benchmark result.

```bash
./bench-cli promote <id>
```

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

### Monitoring Realtime Progress

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/QUICK_REFERENCE.md

Use the `tail -f` command to monitor the progress of the benchmark generation by viewing the output JSONL file in real-time.

```bash
tail -f bench/generate/output/*_stage2_*.jsonl
```

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

### Set Environment Variables for API Key and Base URL

Source: https://github.com/memtensor/text2mem/blob/main/bench/generate/config/README.md

Recommended method for configuring API keys and base URLs. These variables are automatically read by the system, ensuring security and preventing exposure in Git.

```bash
export OPENAI_API_KEY=sk-your-key
export OPENAI_API_BASE=https://api.openai.com/v1  # Optional
```

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

### Run Complete Workflows

Source: https://github.com/memtensor/text2mem/blob/main/README.md

Execute multi-step workflows defined in a JSON file using the `workflow` command. The output shows the progress of each step.

```bash
python manage.py workflow path/to/workflow.json

# Output shows each step:
# Step 1/N: ... ✅
```

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

### Set OpenAI API Key

Source: https://github.com/memtensor/text2mem/blob/main/docs/CONFIGURATION.md

Instructions to obtain an OpenAI API key and set it in the .env file for cloud-based LLM access. This is a crucial step for using the OpenAI provider.

```bash
# 1. Get API key from https://platform.openai.com/api-keys

# 2. Edit .env
nano .env

# 3. Add your key
OPENAI_API_KEY=sk-your-actual-key-here

# 4. Verify
python manage.py status
```

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

### Generate New Benchmark

Source: https://github.com/memtensor/text2mem/blob/main/bench/GUIDE.md

Generates a new benchmark, optionally using a specified configuration file or the default generation directory.

```bash
./bench-cli generate [OPTIONS]

Options:
  --config FILE            Configuration file path
  --output-id ID           Output ID
  --use-generation-dir     Use generation/ directory
```

```bash
./bench-cli generate                        # Use default config
```

```bash
./bench-cli generate --config my_plan.yaml  # Use custom config
```