요약 (TL;DR) — 저는 AI 에이전트들이 지식 그래프(Knowledge Graph)를 기반으로 지속적이고 공유된 메모리를 가질 수 있는 오픈 소스 TypeScript 프레임워크를 구축했습니다. 에이전트들은 출처 추적(Provenance tracking)과 함께 사실을 동기화할 수 있고, LLM을 통해 모순을 감지 및 해결하며, 동기화 프로토콜을 통해 시간이 지남에 따라 신뢰를 구축할 수 있습니다. 이 엔진은 5개의 LLM 제공업체에 대해 플러그인 방식으로 연결 가능하며, Cognee의 Rust 기반 그래프/벡터 백엔드를 사용합니다.

문제점 (The Problem)

오늘날 대부분의 AI 에이전트들은 상태가 없습니다 (stateless). 프롬프트를 받고 답변을 생성한 뒤, 대화가 종료되는 순간 모든 것을 잊어버립니다. RAG(검색 증강 생성)나 채팅 기록을 사용하는 에이전트들조차 다음과 같은 기능이 부족합니다:

• 멀티 에이전트 공유 메모리 (Multi-agent shared memory) — 동일한 도메인에서 작업하는 두 에이전트가 지식을 공유하거나 조정할 방법이 없습니다.
• 출처 (Provenance) — 에이전트 A가 에이전트 B로부터 무언가를 배웠을 때, 관리 연속성(Chain-of-custody)이 존재하지 않습니다.
• 모순 처리 (Contradiction handling) — 상충하는 사실들이 아무런 신호 없이 서로를 조용히 덮어씁니다.
• 신뢰 진화 (Trust evolution) — 에이전트가 _어떤 피어(Peer)_를 믿을지 결정할 메커니즘이 없습니다.

Mycelium은 이 네 가지 문제를 해결하기 위해 구축되었습니다.

아키텍처 (Architecture)

                      ┌──────────────────┐
                      │    Dashboard     │  Next.js 15 / React 19
                      │  d3-force viz   │
...

모든 에이전트는 하나의 Cognee 데이터셋에 매핑됩니다. 동기화 엔진(Sync engine)은 출처 태깅(Provenance tagging)과 함께 데이터셋 간의 사실 교환을 중개합니다. 디프 엔진(Diff engine)은 모든 improve() 호출 시 실행되어 구조적 변화, 임베딩 드리프트(Embedding drift), 그리고 논리적 모순을 감지합니다.

기술 스택 (Tech Stack)

계층 (Layer)	기술 (Technology)	이유 (Why)
언어 (Language)	TypeScript (ES2022)	그래프 데이터 구조를 위한 타입 안정성 (Type safety)
...

핵심 개념 (Core Concepts)

1. 에이전트 (Agent)

각 에이전트는 Cognee 데이터셋을 래핑(Wrap)하며 상위 수준의 API를 노출합니다:

const planner = new Agent("travel_planner", "dataset_travel", client);

// 사실 주입 (선택적 출처 포함)
...

2. CogneeClient

2. CogneeClient

