memorytrace 0.1.0__tar.gz

memorytrace-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.db
+*.db-wal
+*.db-shm
+.engram/
+/tmp/
+*.tmp
+.DS_Store
+.env
+.venv/
+venv/

memorytrace-0.1.0/CLAUDE.md

@@ -0,0 +1,196 @@
+# Engram — AI Agent Memory System
+
+## Overview
+AI 에이전트를 위한 지속적·구조적·신뢰할 수 있는 메모리 시스템.
+SQLite+FTS5 기반, MCP 통합, 품질 게이트 내장.
+
+## Tech Stack
+- Language: Python 3.9+
+- Storage: SQLite + FTS5 (표준 라이브러리, 제로 코어 의존성)
+- Search: FTS5 내장 BM25 (기본) / 임베딩 시맨틱 (선택)
+- Agent Integration: MCP 서버 (Claude Code / Codex)
+- LLM: Optional 플러그인 (`pip install engram[llm]`)
+
+## Project Structure
+```
+engram/
+├── models/       # 순수 데이터 클래스 (로직 없음)
+├── storage/      # SQLite+FTS5 백엔드 + Markdown 내보내기
+├── search/       # FTS5 BM25 + 시맨틱 + 하이브리드
+├── extraction/   # 정규식 NER + LLM 추출기
+├── quality/      # 신뢰도, 충돌, PII 게이트
+├── session/      # 세션 관리 + Working Memory
+├── integrations/ # MCP 서버 + Python SDK
+└── cli/          # 사람용 CLI 인터페이스
+```
+
+## Commands
+- `pip install -e ".[dev]"` — 개발 설치
+- `python3 -m pytest tests/ -v` — 전체 테스트
+- `python3 -m engram.cli.app --db ~/.engram/memory.db init` — 메모리 DB 초기화
+- `python3 -m engram.cli.app --db ~/.engram/memory.db store "텍스트"` — 정보 저장
+- `python3 -m engram.cli.app --db ~/.engram/memory.db search "쿼리"` — 검색
+
+## Engram Memory 사용 가이드 (Claude Code용)
+
+### 대화에서 중요한 정보가 나왔을 때 — 저장하기
+
+```bash
+python3 -m engram.cli.app --db ~/.engram/memory.db store "저장할 정보"
+```
+
+### 이전 대화에서 논의한 내용이 필요할 때 — 검색하기
+
+```bash
+python3 -m engram.cli.app --db ~/.engram/memory.db search "검색어"
+python3 -m engram.cli.app --db ~/.engram/memory.db --json search "검색어"
+```
+
+### 특정 인물/조직 정보 조회
+
+```bash
+python3 -m engram.cli.app --db ~/.engram/memory.db get "엔티티 이름"
+python3 -m engram.cli.app --db ~/.engram/memory.db --json get "엔티티 이름"
+```
+
+### Python SDK로 직접 사용 (Bash 도구에서)
+
+```python
+python3 -c "
+from pathlib import Path
+from engram.config import EngramConfig
+from engram.engine import MemoryEngine
+
+engine = MemoryEngine(EngramConfig(base_dir=Path.home() / '.engram'))
+
+# 저장
+engine.store('저장할 텍스트')
+
+# 검색
+result = engine.search('검색어')
+print(result.to_agent_context())
+
+# 엔티티 조회
+entity = engine.get_entity('이름')
+facts = engine.get_facts('이름')
+
+engine.close()
+"
+```
+
+### 사용 시나리오
+
+1. **사용자가 새로운 정보를 공유할 때**: `store`로 저장
+2. **이전 대화 내용이 필요할 때**: `search`로 검색
+3. **특정 인물/조직 배경이 필요할 때**: `get`으로 조회
+4. **프로젝트 시작 시**: `search`로 관련 컨텍스트 로드
+
+## Conventions
+- 커밋 메시지: 한국어 허용, 변경 이유 중심으로 작성
+- 코어 엔진에 `print()` 금지 — CLI 계층에서만 출력
+- 모든 메서드는 구조화된 객체를 반환 (stdout 오염 없음)
+- 타입 힌트 필수, `from __future__ import annotations` 사용
+
+## Design Principles
+1. **에이전트 퍼스트**: MCP/SDK가 1급 인터페이스, CLI는 래퍼
+2. **LLM-Optional**: 코어는 제로 디펜던시, LLM은 선택적 플러그인
+3. **이중 레이어 저장소**: SQLite(쿼리용) + Markdown(열람용)
+4. **방어적 쓰기**: 품질 게이트 → 신뢰도 점수, 충돌 검사, PII 마스킹
+5. **세션 연속성**: 대화 ID 기반 세션, Working Memory, 컨텍스트 캐리오버
+6. **인터페이스 추상화**: storage/search/extraction 교체 가능한 Protocol
+
+## 3단계 검증 (3-Step Verification)
+
+모든 코드 변경 시 아래 3단계를 반드시 거칠 것:
+
+### 1단계: 설계 검증 (Design Review)
+- 변경 사항이 기존 아키텍처와 일관성이 있는가?
+- 불필요한 복잡도를 추가하지 않는가?
+- 해당 기능의 요구사항을 정확히 반영하는가?
+
+### 2단계: 구현 검증 (Implementation Review)
+- 코드가 정상 동작하는가? (빌드, 린트, 타입 체크)
+- 보안 취약점이 없는가? (OWASP Top 10 기준)
+- 에러 핸들링이 적절한가?
+
+### 3단계: 통합 검증 (Integration Review)
+- 기존 기능에 영향을 주지 않는가?
+- 테스트가 모두 통과하는가?
+- 성능 저하가 없는가?
+
+## Code Review Protocol (코드리뷰)
+
+"코드리뷰 진행해줘"라고 요청 시 아래 프로토콜을 따른다. 최대 15회차, 1회차씩 순차 진행. 한 번에 여러 회차 동시 진행 금지.
+
+### 구조: 5단계 × 3회차
+
+| 회차 | 단계 | 포커스 영역 | 체크 항목 |
+|------|------|-----------|----------|
+| 1~3 | 🔴 보안/권한 | OWASP Top 10 | 인증/인가 누락, 입력 검증, SQL 인젝션, XSS, 민감정보 노출, CORS, Rate Limit |
+| 4~6 | 🟠 로직/정합성 | 비즈니스 로직 | 엣지 케이스, 에러 핸들링, null/undefined 처리, 트랜잭션 정합성, 데이터 정합성 |
+| 7~9 | 🟡 성능/최적화 | 쿼리/연산 | N+1 쿼리, 불필요한 재렌더링, 메모리 누수, 번들 사이즈, 캐싱 부재, 인덱스 누락 |
+| 10~12 | 🔵 구조/설계 | 아키텍처 | 의존성 방향, 모듈 분리, 중복 코드, 확장성, SOLID 원칙, 패키지 경계 |
+| 13~15 | ⚪ 컨벤션/가독성 | 코드 품질 | 네이밍, 타입 정확성, 일관성, 불필요한 코드, 주석 필요 여부 |
+
+### 회차 진행 규칙
+
+1. **1회차에 1개 포커스만** — 해당 단계의 포커스 영역만 리뷰
+2. **리뷰 → 수정 → 다음 리뷰** — 수정 없이 다음 회차 진행 금지 (이슈 0건 제외)
+3. **다음 회차 시작 시 이전 수정 검증** — 회귀 체크 먼저 수행
+
+### 조기 종료 조건
+
+- 해당 단계 내 3회 연속 이슈 0건 → 다음 단계로 스킵
+- 전체 리뷰에서 5회 연속 이슈 0건 → 코드리뷰 종료
+- **최소 보장: 🔴 보안/권한 단계(1~3회차)는 반드시 수행**
+
+### 이슈 심각도 분류
+
+| 등급 | 라벨 | 설명 | 수정 필수 |
+|------|------|------|----------|
+| P0 | [CRITICAL] | 보안 취약점, 데이터 손실 가능 | 즉시 수정 |
+| P1 | [ERROR] | 기능 오작동, 로직 오류 | 반드시 수정 |
+| P2 | [WARNING] | 잠재적 문제, 성능 저하 | 권장 수정 |
+| P3 | [INFO] | 개선 제안, 컨벤션 | 선택 수정 |
+
+### 회차별 리포트 형식
+
+```
+## 코드리뷰 [N/15] — {단계 이모지} {단계명}
+
+### 이전 수정 검증
+[PASS/FAIL] {이전 회차 수정 사항 검증 결과}
+
+### 발견 이슈
+1. [P0/P1/P2/P3] 파일명:라인 — 이슈 설명
+   → 수정 방안: ...
+
+### 요약
+- 발견: N건 (Critical: N, Error: N, Warning: N, Info: N)
+- 수정 필요: N건
+- 현재 진행: [N/15] {단계명}
+```
+
+### 코드리뷰 최종 리포트
+
+모든 회차 종료 후 (또는 조기 종료 시) 최종 리포트 작성:
+
+```
+## 코드리뷰 최종 리포트
+- 총 회차: N/15
+- 총 발견 이슈: N건
+- 수정 완료: N건
+- 단계별 이슈: 🔴 N건 / 🟠 N건 / 🟡 N건 / 🔵 N건 / ⚪ N건
+- 잔여 이슈: N건 (사유 명시)
+```
+
+## Development Rules
+
+### Edit Safety
+- 편집 전 파일 재읽기
+- 함수/타입/변수 이름 변경 시: 모든 참조 grep 후 변경
+- 파일 삭제 전 참조 없음 확인
+
+### Context Management
+- 10+ 메시지 후에는 파일 편집 전 반드시 재읽기
+- 5+ 독립 파일 작업 시 서브에이전트 병렬 분배

