English | 日本語

Hybrid RAG — Sistema de memoria a largo plazo para agentes

Un sistema RAG híbrido que combina recuperación densa y dispersa, con un mecanismo de memoria basado en etiquetas (importancia, tasa de obsolescencia por knowledge_type y frecuencia de acceso) integrado en su reranking. Para el fundamento del diseño, consulte hybrid_rag_agent_spec.en.md.

Ejecútelo como servidor MCP y agentes como Claude Code pueden usarlo directamente como "memoria a largo plazo".

Cómo funciona este mecanismo

Siguiendo la especificación, el procesamiento se divide en dos tipos.

La "importancia" y la "tasa de obsolescencia por knowledge_type" se tratan como ejes separados; en lugar de una combinación lineal simple, se aplican por etapas: ① corte por importancia → ② decaimiento temporal por knowledge_type → ③ refuerzo por frecuencia de acceso (consulte la sección 2.3 de la especificación para más detalles).

principle  : no decay (MBSE design principles, math/algorithms)
paper      : re-evaluated roughly every half year (papers, technical articles)
news       : decays significantly over weeks to months (news, model-release info)
experiment : decays according to project duration (experiment logs, run records)

knowledge_type está diseñado para determinarse de forma determinista a partir de la fuente de ingesta, en lugar de ser juzgado por un LLM a partir del contenido del fragmento (por ejemplo, un documento de diseño registrado explícitamente por un humano → principle; un artículo de arXiv/artículo técnico → paper; noticias/resultados de búsqueda web → news; un registro de ejecución → experiment).

Nota: principle (sin decaimiento) no garantiza que un fragmento "nunca sea olvidado por run_forgetting_batch". Debido a que el reranking por etapas aplica primero el corte de importancia ①, un fragmento con knowledge_type=principle aún puede convertirse en objetivo de archivado si su importance se establece en un valor bajo y cae por debajo de importance_threshold (confirmado por tests/test_archival.py). "Sin decaimiento" se aplica solo a la etapa de decaimiento temporal ② — no es una garantía de "nunca olvidado" en todo el pipeline ①②③.

Nota: El mecanismo de memoria (knowledge_type/importance/reranking por etapas/lote de olvido/servidor MCP) está implementado solo para el backend FAISS (HybridRAGSystem). Las versiones Qdrant/Chroma/PostgreSQL están disponibles solo como biblioteca de búsqueda híbrida simple.

Related MCP server: mnemostack

Instalación

pip install -r requirements.txt

Para desarrollo/pruebas:

pip install -r requirements-dev.txt

Uso ① Como servidor MCP (recomendado)

Iniciar el servidor

python mcp_server/server.py

Las ubicaciones de almacenamiento se pueden configurar mediante variables de entorno (valores predeterminados: hybrid_rag.db / indices).

HYBRID_RAG_DB_PATH=my_memory.db HYBRID_RAG_INDEX_PATH=my_indices python mcp_server/server.py

Registro con Claude Code

.mcp.json en la raíz del proyecto ya está configurado de la siguiente manera. Claude Code lo recoge automáticamente cuando abre este repositorio.

{
  "mcpServers": {
    "hybrid-rag-memory": {
      "type": "stdio",
      "command": "python",
      "args": ["mcp_server/server.py"],
      "env": {
        "HYBRID_RAG_DB_PATH": "hybrid_rag.db",
        "HYBRID_RAG_INDEX_PATH": "indices"
      }
    }
  }
}

Si usa un entorno virtual, reescriba command con la ruta absoluta del intérprete de Python dentro de su venv (por ejemplo, "command": "./.venv/Scripts/python.exe").

Herramientas proporcionadas

Además de las 3 herramientas mínimas (①–③) requeridas en la sección 5 de la especificación, este servidor proporciona 10 herramientas más (④–⑬, extensiones de la especificación) para ingesta de datos, etiquetado, prevención de duplicados, lotes de olvido y comprobaciones de salud.

Sin ④–⑬, las herramientas ①–③ por sí solas no pueden ingerir datos, finalizar etiquetas de importancia ni evitar el registro duplicado de la misma fuente — lo que hace que el sistema sea poco práctico, por lo que se añadieron.

