feat: update readme and contribuing guide

.env.example

@@ -0,0 +1,12 @@
+# Cipher Memory Agent Environment Configuration
+# Copy this file and fill in your actual API keys
+
+# OpenAI Configuration (optional - only if using OpenAI)
+#OPENAI_API_KEY=your_openai_api_key_here
+
+# Anthropic Configuration (optional - only if using Anthropic)
+# ANTHROPIC_API_KEY=your_anthropic_api_key_here
+
+# Logger Configuration (optional)
+# CIPHER_LOG_LEVEL=info
+# REDACT_SECRETS=true

CONTRIBUTING.md

@@ -0,0 +1,248 @@
+# Contributing to Cipher
+
+Thank you for your interest in contributing to **cipher**! We're excited to have you as part of our community building the next generation of agent memory systems with Model Context Protocol (MCP).
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+Before you begin, ensure you have:
+
+- **Node.js** ≥ 20.0.0
+- **pnpm** ≥ 9.14.0 (we use pnpm, not npm)
+- **Git** configured with your GitHub account
+
+### 1. Fork & Clone
+
+1. **Fork** the repository to your GitHub account by clicking the "Fork" button
+2. **Clone** your fork:
+
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/cipher.git
+   cd cipher
+   ```
+
+### 2. Set Up Development Environment
+
+```bash
+# Install dependencies
+pnpm install
+
+# Set up environment variables
+cp .env.example .env
+# Edit .env and add your API keys (at least one required):
+# OPENAI_API_KEY=your_openai_key
+# ANTHROPIC_API_KEY=your_anthropic_key
+
+# Build the project
+pnpm run build
+
+# Verify setup by running tests
+pnpm test
+```
+
+### 3. Create Feature Branch
+
+```bash
+git checkout -b feature/your-descriptive-branch-name
+# Examples:
+# - feature/add-memory-persistence
+# - fix/mcp-connection-timeout
+# - docs/update-api-examples
+```
+
+## 🛠 Development Workflow
+
+### Code Quality Standards
+
+Before committing, ensure your code meets our standards:
+
+```bash
+# Type checking
+pnpm run typecheck
+
+# Linting (with auto-fix)
+pnpm run lint:fix
+
+# Code formatting
+pnpm run format
+
+# Run tests
+pnpm test
+
+# Full build verification
+pnpm run build
+```
+
+### Project Structure
+
+Understanding the codebase structure:
+
+```
+src/
+├── app/           # CLI application entry point
+├── core/
+│   ├── brain/     # Core agent logic
+│   │   ├── llm/       # LLM providers (OpenAI, Anthropic)
+│   │   ├── memAgent/  # Agent management
+│   │   └── systemPrompt/
+│   ├── mcp/       # Model Context Protocol integration
+│   ├── session/   # Session management
+│   └── logger/    # Logging infrastructure
+└── utils/         # Shared utilities
+```
+
+### Development Guidelines
+
+#### TypeScript Best Practices
+
+- Use strict TypeScript configuration
+- Implement proper error handling with custom error types
+- Use interfaces and types for clear API contracts
+
+#### Code Style
+
+- Follow existing naming conventions
+- Write self-documenting code with clear variable names
+- Add JSDoc comments for public APIs
+- Maintain consistent indentation and formatting
+
+#### Testing
+
+- Write tests for new functionality in `__test__/` directories
+- Maintain or improve test coverage
+- Use descriptive test names that explain the behavior
+- Mock external dependencies appropriately
+
+#### MCP Integration
+
+- Follow MCP protocol specifications
+- Implement proper connection lifecycle management
+- Add timeout and error handling for server connections
+- Use type-safe server configuration validation
+
+## 📋 Contribution Types
+
+### 🐛 Bug Fixes
+
+- Check existing issues before creating new ones
+- Include reproduction steps and environment details
+- Write regression tests to prevent future occurrences
+
+### ✨ New Features
+
+- **Open an issue first** for discussion on larger features
+- Ensure the feature aligns with cipher's core mission
+- Include comprehensive tests and documentation
+- Update configuration schemas if needed
+
+### 📚 Documentation
+
+- Keep README.md and docs/ up to date
+- Include code examples that work out-of-the-box
+- Update configuration references for new options
+
+### 🔧 Refactoring
+
+- Maintain backward compatibility unless discussed
+- Include performance benchmarks for optimization claims
+- Update related tests and documentation
+
+## 🔄 Submission Process
+
+### 5. Commit Your Changes
+
+Follow conventional commit format:
+
+```bash
+git add .
+git commit -m "feat: add persistent memory layer for agent sessions"
+# Other examples:
+# git commit -m "fix: resolve MCP connection timeout issues"
+# git commit -m "docs: update configuration examples"
+# git commit -m "test: add integration tests for memory persistence"
+```
+
+### 6. Push and Create Pull Request
+
+```bash
+git push origin feature/your-branch-name
+```
+
+Open a Pull Request against the `main` branch with:
+
+- **Clear title** describing the change
+- **Detailed description** explaining:
+  - What problem this solves
+  - How you solved it
+  - Any breaking changes
+  - Testing performed
+- **Link related issues** using `Fixes #123` or `Closes #123`
+
+### Pull Request Checklist
+
+- [ ] Code follows project style guidelines
+- [ ] Self-review completed
+- [ ] Tests added/updated and passing
+- [ ] Documentation updated if needed
+- [ ] No breaking changes (or clearly documented)
+- [ ] Commits follow conventional format
+- [ ] Branch is up to date with main
+
+## 🧪 Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+pnpm test
+
+```
+
+### Test Categories
+
+- **Unit tests**: Test individual functions and classes
+
+## 🐛 Reporting Issues
+
+When reporting bugs, include:
+
+1. **Environment details**: Node.js version, OS, pnpm version
+2. **Reproduction steps**: Minimal code example that demonstrates the issue
+3. **Expected behavior**: What should happen
+4. **Actual behavior**: What actually happens
+5. **Configuration**: Relevant parts of your `cipher.yml` and `.env` (redact API keys)
+6. **Logs**: Any error messages or relevant log output
+
+## 💡 Feature Requests
+
+Before suggesting new features:
+
+1. **Check existing issues** to avoid duplicates
+2. **Explain the use case** - what problem does this solve?
+3. **Propose implementation** if you have ideas
+4. **Consider alternatives** that might already exist
+
+## 🏷 Release Process
+
+We follow semantic versioning:
+
+- **Patch** (0.1.x): Bug fixes, small improvements
+- **Minor** (0.x.0): New features, non-breaking changes
+- **Major** (x.0.0): Breaking changes
+
+## 🤝 Community
+
+- **Discord**: Join our [Discord community](https://discord.com/invite/UMRrpNjh5W)
+- **GitHub Discussions**: For broader conversations and Q&A
+- **Issues**: For bug reports and feature requests
+
+## 📜 License
+
+By contributing to cipher, you agree that your contributions will be licensed under the [Apache License 2.0](LICENSE).
+
+---
+
+**Questions?** Don't hesitate to ask in our Discord or open a discussion on GitHub. We're here to help make your contribution experience smooth and rewarding!
+
+Happy coding! 🎉