Update

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,59 @@
+---
+name: Bug report
+about: Report a defect in iai-mcp
+title: "[bug] "
+labels: bug
+---
+
+## Summary
+
+<!-- One sentence describing what is wrong. -->
+
+## Environment
+
+- iai-mcp version: `iai-mcp --version`
+- macOS version:
+- Python version: `python --version`
+- Node version: `node --version`
+- MCP host (Claude Code / Claude Desktop / other):
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Expected behaviour
+
+<!-- What should have happened. -->
+
+## Actual behaviour
+
+<!-- What actually happened. -->
+
+## Doctor output
+
+```
+$ iai-mcp doctor
+<paste full output here>
+```
+
+## Daemon status
+
+```
+$ iai-mcp daemon status
+<paste output here>
+```
+
+## Relevant logs
+
+If applicable, paste the last 30-50 lines from:
+
+```
+~/.iai-mcp/logs/daemon-YYYY-MM-DD.log
+~/.iai-mcp/logs/capture-YYYY-MM-DD.log
+```
+
+## Additional context
+
+<!-- Anything else that helps. Screenshots, related issues, suspected cause. -->

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Documentation
+    url: https://github.com/CodeAbra/iai-mcp#readme
+    about: Check the README for installation, configuration, and troubleshooting.
+  - name: Security report
+    url: https://github.com/CodeAbra/iai-mcp/security/advisories/new
+    about: Report a security issue privately via GitHub Security Advisories.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,35 @@
+---
+name: Feature request
+about: Suggest a feature or enhancement
+title: "[feature] "
+labels: enhancement
+---
+
+## What problem does this solve?
+
+<!-- Describe the user-facing problem or limitation. What can't you do today? -->
+
+## Proposed solution
+
+<!-- What you'd like to see. Concrete is better than abstract. -->
+
+## Alternatives considered
+
+<!-- Other approaches you thought about and why they're worse. -->
+
+## Affected areas
+
+- [ ] Capture path
+- [ ] Recall / retrieval
+- [ ] Consolidation / sleep cycles
+- [ ] Daemon lifecycle
+- [ ] Storage / encryption at rest
+- [ ] MCP wrapper
+- [ ] Bench harness
+- [ ] CLI / doctor
+- [ ] Documentation
+- [ ] Other: ___
+
+## Additional context
+
+<!-- Use case, related issues, prior art. -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,41 @@
+## Summary
+
+<!-- One or two sentences on what this PR changes and why. -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor (no behaviour change)
+- [ ] Documentation
+- [ ] Build / tooling
+
+## Affected areas
+
+- [ ] Capture path
+- [ ] Recall / retrieval
+- [ ] Consolidation / sleep cycles
+- [ ] Daemon lifecycle / FSM
+- [ ] Storage / encryption at rest
+- [ ] MCP wrapper (TypeScript)
+- [ ] Bench harness
+- [ ] CLI / doctor
+- [ ] Other: ___
+
+## Testing
+
+- [ ] `pytest` passes locally
+- [ ] `ruff check src/ tests/` clean
+- [ ] New tests added for changed behaviour, or rationale below for why not
+
+## Benchmarks
+
+If this PR touches retrieval, capture, or consolidation, include before/after numbers from the relevant `bench.*` harness.
+
+- Bench command run: `python -m bench.___`
+- Before:
+- After:
+
+## Notes for reviewers
+
+<!-- Anything reviewers should know: known limitations, follow-ups, design choices. -->

CODE_OF_CONDUCT.md

@@ -0,0 +1,21 @@
+# Code of Conduct
+
+This project adopts the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/), version 2.1, as its code of conduct.
+
+The full text is available at the link above and is incorporated here by reference.
+
+## Scope
+
+This Code applies to all project spaces, including the GitHub repository, issue tracker, pull requests, discussions, and any communication channel set up for the project. It also applies when an individual is officially representing the project in public spaces.
+
+## Reporting
+
+Concerns about behaviour in project spaces can be reported privately to the project maintainer via GitHub Security Advisories on this repository, or by direct message to the maintainer's GitHub account.
+
+All reports are reviewed promptly and treated as confidential. Reporters will not be identified to the subject of the report without consent.
+
+## Enforcement
+
+The project maintainer is responsible for clarifying and enforcing this Code of Conduct, and may take any action they deem appropriate in response to a report, up to and including a permanent ban from project spaces.
+
+Decisions are final at the maintainer's discretion. This is a small project; there is no separate enforcement committee.

CONTRIBUTING.md

