[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-79678":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":20,"hasPages":20,"topics":22,"createdAt":10,"pushedAt":10,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":15,"starSnapshotCount":15,"syncStatus":26,"lastSyncTime":27,"discoverSource":28},79678,"agent-oss","quarqlabs\u002Fagent-oss","quarqlabs","A recursive evidence-gated cognitive runtime for memory-native AI agents, combining hybrid retrieval, temporal reasoning, async learning, and plug-and-play tools.","",null,"Python",248,24,77,0,13,114,4.19,"Apache License 2.0",false,"main",[],"2026-06-12 02:03:54","# Quarq Agent\n\n**Local memory. Hybrid retrieval. Self-correcting reasoning. Benchmark-grade recall.**\n\nQuarq Agent is a memory-first AI agent built by QuarqLabs for long-context personal intelligence, grounded recall, temporal reasoning, quantitative reasoning, and tool use.\n\nIt 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.\n\nThe current local benchmark run is in progress on LongMemEval-S and is tracking in the 99.6% to 99.7% range. The latest checked report in `reports\u002Flongmemeval_results.json` shows `256` yes, `1` no, or `99.61%`, with the full 500-question run still continuing.\n\n## Why Quarq Exists\n\nMost agents can chat. Fewer can remember. Almost none can remember carefully.\n\nQuarq Agent is built around a simple idea: memory is not just vector search. A serious memory agent needs to know what a memory means, when it happened, what numbers belong to, which entity a fact is attached to, when evidence is incomplete, and when it must search again instead of guessing.\n\nQuarq combines:\n\n- local FAISS vector memory\n- semantic, episodic, and procedural memory separation\n- hybrid vector plus keyword retrieval\n- HyDE-style query expansion\n- dynamic recall depth\n- strict temporal grounding\n- numeric attribution and exact aggregation rules\n- self-correcting fallback retrieval\n- background memory consolidation\n- LangGraph orchestration\n- progressive tool routing\n\nThe result is an agent that behaves less like a stateless chatbot and more like a disciplined cognitive system.\n\n## What Makes It Different\n\nQuarq is not a wrapper around a vector database. It is a full memory reasoning loop.\n\nStandard RAG systems usually fail long-memory tasks for one of four reasons:\n\n1. They retrieve the wrong memory.\n2. They retrieve the right memory but attach it to the wrong entity.\n3. They confuse storage time with event time.\n4. They calculate with nearby numbers that do not belong to the question.\n\nQuarq directly attacks those failure modes with retrieval decomposition, evidence attribution, temporal guardrails, numeric scope checks, and a second-pass recovery path when the first context is incomplete.\n\n## Highlights\n\n- Local-first memory: no Supabase pgvector dependency. Memories and rules are saved under `local_memory\u002F\u003CAGENT_ID>\u002F`.\n- Three memory types: semantic facts, episodic events, and procedural behavioral rules.\n- FAISS-backed retrieval: normalized OpenAI embeddings with `IndexFlatIP` cosine-style similarity.\n- Hybrid search: every retrieval pass combines vector search and direct keyword matching.\n- HyDE query optimizer: rewrites the user prompt into multiple retrieval probes before search.\n- Dynamic thresholds: wide-net `deep` mode for aggregation, timelines, broad categories, and recommendations; stricter `standard` mode for point facts.\n- Required-data fallback: the model can request a targeted second retrieval pass when evidence is missing.\n- Temporal truth protocol: separates database storage time from narrative event time.\n- Quantitative fidelity: numbers are stored and used with owner, property, item, and exactness.\n- Background learning: user responses return immediately while memory extraction runs asynchronously.\n- Progressive tool loading: tool docs are only injected when a skill is selected.\n- Benchmark mode: disables tool routing and waits for pending background learning before final evaluation.\n\n## Architecture\n\n```text\nUser \u002F API\n    |\n    v\nLangGraph StateGraph\n    |\n    +-- retrieve_memories\n    |     |\n    |     +-- HyDE query generation\n    |     +-- semantic FAISS search\n    |     +-- episodic FAISS search\n    |     +-- keyword search\n    |     +-- procedural rule routing\n    |\n    +-- route_tools\n    |     |\n    |     +-- skill catalog router\n    |     +-- progressive skill markdown loading\n    |\n    +-- generate_response\n          |\n          +-- grounded answer synthesis\n          +-- optional ReAct tool loop\n          +-- REQUIRED_DATA fallback retrieval\n          +-- background memory learning\n```\n\nThe graph is intentionally compact:\n\n```python\nSTART -> retrieve_memories -> route_tools -> generate_response -> END\n```\n\nLearning is launched in the background from `generate_response`, which keeps the interactive path fast while still preserving durable memory.\n\n## Memory System\n\nQuarq uses three memory layers.\n\n### Semantic Memory\n\nSemantic memory stores durable user facts:\n\n- identity\n- preferences\n- relationships\n- routines\n- long-term projects\n- possessions\n- stable traits\n- active statuses and inventories\n\nExample:\n\n```text\nUser owns a crystal chandelier that originally belonged to their great-grandmother and was given to them by their aunt.\n```\n\n### Episodic Memory\n\nEpisodic memory stores events and interaction history:\n\n- what happened\n- when it happened\n- who was involved\n- what was decided\n- what the user asked for\n- what changed\n\nExample:\n\n```text\nOn March 4, 2023, user received a crystal chandelier from their aunt that originally belonged to their great-grandmother.\n```\n\n### Procedural Memory\n\nProcedural memory stores behavioral rules:\n\n- tone preferences\n- formatting preferences\n- project-specific instructions\n- forbidden wording\n- content generation constraints\n\nProcedural rules are tagged and routed, so the model sees only the relevant rules for the current prompt instead of carrying every rule forever.\n\n## Local Storage Layout\n\nThe current runtime stores memory locally:\n\n```text\nlocal_memory\u002F\n  \u003CAGENT_ID>\u002F\n    semantic_memory\u002F\n      index.faiss\n      memories.json\n    episodic_memory\u002F\n      index.faiss\n      memories.json\n    procedural_memory\u002F\n      rules.json\n```\n\n`AGENT_ID` determines which memory folder is used. Reusing the same `AGENT_ID` reuses the same memory. Changing `AGENT_ID` gives you a clean isolated agent profile.\n\nEach semantic and episodic memory record includes:\n\n- UUID\n- agent ID\n- memory type\n- content\n- embedding\n- created timestamp\n- updated timestamp\n\nThe formatted retrieval output intentionally preserves this shape:\n\n```text\n[STORED_AT: 2026-05-25 14:00:00] [ID: \u003Cuuid>] \u003Cmemory content>\n```\n\nDownstream deduplication, recency sorting, contradiction handling, and memory update logic all depend on that stable format.\n\n## Retrieval Pipeline\n\nQuarq does not simply embed the latest user prompt and hope for the best.\n\nThe retrieval node first asks a lightweight model to produce a structured search plan:\n\n```json\n{\n  \"vector_queries\": [\n    \"User total driving duration and travel history\",\n    \"User vehicle, road trip, transit records\",\n    \"User travel milestones, driving time calculation\",\n    \"hours, road trip, destinations\"\n  ],\n  \"keywords\": \"driving, hours, total\",\n  \"search_mode\": \"deep\"\n}\n```\n\nThen it performs:\n\n1. Semantic vector search\n2. Episodic vector search\n3. Semantic keyword search\n4. Episodic keyword search\n5. ID-based deduplication\n6. recency sorting\n7. procedural rule routing\n\nSearch modes:\n\n- `standard`: strict retrieval for point facts, threshold `0.38`\n- `deep`: wide recall for totals, timelines, histories, recommendations, and broad categories, threshold `0.28`\n\nThis is why Quarq can answer questions that require multiple memories rather than only nearest-neighbor recall.\n\n## Temporal Reasoning\n\nQuarq treats time as evidence, not decoration.\n\nThe agent distinguishes:\n\n- storage timestamp: when the memory was saved\n- narrative date: when the event actually happened\n- benchmark current date: the simulated date for an evaluation question\n- relative dates: phrases like \"yesterday\", \"today\", \"last month\"\n\nThe Temporal Truth Protocol prevents common long-memory errors:\n\n- using database timestamps as event dates\n- borrowing dates from nearby but unrelated memories\n- assuming a discussion date is the same as an event date\n- calculating date gaps from guessed anchors\n\nFor \"how long ago\" questions, Quarq searches for the named event first and only uses the current date as the calculation anchor after retrieval.\n\n## Quantitative Reasoning\n\nLong-memory benchmarks often punish sloppy number handling. Quarq's numeric protocol is built to avoid that.\n\nFor totals, counts, durations, prices, quantities, or money questions, the model must identify:\n\n- actor or entity\n- measured action or property\n- event or item\n- exactness\n\nIt excludes numbers that are merely nearby or topically related.\n\nExample:\n\n```text\nUser helped organize a concert, which raised over $5,000.\n```\n\nThe amount belongs to the concert, not automatically to the user. It is also a lower-bound value, not an exact addend.\n\nFor exact totals, Quarq sums only exact unqualified values unless the user explicitly asks for a minimum, estimate, or range.\n\n## Self-Correcting Retrieval\n\nIf the first retrieval pass does not contain enough evidence, Quarq can emit:\n\n```json\n{\n  \"agent_response\": \"\",\n  \"flags\": [\"REQUIRED_DATA\"],\n  \"hyde_queries\": [\"aunt meetup\", \"received chandelier\", \"chandelier handoff\"]\n}\n```\n\nThe runtime then performs a targeted fallback search and regenerates the answer with expanded context.\n\nThe fallback pass has a strict final verification rule: if the exact target is still missing, the agent must say the information is not available instead of guessing.\n\nThis makes the agent aggressive about recall but conservative about truth.\n\n## Learning Pipeline\n\nAfter every non-benchmark response, Quarq starts background learning.\n\nThe learning model extracts:\n\n- semantic memories\n- episodic memories\n- procedural rules\n\nIt can issue:\n\n```json\n{\n  \"actions\": [\n    {\"action\": \"ADD\", \"content\": \"New memory\"},\n    {\"action\": \"UPDATE\", \"id\": \"uuid\", \"content\": \"Updated memory\"},\n    {\"action\": \"DELETE\", \"id\": \"uuid\"}\n  ]\n}\n```\n\nImportant learning behaviors:\n\n- preserves specific names and proper nouns\n- resolves relative dates using the current date\n- anchors transfer and acquisition events\n- preserves every number and qualifier\n- avoids duplicate memories across semantic and episodic layers\n- prefers exact values over approximate or bounded restatements\n- updates existing records instead of creating conflicting duplicates\n\nBackground learning is protected by:\n\n- persistent retry loop\n- exponential backoff\n- concurrency limit of 4 learning tasks\n- benchmark synchronization before final questions\n\n## Tool System\n\nQuarq includes a progressive skill router.\n\nInstead of injecting all tool instructions into every prompt, the router sees a compact catalog and selects only the relevant skills. The generation model then receives the full markdown and bound tools for those selected skills.\n\nCurrent included skills:\n\n- email\n- calendar\n- PDF generation\n- agent identity management\n\nTool execution uses a ReAct loop with a maximum of 5 iterations. If the loop reaches the limit, the model is forced to stop calling tools and produce a final text response.\n\n### Adding A New Tool\n\nTool expansion is deliberately simple. To add a new capability, drop a new folder inside `tools\u002F` and follow the existing skill convention.\n\n```text\ntools\u002F\n  your_tool\u002F\n    skill.md\n    __init__.py\n    tools.py\n```\n\n`skill.md` defines the router-facing metadata:\n\n```markdown\n---\nname: your_tool\ndescription: One-line description of what this skill can do.\ntriggers: keyword one, keyword two, natural language trigger\n---\n\n# Your Tool Skill\n\nDescribe when to use it, when not to use it, available tools, and operating rules.\n```\n\n`tools.py` defines LangChain tool callables, and `__init__.py` exports them using the folder-name convention:\n\n```python\nfrom .tools import your_first_tool, your_second_tool\n\nYOUR_TOOL_TOOLS = [your_first_tool, your_second_tool]\n```\n\nThat is it. `tools\u002F__init__.py` automatically scans every subdirectory with a `skill.md`, imports the package, reads the frontmatter, and registers the exported `\u003CFOLDER_NAME>_TOOLS` list. No central registry edit is required.\n\nThis gives Quarq a clean capability expansion path: add a folder, describe the skill, export the tools, restart the process, and the agent can route to the new capability.\n\n## Benchmarks\n\nQuarq includes a LongMemEval runner:\n\n```bash\npython run_dataset_evals.py\n```\n\nThe benchmark pipeline:\n\n1. Loads `eval_datasets\u002Flongmemeval_s_cleaned.json`\n2. Splits haystack sessions into chunks\n3. Feeds each chunk through the agent with learning enabled\n4. Waits for background memories before final questions\n5. Asks the benchmark question with learning disabled\n6. Judges with a binary evaluator\n7. Writes results to `reports\u002Flongmemeval_results.json`\n\nCurrent checked local report:\n\n```text\nLongMemEval-S checkpoint: 240 yes \u002F 1 no\nAccuracy: 99.59%\nStatus: 500-question run in progress\n```\n\nThese results are local and in progress until independently reproduced from a clean checkout.\n\n## Requirements\n\n- Python 3.11 or higher\n- An [OpenAI API key](https:\u002F\u002Fplatform.openai.com\u002Fapi-keys)\n\n## Quick Start\n\nCreate a virtual environment:\n\n```bash\npython -m venv .venv\nsource .venv\u002Fbin\u002Factivate   # Windows: .venv\\Scripts\\activate\n```\n\nInstall dependencies:\n\n```bash\npip install -r requirements.txt\n```\n\nCreate `.env`:\n\n```bash\nOPENAI_API_KEY=your_api_key\nUSER_ID=local_user\nAGENT_ID=local_agent\nLOCAL_MEMORY_ROOT=local_memory\n```\n\nRun the terminal agent:\n\n```bash\npython agent.py\n```\n\nRun the API server:\n\n```bash\nuvicorn main:app --reload\n```\n\nCall the API:\n\n```bash\ncurl -X POST http:\u002F\u002F127.0.0.1:8000\u002Fapi\u002Fchat \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"prompt\": \"What do you remember about me?\", \"channel_type\": \"web\"}'\n```\n\n## Environment Variables\n\n| Variable | Required | Description |\n|---|---:|---|\n| `OPENAI_API_KEY` | yes | Used for generation, retrieval planning, learning, and embeddings. |\n| `AGENT_ID` | no | Selects the local memory namespace. Defaults to `local_agent`. |\n| `USER_ID` | API only | Required by `main.py` for the FastAPI worker. |\n| `LOCAL_MEMORY_ROOT` | no | Root folder for local memory. Defaults to `local_memory`. |\n| `AGENT_NAME` | no | Runtime persona name. |\n| `AGENT_PERSONALITY` | no | Runtime tone\u002Fpersonality. |\n| `AGENT_USE_CASES` | no | Comma-separated use-case description. |\n| `AGENT_CUSTOM_PROMPT` | no | Extra custom behavior instructions. |\n\n## Repository Map\n\n```text\nagent.py                  Core LangGraph agent, memory, retrieval, generation, learning\nagent_connector.py        Public async integration gateway\nmain.py                   FastAPI single-tenant worker\nrun_dataset_evals.py      LongMemEval evaluation runner\nmonitor_results.py        Benchmark monitoring helper\ntools\u002F                    Skill registry and tool implementations\neval_datasets\u002F            Cleaned LongMemEval dataset\nreports\u002F                  Evaluation outputs and checkpoints\nlocal_memory\u002F             Local FAISS and JSON memory stores\n```\n\n## Design Principles\n\nQuarq is built around a few hard rules:\n\n- Retrieve broadly, reason narrowly.\n- Store memories with ownership, dates, and qualifiers intact.\n- Prefer saying \"missing data\" over inventing an answer.\n- Treat temporal and numeric claims as evidence-bound operations.\n- Keep user-facing latency low by learning in the background.\n- Keep the context window clean with routing and progressive disclosure.\n- Make the memory system portable, local, and easy to inspect.\n\n## Status\n\nQuarq Agent v0.4.0 is an active OSS release candidate.\n\nThe current version is optimized for long-memory evaluation and single-user local memory. The next natural steps are:\n\n- package cleanup\n- dependency trimming\n- unit tests for memory storage and retrieval\n- reproducible benchmark scripts\n- Docker packaging\n- memory compaction and archival policies\n- multi-user serving with isolated local stores\n\n## License\n\nApache License 2.0. See [LICENSE](LICENSE) for details.\n","Quarq Agent 是一个专注于本地记忆的AI代理，旨在实现长期上下文个人智能、可靠回忆、时间推理、定量推理和工具使用。其核心功能包括基于FAISS的向量检索、语义、情节和程序性记忆分离、混合向量加关键词检索以及自我纠正的检索机制等。技术特点上，Quarq强调对记忆内容的理解与正确归因，确保信息的时间准确性和数值准确性，同时支持背景记忆整合和渐进式工具路由。该项目适用于需要高度精确且持久记忆能力的应用场景，如个人助手、知识管理或任何要求长时间记忆和复杂推理的任务。",2,"2026-06-06 03:59:17","CREATED_QUERY"]