Matryca Plumber

PyPI

PyPI Downloads

GitHub release

Python

Coverage

mypy

License

Platform

Local-first

MCP

Logseq OG

Security

Contributing

Code of Conduct

Discussions

Sponsors

Views

Clones

AI 에이전트에게 내 노트에 접근하게 했더니, 그것들을 손상시켰어.<br>AI가 다시는 이런 일이 일어나지 않도록 Matryca Plumber를 만들었어.

우리는 또 다른 '에이전트 메모리(agentic memory)'를 만드는 것이 아니야..

우리는 인간과 에이전트를 위한 **관리되는 메모리 평면(governed memory plane)**을 구축하고 있어.

인간 소유의 메모리. 에이전트 네이티브 접근. 관리되는 진화.

Matryca Plumber는 그래프 데이터베이스, 벡터 데이터베이스, 임베딩 모델 또는 검색 알고리즘을 정의하거나 요구하지 않아.

v2.0.0 버전이 안정적이며 현재 사용 가능해. Matryca Plumber의 기본 활성화된 외부 Shadow DB, 엄격한 읽기 전용 보호(Strict Read Only protection), Markdown 권한 부여(Markdown authority), 그리고 실패 시 폐쇄되는 폴백 계약(fail-closed fallback contract)은 GitHub Releases와 PyPI에 게시되었어. 정확한 범위 및 업그레이드 노트는 릴리스 기록(release record)와 변경 로그(changelog)를 읽어봐줘.

배포된 유지보수 사전 릴리스: v2.0.1-rc.1은 정확한 역사적 아티팩트로서 선택적 평가를 위해 계속 이용 가능합니다. 이 버전은 Shadow에 질의하거나 그래프를 변경하지 않고 Markdown을 직접 읽는 경계가 지정되고 표준화된(canonical) journal_day 핸들러와 제공자 독립적인 증거 도구링(evidence tooling)을 추가했습니다. 안정 버전인 v2.0.0이 기본 권장 사항으로 유지됩니다. 현재 개발 브랜치는 이 사전 릴리스를 넘어섰기 때문에, 이후의 후보 또는 안정화된 릴리스는 자체적인 정확한 출처 자격 증명(exact-source qualification)을 요구합니다. 릴리스 기록과 역사적 자격 증명 계획을 참조하십시오.

RC2 터미널 히스토리; RC3 게시됨; RC4 대체됨: v2.0.1-rc.2는 GitHub 릴리스 생성 및 PyPI 출판 전에 실패했으며, 이 버전의 서명된 태그와 워크플로우 증거는 불변하지만 공개 아티팩트, Gate B 결과 또는 안정화 승진 크레딧은 아닙니다. v2.0.1-rc.3은 게시된 역사적 사전 릴리스입니다. v2.0.1-rc.4 / 2.0.1rc4는 여전히 미게시 상태입니다. 이전의 정확한 후보 버전(74884c38)은 출처, 빌드 및 설치 리소스 증거를 가지고 있지만, 이후 변경 사항은 자체적인 정확한 출처 자격 증명을 요구합니다. RC4 태그, 공개 아티팩트, Gate B 결과 또는 안정화 승진은 존재하지 않습니다. RC2 실패 게시 기록, RC3 게시 기록, 그리고 역사적 RC4 준비 및 자격 증명 계획을 참조하십시오.

현재 개발 현황: 실험적인 2.1.0a1 준비 단계입니다. 활성 자격 계획서는 오프라인 OG 그래프 식별자 및 완전한 콘텐츠 비의존적 토폴로지 프로듀서를 우선합니다. Linux x86_64, macOS arm64, CPython 3.12/3.13, 그리고 wheel/sdist 경로가 여덟 개의 계획된 행을 구성하며, 이 준비 단계에서는 어느 것도 자격을 갖추지 못했습니다. 대체 기록은 RC4의 역사를 보존하고 미완성된 Windows, 전체 Stage A 및 듀얼 프로파일 게이트 B 의무를 이관합니다. 알파 출판물, 설치형 런타임(installed-runtime), Trama 승인 또는 안정 지원 결과는 주장되지 않으며, v2.0.0이 기본값으로 유지됩니다.**

