bensig
06963ddaed
- Add AGENTS.md with build commands, project structure, conventions - Add .github/dependabot.yml for automated pip + actions updates - Add .github/CODEOWNERS for review routing - Expand .gitignore (.env, .DS_Store, IDE configs, coverage, venvs) - Add C901 complexity rule to ruff (max-complexity=25, benchmarks excluded) - Add --durations=10 to pytest CI for test performance tracking - Add docs/schema.sql for knowledge graph schema documentation - Created P0-P3 priority + area/* + security/performance/docs labels
2.4 KiB
2.4 KiB
AGENTS.md
How to build, test, and contribute to MemPalace.
Setup
pip install -e ".[dev]"
Commands
# Run tests
python -m pytest tests/ -v --ignore=tests/benchmarks
# Run tests with coverage
python -m pytest tests/ -v --ignore=tests/benchmarks --cov=mempalace --cov-report=term-missing
# Lint
ruff check .
# Format
ruff format .
# Format check (CI mode)
ruff format --check .
Project structure
mempalace/
├── mcp_server.py # MCP server — all read/write tools
├── miner.py # Project file miner
├── convo_miner.py # Conversation transcript miner
├── searcher.py # Semantic search
├── knowledge_graph.py # Temporal entity-relationship graph (SQLite)
├── palace.py # Shared palace operations (ChromaDB access)
├── config.py # Configuration + input validation
├── normalize.py # Transcript format detection + normalization
├── cli.py # CLI dispatcher
├── dialect.py # AAAK compression dialect
├── palace_graph.py # Room traversal + cross-wing tunnels
├── hooks_cli.py # Hook system for auto-save
└── version.py # Single source of truth for version
Conventions
- Python style: snake_case for functions/variables, PascalCase for classes
- Linter: ruff with E/F/W rules
- Formatter: ruff format, double quotes
- Commits: conventional commits (
fix:,feat:,test:,docs:,ci:) - Tests:
tests/test_*.py, fixtures intests/conftest.py - Coverage: 85% threshold (80% on Windows due to ChromaDB file lock cleanup)
Architecture
User → CLI / MCP Server → ChromaDB (vector store) + SQLite (knowledge graph)
Palace structure:
WING (person/project)
└── ROOM (topic)
└── DRAWER (verbatim text chunk)
Knowledge Graph:
ENTITY → PREDICATE → ENTITY (with valid_from / valid_to dates)
Key files for common tasks
- Adding an MCP tool:
mempalace/mcp_server.py— add handler function + TOOLS dict entry - Changing search:
mempalace/searcher.py - Modifying mining:
mempalace/miner.py(project files) ormempalace/convo_miner.py(transcripts) - Input validation:
mempalace/config.py—sanitize_name()/sanitize_content() - Tests: mirror source structure in
tests/test_<module>.py