Semvec, Semvec Cortex, Neo4j
12시간 교대 인계에 걸쳐 환자의 전체 이력을 기억하고 3시간 전에 이미 동일한 사례를 조사한 동료가 누구인지 아는 임상 보조자는 모든 대화를 새로운 시작으로 간주하는 보조자와는 전혀 다르게 행동합니다. LLM에는 기본 메모리가 없습니다. 그들은 매 차례마다 전체 대화를 다시 읽어 가짜로 만듭니다. 이는 토큰 비용이 선형적으로 증가한다는 것을 의미합니다. 컨텍스트 창 스냅. 그리고 두 번째 요원이 등장하는 순간 그 환상도 깨집니다.
이 게시물에서는 Semvec이 대략 세 줄의 Python으로 단일 에이전트에 영구 의미 메모리를 제공하는 방법과 Semvec Cortex가 도메인과 대화 상태 모두에 대한 단일 정보 소스인 Neo4j를 사용하여 에이전트 팀 전체에 걸쳐 동일한 엔진을 확장하는 방법을 보여줍니다. 우리는 단일 Python 프로세스로 시작하여 공유 메모리, 드리프트 합의, 교차 교대 핸드오버, 고의적인 합의 투표 및 가져오기 후 알고리즘 드리프트를 포착하는 행동 일관성 프로브를 갖춘 다중 부서 네트워크로 성장하는 의료 도우미를 구축합니다. 모든 코드는 공개 참조 저장소 MichaelNeuberger/neo4j-agent-integrations에서 제공되고 PyPI의 Semvec 0.7.0에서 실행되며 274개 테스트 pytest 제품군에서 실행됩니다.
SemvecClient 소개
이 게시물의 모든 코드 조각은 SemvecClient라는 클래스를 사용합니다. SemvecClient는 pip install semvec의 일부가 아닙니다. 이는 src/semvec_neo4j/core/semvec_client.py의 이 저장소에 정의된 in-process 파사드입니다. semvec.api.*의 SessionManager, ClusterManager, RegionalManager, GlobalObserver 및 NetworkManager를 Neo4j로 직접 미러링하는 데 적합한 일반 Python 사전을 반환하는 하나의 인체공학적 표면으로 구성합니다.
PyPI 패키지 semvec은 SemvecState, SemvecConfig, MultiResolutionMemory, PhaseDetector, LiteralCache, ResonanceTrigger, Cortex 패키지(SemvecAgentNetwork, ConsensusEngine, AttentionAggregation 등) 및 전체 예외 계층 구조와 같은 기본 프리미티브를 내보냅니다. 아래 스니펫을 재현하려면 통합 저장소를 복제하세요. pip install semvec만으로는 SemvecClient, 지속성 저장소 또는 데모 시나리오가 포함되지 않습니다.
숫자(앞에)
LOCOMO 장기 대화형 메모리 벤치마크에서 동일한 제품군 mem0, Zep, Letta 및 GPT-4 터보 전체 컨텍스트 기준 보고서에 대한 Semvec은 수집 시 생성 LLM 호출이 전혀 없는 mem0에 가까운 품질에 도달했습니다. 아래 헤드라인 번호는 공개 Semvec 벤치마크 페이지(semvec-docs.pages.dev/benchmarks), 1:1 평가 설정에서 mem0 0.1.x에 대해 측정됨(gpt-4o-mini 리더 + LLM-판사, T=0):
LOCOMO(대화 10개, 1986년 QA; gpt-4o-mini 리더 + 심사위원, T=0)
제로 수집 LLM 호출에서 J 0.605(LLM-as-Judge, Cat 1–4, n=1540) F1 0.424(포터 기반 토큰-F1, n=1986); 리더 호출당 ~2,000개의 컨텍스트 토큰(전체 컨텍스트 재생보다 ~8배 적음, 87% 감소) 44/675회전에서 최대 3분 수집 대 최대 24.5분 수집(~8배 더 빠름)
mem0 J 0.669(종이)
속도 수치에 대한 참고 사항: 위의 ~8×는 단일 대화 수집 벽시계입니다(conv-44, 675 회전). Semvec 문서는 하이브리드 BM25가 활성화된 GPU 참조 플랫폼에서 측정된 전체 1986-QA 제품군에 대해 17× 엔드 투 엔드 벽시계와 mem0을 별도로 보고합니다.semvec-docs.pages.dev/benchmarks.
이러한 비용 절감 덕분에 다중 에이전트 시나리오를 경제적으로 실용적으로 만들 수 있습니다. 10명의 전문가로 구성된 병동이 교대조당 50개의 질문을 작성하는 것은 더 이상 불가능하지 않습니다. 턴당 업데이트는 최근 x86_64 CPU의 차원 384에서 밀리초 미만입니다. Rust 코어는 GIL 외부에서 실행되므로 수학이 Python과 충돌하지 않습니다.
한 장의 사진으로 보는 건축물
동일한 Neo4j 그래프에는 도메인 지식과 대화 상태가 공존합니다. 환자, 약물, 제공자 및 진단은 상담원 세션, 드리프트 이벤트 및 클러스터 멤버십과 함께 제공됩니다. 단일 Cypher 쿼리는 "에이전트가 무엇을 알고 있는지"와 "무엇을, 언제, 누구에게 요청했는지"를 결합할 수 있습니다. 그 다리는 조사된 관계이며 아키텍처의 중심 부분입니다.
Semvec은 수학을 수행합니다. Neo4j는 결과를 저장합니다. 임베딩 생성, 드리프트 스코어링, 클러스터 집계, 관찰자 샘플링, 사실 추출 및 합의 투표는 모두 작은 프로세스 내 API 뒤에서 발생합니다. Neo4j 통합은 의도적으로 얇습니다. 엔진이 생성할 때 세션, 상태, 드리프트 이벤트, 클러스터 관계 및 축어적 사실을 유지하는 저장소입니다. 중복된 논리가 없습니다.
1부. Semvec을 사용한 단일 에이전트 메모리
이제 가장 작은 유용한 에이전트가 화면에 표시됩니다. 패키지를 설치하고 연결합니다.
pip install semvec
# Then, inside the integrations repo:
from semvec_neo4j.core.embedder import SentenceTransformerEmbedder
from semvec_neo4j.core.semvec_client import SemvecClient
semvec = SemvecClient(embedder=SentenceTransformerEmbedder()) # default: all-mpnet-base-v2 (768-d)
session_id = None
prev_response = None
for user_msg in conversation:
result = semvec.run(message=user_msg, session_id=session_id, response=prev_response)
session_id = result["session_id"] # captured on first turn
answer = call_llm(result["context"], user_msg) # your LLM, your prompt
prev_response = answer # stored alongside the next .run()두 가지 세부 사항이 중요합니다. 먼저, session_id는 첫 번째 호출 시 Semvec에 의해 할당되고 이후 재사용됩니다. 이는 동일한 에이전트가 프로세스가 다시 시작될 때 중단된 부분부터 시작하는 방법입니다. 둘째, 이전 LLM 응답이 버퍼링되어 다음 run() 호출과 함께 전송됩니다. 저장 및 검색이 함께 발생하므로 답변이 제공되었지만 아직 기억되지 않는 경주 기간이 없습니다.
PydanticAI 통합
Semvec 컨텍스트는 @agent.system_prompt 데코레이터를 통해 에이전트 시스템 프롬프트의 일부가 됩니다. 매 턴마다 엔진이 현재 사용자 메시지와 관련이 있다고 간주하는 메모리만 주입됩니다.
@agent.system_prompt
async def inject_semvec_context(ctx: RunContext[Deps]) -> str:
if ctx.deps.semvec_context:
return f"Memory context from previous conversations:\n{ctx.deps.semvec_context}"
return ""무료로 얻을 수 있는 것
각 Semvec 응답은 압축된 텍스트 이상의 내용을 전달합니다. 결과 dict에는 다음이 포함됩니다.
• Drift_phase: 안정/이동/드리프트; 점프는 주제 전환 신호를 보냅니다(6개의 대화 상태 단계 — 불안정을 통한 초기화와는 다름).
• Drift_score: 누적된 컨텍스트로부터 0.0~1.0 숫자 거리
• top_similarity: 최근 임베딩의 롤링 Top-K에 대한 코사인 유사성
• short_circuit: 이전 질문의 다른 표현이 인식되고 LLM 호출을 건너뛸 수 있는 경우 true입니다.
세션은 최신 노드에 대한 CURRENT_STATE 포인터를 사용하여 SemanticState 노드 체인으로 Neo4j에서 즉시 쿼리할 수도 있습니다.
라이브 토큰 절약 패널
이 게시물 상단에 있는 표의 압축 수치는 일회성 벤치마크가 아닙니다. 모든 회전에는 자체 측정이 수행됩니다. SemvecChatProxy는 OpenAI 모양의 llm_call 호출 가능 항목을 래핑하고 전체 기록을 재생할 경우 동일한 대화에 드는 비용 옆에 PSS 압축 프롬프트 토큰 수를 반환합니다. 래퍼는 SemvecClient.create_chat_proxy를 통해 이를 노출합니다.
proxy = semvec.create_chat_proxy(
llm_call=my_llm, # any callable; expose .last_usage for exact counts
system_prompt="You are a clinical assistant.",
)
for question in clinic_questions:
turn = proxy.turn(question)
print(turn["pss_input_tokens"], "vs", turn["baseline_input_tokens"], "phase", turn["phase"])
print(proxy.summary()) # totals + per-turn breakdown데모의 시나리오 1은 입력할 때 턴당 토큰 수와 누적 토큰 수를 모두 인쇄합니다. 압축 비율은 헤드라인 벤치마크에서 예측한 대로 대화 깊이에 따라 높아지며 선별된 데이터 세트가 아닌 질문과 LLM에 대해서도 마찬가지입니다.
앵커, 트리거 및 합성 메모리 주입
에이전트에 고정 도메인이 있는 경우 앵커로 세션을 고정하고 Neo4j 도메인 그래프에서 합성 메모리를 주입합니다. 종양학 약사의 경우 그래프의 모든 금기 사항은 세션이 시작되기도 전에 장기 기억이 됩니다.
session_id = semvec.create_session()["session_id"]
for c in contraindications_from_neo4j: # fetched via Cypher
text = f"CRITICAL: {c['drug_a']} and {c['drug_b']} are contraindicated."
semvec.inject_memory(
session_id=session_id,
embedding=embedder.get_embedding(text).astype(float).tolist(),
text=text, tier="long_term", importance=1.0,
)
semvec.add_trigger(session_id, keyword="contraindication")
semvec.add_anchor(session_id, embedder.get_embedding("oncology chemotherapy treatment").astype(float).tolist())
semvec.set_isolation(session_id, level="QUARANTINE", similarity_threshold=0.55)축어적 사실: 날짜, 복용량, 식별자
의미기억은 의미에 대해 잘 작동합니다. 정확한 값은 안전하지 않습니다. "다음 주입은 2026-05-15입니다"를 임베딩으로 압축하고 나중에 임상의가 "다음 주입은 언제입니까?"라고 묻습니다. "다음 달"을 받을 수도 있고, 더 나쁜 경우에는 잘못된 날짜를 받을 수도 있습니다. 규정 준수 추출기 경로는 입력이 EMA 벡터에 포함되기 전에 정규식 인식 사실(ISO/DE/US 날짜, EUR/USD/kg/% 숫자, UUID/IBAN/DE-VAT 식별자)을 자유 텍스트에서 가져옵니다. 각 사실은 바이트 단위로 압축된 후에도 유지되는 리터럴 캐시에 저장됩니다.
text = "Carlos starts therapy on 2026-05-15. Reimbursement IBAN DE89 3704 0044 0532 0130 00."
facts = semvec.extract_facts(text)
# [{"kind": "date", "raw": "2026-05-15", "value": "2026-05-15T00:00:00+00:00", ...},
# {"kind": "identifier", "raw": "DE89 3704 0044 0532 0130 00",
# "value": "DE89370400440532013000", "id_type": "iban", ...}]
semvec.store_facts_as_entities(session_id, text)
# {"stored": 2} # entries land in the session's literal cache두 가지 실용적인 경고. 업스트림 단위 화이트리스트는 규모가 작으므로(재무 및 운영용으로 구축됨) mg/m²와 같은 의료 단위는 자동 감지되지 않습니다. 그런 경우에는 전체 문장이 포함된 inject_memory를 선호합니다. 그리고 업스트림 EntityKind 열거형이 닫혀 있기 때문에 리터럴 캐시는 종류 상수 아래에 사실을 저장합니다. 원래 종류(숫자/날짜/식별자)는 항목 컨텍스트에 보존되므로 다운스트림 쿼리에서 계속해서 구분할 수 있습니다.
2부. Semvec Cortex를 사용한 다중 에이전트 메모리
Cortex 메서드는 동일한 SemvecClient에 있습니다. 배포할 추가 서비스가 없습니다. 클러스터, 지역, 관찰자, 네트워크, 합의 엔진 및 채팅 프록시는 모두 semvec 패키지에 번들로 제공되며 하나의 Facade를 통해 연결할 수 있습니다.
레이어 2. 클러스터: 에이전트 간 메모리 공유
클러스터는 여러 에이전트 세션에서 읽고 쓰는 공유 의미 체계 상태입니다. 데이비드 박(본태성 고혈압 + COPD)을 검사하는 세 명의 전문가:
cluster = semvec.create_cluster(name="ward_round_david_park", aggregation_mode="weighted_average")
cid = cluster["cluster_id"]
semvec.add_cluster_member(cid, chen_session)
for question, answer in chens_baseline_qa_pairs:
semvec.cluster_store(cid, message=question, response=answer)
semvec.add_cluster_member(cid, volkov_session)
result = semvec.cluster_run(
cluster_id=cid,
message="What's the patient's current oxygen saturation trend?",
short_circuit_threshold=0.52, # calibrated for all-mpnet-base-v2 (768-d)
)Neo4j 측은 각 에이전트의 클러스터 멤버십과 조사된 에지를 터치한 엔터티에 저장합니다. 단일 Cypher 쿼리는 "David Park을 본 사람은 누구이며, 각 사람은 무엇을 찾았습니까?"라고 대답합니다.
레이어 3. 지역: 클러스터 간 합의 드리프트
지역은 여러 클러스터를 그룹화하고 상관된 드리프트 이벤트를 감시합니다. Memorial General의 심장학과 Riverside Medical의 응급 상황이 모두 구성 가능한 시간 내에 동일한 도메인 외부 주제로 표류하는 경우 해당 지역에서는 합의 드리프트 이벤트를 발생시킵니다.
region = semvec.create_region(name="hospital_network_north",
consensus_threshold=0.5,
vote_window_seconds=60.0)
rid = region["region_id"]
semvec.add_region_cluster(rid, cardiology_cluster_id)
semvec.add_region_cluster(rid, emergency_cluster_id)
events = semvec.get_region_events(rid, limit=20)이것이 실제로 포착할 수 있는 점: 병원 네트워크 IT 중단은 단일 티켓이 헬프 데스크에 도달하기 훨씬 전에 임상 쿼리에서 '차트에 액세스할 수 없습니다' 쿼리로 동시에 표류하는 여러 클러스터로 나타납니다.
계층 4. 전역 관찰자: 지역 간 이상 탐지
관찰자는 지역보다 한 수준 위에 위치하여 개별 지역이 표시하지 않는 이상 현상, 즉 너무 오랫동안 침묵하는 클러스터, 합의 이벤트가 가속화되는 지역 또는 두 지역 간의 비정상적인 결합을 감지합니다.
semvec.create_observer(sample_interval_seconds=30.0,
region_ids=[north_region_id, south_region_id])
semvec.observer_sample()
for a in semvec.get_anomalies(limit=20):
print(a["severity"], a["anomaly_type"], a["affected_cluster_ids"], a["description"])레이어 5. 내보내기/가져오기를 통한 교대 핸드오버
야간 근무 의사의 세션은 어려운 환자에 대한 깊은 맥락을 구축했습니다. 오전 6시에 그녀는 이를 내보내고(SHA-256 체크섬 포함) 주간 근무 의사가 이를 가져옵니다. 그의 첫 번째 쿼리는 처음부터 0.000 대신 top_similarity = 0.578로 관련 기억을 즉시 표시합니다.
exported = semvec.export_session(volkov_session_id) # {"state_dict": ..., "checksum": "<sha256>"}
tanaka_session_id = semvec.create_session()["session_id"]
semvec.import_session(tanaka_session_id, state_dict=exported["state_dict"])
# Optional: a partial semantic-delta transfer instead of a full import,
# capped at max_weight to avoid swamping the receiver's existing context.
semvec.transfer_delta(source_session_id=volkov_session_id,
target_session_id=tanaka_session_id,
max_weight=0.15)레이어 6. 가져온 후 동작 일관성 프로브
레이어 5 체크섬은 전송 시 비트 수준 손상을 포착합니다. 이는 유용하지만 가져온 상태가 실제로 소스처럼 작동하는지 여부를 알 수는 없습니다. verify_consistency는 두 세션을 통해 임베딩 프로브를 실행하고 구성 가능한 허용 오차 내에서 코사인 유사성이 일치하는지 확인합니다.
exp = semvec.export_session(volkov_session_id)
semvec.import_session(tanaka_session_id, exp["state_dict"])
probes = [embedder.get_embedding(t).astype(float).tolist() for t in (
"Morrison overnight glucose trend",
"Metformin held for catheterization",
"Cardiac biomarkers at 6h",
)]
passed = semvec.verify_consistency(
tanaka_session_id, probes,
reference_session_id=volkov_session_id,
tolerance=1e-3,
)
print("consistency probe:", "PASSED" if passed else "FAILED")데모의 교대근무 시나리오는 가져오기 라인 바로 아래에 판정을 인쇄하므로 잘못된 추천이 표면화될 때 3턴 후에 손상된 핸드오프가 경계에서 표시되지 않습니다.
레이어 7. ConsensusEngine: 지역 드리프트 위에 명시적 투표
지역 수준 드리프트 감지(레이어 3)는 자체적으로 상관 드리프트에 플래그를 지정합니다. 때때로 애플리케이션은 해당 신호 위에 의도적으로 명명된 투표 프로토콜을 원합니다. semvec.cortex.ConsensusEngine은 모든 합의 모드에 SIMPLE_MAJORITY, QUALIFIED_MAJORITY, UNANIMOUS, WEIGHTED_VOTE, ADAPTIVE_THRESHOLD와 같은 최고 수준의 API를 제공합니다. 래퍼는 이를 통해 다음을 수행합니다.
eng = semvec.create_consensus_engine(
local_id="hospital-orchestrator",
network_id="hospital-network",
level="qualified_majority",
)
for inst, weight in [("cardio", 1.0), ("emerg", 1.0), ("supervisor", 1.5)]:
semvec.register_consensus_voter(eng["engine_id"], inst, weight=weight)
prop = semvec.submit_consensus_proposal(
eng["engine_id"],
proposal_type="admin_pivot_alert",
proposed_state=[0.0] * 8,
rationale="Both clusters drifted to facility-admin within the vote window. Incident?",
)
semvec.vote_on_consensus(eng["engine_id"], prop["proposal_id"], True, voting_instance="cardio")
semvec.vote_on_consensus(eng["engine_id"], prop["proposal_id"], False, voting_instance="emerg")
semvec.vote_on_consensus(eng["engine_id"], prop["proposal_id"], True, voting_instance="supervisor")
verdict = semvec.evaluate_consensus(eng["engine_id"], prop["proposal_id"])
# {"accepted": True, "ratio": 0.71, "votes_for": 2, "votes_against": 1, "status": "accepted"}병원 네트워크 시나리오는 이를 기존 지역 드리프트 단계 바로 뒤에 연결합니다. 두 병원 클러스터가 모두 관리 주제로 드리프트할 때 자격을 갖춘 과반수 투표(감독자 가중치 1.5)를 통해 네트워크 전체 사고로 에스컬레이션할지 여부를 결정합니다.
브리지: Neo4j에서 조사됨
에이전트가 도메인 엔터티(환자, 약물, 진단)에 접근할 때마다 풍부한 감사 추적 페이로드를 전달하는 조사 에지가 Neo4j에 기록됩니다. 모든 에지의 속성에는 step,phase,drift_score,started_at,ended_at,duration_ms,query_preview,response_preview,top_k_similarity, semvec_drift_phase,short_circuit,llm_call,agent_role과 함께 Cluster_id,shift,imported_from,baseline_delta,paraphrase_of,trigger_keyword와 같은 시나리오별 추가 기능이 포함됩니다.
단일 Cypher 쿼리가 양쪽을 조인합니다. 어떤 요원이 제임스 모리슨을 조사했고, 어느 클러스터에서 표류한 사람이 있었으며, 결국 어떤 진단에 이르렀나요?
MATCH (s:AgentSession)-[inv:INVESTIGATED]->(pat:Patient {name: 'James Morrison'})
MATCH (pat)-[:DIAGNOSED_WITH]->(diag:Diagnosis)
OPTIONAL MATCH (s)-[:CURRENT_STATE]->(:SemanticState)-[:TRIGGERED]->(d:DriftEvent)
OPTIONAL MATCH (s)-[:MEMBER_OF]->(c:Cluster)
RETURN s.agent_id, inv.step, inv.drift_score, inv.duration_ms,
inv.semvec_drift_phase, diag.name AS diagnosis,
d.severity AS drift_severity, c.name AS cluster
ORDER BY s.agent_id, inv.step;지난 주에 단락된 모든 차례에 대한 규정 준수 검토자의 쿼리:
MATCH (s:AgentSession)-[inv:INVESTIGATED]->(pat:Patient)
WHERE inv.short_circuit = true
AND inv.started_at >= datetime() - duration('P7D')
RETURN s.agent_id, pat.name, inv.query_preview, inv.paraphrase_of,
inv.top_k_similarity, inv.duration_ms
ORDER BY inv.started_at DESC;일류 그래프 시민으로서의 에이전트, 사실 및 관찰자
세션, 상태 및 드리프트 이벤트는 대화 상태 그래프의 절반에 불과합니다. 독점 semvec 0.7.0 엔진 위에 깔끔하게 설치 가능한 Python 패키지(src/semvec_neo4j/, MIT 라이선스) 통합은 전용 저장소를 통해 4가지 추가 노드 유형을 유지하여 그래프의 절반을 완전하고 쿼리 가능한 감사 표면으로 전환합니다. db.schema.visualization()에 표시되는 모든 노드 유형은 엔진이 실제로 작성하는 항목에 해당합니다. 고아 라벨이 없습니다.
세션 간 앵커 역할을 하는 에이전트
상담원은 단일 대화 그 이상입니다. (:Agent)-[:RAN]->(:AgentSession)을 통해 각 실행에 연결된 일류(:Agent) 노드는 분산된 세션을 쿼리 가능한 명단으로 전환합니다. 이는 에이전트별 신뢰를 위한 자연스러운 본거지이며 시간이 지남에 따라 분석에 영향을 미칩니다. 각 세션의 기본 Agent_id 속성을 사용하면 특정 임상의가 실행한 모든 것을 단일 홉으로 요청할 수 없습니다.
MATCH (a:Agent)-[:RAN]->(s:AgentSession)
RETURN a.agent_id AS agent, count(s) AS sessions
ORDER BY sessions DESC그래프의 축어적 사실
1부에서는 extract_facts가 날짜, 복용량 및 식별자를 바이트 단위로 리터럴 캐시로 가져오는 것을 보여주었습니다. (:AgentSession)-[:EXTRACTED]->(:LiteralFact)를 통해 세션에 연결된 (:LiteralFact) 노드와 동일한 사실이 Neo4j에 도착합니다. (session_id, key) 쌍은 고유하므로 동일한 축어적 범위를 다시 추출하는 것은 멱등성 upsert입니다. 규정 준수 검토자는 상담원이 환자 기록에서 가져온 정확한 값이 무엇인지 물을 수 있으며 압축된 설명이 아닌 바이트 단위의 정확한 답변을 얻을 수 있습니다.
MATCH (s:AgentSession)-[:EXTRACTED]->(f:LiteralFact)
RETURN s.agent_id, f.kind, f.key AS verbatim, f.value, f.unit, f.id_type
ORDER BY s.agent_id, f.kind종양학 안전성 실행에서는 화학 요법 시작 날짜 2026~05~15, 독일 형식 날짜 2개, 환급 금액 4500,00유로, 검증된 IBAN 을 캡처했습니다. 각각은 작성된 대로 정확하게 저장되었습니다.
감사 노드로서의 관찰자와 변칙
레이어 4의 Global Observer는 OBSERVES를 통해 감시하는 지역에 연결된 (:GlobalObserver) 노드로 유지되며, 이 레이어가 감지한 클러스터 간 이상 현상은 (:GlobalObserver)-[:DETECTED]->(:AnomalyEvent) 를 통해 (:AnomalyEvent) 노드로 기록됩니다. (:SemanticState)-[:TRIGGERED]->(:DriftEvent) 세션별 드리프트를 기록하는 에지입니다. 관찰자는 임계값이 넘어갈 때만 이상 현상을 내보냅니다(≥2개 영역이 수렴하거나 클러스터 전체에 걸친 대부분의 체계적 표류). 지속성 경로는 독립적으로 단위 테스트되므로 실제 이상이 발생하는 순간 감사 추적이 안정적입니다.
단일 전체 실행으로 생성되는 결과
라이브 Neo4j에 대해 6가지 데모 시나리오를 한 번 실행하면 번들 의료 그래프가 아래 인벤토리를 생성합니다. 모든 수치는 모형이 아닌 실제 실행에서 나온 것입니다.
실제로 드리프트 감지
Drift_score의 순수 임계값만으로는 완전히 분리되지 않습니다. 의료 하위 주제(Lisinopril 대 Atorvastatin 대 카테터 삽입)는 실제 전문 스위치와 동일한 대역에서 드리프트 점수를 생성합니다. 실제로 작동하는 것은 결합된 규칙입니다.
def is_drift(result: dict) -> bool:
if result.get("drift_detected", False):
return True # Semvec's own verdict (>= 0.5)
return result["drift_score"] >= 0.35 and result["top_similarity"] <= 0.45직관: 여전히 높은 top_similarity와 높은 Drift_score는 새 쿼리가 의미상 참신하지만 축적된 컨텍스트가 이미 해당 쿼리를 다루고 있음을 의미합니다(새 도메인이 아닌 하위 주제). 높은 Drift_Score와 낮은 Top_similarity는 쿼리가 참신하고 메모리에 있는 어떤 것과도 관련이 없음을 의미합니다. 즉, 실제 주제 전환입니다.
의료 데모는 하나의 에이전트를 통해 당뇨병(James Morrison) 17턴, 정신과(Aisha Patel) 5턴, 심장학(Maria Rodriguez) 3턴, 5개의 의역된 1단계 쿼리 등 4단계로 실행됩니다. DRIFT는 전문 분야 내 주제 전환이 아닌 실제 전문 스위치(1단계 → 2단계 및 2단계 → 3단계)에서만 실행됩니다.
생산 패턴
• 하나의 임베더를 선택하고 계속 사용하세요.기본값은 all-mpnet-base-v2(768-d)이며, all-MiniLM-L6-v2(384-d)보다 재현율이 더 좋습니다. Neo4j의 벡터 인덱스 차원은 일치해야 합니다. 배포 중간에 전환하려면 지속된 모든 SemanticState를 다시 포함해야 합니다.
• 클러스터 수명 주기는 기본적으로 수명이 짧습니다.클러스터는 공유 작업 단위(병동 라운드, 사고 대응 또는 영업 통화 팀)에 매핑됩니다. 작업이 시작되면 생성하고 작업이 끝나면 삭제하세요. 수명이 긴 클러스터가 표류합니다. 대신 진정으로 장기적인 공유 지식을 도메인 그래프로 명시적으로 홍보하세요.
• 합의_임계값은 위양성 다이얼입니다.너무 낮게 설정하면(0.2) 임의의 상관관계에 대한 지역 이벤트를 받게 됩니다. 너무 높게 설정하면(0.9) 이미 큰 사건이 발생할 때까지 아무 것도 볼 수 없습니다. vote_window_seconds=60으로 0.5에서 시작한 다음 관찰된 이벤트 비율을 조정하세요. 해당 신호 위에 명명된 프로토콜이 필요한 경우(예: "모든 에스컬레이션에는 적격한 다수의 클러스터와 명시적인 감독자 투표가 필요합니다") ConsensusEngine을 수동으로 롤링하는 임계값으로 접는 대신 연결하세요.
• 앵커와 QUARANTINE 격리는 의미 계층에서 즉각적인 주입을 방지합니다.세션이 종양학 약물 안전에 기반을 두고 있고 누군가 신용 카드 번호에 대한 질문을 하는 경우 LLM에 도달하기 전에 격리 필터가 이를 포착합니다.
• 항상 가져올 때 내보내기 체크섬을 확인한 다음 맨 위에서 동작을 조사하세요.import_session은 SHA-256을 반환합니다. import_session은 dict가 일치하지 않으면 로드를 거부합니다. 그런 다음 소수의 프로브 임베딩으로 verify_consistency를 실행하여 가져온 상태가 실제로 소스처럼 작동하는지 확인합니다. 네트워크 전송은 상태 손상이 자동으로 발생하는 곳입니다.
• 복용량, 날짜 및 식별자를 그대로 저장합니다.extract_facts 및 store_facts_as_entities는 자유 텍스트에서 정확한 값을 가져오고 포함 압축을 우회합니다. 규제된 데이터의 경우 이는 "다음 주입은 5월에 있습니다"와 "다음 주입은 2026-05-15에 있습니다"의 차이입니다.
주요 시사점
• Semvec은 세 줄의 Python으로 단일 에이전트 영구 메모리를 제공합니다.SemvecClient(임베더=…), client.run(메시지), client.store(session_id, 응답). 턴당 일정한 토큰 비용, 무제한 세션 길이, 무료 위상 추적 및 드리프트 감지.
• Cortex는 추가 서비스 없이 다중 에이전트 시나리오로 확장됩니다.create_cluster, Cluster_run, create_region, create_observer, transfer_delta, create_consensus_engine, verify_consistency는 모두 동일한 SemvecClient 인스턴스에 있습니다.
• 도메인과 메모리 모두에 대한 단일 진실 소스로서 Neo4j는 두 시스템을 실행하는 것보다 뛰어납니다.SemanticState의 벡터 인덱스, AgentSession의 제약 조건, 도메인 엔터티에 대한 표준 그래프 순회가 모두 한곳에서 하나의 Cypher로 쿼리됩니다.
• 조사된 관계는 다리입니다.모든 에지에 있는 14개 이상의 속성을 통해 구조화된 데이터처럼 대화 상태를 쿼리할 수 있으며 구조화된 데이터를 합성 메모리로 주입할 수 있습니다.
• 드리프트 감지는 디버깅 도구가 아닌 일류 신호입니다.이를 알림에 연결하세요. 임상 교대 중에 관리 주제로 이동하는 클러스터는 모델이 아닌 운영에 대해 알려주는 것입니다.
• 라이브 토큰 절감액은 턴별로 측정 가능합니다.create_chat_proxy는 모든 호출에 대한 전체 기록 기준 옆에 PSS 압축 프롬프트 토큰 수를 반환하므로 사용자의 질문에 대해 헤드라인 ~8× 토큰 감소가 재현됩니다.
• 축어적 사실은 압축 후에도 유지됩니다.extract_facts 및 store_facts_as_entities는 날짜, 복용량, 식별자를 리터럴 캐시에 바이트 단위로 정확하게 유지합니다.
• API 키가 없습니다. 기본 URL이 없습니다. 네트워크 왕복이 없습니다. 원격 측정이 없습니다.semvec 패키지는 완전히 in-process로 실행됩니다. 모니터링할 종속성이 하나 줄어들고 요청당 송신 비용이 0이 됩니다.
자원
- 설치하다:pip install semvec.
- PyPI: pypi.org/project/semvec. 최신 테스트 버전: 0.7.0.
- 참조 구현:. SemvecClient 래퍼, 의료 데모(6개의 대화형 시나리오 + Cypher 탐색기), 274개 테스트 pytest 제품군.pip install semvec만으로는 SemvecClient, 지속성 저장소 또는 데모 시나리오가 포함되지 않습니다. 그것들은 이 저장소에 있습니다.
- 선적 서류 비치:semvec-docs.pages.dev. 빠른 시작, 개념, 모든 공개 클래스, REST 엔드포인트 카탈로그, LangChain, DeepAgents, PostgreSQL, Neo4j 및 Mem0에 대한 통합 레시피.
- 가격 및 라이선스:semvec.io. 커뮤니티/프로/엔터프라이즈 등급; Air-Gapped 배포를 위한 오프라인 발급 JWT입니다.
- Neo4j AuraDB 무료:neo4j.com/cloud/aura-free. 벡터 인덱스를 지원하는 무료 호스팅 Neo4j 5.x입니다.
- 의료 데모 데이터:uvx 생성-컨텍스트-그래프 의료-테스트-데이터 –도메인 의료 –프레임워크 pydanticai –demo-data
- 지원하다:[이메일 보호됨] · 보안 공개: [이메일 보호됨] · 설립자: [이메일 보호됨]
- 임시 미국 특허 출원 번호 19/269,195 및 19/550,466 계류 중; 유럽 출원 EP 25 188 105 · EP 26 160 795.
데모를 처음부터 끝까지 실행하세요.
git clone https://github.com/VersinoPsiOmega/Semvec-neo4j-agent-integration.git
python3 -m venv .venv && source .venv/bin/activate
uv pip install -e ".[dev]" # pulls semvec from PyPI + repo extras
cp .env.example .env # fill in NEO4J_TEST_PASSWORD + OPENAI_*
python scripts/seed_test_data.py # seed the healthcare graph (required once)
python scripts/interactive_demo.pysemvec-docs.pages.dev · semvec.io · pypi.org/project/semvec
- AI 에이전트
- 지식 그래프