memorytrace-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Engram Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memorytrace-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: memorytrace
+Version: 0.1.0
+Summary: AI agent memory system with SQLite+FTS5, MCP integration, and quality gates
+Project-URL: Homepage, https://github.com/engram-memory/engram
+Project-URL: Issues, https://github.com/engram-memory/engram/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,fts5,llm,mcp,memory,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: engram[llm]; extra == 'full'
+Requires-Dist: engram[mcp]; extra == 'full'
+Requires-Dist: engram[semantic]; extra == 'full'
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.40.0; extra == 'llm'
+Requires-Dist: openai>=1.50.0; extra == 'llm'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Provides-Extra: semantic
+Requires-Dist: numpy>=1.24.0; extra == 'semantic'
+Description-Content-Type: text/markdown
+
+# Engram
+
+AI agent memory that learns across conversations.
+
+## Install
+
+```bash
+pip install git+https://github.com/aop60003/default.git
+```
+
+## Use
+
+```bash
+engram save "Minseong Jeong is the Space King of Galaxy Corp"
+engram find "Space King"
+engram who "Minseong Jeong"
+```
+
+That's it. 3 commands. No config, no API keys, no database setup.
+
+## All Commands
+
+```
+engram save "text"                   Save information (auto-extracts entities & facts)
+engram find "query"                  Search memory
+engram who "name"                    Look up a person/org
+engram remember "name" "fact"        Manually remember something
+engram all                           List everything
+engram status                        Health check
+engram forget "name"                 Delete an entity
+engram export                        Export to Markdown files
+```
+
+## Examples
+
+```bash
+# Store meeting notes
+engram save "Met Alice Johnson, VP of Engineering at Google. Discussed cloud AI partnership."
+
+# Store Korean
+engram remember "정민성" "AI와 우주 탐사에 관심이 많다"
+
+# Search later
+engram find "Google partnership"
+engram who "Alice Johnson"
+
+# Check status
+engram status
+```
+
+## What It Does Automatically
+
+- **Extracts** people & organizations from text (English, Korean, Chinese, Japanese)
+- **Masks PII** — phone numbers, credit cards, emails become `[REDACTED]`
+- **Deduplicates** — same fact won't be stored twice
+- **Detects conflicts** — "CEO" then "CTO" for same person gets flagged
+- **Generates summaries** — auto-summary when you don't provide one
+- **Learns across sessions** — every conversation builds on previous ones
+
+## For Claude Code Users
+
+Add slash commands to use memory inside Claude Code:
+
+```bash
+# Copy command files
+mkdir -p ~/.claude/commands
+# See docs/04-usage-guide/02-claude-code-setup.md for details
+```
+
+Then use: `/memory-save`, `/memory-find`, `/memory-who`, `/memory-remember`, `/memory-status`
+
+## For Developers (Python SDK)
+
+```python
+from engram.integrations.sdk import EngramSDK
+
+with EngramSDK() as sdk:
+    sdk.store("Minseong Jeong is the Space King of Galaxy Corp")
+    result = sdk.search("Space King")
+    print(result.to_agent_context())
+```
+
+## How It Works
+
+```
+Text → NER Extraction → Quality Gate → SQLite+FTS5 → BM25 Search
+                              ↓
+                     Confidence Scoring
+                     PII Masking
+                     Duplicate Check
+                     Conflict Detection
+```
+
+- **Storage**: SQLite + FTS5 (zero dependencies, genuine BM25)
+- **Export**: Markdown files for human reading
+- **Session**: Context carries over between conversations
+
+## License
+
+MIT

