Operations

This page is the practical runbook for developing and checking MemorySmith.

Run Locally

dotnet run --project MemorySmith.App --launch-profile http

The default local URL is http://localhost:5089.

Useful pages:

For setting-level guidance, use Configuration Reference. For model profile and maintenance-agent routing questions, use Agent and Model Configuration.

Validate Changes

Use the solution file for normal validation:

dotnet build MemorySmith.slnx --configuration Release
dotnet test MemorySmith.slnx --configuration Release

For search quality work, also run the focused search and semantic tool tests. For benchmark smoke checks, use the benchmark project rather than assuming UI behavior proves search quality.

For wiki-specific guardrails and the current live-memory validation gap, use Wiki Health and Validation.

Data Deployment Folder

The deployed Data folder is the operational anchor. A complete deployment should have these siblings:

Data/
  Events/
  Graph/
  Memories/
  Models/
  Pages/
  vars.json

MemorySmith:DataPath usually points at Data/Memories. When semantic embedding paths are relative, they resolve from the parent Data folder, not from the process working directory. This matters for Windows Service deployments because the service current directory can be somewhere like C:\Windows.

Default semantic model paths:

{
  "ModelPath": "Models/e5-base-v2.onnx",
  "VocabularyPath": "Models/vocab.txt"
}

Those resolve to Data/Models/e5-base-v2.onnx and Data/Models/vocab.txt. Legacy ../Data/Models/... values are still interpreted relative to the same data root.

Windows Service Notes

The app can run as a Windows Service. When checking a service deployment, verify:

• The service is running after install or restart.
• /health reports the expected data, pages, event log, vars, and semantic model paths.
• Data/Events/audit.log is writable.
• Data/Pages and Data/Memories point to the intended deployment copy, not a build output accident.

For hosted TLS deployment patterns (IIS/reverse proxy/Kestrel cert binding), use HTTPS Production TLS Guide.

Remote Access Outside Home

MemorySmith can be reached from outside the home network, but the current recommended pattern is private remote access, not direct public internet exposure.

Preferred approach:

1. Use a VPN or private mesh such as WireGuard or Tailscale.
2. Keep the app bound behind your home network boundary.
3. Trust artifacts/certs/MemorySmith-LAN-Root-CA.cer on the remote client.
4. Browse to https://memorysmith.home.arpa:7090 or https://192.168.1.8:7090.

Avoid treating the current local/LAN certificate setup as a public hosting solution. memorysmith.home.arpa and the local root CA are appropriate for private network trust, not for public internet clients.

Current repo security planning still treats hardened public remote mode as incomplete. In particular, remote/API guardrails and broader transport/proxy hardening are still tracked as active work, so direct port-forwarding to the internet is not the recommended default posture.

For exact Windows and Android root-CA import steps, use HTTPS Setup Guide.

Pages Publishing

GitHub Pages publishing builds a static site from README.md, Data/Pages, and the structured memory index. The source command is:

python docs/build_pages_site.py

The generated docs/output/wiki directory is build output. It should be regenerated by CI rather than committed by hand.

When Something Looks Wrong

Start with /health, then check configuration in this order:

1. MemorySmith:DataPath
2. MemorySmith:PagesPath
3. MemorySmith:EventLogPath
4. MemorySmith:VarsPath
5. MemorySmith:SemanticSearch:*
6. MemorySmith:Chat:*

Most surprising behavior comes from a path resolving to a different data folder than the one the operator expects.

If the paths look right but the wiki still behaves unexpectedly, follow the focused checks in Wiki Health and Validation before assuming the stored content is wrong.