@@ -0,0 +1,102 @@
+# Contributing to iai-mcp
+
+Thanks for considering a contribution. This project is small and opinionated. Read this before opening a large PR.
+
+## Scope
+
+iai-mcp is a local memory layer for MCP-over-stdio hosts. Contributions that fit the scope:
+
+- Bug fixes in capture, recall, consolidation, daemon lifecycle, or the MCP wrapper.
+- New bench harnesses, or improvements to existing ones.
+- Documentation fixes and clarifications.
+- Platform support (Linux, Windows) once the abstractions are ready.
+- Compatibility with additional MCP-over-stdio hosts (with evidence it was tested end to end).
+
+Contributions outside scope (will likely be declined):
+
+- Cloud sync, remote storage, or any network-exposed surface beyond the existing local UNIX socket.
+- Major architectural rewrites without prior discussion in an issue.
+- Replacing the three-tier memory model (episodic / semantic / procedural).
+- Telemetry of any kind.
+
+If you're not sure, open an issue first to discuss before writing code.
+
+## Development setup
+
+```bash
+git clone https://github.com/CodeAbra/iai-mcp.git
+cd iai-mcp
+python3.12 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Build the TypeScript MCP wrapper:
+
+```bash
+cd mcp-wrapper
+npm install
+npm run build
+cd ..
+```
+
+## Tests
+
+```bash
+pytest
+```
+
+A handful of daemon and bridge tests are sensitive to test-pollution and may pass cleanly on a rerun. The harness retries up to twice automatically. If a test fails three times, it's a real failure.
+
+For changes to a specific area, the relevant test files:
+
+- Capture: `tests/test_capture_*`
+- Recall: `tests/test_recall_*`
+- Consolidation: `tests/test_consolidation_*`, `tests/test_sleep_*`
+- Daemon lifecycle: `tests/test_daemon_*`, `tests/test_fsm_*`
+- MCP wrapper: `mcp-wrapper/test/`
+
+## Lint
+
+```bash
+ruff check src/ tests/
+ruff format --check src/ tests/
+```
+
+PRs are expected to pass `ruff check` clean.
+
+## Benchmarks
+
+If your change touches retrieval, capture, or consolidation, include before/after numbers from the relevant bench in the PR description:
+
+```bash
+python -m bench.verbatim
+python -m bench.neural_map
+python -m bench.tokens
+python -m bench.longmemeval_blind --split S --out /tmp/out.json
+```
+
+Don't tune to the bench. The LongMemEval-S run is blind on purpose.
+
+## Commit style
+
+- Imperative mood: `Fix X`, `Add Y`, not `Fixed X` or `Adding Y`.
+- One logical change per commit.
+- Keep messages short. One-line subject, body only when motivation is non-obvious.
+
+## Pull requests
+
+- Small PRs land faster than large ones.
+- Reference the issue your PR addresses.
+- Include test coverage for changed behaviour, or explain in the PR description why it isn't applicable.
+- For retrieval / capture / consolidation changes, include bench re-runs.
+
+The PR template will prompt for the relevant items.
+
+## Reporting issues that involve security
+
+Do not open a public issue for anything that looks like a security defect. See [SECURITY.md](SECURITY.md) for the private reporting flow.
+
+## Code of conduct
+
+By participating, you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md).

SECURITY.md

@@ -0,0 +1,69 @@
+# Security Policy
+
+## Supported versions
+
+iai-mcp is pre-1.0 and experimental. Only the latest tagged release on `main` receives fixes. Older tags are not maintained.
+
+| Version | Supported |
+|---------|-----------|
+| 0.1.x   | Yes (latest) |
+| < 0.1   | No |
+
+## Reporting an issue
+
+Please do **not** open a public issue for defects that have security implications. This includes anything that could:
+
+- Disclose stored memories to a third party.
+- Allow recovery of data without the configured passphrase.
+- Cause the daemon to execute arbitrary code from untrusted input.
+- Bypass the local-only network posture.
+
+### How to report
+
+Use GitHub Security Advisories on the repository:
+
+https://github.com/CodeAbra/iai-mcp/security/advisories/new
+
+Include:
+
+- A description of the issue and its impact.
+- Steps to reproduce, or a proof-of-concept if available.
+- Affected version (`iai-mcp --version`).
+- Your environment (macOS version, Python version).
+
+You will receive an acknowledgement within a reasonable window. There is no formal SLA; this is a single-maintainer project. Reports are handled on a best-effort basis.
+
+## Disclosure
+
+Once a fix is available, the advisory is published with credit to the reporter (unless anonymity is requested). Backports to older releases are not guaranteed.
+
+## Threat model and scope
+
+iai-mcp runs locally and is designed around the following assumptions:
+
+- The host machine is trusted. An attacker with local code execution as the user can read the encryption key (`~/.iai-mcp/.key`) and the unlocked store.
+- The MCP host (Claude Code, Claude Desktop, etc.) is trusted. Captured turns include whatever content the host sends.
+- No network exposure. The daemon listens on a UNIX socket only. Any change that adds a TCP listener, HTTP server, or remote sync is out of scope and should be discussed in a public issue first.
+
+### In scope for security reports
+
+- Disclosure of stored records without the passphrase.
+- Weakening of the AES-256-GCM encryption-at-rest (key derivation, nonce reuse, etc.).
+- Arbitrary code execution triggered by captured content.
+- Path traversal or unsafe file operations under `~/.iai-mcp/`.
+- Injection into the MCP wrapper that affects the host process.
+
+### Out of scope
+
+- Social engineering of the user.
+- Physical access to an unlocked machine.
+- Defects requiring the user to manually set insecure file permissions on `~/.iai-mcp/.key`.
+- Denial-of-service against a single user's local daemon by their own process (the daemon is single-user by design).
+
+## Cryptographic notes
+
+- Records are encrypted at rest with AES-256-GCM via the `cryptography` library (pyca/cryptography).
+- The key is derived from a user-provided passphrase using a standard KDF and stored at `~/.iai-mcp/.key` with mode 0600.
+- The OS keychain is used opportunistically via the `keyring` package on platforms where it is available.
+
+Cryptographic primitives are intentionally not hand-rolled. If you spot a misuse of an existing primitive, please report via the advisory flow above.