memorytrace-0.1.0/README.md

@@ -0,0 +1,100 @@
+# Engram
+
+AI agent memory that learns across conversations.
+
+## Install
+
+```bash
+pip install git+https://github.com/aop60003/default.git
+```
+
+## Use
+
+```bash
+engram save "Minseong Jeong is the Space King of Galaxy Corp"
+engram find "Space King"
+engram who "Minseong Jeong"
+```
+
+That's it. 3 commands. No config, no API keys, no database setup.
+
+## All Commands
+
+```
+engram save "text"                   Save information (auto-extracts entities & facts)
+engram find "query"                  Search memory
+engram who "name"                    Look up a person/org
+engram remember "name" "fact"        Manually remember something
+engram all                           List everything
+engram status                        Health check
+engram forget "name"                 Delete an entity
+engram export                        Export to Markdown files
+```
+
+## Examples
+
+```bash
+# Store meeting notes
+engram save "Met Alice Johnson, VP of Engineering at Google. Discussed cloud AI partnership."
+
+# Store Korean
+engram remember "정민성" "AI와 우주 탐사에 관심이 많다"
+
+# Search later
+engram find "Google partnership"
+engram who "Alice Johnson"
+
+# Check status
+engram status
+```
+
+## What It Does Automatically
+
+- **Extracts** people & organizations from text (English, Korean, Chinese, Japanese)
+- **Masks PII** — phone numbers, credit cards, emails become `[REDACTED]`
+- **Deduplicates** — same fact won't be stored twice
+- **Detects conflicts** — "CEO" then "CTO" for same person gets flagged
+- **Generates summaries** — auto-summary when you don't provide one
+- **Learns across sessions** — every conversation builds on previous ones
+
+## For Claude Code Users
+
+Add slash commands to use memory inside Claude Code:
+
+```bash
+# Copy command files
+mkdir -p ~/.claude/commands
+# See docs/04-usage-guide/02-claude-code-setup.md for details
+```
+
+Then use: `/memory-save`, `/memory-find`, `/memory-who`, `/memory-remember`, `/memory-status`
+
+## For Developers (Python SDK)
+
+```python
+from engram.integrations.sdk import EngramSDK
+
+with EngramSDK() as sdk:
+    sdk.store("Minseong Jeong is the Space King of Galaxy Corp")
+    result = sdk.search("Space King")
+    print(result.to_agent_context())
+```
+
+## How It Works
+
+```
+Text → NER Extraction → Quality Gate → SQLite+FTS5 → BM25 Search
+                              ↓
+                     Confidence Scoring
+                     PII Masking
+                     Duplicate Check
+                     Conflict Detection
+```
+
+- **Storage**: SQLite + FTS5 (zero dependencies, genuine BM25)
+- **Export**: Markdown files for human reading
+- **Session**: Context carries over between conversations
+
+## License
+
+MIT