Una nota sobre ingerir muchos archivos seguidos (importante)

Antecedentes (un problema pasado corregido el 2026-07-30): ingest solía tener como valor predeterminado "re-embedding de cada fragmento en la base de datos y reconstrucción del índice en cada llamada", por lo que el costo de una sola llamada crecía linealmente con el tamaño del corpus, e ingerir archivos uno a la vez en una fila provocaba tiempos de espera. ingest(rebuild_index=True) (el valor predeterminado) ahora llama internamente a update_index() — un enfoque incremental que solo hace embedding de los fragmentos recién añadidos desde la última actualización y los añade (.add()) al índice FAISS — por lo que ahora es rápido independientemente del tamaño total del corpus (el lado BM25 todavía hace una reconstrucción completa ligera cada vez, porque sus estadísticas IDF dependen de todo el corpus, pero esto es barato ya que no implica embedding neuronal).

Dicho esto, ejecutar una actualización incremental en cada archivo individual sigue siendo una sobrecarga innecesaria, por lo que al ingerir muchos archivos seguidos es mejor pasar rebuild_index=False a cada llamada ingest y llamar a update_index() una vez al final del lote para reconciliar todo de una vez. .claude/agents/doc-to-memory.md y .claude/agents/session-to-memory.md ya están implementados con este patrón. Verificar la base de datos mediante find_by_tag (para prevención de duplicados / verificación de progreso) consulta SQLite directamente, por lo que funciona sin esperar a que el índice se ponga al día.

Cuando se requiere un rebuild_index() completo: siempre que el lote incluya incluso una sola llamada delete_document o una pasada de archivo de run_forgetting_batch (es decir, cualquier eliminación de vectores). La adición incremental (update_index) solo admite añadir a FAISS, no eliminar de él, por lo que cualquier lote que incluya eliminaciones debe terminar con un rebuild_index() completo. Un lote compuesto únicamente por nuevas adiciones es suficiente con update_index().

Prevención de duplicados al volver a registrar la misma fuente

Debido a que ingest deriva doc_id de un hash del contenido del archivo, volver a ingerir contenido byte-idéntico se omite automáticamente (una actualización basada en diferencias). Sin embargo, en los casos en que la misma fuente (por ejemplo, la misma sesión) se vuelve a resumir mediante un LLM y se vuelve a ingerir cada vez, pequeñas variaciones en el texto del resumen cada vez harán que se trate como un documento diferente — creando duplicados.

Para evitar esto, ingiera con una etiqueta de identificador único (por ejemplo, session_id:xxx) y una etiqueta de actualizado en (por ejemplo, session_last_activity:2026-07-28T15:59:49Z), y en ejecuciones posteriores:

1. Compruebe si el documento ya existe mediante find_by_tag("session_id:xxx")

2. Si la etiqueta de actualizado en existente coincide con el valor actual, omita — no haga nada

3. Solo si difiere (la fuente ha cambiado), elimine el anterior con delete_document(doc_id, rebuild_index=False) antes de ingerir el nuevo contenido

Se recomienda implementar este patrón de "omitir si no ha cambiado, reemplazar si ha cambiado". .claude/agents/session-to-memory.md es una implementación de referencia de este patrón.

Ejemplo de uso (conceptual)

1. ingest(["design_doc.md"], metadata={"knowledge_type": "principle", "tags": ["mbse"]})
2. hybrid_search("about consistency between requirements and architecture", top_k=5)
   -> [{"doc_id": ..., "chunk_index": ..., "content": ..., "knowledge_type": "principle",
        "importance": null, "access_count": 0, "score": 0.87}, ...]
3. set_chunk_tags(doc_id, chunk_index, importance=0.9)
4. rerank(chunks, time_weight=0.5, freq_weight=0.1, importance_threshold=0.3)
   -> chunks reordered along the memory axis (staleness, frequency, importance)

Uso ② Como agente de Claude Code

.claude/agents/rag-memory.md proporciona una definición de subagente responsable del "lado del agente (clase ①)" de este mecanismo de memoria. Una vez registrado .mcp.json, puede invocarlo desde Claude Code de la siguiente manera:

Use the rag-memory agent to look into past design decisions

