fieldmemo

Deployment preflight and memory for Forward Deployed Engineering teams.

fieldmemo reads the scattered traces around a customer deployment and turns them into the artifact an FDE needs before the next meeting:

• top deployment risks
• missing owners, access, systems, data, and eval evidence
• sales assumptions to verify before scope hardens
• operator workflow gaps and workarounds
• first end-to-end slice suggestions
• product-gap evidence with citations
• next questions for the customer, sales, product, or delivery team

The first payoff is current-deployment clarity. Approved, reusable memory compounds as a side effect.

Install

From this repo:

npm install -g .
fieldmemo --help

When published:

npm install -g fieldmemo

Requires Node.js 22.5+ for the local SQLite store.

Five-minute kickoff demo

fieldmemo demo
fieldmemo preflight northstar-logistics

Start with the preflight. The command prints the generated Markdown path; open that file to see what is risky, what evidence is missing, and what to ask before kickoff.

Then, if you want an interactive notebook:

fieldmemo serve --customer northstar-logistics

Open the printed localhost URL and ask follow-up questions like:

What is missing before kickoff?
What are the integration risks?
What should product learn from this customer?
What is the first end-to-end slice?

No LLM key? Chat still shows retrieval-only context. For synthesis, set one:

export OPENAI_API_KEY=...
# or
export ANTHROPIC_API_KEY=...
# or local Ollama
export OLLAMA_HOST=http://localhost:11434

Real workflow

For your own deployment, start with a local folder of notes or exports. Put Markdown, transcripts, copied Slack snippets, tickets, CSVs, or other customer traces in ./exports/acme, then run:

fieldmemo init
fieldmemo onboard acme --path ./exports/acme
fieldmemo preflight acme
fieldmemo review acme --for preflight
fieldmemo changes acme
fieldmemo serve --customer acme
fieldmemo backup verify
fieldmemo brief acme

onboard is the main ingestion command. It configures available connectors, syncs traces, extracts memory candidates, and opens the approval flow when running in a terminal.

preflight is the main first-use artifact. Run it before kickoff, before a customer call, or before scope hardens. Use review to approve or reject claims that should become durable memory, then generate a fuller brief when you need a longer handoff.

--approve-all exists for disposable demos and automation, but it is not the recommended path for team memory. Durable claims should be reviewed in context before they are reused.

Live tools are optional. If you want onboard to sync directly from your systems instead of a local folder:

export NOTION_API_KEY=...
export LINEAR_API_KEY=...
export GITHUB_TOKEN=...
export SLACK_BOT_TOKEN=...

fieldmemo onboard acme --slack-channel C123 --notion --linear-team ENG --github-repo org/repo

Outputs stay local:

.fieldmemo/              local config, SQLite database, source index, sync state
sources/{customer}/      normalized source traces
memory/candidates/       proposed field memories awaiting review
memory/cards/            approved memory cards as JSON + Markdown
memory/clusters/         recurring cross-customer pattern clusters
memory/preflight/        before-deployment risk briefs
memory/changes/          deployment change digests
memory/product-digest.md product-gap and product-learning evidence
memory/sales-risks.md    sales scoping risks and questions
briefs/{customer}.md     deployment discovery brief

SQLite is the source of truth after fieldmemo init. Existing JSON and Markdown files are kept as backup/export artifacts. One-time migration imports legacy source traces, candidates, approved cards, and clusters; approved cards with missing source evidence are skipped and logged in the audit log instead of becoming broken memory.

Current FDE workflow

FDE-facing commands stay small:

onboard   set up a customer and build first memory
preflight show risks, missing evidence, and next questions
changes  show new deltas: blockers, resolved blockers, decisions, questions, gaps, and mitigations
review    approve or reject claims before they become durable memory
brief     generate a longer customer deployment brief with handoff blocks
sync      refresh traces after new meetings or tool updates
serve     open the deployment notebook

Other workflow outputs:

product-digest  cited product-gap evidence
sales-risks     scoping questions and delivery red flags
patterns        repeated cross-customer lessons
chat            exploratory Q&A after the core artifact

Memory model

Internally, onboard and sync run the lower-level pipeline:

connectors
-> source traces
-> memory candidates
-> FDE approval
-> memory cards
-> pattern clusters

sync records connector state in SQLite. Folder sync tracks per-file hash/mtime, Slack uses timestamp cursors, Linear and GitHub use updated-time filters, and Notion records last-edited cursor metadata. Content hashes still provide final duplicate protection.

Memory lifecycle states are explicit:

candidate -> local_only | approved | rejected
approved  -> pattern_candidate -> confirmed_pattern
approved  -> stale | superseded

lessons shows recurrence-1 approved memory. patterns shows repeated memory only. High-risk memory with old evidence is marked stale; newer resolved evidence can mark an older blocker superseded. Artifacts keep stale and superseded memories visible in freshness/conflict sections instead of silently hiding them.