memorytrace-0.1.0/docs/01-project-analysis/01-overview.md

@@ -0,0 +1,49 @@
+# 1. 프로젝트 개요
+
+## MemKraft란?
+
+MemKraft는 **AI 에이전트를 위한 제로 디펜던시 복합 메모리 시스템**이다. 핵심 철학은 "모든 대화가 다음 대화를 더 똑똑하게 만든다"는 것으로, AI 에이전트가 세션마다 처음부터 시작하는 대신 지속적이고 구조화된 메모리를 갖도록 한다.
+
+- **저자**: Seojun Kim (simonkim.nft@gmail.com)
+- **라이선스**: MIT
+- **버전**: 0.1.0 (Alpha)
+- **설치**: `pipx install memkraft`
+
+## 핵심 컨셉
+
+### 1. Zero Dependencies (제로 의존성)
+Python 표준 라이브러리만으로 구현. 벡터 DB, spaCy, 외부 API 없이 모든 기능이 동작한다.
+
+### 2. Markdown as Database
+모든 지식을 사람이 읽을 수 있는 Markdown 파일로 저장한다. Git으로 추적 가능하며, 벤더 종속 없이 어떤 텍스트 에디터로든 편집 가능하다.
+
+### 3. Compiled Truth + Timeline
+GBrain 프로젝트에서 차용한 이중 레이어 구조:
+- **Compiled Truth** (상단): 현재 상태의 요약 (Executive Summary, 역할, 소속 등)
+- **Timeline** (하단): 시간순 기록 (`[Source: who, channel, date]` 형식의 출처 표기 필수)
+
+### 4. 출처 추적 (Source Attribution)
+모든 사실에는 출처 태그가 필수다. Dream Cycle이 출처 없는 사실을 자동으로 감지하여 경고한다.
+출처 우선순위: 직접 발언 > 1차 자료 > API > 웹 > 소셜 미디어
+
+### 5. MECE 분류 원칙
+RESOLVER.md 결정 트리를 통해 모든 정보가 정확히 하나의 "홈" 디렉토리를 갖도록 한다. 중복 저장 대신 `[[wiki-links]]`와 "See Also"로 교차 참조한다.
+
+## 프로젝트 포지셔닝
+
+MemKraft는 다음 도구들과 경쟁하는 포지션에 있다:
+
+| 경쟁사 | 차이점 |
+|--------|--------|
+| Mem0 | 벡터 DB 기반 vs. MemKraft의 파일 기반 |
+| Cognee | 그래프 DB + LLM 파이프라인 vs. 순수 Python |
+| Zep | 서버 기반 메모리 vs. 로컬 파일 시스템 |
+| Letta/MemGPT | 복잡한 메모리 계층 vs. 단순한 3-tier 구조 |
+| GBrain | Compiled Truth 모델의 원류 (MemKraft가 차용) |
+
+## 타겟 사용자
+
+- AI 에이전트 개발자
+- 지식 관리 시스템이 필요한 개인/팀
+- 외부 의존성 없이 가벼운 메모리 시스템을 원하는 개발자
+- 한국어/다국어 환경에서 작업하는 사용자