Las reglas operativas para acciones que requieren confirmación de intención humana — etiquetado de importancia, re-etiquetado de knowledge_type, decisión de cuándo ejecutar el lote de olvido — también están escritas en esta definición de agente.

Además, .claude/agents/session-to-memory.md es un agente dedicado que resume sesiones pasadas de Claude Code (transcripciones de chat) y las ingiere en la memoria a largo plazo como knowledge_type="experiment". Se ejecuta en un modelo Haiku para mantener los costos bajos, y al reprocesar la misma sesión, compara con la entrada existente mediante las etiquetas session_id/actualizado en — omitiendo si no ha cambiado, reemplazando si ha cambiado (ver la sección anterior). El llamador debe especificar explícitamente qué sesiones se van a procesar; nunca se dirige a todas las sesiones sin límite.

Uso ③ Directamente como biblioteca de Python

También puede llamarlo directamente desde código Python sin pasar por el servidor MCP.

from hybrid_rag import HybridRAGSystem

rag = HybridRAGSystem(db_path="hybrid_rag.db", index_path="indices")

rag.ingest_documents(
    ["design_doc.md"],
    metadata={"knowledge_type": "principle", "importance": 0.9, "tags": ["mbse"]},
)

result = rag.query(
    "about consistency between requirements and architecture",
    top_k=5,
    enable_memory_rerank=True,   # enable the memory mechanism's staged reranking
    memory_time_weight=0.5,
    memory_freq_weight=0.1,
    memory_importance_threshold=0.3,
)
print(result["context"])

# assign an importance tag after the fact (no vector rebuild needed)
rag.set_chunk_tags(doc_id="design_doc_xxxx", chunk_index=0, importance=0.9)

# forgetting/archival batch (normally run infrequently)
report = rag.run_forgetting_batch(score_threshold=0.05, dry_run=True)

Ejecución del lote de olvido desde la CLI

Un script destinado a la ejecución por lotes poco frecuente — por ejemplo, en un ciclo de 3 meses o cuando se lanza un nuevo modelo (nunca se ejecuta automáticamente dentro del servidor).

python scripts/run_forgetting_batch.py --dry-run
python scripts/run_forgetting_batch.py --score-threshold 0.1 --time-weight 0.8

Opciones principales: --db-path --index-path --archive-path --time-weight --freq-weight --importance-threshold --score-threshold --dry-run

Los fragmentos archivados se evacúan a archive/chunks_archive.jsonl (texto sin formato + metadatos + puntuación + motivo de eliminación + marca de tiempo de eliminación), y sus representaciones vectoriales se descartan.

Evaluación automática de la precisión de recuperación desde la CLI

Un script que mide la precisión de recuperación contra un conjunto de consultas doradas (Precision@k/Recall@k/MRR/NDCG@k/Hit Rate@k, rango del documento de autoridad, tasa de ruido) de manera reproducible, en lugar de depender de consultas manuales y de la inspección visual de resultados mediante Cursor/Claude Code.

cp eval/golden_queries.example.yaml eval/golden_queries.yaml  # once, at first use — rewrite the doc_ids for your own corpus
python scripts/run_evaluation.py --db-path mcp_server/hybrid_rag.db --index-path mcp_server/hybrid_rag_indices

Opciones principales: --db-path --index-path --golden-set (predeterminado eval/golden_queries.yaml) --k-values (predeterminado 1,3,5,10) --authority-window (predeterminado 20) --output

Auditoría de ingesta casi duplicada

La detección de duplicados de ingest no puede detectar casos en los que contenido idéntico entra a través de un archivo diferente (una ruta/nombre de archivo diferente — ver "Prevención de duplicados al volver a registrar la misma fuente" arriba). Este script solo lista casi duplicados que ya han entrado en un corpus existente. Nunca elimina nada.

python scripts/find_near_duplicates.py --db-path mcp_server/hybrid_rag.db
python scripts/find_near_duplicates.py --db-path mcp_server/hybrid_rag.db --output eval/duplicates_report.json

Agrupa documentos cuyo hash de contenido normalizado (documents.content_hash) coincide. Decidir cuál conservar — y si eliminar algo — queda a criterio del usuario; llame a delete_document(doc_id, rebuild_index=False) manualmente (y asegúrese de llamar a rebuild_index al final del lote).