Logseq OG에서 영감을 받은 로컬 우선 인간/에이전트 메모리 및 Logseq용 유지보수 기능. Matryca Plumber는 사람과 에이전트에게 마크다운 지식 그래프(Markdown knowledge graph)에 대한 안전하고 구조화된 인터페이스를 제공하며, 그 과정에서 불투명한 데이터베이스나 모델 제공업체가 해당 지식의 소유자가 되는 것을 방지합니다.

비디오 개요: 이 영상을 시청하여 Matryca Plumber가 어떻게 작동하는지, 더 넓은 Matryca 생태계와 어떻게 연결되는지, 그리고 공유된 인간/에이전트 메모리에서 어떤 위치를 차지하는지 알아보세요.

빠른 시작 (Quick start)

Python 3.12 이상 및 Logseq OG 그래프가 필요합니다.

# 아무것도 영구적으로 설치하지 않고 UI 실행하기
uvx matryca-plumber status

http://127.0.0.1:8500을 열고, 복제된 Logseq 그래프를 선택한 다음, 사전 비행 점검(pre-flight checks)을 검토하고 준비가 되면 엔진을 시작하세요.

# 선택 사항: 명령어 및 백그라운드 서비스 설치
uv tool install matryca-plumber
matryca service install

그래프의 복제본(clone)으로 시작하는 것이 좋습니다. 특히 쓰기 기능을 활성화하거나 가져오기(import)를 적용하기 전에는 더욱 그렇습니다. operator contract, security policy, 그리고 support guide를 참조하십시오.

안정 버전(stable release)을 명시적으로 설치하려면:

uv tool install matryca-plumber==2.0.0

평가자들은 안정 권장 사항을 변경하지 않고도 게시된 RC1 히스토리 아티팩트를 명시적으로 설치할 수 있습니다:

uv tool install matryca-plumber==2.0.1rc1

2.0.1rc2는 공개적으로 출시되지 않았으며 설치해서는 안 됩니다. 2.0.1rc3은 게시된 히스토리 프리릴리스이며 평가 목적으로만 설치할 수 있습니다:

uv tool install matryca-plumber==2.0.1rc3

2.0.1rc4는 게시되지 않았으며 설치해서는 안 됩니다. 실험적인 2.1.0a1 트랙은 설치 권장 사항이나 게시 기록이 아닌 준비 단계입니다. RC3의 사용 가능 여부나 알파 준비가 Gate B 또는 안정 자격을 증명하지는 않습니다.

위의 일반적인 빠른 시작 방법은 실험적인 OG 게이트웨이 부트스트랩(bootstrap) 방식이 아닙니다. 해당 게이트웨이는 완전한 해시 잠금 파서 1.9.0 종속성 프로필을 갖춘 전용 환경을 요구하며, 그 후 --no-deps를 사용하여 검증된 공개 휠(wheel)을 설치해야 합니다. 광범위한 애플리케이션 종속성 범위와 일반적인 uvx 해결 방식으로는 이 정확한 프로필을 충족할 수 없습니다. 선언된 게이트를 통과한 후에만 alpha plan을 따르십시오.

v2.0.0에서 변경된 사항

안정적인 v2 릴리스는 소유권(ownership)과 변형 경계(mutation boundaries)를 명시적으로 유지하는 동시에 Shadow 읽기 경로를 실용적인 기본값으로 만듭니다:

• 기본 External Shadow DB: 건강한 FTS5 및 서브트리 읽기는 Logseq 그래프 외부의 임시 캐시를 사용합니다. MATRYCA_SHADOW_DB_ENABLED=false로 설정하여 이 기능을 비활성화할 수 있습니다.
• Strict Read Only는 여전히 유용함: MATRYCA_READ_ONLY=true는 그래프 로컬 변형(mutation)을 차단하지만, 검증된 외부 Shadow 유지 관리는 계속 사용할 수 있습니다.
• Markdown이 권위적임: Shadow가 Logseq Markdown, OCC, 또는 파서 인식 쓰기 평면(write plane)을 대체하는 일은 없습니다. 사용 불가능하거나, 오래되었거나, 건강하지 않은 Shadow 상태는 Markdown 기반의 BM25 읽기로 폴백(fallback)합니다.
• 자격 부여된 파서 기준선 및 지원 범위: v2.0.0은 logseq-matryca-parser 1.7.1로 자격 부여되었습니다. 패키지 메타데이터는 >=1.7.1,<2.0.0을 수용하므로, 새로 설치하면 선언된 이 범위 내에서 더 새로운 파서를 해결할 수 있습니다. 실험적인 2.1.0 트랙은 오직 선언된 정확한 파서 프로필만 자격 부여하며, 메타데이터 범위가 다른 해결된 버전에 대한 게이트웨이 자격 부여는 아닙니다.

