智能代理

Requirements

• Python 3.11 or higher
• An OpenAI API key

Quick Start

Create a virtual environment:

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

Install dependencies:

pip install -r requirements.txt

Create .env:

OPENAI_API_KEY=your_api_key
USER_ID=local_user
AGENT_ID=local_agent
LOCAL_MEMORY_ROOT=local_memory

Run the terminal agent:

python agent.py

Run the API server:

uvicorn main:app --reload

Call the API:

curl -X POST http://127.0.0.1:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What do you remember about me?", "channel_type": "web"}'

Prompt Regression Samples

For faster iteration on prompt and retrieval changes, use the sample runner:

python run_dataset_evals_sample.py

It reuses the parallel evaluator, selects a deterministic sample, writes a manifest of sampled questions, keeps per-worker checkpoints, and merges results into a sample-specific report. Useful environment variables:

EVAL_SAMPLE_NAME=prompt_regression
EVAL_SAMPLE_SIZE=60
EVAL_SAMPLE_SOURCE_LIMIT=500
EVAL_SAMPLE_SEED=test6
EVAL_SAMPLE_QUESTION_IDS=<comma-separated ids>
EVAL_SAMPLE_FRESH=1
EVAL_WORKERS=20

To monitor live results across both the main and worker result files:

python monitor_results.py

Current local report files:

reports/longmemeval_results.json
reports/longmemeval_results.worker*.json

Environment Variables

Retrieval Pipeline

Quarq does not simply embed the latest user prompt and hope for the best.

The retrieval node first asks a lightweight model to produce a structured search plan:

{
  "vector_queries": [
    "User total driving duration and travel history",
    "User vehicle, road trip, transit records",
    "User travel milestones, driving time calculation",
    "hours, road trip, destinations"
  ],
  "keywords": "driving, hours, total",
  "search_mode": "deep"
}

Then it performs:

1. Semantic vector search
2. Episodic vector search
3. Semantic keyword search
4. Episodic keyword search
5. ID-based deduplication
6. recency sorting
7. procedural rule routing

Search modes:

• standard: strict retrieval for point facts, threshold 0.38
• deep: wide recall for totals, timelines, histories, recommendations, and broad categories, threshold 0.28

This is why Quarq can answer questions that require multiple memories rather than only nearest-neighbor recall.

Learning Pipeline

After every normal response, Quarq starts background learning.

Benchmark memory-ingestion prompts are the exception. They are learned synchronously before the ingestion response returns, so run_dataset_evals.py does not feed the next history chunk until the previous chunk has been learned and committed.

The learning model extracts:

• semantic memories
• episodic memories
• procedural rules

It can issue:

{
  "actions": [
    {"action": "ADD", "content": "New memory"},
    {"action": "UPDATE", "id": "uuid", "content": "Updated memory"},
    {"action": "DELETE", "id": "uuid"}
  ]
}

Important learning behaviors:

• preserves specific names and proper nouns
• resolves relative dates using the current date
• anchors transfer and acquisition events
• preserves every number and qualifier
• avoids duplicate memories across semantic and episodic layers
• prefers exact values over approximate or bounded restatements
• updates existing records instead of creating conflicting duplicates
• keeps normal prose learning active
• splits benchmark ingestion chunks into individual user/assistant pairs
• stages semantic and episodic ADD, UPDATE, and DELETE actions in RAM between pairs
• commits staged semantic and episodic vector actions after all pairs in the chunk have been processed
• reloads procedural context between ingestion pairs when procedural rules change

Background learning is protected by:

• persistent retry loop
• exponential backoff
• concurrency limit of 4 learning tasks for normal background learning
• benchmark ingestion lock for synchronous memory-ingestion learning
• benchmark synchronization before final questions

Quarq Agent

Local memory. Hybrid retrieval. Self-correcting reasoning. Benchmark-grade recall.

Quarq Agent is a memory-first AI agent built by QuarqLabs for long-context personal intelligence, grounded recall, temporal reasoning, quantitative reasoning, and tool use.

It is designed as an open, inspectable alternative to memory agents such as Hermes or OpenClaw, with a stronger emphasis on durable local memory, strict attribution, self-correcting retrieval, and benchmark-grade long-term recall.

The current local implementation keeps normal semantic, episodic, and procedural learning in agent.py. Deterministic structured-artifact extractor code exists in the repo, but it is disabled in the active learning path while benchmark memory quality is being tuned.

Local LongMemEval-S reports are checkpoints while learning and generation behavior is being validated. Treat checked-in report files as local progress snapshots, not final published benchmark numbers.

Benchmark cost warning: a full 500-question LongMemEval-S run with the current model mix has cost about $2,500 in practice, or about $5 per average question. Run a 1-question or small-sample benchmark first before starting the full dataset.