Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
116 lines (85 loc) · 3.68 KB

CONTRIBUTING.md

File metadata and controls

116 lines (85 loc) · 3.68 KB

Contributing to ODEI Agent Memory

Thank you for your interest in contributing. This project is the intellectual property showcase of ODEI's persistent memory architecture.

How to Contribute

Reporting Issues

Open a GitHub issue with:

  • Clear description of the problem
  • Steps to reproduce (if applicable)
  • Expected vs actual behavior
  • Environment details (Neo4j version, Node.js version)

Documentation Improvements

Documentation PRs are welcome. Please ensure:

  • Technical accuracy (all code snippets must reflect the actual codebase)
  • Consistent terminology (use the glossary below)
  • No marketing language in technical docs

Code Contributions

For code contributions to the ODEI MCP server:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feat/your-feature
  3. Write tests for new functionality
  4. Ensure npm run build and npm run lint pass
  5. Commit with conventional format: feat(guardian):, fix(temporal):, docs:
  6. Open a PR with a clear description

Commit Message Format

type(scope): description

Examples:
  feat(guardian): add referential integrity check for cross-layer relationships
  fix(temporal): correct health score calculation for goals without tasks
  docs(schema): update relationship cardinality documentation
  refactor(rbac): extract permission matrix to configuration

Types: feat, fix, docs, refactor, test, chore

Scopes: guardian, temporal, schema, rbac, embedding, audit, retrieval, cache

Development Setup

Prerequisites

  • Node.js 20+
  • Neo4j 5.x (Community or Enterprise)
  • TypeScript 5.x
  • OpenAI API key (for embeddings)

Local Development

# Install dependencies
cd servers/odei-neo4j
npm install

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint

# Export schema documentation
npm run schema:export

Environment Variables

NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password
NEO4J_DATABASE=memory
OPENAI_API_KEY=sk-...
EMBEDDING_MODEL=text-embedding-3-large  # optional, this is the default
LOG_LEVEL=info                           # optional, default 'info'

Code Quality Standards

  • TypeScript strict mode
  • No any types without justification in a comment
  • All Guardian checks must be unit tested with pass and fail cases
  • Zod schemas for all external inputs
  • Provenance required on every write path

Glossary

Term Definition
Entity Any node in the knowledge graph (universal Neo4j label)
Layer One of the 6 semantic layers (foundation, vision, strategy, tactics, execution, track) + cross-cutting (mind, policy, audit)
Guardian The 9-layer validation pipeline that runs on every write
Provenance Metadata tracking who made a write, from which module, with what confidence
Preflight Pre-write checks against the live graph (temporal, referential, constitutional, orphan)
Constitutional score 0-1 measure of how well new content aligns with foundation values and principles
Evidence bucket Node types that agents can write without a Proposal (Insight, Pattern, Observation, etc.)
Fact entity Immutable historical record (Decision, Action, Observation, Event, Signal) -- restricted updates
Audit entity Strictly append-only record (AuditLogEntry, GraphOp, ActionOp) -- no updates, no deletes
Sudo Co-founder override that bypasses some Guardian layers (but never orphan/ref integrity/immutability)
Effective actor The Guardian-attested identity of the caller, based on runtime context not payload

License

By contributing, you agree that your contributions will be licensed under the MIT License.