eval/golden_queries.yaml está en .gitignore, ya que son datos personales que contienen doc_ids específicos de su corpus real. Los informes se escriben en eval/eval_report_<date>.md (además de un .json con el mismo nombre), que también están en .gitignore (permanecen en su máquina para un seguimiento continuo).

Campos del mecanismo de memoria

Campos transportados en los metadata de ingest/la API de Python, o por fragmento:

Pruebas

pytest tests/ -v

• test_metadata_pipeline.py: una prueba de regresión que knowledge_type/importance/tags sobreviven al pipeline de ingest → build_index → query

• test_memory_scoring.py: pruebas unitarias para el re-ranking por etapas (corte, decadencia, refuerzo de frecuencia)

• test_archival.py: pruebas unitarias para el lote de olvido/archivo

• test_index_health.py: pruebas unitarias para index_health (verificación de consistencia índice/DB)

Consulte Estructura de archivos para la lista completa y el rol de los otros archivos de prueba.

Funcionalidad de la biblioteca base (común entre backends)

La funcionalidad RAG base — búsqueda híbrida densa/dispersa, RRF, re-ranking con Cross-encoder, selección de diversidad MMR, expansión de consultas, caché, etc. — es común a todos los backends (FAISS/Qdrant/Chroma/PostgreSQL).

from hybrid_rag import create_rag_system

rag = create_rag_system(backend="faiss")   # "qdrant" / "chroma" / "postgres" are also available
rag.ingest_documents(["document1.pdf", "document2.md"])
result = rag.query("What is machine learning?", top_k=5)

Instalaciones opcionales: este repositorio no tiene pyproject.toml/setup.py, por lo que no se distribuye en la forma pip install hybrid-rag[...]. Para usar las versiones Qdrant/Chroma/PostgreSQL, instale la biblioteca cliente correspondiente directamente (pip install qdrant-client / pip install chromadb / pip install "psycopg[binary]" pgvector — todas ellas ya están listadas en requirements.txt, por lo que pip install -r requirements.txt por sí solo las cubre).

Configuraciones adicionales clave (un subconjunto de los argumentos del constructor de HybridRAGSystem de la versión FAISS):

rag = HybridRAGSystem(
    dense_model="paraphrase-multilingual-MiniLM-L12-v2",
    rerank_model="BAAI/bge-reranker-v2-m3",
    max_chunk_size=512,
    index_type="hnsw",           # "flat" / "ivf" / "hnsw"
    enable_mmr=True, mmr_lambda=0.6,
    enable_cache=True, cache_ttl_seconds=3600,
    query_expander=None,          # pass a QueryExpander instance for LLM-based query expansion
    memory_half_life_overrides=None,  # override the half-life (days) per knowledge_type
    enable_guaranteed_candidates=True,  # always add principle/high-importance chunks to the candidate pool (default True)
    guaranteed_knowledge_types=None,    # defaults to ["principle"]
    guaranteed_importance_threshold=0.7,
    guaranteed_candidates_limit=50,
)

enable_guaranteed_candidates (predeterminado True) aborda un problema donde los fragmentos knowledge_type=principle (o fragmentos con importance>=0.7) nunca llegaban al grupo de candidatos de búsqueda en primer lugar, y el re-ranking por etapas no podía rescatarlos (el problema de "documentos de principio enterrados" reportado en RAG_EVALUATION_REPORT_2026-07-30.md/RAG_精度テスト_2026-07-31.md). Funciona añadiendo siempre fragmentos coincidentes al grupo de candidatos justo después de la recuperación y dejando que el Cross-encoder puntúe su relevancia — no los fuerza a la parte superior. Las llamadas a query()/hybrid_search que pasan metadata_filters (filters) omiten esta fusión.

Documentación (Sphinx) / diagramas (PlantUML)

pip install sphinx sphinx-rtd-theme
python -m sphinx -b html docs/source docs/build

docs/uml/ está destinado a contener fuentes PlantUML para diagramas de clases, diagramas de secuencia y diagramas de máquina de estados (aún no poblados al momento de escribir esto).

