Thanks for your interest in ContextFirewall! It is a trust firewall for AI coding-agent memory: every memory an agent recalls goes through four checks (staleness, contradiction, secrets, evidence) before it can reach the model. Contributions of every size are welcome — bug reports, docs fixes, new secret detectors, tests, UI polish, and new firewall checks.
By participating you agree to follow our Code of Conduct.
- Ways to contribute
- Finding something to work on
- Project layout
- Development setup
- Running the checks
- Project invariants
- Common contributions
- Coding guidelines
- Commits and pull requests
- Reporting security issues
- License
- Report a bug with the bug report form.
- Propose a feature (a new check, MCP tool, or integration) with the feature request form.
- Improve the docs: README,
mcp/README.md,.env.example, or this guide. - Pick up an open issue and send a pull request.
- Try it in your agent (Claude Code, Cursor, Windsurf, Cline) and tell us what broke or was confusing.
For anything larger than a small fix, please comment on the issue (or open one) before you start, so we can agree on the approach and avoid duplicate work.
| Label | Meaning |
|---|---|
good first issue |
Small, well-scoped, with pointers to the code involved |
help wanted |
Larger tasks where we'd especially welcome help |
security, performance, testing, ci, devex, frontend, mcp, documentation |
Area of the codebase |
Comment "I'd like to work on this" on an issue to claim it. If you go quiet for two weeks we may unassign it so someone else can pick it up — no hard feelings.
backend/ FastAPI + Cognee service (Python 3.12) — deployed to a Hugging Face Space
app/main.py REST API (/pack, /audit, /remember, /forget, /graph, ...)
app/mcp_server.py Hosted MCP server mounted at /mcp (the six tools)
app/firewall/ The four checks (checks.py), secret detector (secrets.py), audit + pack
app/cognee_runtime/ Cognee bootstrap, ingest, recall, improve (memify), forget, LLM + embeddings
app/identity.py API key → namespace resolution (multi-tenant isolation)
data/sessions/ The bundled, fictional taskflow-api demo session
scripts/ Live probes and the end-to-end integration script (need real credentials)
tests/ Unit tests (pytest) — no network, no model calls
frontend/ Next.js 14 + Tailwind console (graph, session replay, Connect view)
mcp/ Standalone stdio MCP package (`uvx contextfirewall-mcp`) that calls the REST API
supabase/migrations/ Auth tables, API keys, and RLS lockdown for the hosted deployment
server.json MCP registry manifest
The REST API and the hosted MCP server share one firewall/Cognee core, so logic belongs in
app/firewall/ or app/cognee_runtime/, not in endpoint handlers.
- Python 3.12 (we recommend
uv) - Node.js 20 and npm 10 (the version CI uses)
- A Hugging Face API token — only needed to run the backend for real; the unit tests don't need one
cd backend
uv venv --python 3.12 .venv
uv pip install -p .venv -r requirements.txt pytest
cp .env.example .env # add your Hugging Face token; never commit .env
set -a && . ./.env && set +a
PYTHONPATH=. .venv/bin/uvicorn app.main:app --reload --port 8000The API is now at http://localhost:8000 (interactive docs at /docs) and the MCP server at /mcp.
In development Cognee uses local file stores under CF_DATA_DIR (./.cf_data, gitignored), so you
don't need Postgres or Neo4j. Load the sample session with curl -X POST localhost:8000/demo/seed.
cd frontend
npm ci
cp .env.local.example .env.local # NEXT_PUBLIC_API_URL=http://localhost:8000
npm run dev # http://localhost:3000Sign-in and per-account API keys also need NEXT_PUBLIC_SUPABASE_URL and
NEXT_PUBLIC_SUPABASE_ANON_KEY; without them the console runs in read-only demo mode with the
auth UI hidden.
cd mcp
uv venv .venv && uv pip install -p .venv -e .
CF_API_BASE=http://localhost:8000 .venv/bin/contextfirewall-mcp # stdio serverTo try it in Claude Code against your local backend:
claude mcp add contextfirewall-dev --env CF_API_BASE=http://localhost:8000 \
-- /absolute/path/to/mcp/.venv/bin/contextfirewall-mcpCI (.github/workflows/ci.yml) runs these on every pull request. Please run them locally first:
# Backend unit tests — fast, offline, no credentials needed
cd backend && PYTHONPATH=. .venv/bin/python -m pytest -q
# Frontend lint, typecheck, production build
cd frontend && npm run lint && npx tsc --noEmit && npm run build
# MCP package tests (Part B talks to a live API — point it at your local backend)
cd mcp && CF_API_BASE=http://localhost:8000 .venv/bin/python -m tests.test_mcpThe scripts in backend/scripts/ (dev_integration.py, mcp_full_probe.py, …) hit real Cognee and
Hugging Face models. Run them when you change ingest, recall, or model plumbing, and mention the
result in your PR. They are not part of CI.
These properties are the point of the project. PRs that weaken them won't be merged, so please call out anything that touches them in your PR description.
- Secrets never persist. Credentials are redacted before anything is written to the graph, vector store, or cognified transcript, and redacted again on every read path. Never log, return, or store raw secret values — including in tests and error messages.
- Fail closed. If a check can't decide (model unavailable, unparsable date, missing data), the memory must not silently become more trusted. An authentication failure must never widen access.
- Namespaces are isolated. A caller only reads, audits, or forgets memories in its own namespace.
The
demonamespace is read-only for everyone except admin flows. - One core, two transports. The six MCP tools must keep the same names, arguments, and semantics
in
backend/app/mcp_server.py(hosted) andmcp/contextfirewall_mcp/(stdio). Change both together and updateREADME.md,mcp/README.md, andserver.json. - No fabricated results. Verdicts, rules, and packs come from real checks over real data. Don't hard-code outputs to make the demo look good.
- Add a
(kind, label, regex)entry to_PATTERNSinbackend/app/firewall/secrets.py. - Add tests to
backend/tests/test_secrets.py: at least one positive match, one realistic negative (a string that looks similar but isn't a secret), and a check thatredact_textremoves the value. - Use obviously fake fixtures (e.g.
AKIAIOSFODNN7EXAMPLE). Real-looking live tokens trip GitHub push protection and other people's scanners.
Checks live in backend/app/firewall/checks.py and return a CheckOutcome(check, passed, reason, severity).
They run in audit_cluster (backend/app/firewall/audit.py), where order decides which block reason
is shown. When you add or change a check:
- keep it deterministic where possible; LLM-assisted logic needs a deterministic fallback (
use_llm=False), - give it a clear, human-readable
reason— it is shown to users and agents, - add unit tests in
backend/tests/test_checks.pycovering pass, block, and edge cases, - make sure the demo session still produces sensible verdicts (
POST /demo/seed, thenPOST /audit).
Update both MCP surfaces (see invariant 4), the request/response models in backend/app/models.py,
the API table in README.md, and the frontend types in frontend/lib/types.ts if the shape changed.
New environment variables must be documented in backend/.env.example (or frontend/.env.local.example)
with a safe default and a one-line comment.
Python (backend, mcp)
- Target Python 3.12 for the backend (the
mcp/package supports 3.10+ — don't use newer syntax there). - Use type hints on public functions and
from __future__ import annotations, as existing modules do. - Keep endpoint handlers thin; put logic in
app/firewall/orapp/cognee_runtime/. - Don't swallow exceptions silently. If a fallback is intentional, keep it narrow and explain why.
- Match the surrounding style: PEP 8, 4-space indentation, double quotes.
TypeScript (frontend)
npm run lintandnpx tsc --noEmitmust pass. Prefer explicit types overany.- Keep API calls in
frontend/lib/api.tsand shared types infrontend/lib/types.ts. - Interactive elements must be keyboard accessible and have accessible names.
- For visual changes, include a before/after screenshot in the PR.
Tests
- Every bug fix should come with a test that fails without the fix.
- Unit tests must not need network access, credentials, or a model. Mock Cognee and the LLM.
- Fork the repository and create a branch from
main(e.g.fix/staleness-timezones). - Make focused changes — one logical change per PR is much easier to review.
- Use Conventional Commits-style messages and PR titles, as the
history does:
feat:,fix:,docs:,test:,ci:,refactor:,chore:(e.g.fix(checks): normalise timezones before comparing dates). - Run the checks above, then open a PR and fill in the template. Link the issue with
Closes #123. - A maintainer will review as soon as possible. Please address feedback by pushing new commits rather than force-pushing, so reviewers can see what changed.
Merges to main that touch backend/ are automatically deployed to the public Hugging Face Space,
so main should always be deployable.
Please do not open public issues for vulnerabilities such as redaction bypasses, cross-namespace access, or auth flaws. Follow SECURITY.md instead.
ContextFirewall is MIT licensed. By contributing, you agree that your contributions are licensed under the same license.