changes uses connector sync state plus a local changes cursor. If the last sync imported no new traces, it renders "No meaningful changes since the last sync"; if a changes digest already showed the current deltas, it does not repeat them. Use fieldmemo changes acme --all to force a pending-candidate view.

review records reviewer, role, reason, approval scope, and optional revalidation date. Product-gap memory enters product-digest only after product/admin approval unless --include-unreviewed-product is explicitly used.

export writes portable JSON/Markdown artifacts. backup verify checks evidence citations against stored source traces and fails on broken references.

The advanced commands still exist for debugging and automation: connect, extract, review, preflight, product-digest, sales-risks, gaps, chat, serve, export, and backup verify.

How this differs from generic memory

Generic memory stores context and retrieves relevant chunks.

Fieldmemo stores approved field lessons:

SourceTrace
-> Evidence
-> MemoryCandidate
-> MemoryCard
-> PatternCluster
-> WorkflowOutput

The graph uses FDE-specific objects and edges: deployment, customer, system, integration, stakeholder, blocker, product gap, workaround, eval criterion, evidence_for, blocks, owned_by, applies_when, repeated_in, and converted_to_product_gap.

Connectors

Connectors are easiest through onboard. Tokens stay in environment variables; Fieldmemo stores only env var names and customer/source config.

Folder/local exports

Use this for customer docs, copied Slack snippets, call transcripts, Postman collections, CSVs, exported tickets, or anything you can put in a folder.

fieldmemo onboard acme --path ./exports/acme --tags kickoff,erp

Supported local inputs:

• Markdown
• text/log files
• JSON/JSONL
• CSV
• Postman collection JSON
• Slack export-style JSON files

Slack

export SLACK_BOT_TOKEN=xoxb-...
fieldmemo onboard acme --slack-channel C123456

The Slack token needs access to the channel history.

Linear

export LINEAR_API_KEY=lin_api_...
fieldmemo onboard acme --linear-team ENG

If you omit --linear-team, Fieldmemo searches recent Linear issues for the customer name.

Notion

export NOTION_API_KEY=secret_...
fieldmemo onboard acme --notion

Share the relevant Notion pages with your integration first.

GitHub

export GITHUB_TOKEN=ghp_...
fieldmemo onboard acme --github-repo org/repo

If you omit --github-repo, Fieldmemo searches accessible GitHub issues/PRs for the customer name.

GitHub token is optional for public repos, recommended for private repos/rate limits.

Chat and notebook

Terminal chat:

fieldmemo chat --customer acme

Browser chat:

fieldmemo serve --customer acme --port 4738

This is not generic "chat with docs." The system prompt is FDE-specific: operator context, integration risk, first slice, evals, scope, reusable patterns, and product gaps.

The browser opens as a deployment notebook: preflight, changes, open questions, candidate review controls, approved lessons, product gaps, sales risks, and chat. Chat is secondary; the first screen shows deployment state without requiring a question.

Brief

fieldmemo brief --customer acme --llm

Brief sections:

• outcome and done definition
• sponsor, champion, operator, IT partner map
• real workflow and hidden workarounds
• systems, data, and access checklist
• integration risks
• first end-to-end slice
• eval criteria and feedback loop
• reusable patterns found
• product-gap candidates
• open questions
• next FDE actions

Without --llm, fieldmemo generates a deterministic evidence brief. With --llm, it synthesizes a cleaner brief and cites source IDs.

Privacy model

• Secrets are read from environment variables, not stored by value.
• .fieldmemo/connections.json stores connector config and env var names.
• Sources and generated artifacts stay on your machine.
• Source text is redacted before persistence for common emails, phone numbers, token-like secrets, bearer tokens, and card-like numbers. Context is redacted again before LLM calls.
• Source traces track permission scope. Retrieval is customer/deployment scoped by default and denies cross-customer retrieval unless an explicit cross-customer mode is used.
• Retrieval uses SQLite FTS, graph traversal over approved memory/conflict edges, local semantic expansion behind the vector-search interface, and task-aware reranking for preflight, product digest, sales risks, changes, patterns, brief, and chat.
• LLM calls only happen when you use chat, serve, or brief --llm.
• You choose OpenAI, Anthropic, Ollama, or retrieval-only mode.

What this is not

• Not a management dashboard.
• Not a replacement for talking to operators.
• Not a "single source of truth."
• Not trying to automate away FDE judgment.
• Not generic agent memory.

It is a deployment learning system with human approval.

Roadmap

• richer connector coverage: Jira, Google Drive/Docs, Teams, and deeper Slack/Linear support
• deeper notebook polish around review batching and handoff export
• hosted/team version with SSO, permissions, and managed retention

License

Apache-2.0.