생물학적 메모리(Biological memory), 네이티브 Logseq DB Safe-Sync 쓰기, 콘텐츠 인식 Tana 병합(merge), 그리고 능동 적응형 런타임(proactive adaptive runtime)은 향후 작업으로 남아 있습니다. 이들은 v2.0.0 계약에 조용히 포함되지 않습니다.

실험적인 OG 프로듀서 방향 (Experimental OG producer direction)

활성 2.1.0 알파 프로그램은 그래프 식별 및 완전한 순서가 지정된, 콘텐츠 없는 OG 토폴로지를 위한 격리되고 오프라인 프로세스 경계를 추가합니다. 계획된 설치 매트릭스(installed matrix), 정확한 의존성 프로필(dependency profile) 및 공개 아티팩트 핸드오프는 alpha 자격 부여 계획에 정의되어 있습니다. 준비와 정적 계약은 설치된 지원이나 사용 가능한 Trama 어댑터를 증명하지 못합니다. 텍스트/속성(properties), Logseq DB, 쓰기, 이벤트, 동기화(sync), 그리고 능동 데스크톱 공존(active-desktop coexistence)은 포함되지 않습니다. Windows 게이트웨이 거부는 부정적 통제(negative control)일 뿐이며, Windows 자격 부여가 아닙니다. 전체 자격 부여 의무는 별도로 남아 있습니다.

<a id="what-the-proposed-v201-rc4-candidate-adds"></a>

역사적인 v2.0.1 RC4 후보 범위 (Historical v2.0.1 RC4 candidate scope)

이 섹션은 대체된(superseded) 미발표 RC4 범위를 보존합니다. 이는 현재의 알파 범위(alpha scope)를 정의하거나 과거에 RC4 후보가 선택되지 않았다고 주장하지 않습니다.

journal_day는 단일 표준 ISO 날짜가 지정된 Logseq 저널을 위한 좁은 읽기 대상입니다. 이는 v2와 동일한 소유권 모델을 유지합니다: Markdown이 권위적이며, 응답에는 제한된 출처(bounded provenance)와 출처 요약(source digest)이 포함됩니다. 잘못된 날짜 및 페이지네이션 요청은 안전하게 실패하며(fail closed), 핸들러는 Shadow 캐시를 초기화하거나 쿼리하지 않습니다. 일반적인 CLI 또는 MCP 프로세스 시작 시에는 여전히 구성된 Shadow 프로필을 전송 전에 준비할 수 있습니다. 이 별도의 부트스트랩 과정은 변경되지 않았습니다. 이 기능은 운영자나 에이전트가 주변 그래프로 검색 범위를 넓히지 않고 하루치 컨텍스트만 필요할 때 유용합니다.

제안된 후보는 기본 활성화된 Shadow 계약(Shadow contract), 읽기 전용 경계(Read Only boundaries), 또는 쓰기 평면(write plane)을 변경하지 않습니다. 이는 내부적이고 세션에 한정된 OG 토폴로지 투영(OG topology projection)을 추가하고 정적인 공개 계약/TCK 바이트만 패키징합니다. Python 어댑터, 전송 계층(transport), CLI/MCP 경로, Logseq DB 기능, 소비자 배선(consumer wiring), UI 또는 LENS 표면을 노출하지 않습니다. 증거 도구는 제공업체에 구애받지 않으며 벤치마크, 실제 에이전트 평가, 또는 출시 결과가 아닙니다. RC4 준비에는 태그, 공개 아티팩트, Gate B 결과, 또는 안정화 승진 결정이 없습니다. RC2 및 RC3의 과거 증거는 RC4를 자격 부여할 수 없습니다.

Matryca Plumber가 필요한 이유