CONTRIBUTING.md

Contributing to agentmemory-python

Thanks for your interest. This covers the path from "I have an idea" to "it's merged."

License

Apache-2.0. Every contribution is covered by it.

Before opening an issue

Search open issues and closed issues first.

Bug reports — include:

• Python version (python --version)
• OS
• Exact steps to reproduce
• What you expected vs. what happened
• Any relevant log lines from the server

Feature requests — describe the user problem before the implementation. "I couldn't X because Y" is more useful than "please add Z."

Before opening a PR

1. Fork the repo and create a branch off main:

   • feat/<short-name> for new features
   • fix/<issue-number>-<short-name> for bug fixes
   • docs/<topic> for documentation
   • refactor/<topic>, chore/<topic> for everything else

2. Install dependencies:

   pip install -r requirements.txt
   

3. Make your change. Keep it focused — one logical change per PR.

4. Run the server and test manually:

   python src/app.py
   curl http://localhost:3111/agentmemory/livez
   

5. No test runner is configured yet. If you're adding tests, use pytest:

   pip install pytest
   pytest
   

6. Run linting before submitting:

   pip install ruff
   ruff check src/
   ruff format src/
   

Pull request guidelines

• Write a clear description: what it does, why, and how to verify.
• Link the issue the PR resolves (Fixes #NNN or Closes #NNN).
• Keep PRs small — large PRs are harder to review and slower to merge.
• Address review feedback in new commits, not force-pushes.

Code style

• Python 3.10+. No walrus operator or match/case unless there's a real reason.
• No comments that restate what the code does. Only comment the why — a hidden constraint, a workaround for a specific bug, a non-obvious invariant.
• No dead code or commented-out blocks.
• Validate inputs at system boundaries (REST endpoints, MCP handlers). Never pass raw request bodies to internal functions.
• Use hmac.compare_digest for secret comparisons — never ==.

Architecture rules

When adding a REST endpoint, also update:

• README.md API Reference table
• AGENTS.md if it's agent-callable

When adding an MCP tool, also update:

• The schema list in GET /agentmemory/mcp/tools in src/app.py
• The dispatch handler in POST /agentmemory/mcp/tools in src/app.py
• The tool table in README.md
• The tool list in AGENTS.md

When adding a new KV scope, also update:

• The KV class in src/functions.py
• The scope table in AGENTS.md

Good first contributions

• Add pytest test coverage for src/functions.py
• Add a hook script for a new agent (see INSTALL_FOR_AGENTS.md)
• Add support for an additional embedding provider (OpenAI, Cohere, local)
• Improve error messages in the viewer
• Add a language-specific README to READMEs/

Questions?

Open an issue or start a discussion. The project is small enough that a quick question is usually faster than reading all the code.