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:

Route	Check
`/memories`	Memory records load, search works, edit dialogs save.
`/pages`	Markdown pages load, preview works, assets render.
`/chat`	Provider/model options load, context chips appear, responses stream.
`/health`	Readiness is clear, data paths are correct, semantic search status is visible.
`/variables`	`%VarName%` values are available for source links.

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.

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/embedding-model.onnx",
  "VocabularyPath": "Models/vocab.txt"
}

Those resolve to Data/Models/embedding-model.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.

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:

MemorySmith:DataPath
MemorySmith:PagesPath
MemorySmith:EventLogPath
MemorySmith:VarsPath
MemorySmith:SemanticSearch:*
MemorySmith:Chat:*

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