Estructura de archivos

hybrid_rag_agent_spec.md   # design spec for the memory mechanism
.mcp.json                  # MCP server registration for Claude Code
.claude/agents/rag-memory.md  # sub-agent definition for Claude Code

mcp_server/
└── server.py              # the MCP server itself (13 tools, see the table above)

scripts/
├── run_forgetting_batch.py       # CLI for the forgetting/archival batch
├── run_evaluation.py             # CLI that automatically evaluates retrieval accuracy against a golden query set
├── find_near_duplicates.py       # CLI that audits near-duplicate ingests in the existing corpus (report-only, never deletes)
├── backfill_source_date.py       # bulk-backfills source_date on existing chunks
├── list_md_files.py              # lists candidate Markdown files for ingestion
├── manage_ingest_status.py       # tracks ingest progress against list_md_files.py's listing
├── manage_conv_ingest_status.py  # tracks ingest progress against convert_conversations.py's output
└── convert_conversations.py      # converts a Claude.ai export (JSON) into Markdown

hybrid_rag/
├── __init__.py
├── ingestion.py            # document processing
├── chunking.py             # semantic chunking
├── indexing.py             # dense & sparse index (FAISS)
├── indexing_bm25.py        # BM25 index
├── indexing_sparse_tfidf.py  # TF-IDF sparse index (shared by the Chroma/Postgres/Qdrant backends)
├── indexing_qdrant.py / indexing_chroma.py / indexing_postgres.py
├── retrieval.py            # RRF search
├── reranking.py            # Cross-encoder reranking (relevance axis)
├── memory_scoring.py        # staged reranking (memory axis: importance/decay/frequency)
├── archival.py              # forgetting/archival batch processing
├── index_health.py          # index/DB consistency checking (backs the ⑫ index_health tool)
├── caching.py / embedding_cache.py
├── context.py / diversity.py / evaluation.py
├── storage.py               # SQLite database (including memory-mechanism fields)
├── query_expansion.py
├── rag_system.py            # main orchestrator (FAISS version, implements the memory mechanism)
├── _rag_system_indexing.py  # ^ ingest/build/incremental-update/load (mixin)
├── _rag_system_query.py     # ^ query pipeline (mixin)
├── _rag_system_memory.py    # ^ tags/neighboring chunks/forgetting batch (mixin)
├── _rag_system_stats.py     # ^ stats & cache management (mixin)
├── _rag_system_docops.py    # ^ embedding/delete/lightweight search (mixin)
├── rag_system_base.py       # base class shared by the Chroma/Postgres/Qdrant backends
├── rag_system_qdrant.py / rag_system_chroma.py / rag_system_postgres.py
└── rag_system_factory.py

tests/
├── test_metadata_pipeline.py   # metadata regression test across ingest → build_index → query
├── test_memory_scoring.py      # unit tests for staged reranking
├── test_archival.py            # unit tests for the forgetting/archival batch
├── test_incremental_index.py   # unit/integration tests for update_index (incremental updates)
├── test_index_health.py        # unit tests for index_health (index/DB consistency check)
├── test_result_dedup.py        # unit tests for RRF fusion-key stability and search-result dedup
├── test_diversity.py           # unit tests for MMR diversity selection
├── test_reranking.py           # unit tests for Cross-encoder reranking stats
├── test_retriever_shutdown.py  # tests for RRFRetriever resource cleanup (thread leaks)
├── test_indexing_bm25.py       # unit tests for the BM25 index
├── test_storage_concurrency.py # unit tests for concurrent SQLite writes
├── test_source_date.py         # unit tests for source_date derivation (time-decay reference point)
├── test_document_chunks.py     # unit tests for get_document_chunks (fetching neighboring chunks)
├── test_evaluation.py          # unit tests for RAGEvaluator (Precision@k, etc.)
├── test_database_stats.py      # unit tests for get_database_stats / duplicate-ingest detection
├── test_guaranteed_candidates.py  # unit tests for guaranteed candidate-pool merging (the fix for principle burial)
├── test_rag_system_factory.py  # unit tests for create_rag_system (backend switching)
└── conftest.py                 # shared pytest configuration

Licencia

Licencia MIT