feat: lightweight agent memory layer for multi-session incident knowledge

[mordonez]

Background

ldev is increasingly used as the operational backbone for agentic workflows around Liferay: diagnosing issues, interacting with the portal, and managing local environments.

Today, every agentic session starts stateless. Even if the same issue was solved yesterday, there is no shared, persistent memory of:

• what symptoms were observed
• what root cause was identified
• what fix actually worked

This leads to repeated reasoning, slower resolution, and lost team knowledge.

---

Problem

When resolving recurring operational issues (e.g. OSGi bundles stuck, Docker disk pressure, portal not reachable), agents and developers:

• re-discover the same causes multiple times
• spend tokens re-exploring already known problem spaces
• lack a shared, tool-agnostic memory across sessions and team members

This is especially visible in bounded domains like Liferay + OSGi + Docker, where incidents are typed and repetitive, not open-ended.

---

Proposal

Introduce a repository-backed episodic incident log, designed to:

• persist resolved incidents in a structured way
• live inside the repo (no external infra)
• be readable by any tool (Claude, Copilot, Codex, Gemini, etc.)
• be surfaced through ldev context to warm-start agents

This is not a general memory system. It is a minimal, structured incident history.

---

MVP Scope

1. Incident Log (JSONL in repo)

Path:

.ldev/memory/incidents.jsonl

Append-only, human-readable, git-friendly.

Example entry:

{
"ts": "2026-04-08T10:00Z",
"type": "osgi-resolved-bundle",
"symptom": "Bundle com.example.x stuck in RESOLVED state",
"cause": "Missing dependency on com.example.y",
"fix": "ldev deploy --module example-y && ldev osgi refresh",
"tags": ["osgi", "deploy"],
"branch": "feature/my-feature"
}

---

2. ldev memory add

Basic command to append a new incident.

Initial version:

• interactive mode
• or --file / --stdin-json for automation

No agent automation required in the first iteration.

---

3. ldev context --memory

Extend ldev context to optionally include recent incidents:

ldev context --memory
ldev context --memory --limit 5

Output should include:

• last N incidents (bounded)
• compact formatting suitable for LLM consumption

Example:

Recent incidents:

• [osgi-resolved-bundle] Missing dependency on com.example.y → fixed via deploy + refresh
• [docker-disk] High usage in /var/lib/docker → cleaned unused volumes

This allows agents to start with:

• current environment state (already supported)
• recent, relevant historical hints

---

4. Minimal Schema

Required fields:

• ts
• type
• symptom
• cause
• fix
• tags
• branch

Optional (future):

• liferayVersion
• environment

---

Non-Goals (for MVP)

Out of scope:

• semantic search / embeddings / vector DB
• automatic agent writes
• rule extraction (propose-rule)
• scoring / ranking
• auto-commit behavior
• lifecycle management (trim/rotate)

---

Why This Approach

• aligns with ldev philosophy: local, reproducible, repo-driven
• zero infrastructure
• fully transparent and reviewable in git
• tool-agnostic

For this domain, structured episodic memory is a simpler and more predictable starting point.

---

Open Questions

• Best formatting for ldev context --memory?
• Schema validation needed?
• Sanitization of sensitive values?
• Default limit (5? 10?)?

---

Success Criteria

• Agents reach a useful hypothesis faster
• Developers actually log incidents
• Log stays readable in git
• Context improves troubleshooting without noise

---

Future (Out of Scope)

• agent-assisted logging
• pruning / archival
• heuristics (recency/type)
• rule extraction (with human review)

---

Related

• ldev context — extend with --memory
• src/features/agent/agent-context.ts