Cognee Rust SDK를 감싸는 설정 가능한 래퍼(wrapper)로, 복잡한 환경 변수(env-var) 설정을 처리합니다 (Cognee는 내부적으로 Groq/Ollama로 라우팅할 때조차 LLM_PROVIDER로 `

const engine = new SyncEngine({
  trustStore,
  autoMergeThreshold: 0.6,  // 신뢰도(trust) ≥ 0.6 → 자동 병합(auto-merge)
...

신뢰 모델 (Trust model): 0.5에서 시작하여, 동기화(sync)를 수락하면 +0.05를 추가하고, 거부하면 -0.2를 차감합니다. 이러한 비대칭성은 에이전트가 주의를 기울이도록 유도합니다 — 거부(rejection)의 가중치가 수락(acceptance)보다 4배 더 높습니다.

6. 출처 (Provenance)

에이전트 경계를 넘나드는 모든 사실(fact)에는 태그가 지정됩니다:

tagWithProvenance(text, { sourceAgentId, factId, timestamp })
// → '__provenance__:{"sourceAgentId":"assistant","factId":"src_123","timestamp":…}\n fact text here'

이 접두사(prefix)는 Cognee의 텍스트 저장소에 그대로 유지되므로, extractProvenance()를 통해 회상(recall) 시 관리 연속성(chain of custody)을 검색할 수 있습니다.

LLM 제공자(Provider) 설정

LLM_PROVIDER=groq                          # openai | groq | lm-studio | ollama | custom-openai-compatible
LLM_ENDPOINT=https://api.groq.com/openai/v1
LLM_API_KEY=gsk_...
...

코드 변경 없이 환경 변수(env var) 하나로 제공자를 교체할 수 있습니다:

# OpenAI
USE_LLM_PROVIDER=openai pnpm demo

...

resolveLlmConfig() 함수는 명시적 입력 > 환경 변수 > 제공자 프리셋(provider presets) > 기본값(hard defaults) 순으로 병합합니다. 레거시 별칭(legacy aliases)인 OPENAI_URL / OPENAI_TOKEN은 여전히 폴백(fallback)으로 작동합니다.

여행 어시스턴트 데모 (The Travel Assistant Demo)

examples/travel-assistant-demo/에 있는 엔드 투 엔드(end-to-end) 데모:

pnpm --filter travel-assistant-demo demo

1. 두 명의 에이전트 생성: 여행 플래너 (Travel Planner) 및 개인 비서 (Personal Assistant)
2. 플래너에는 "Alice는 비행기를 타는 것을 즐긴다"를, 비서에는 "Alice는 비행기를 타는 것을 두려워한다"라는 정보를 주입 — 의도적인 모순(contradiction) 발생
3. LLM 호출을 통해 모순 탐지(contradiction detection) 실행
4. 비서의 사실(facts)을 출처(provenance) 태그와 함께 플래너의 데이터셋으로 동기화(sync)
5. improve()를 실행하여 전/후 스냅샷을 캡처하고, 전체 차이점 파이프라인(diff pipeline)을 실행하며, 선택적으로 모순을 자동 해결(auto-resolve)
6. 동기화를 수락하여 신뢰도(trust)를 0.5에서 0.55로 상승

디렉토리 구조 (Directory Structure)

packages/
  core/          src/    — Agent, CogneeClient, diff, LLM config, types
  cli/           src/    — inspectDiff, simulateSync, spawnAgent
...

포크(Fork) 및 기여(Contribute) 방법

1. 클론(Clone) 및 설치:

   git clone https://github.com/harishkotra/mycelium
   cd mycelium
   pnpm install

1. LLM 제공자(Provider) 설정:

   cp packages/core/.env.example packages/core/.env
   # .env 파일을 본인의 API 키로 수정하세요

1. 데모 실행:

   pnpm --filter travel-assistant-demo demo

1. 테스트 실행:

   npx tsx packages/core/test-llm.mjs           # 36개의 LLM 설정 테스트
   npx tsx packages/core/test-improve.ts         # 32개의 개선/해결사 (improve/resolver) 테스트

기여자를 위한 기능 아이디어

기능	난이도	설명
동기화 실행 이력 유지 (Persist sync run history)	쉬움	현재는 인메모리 (in-memory) 방식입니다. JSON 또는 SQLite에 기록하도록 구현하세요
...

설계 원칙 (Design Principles)

• 숨겨진 부작용 없음 (No hidden side-effects) — 순수 함수 (diffSnapshots, resolveContradictions, cosineDistance)는 명시적으로 표시되어 있으며 테스트하기 쉽습니다.
• 환경 변수 우선 설정 (Env-var-first config) — 하나의 환경 변수 (LLM_PROVIDER)만으로 전체 LLM 스택을 변경할 수 있으며, 코드 수정이 필요하지 않습니다.
• 제공자 추상화 (Provider abstraction) — 모순 탐지기 (Contradiction detector)는 제공자별 SDK를 임포트하는 대신, OpenAI 호환 API에 원시 fetch()를 호출합니다.
• Cognee를 구현 세부 사항으로 처리 (Cognee as implementation detail) — Agent 클래스는 내부적으로 Cognee를 래핑(wrap)합니다. 사용자는 Cognee 타입을 직접 임포트하지 않습니다.

코드 및 기타 정보: https://www.dailybuild.xyz/project/180-mycelium