memorytrace-0.1.0/docs/01-project-analysis/02-tech-stack.md

@@ -0,0 +1,60 @@
+# 2. 기술 스택 및 의존성
+
+## 기술 스택 요약
+
+| 계층 | 기술 |
+|------|------|
+| **언어** | Python 3.9+ (3.9 ~ 3.12 지원) |
+| **의존성** | 없음 (Python 표준 라이브러리만 사용) |
+| **스토리지** | 로컬 파일 시스템 (Markdown 파일) |
+| **세션 로깅** | JSONL 포맷 |
+| **검색 엔진** | 커스텀 BM25 스타일 IDF 가중치 토큰 스코어링 |
+| **퍼지 매칭** | `difflib.SequenceMatcher` |
+| **개체명 인식 (NER)** | 정규식 기반 다국어 엔티티 탐지 |
+| **빌드 시스템** | setuptools (`pyproject.toml` + `setup.py`) |
+| **테스트** | pytest (51개 테스트) |
+| **배포** | PyPI 패키지 (CLI 엔트리포인트) |
+
+## 의도적으로 사용하지 않는 기술
+
+MemKraft는 "제로 디펜던시"를 철학으로 삼고 있다. 다음 기술들을 의도적으로 배제했다:
+
+| 일반적 선택 | MemKraft 대안 | 이유 |
+|-------------|---------------|------|
+| 벡터 DB (Pinecone, Chroma 등) | 커스텀 BM25 + IDF 스코어링 | 외부 의존성 제거 |
+| spaCy / Transformers (NER) | 정규식 기반 탐지 | 설치 용량 및 의존성 최소화 |
+| rapidfuzz (퍼지 매칭) | `difflib.SequenceMatcher` | 표준 라이브러리 활용 |
+| SQLite / PostgreSQL | Markdown 파일 | 사람이 읽을 수 있는 형식 유지 |
+| FastAPI / Flask (API 서버) | CLI 인터페이스 | 단순성 우선 |
+| Pillow (이미지 처리) | 순수 Python PNG 생성기 | 의존성 제거 |
+
+## 사용하는 표준 라이브러리 모듈
+
+- `argparse` - CLI 인자 파싱
+- `pathlib` - 파일 경로 처리
+- `json` - JSON 직렬화/역직렬화
+- `datetime` - 날짜/시간 처리
+- `re` - 정규식 패턴 매칭 (NER)
+- `difflib` - 퍼지 문자열 매칭
+- `math` - IDF 계산 (log)
+- `collections` - Counter, defaultdict
+- `shutil` - 파일 복사 (템플릿 초기화)
+- `os` - 환경 변수 (`MEMKRAFT_DIR`)
+- `zlib` - PNG 압축 (배너 생성 스크립트)
+- `struct` - 바이너리 데이터 패킹 (PNG 생성)
+
+## 패키징
+
+```toml
+# pyproject.toml 핵심 설정
+[project]
+name = "memkraft"
+version = "0.1.0"
+requires-python = ">=3.9"
+dependencies = []  # 제로 디펜던시
+
+[project.scripts]
+memkraft = "memkraft.cli:main"
+```
+
+개발 의존성은 `pytest`만 존재한다.