Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ Scale regression: Qarinah also passed **380 / 380 file-specific exact and typo-t

<p align="center">
<a href="https://qarinah.io"><strong>Website</strong></a>&nbsp;&middot;&nbsp;
<a href="https://qarinah.io/docs/features/"><strong>Features</strong></a>&nbsp;&middot;&nbsp;
<a href="https://qarinah.io/docs/getting-started/"><strong>Install</strong></a>&nbsp;&middot;&nbsp;
<a href="https://qarinah.io/docs/"><strong>Documentation</strong></a>&nbsp;&middot;&nbsp;
<a href="https://qarinah.io/paper/"><strong>White paper</strong></a>&nbsp;&middot;&nbsp;
<a href="docs/RESEARCH-BENCHMARK.md"><strong>Research benchmark</strong></a>&nbsp;&middot;&nbsp;
Expand Down Expand Up @@ -139,7 +141,7 @@ npx qarinah query "release provenance" \
--format markdown
```

Start with the [five-minute guide](docs/GETTING-STARTED.md), then use the [cross-agent handoff guide](docs/CROSS-AGENT-HANDOFFS.md), [dashboard guide](docs/DASHBOARD.md), [team-memory guide](docs/TEAM-MEMORY.md), [CLI reference](docs/CLI-REFERENCE.md), [JavaScript API reference](docs/API-REFERENCE.md), [MCP guide](docs/MCP-GUIDE.md), [task recipes](docs/RECIPES.md), or [troubleshooting guide](docs/TROUBLESHOOTING.md).
Start with the [feature map](docs/FEATURES.md) and [five-minute installation guide](docs/GETTING-STARTED.md), then use the [cross-agent handoff guide](docs/CROSS-AGENT-HANDOFFS.md), [dashboard guide](docs/DASHBOARD.md), [team-memory guide](docs/TEAM-MEMORY.md), [CLI reference](docs/CLI-REFERENCE.md), [JavaScript API reference](docs/API-REFERENCE.md), [MCP guide](docs/MCP-GUIDE.md), [task recipes](docs/RECIPES.md), or [troubleshooting guide](docs/TROUBLESHOOTING.md).

Your project already contains the decisions and evidence behind its changes. Qarinah lets the next agent query that record and receive a bounded, cited pack selected for the current task. The same local memory can support Codex, Claude Code, CLI workflows, and compatible MCP clients instead of locking project context to one editor.

Expand Down
45 changes: 45 additions & 0 deletions docs/FEATURES.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# Qarinah features

Qarinah is evidence-linked project memory for coding agents. It keeps an inspectable record beside a software project and compiles bounded, cited context packs for Codex, Claude Code, Cursor, CLI workflows, and compatible MCP clients.

## Project-owned memory

- A canonical, append-only JSONL event record stored with the project.
- Stable event identities, content hashes, and chain verification for detectable edits, deletions, truncation, duplicates, and broken continuity.
- Explicit workspace initialization, machine-local trust, and metadata-only capture by default.
- Configurable content capture, redaction, retention, size, repository, time, and disclosure boundaries.

## Cited context compilation

- Bounded lexical, typo-tolerant, graph, and optional semantic retrieval.
- Complete selected records with event IDs, hashes, retrieval manifests, and evidence-coverage diagnostics.
- Token and character budgets with reserved output space and explicit abstention controls.
- Temporal validity, freshness, supersession, conflict, repository, and authority filtering before context is admitted.
- Deterministic Markdown and JSON context packs that can be inspected before they reach a model.

## Project structure and derived views

- Bounded project scanning with typed file, directory, import, link, and unresolved-reference relationships.
- A rebuildable typed graph and retrieval index derived from the authoritative event record.
- An optional SQLite WAL and FTS5 read model that remains disposable derived state.
- A local read-only dashboard for current and superseded decisions, conflicts, citations, permitted activity, affected files, and caller-supplied context measurements.

## Coding-agent integrations

- Reviewed Codex and Claude Code integrations that use the same explicitly trusted project record.
- Cursor setup, terminal workflows, and project-level instructions.
- A native MCP stdio server with diagnostic-only defaults and explicitly authorized, zero-write context retrieval.
- Cross-agent handoff capsules for continuing a task without replaying the complete retained history.

## Team memory and portability

- Multi-repository context packs that preserve separate repository and authority boundaries.
- Freshness diagnostics, encrypted sync bundles, signed checkpoints, and explicit membership records.
- Deterministic Markdown, JSON, typed graph, and Google Open Knowledge Format exports.
- Schemas and adapters for Cockroach Crawler evidence, Cockroach Browser memory records, ProductLoop runtime events, and optional Maqam authority scopes.

## Verify the boundary

Qarinah is not an autonomous agent runtime, a hosted personalization service, or a guarantee that a model answer is correct. It supplies inspectable project memory to a caller that remains responsible for model choice, current source files, tools, and execution authority.

Continue with [installation and setup](GETTING-STARTED.md), [host integrations](HOST-INTEGRATIONS.md), the [CLI reference](CLI-REFERENCE.md), or the [JavaScript and TypeScript API](API-REFERENCE.md).
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@
"schemas/",
"docs/ARCHITECTURE.md",
"docs/GETTING-STARTED.md",
"docs/FEATURES.md",
"docs/CROSS-AGENT-HANDOFFS.md",
"docs/CROSS-SESSION-CONTINUATION-BENCHMARK.md",
"docs/CROSS-AGENT-VIDEO-PROTOCOL.md",
Expand Down
76 changes: 60 additions & 16 deletions scripts/build-site.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,19 @@ const packageJson = JSON.parse(await readFile(path.join(root, "package.json"), "
const productVersion = packageJson.version;
const productPositioning = "Evidence-linked project memory for coding agents.";
const productExplanation = "Qarinah keeps one compact, cited project memory beside your code, so Codex, Claude Code, Cursor, and compatible tools can continue from verified context instead of starting from zero.";
const qarinahFeatures = [
"Verified handoffs between coding agents",
"Local append-only project memory",
"Evidence-linked cited context packs",
"Typed project and provenance graph",
"Budgeted hybrid retrieval",
"Codex and Claude Code integrations",
"Consent-gated MCP context retrieval",
"Multi-repository memory with separate authority",
"Freshness checks and a visual memory dashboard",
"Encrypted team bundles and signed checkpoints",
"Deterministic Markdown, JSON, graph, and OKF exports"
];
const answerEngineQuestions = [
{
name: "What is Qarinah?",
Expand Down Expand Up @@ -313,6 +326,14 @@ const docPages = [
section: "Start",
aliases: ["install qarinah", "project setup", "first query", "coding agent memory quickstart"]
},
{
route: "docs/features",
source: "docs/FEATURES.md",
title: "Features",
description: "Explore Qarinah project memory, cited context compilation, agent integrations, local dashboards, team memory, exports, and operating boundaries.",
section: "Start",
aliases: ["qarinah features", "project memory features", "coding agent memory capabilities", "context compiler capabilities"]
},
{
route: "docs/cli",
source: "docs/CLI-REFERENCE.md",
Expand Down Expand Up @@ -615,7 +636,9 @@ function rewritePublicationLink(markdown, source) {

function nav(active = "") {
const items = [
["Product", "/", "home"],
["Overview", "/", "home"],
["Features", "/docs/features/", "features"],
["Install", "/docs/getting-started/", "install"],
["Docs", "/docs/", "docs"],
["Answers", "/docs/faq/", "answers"],
["Compare", "/alternatives/", "alternatives"],
Expand Down Expand Up @@ -652,7 +675,8 @@ function footer() {
</div>
<div>
<strong>Build</strong>
<a href="/docs/getting-started/">Getting started</a>
<a href="/docs/features/">Features</a>
<a href="/docs/getting-started/">Install and get started</a>
<a href="/docs/cli/">CLI reference</a>
<a href="/docs/api/">JavaScript API</a>
<a href="/docs/integrations/">Integrations</a>
Expand Down Expand Up @@ -758,19 +782,7 @@ function structuredData({ title, description, canonical, kind = "doc" }) {
installUrl: `${siteOrigin}/docs/getting-started/`,
codeRepository: github,
releaseNotes: `${github}/releases/tag/v${productVersion}`,
featureList: [
"Verified handoffs between coding agents",
"Local append-only project memory",
"Evidence-linked cited context packs",
"Typed project and provenance graph",
"Budgeted hybrid retrieval",
"Codex and Claude Code integrations",
"Consent-gated MCP context retrieval",
"Multi-repository memory with separate authority",
"Freshness checks and a visual memory dashboard",
"Encrypted team bundles and signed checkpoints",
"Deterministic Markdown, JSON, graph, and OKF exports"
],
featureList: qarinahFeatures,
offers: {
"@type": "Offer",
price: "0",
Expand Down Expand Up @@ -919,6 +931,32 @@ function structuredData({ title, description, canonical, kind = "doc" }) {
}))
}
);
} else if (kind === "features") {
graph.push(
{
"@type": "CollectionPage",
"@id": `${url}#features`,
name: title,
description,
url,
inLanguage: "en",
dateModified: releaseDate,
author: { "@id": person["@id"] },
about: { "@id": `${siteOrigin}/#software` }
},
{
"@type": "ItemList",
"@id": `${url}#capability-list`,
name: "Qarinah product capabilities",
itemListOrder: "https://schema.org/ItemListUnordered",
numberOfItems: qarinahFeatures.length,
itemListElement: qarinahFeatures.map((name, index) => ({
"@type": "ListItem",
position: index + 1,
name
}))
}
);
} else if (kind === "benchmark") {
graph.push(
{
Expand Down Expand Up @@ -1794,7 +1832,11 @@ async function markdownPage(page) {
? "benchmarks"
: page.route === "docs/faq"
? "answers"
: "docs";
: page.route === "docs/features"
? "features"
: page.route === "docs/getting-started"
? "install"
: "docs";
const publicationLink = page.route === "paper"
? `<a href="${doi}">Published v1.4 DOI: 10.5281/zenodo.21850747</a> · <a href="${conceptDoi}">Paper series DOI</a> · <a href="${historicalVersionDoi}">Published v1.3</a>`
: "";
Expand All @@ -1810,6 +1852,8 @@ async function markdownPage(page) {
? "benchmark"
: page.route === "docs/faq"
? "faq"
: page.route === "docs/features"
? "features"
: page.route === "docs/getting-started" || page.route === "docs/cross-agent-handoffs"
? "howto"
: page.route === "docs/api" || page.route === "docs/cli" || page.route === "docs/mcp"
Expand Down
25 changes: 25 additions & 0 deletions scripts/check-site.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ const required = [
"docs/index.html",
"docs/cross-agent-handoffs/index.html",
"docs/getting-started/index.html",
"docs/features/index.html",
"docs/cli/index.html",
"docs/api/index.html",
"docs/integrations/index.html",
Expand Down Expand Up @@ -209,6 +210,7 @@ for (const crawler of ["Googlebot", "Bingbot", "OAI-SearchBot", "Claude-SearchBo
const llms = await readFile(path.join(output, "llms.txt"), "utf8");
for (const canonicalResource of [
"https://qarinah.io/docs/",
"https://qarinah.io/docs/features/",
"https://qarinah.io/docs/faq/",
"https://qarinah.io/alternatives/",
"https://qarinah.io/articles/open-source-governed-agent-toolkit/",
Expand All @@ -224,6 +226,7 @@ const alternatives = await readFile(path.join(output, "alternatives", "index.htm
const toolkit = await readFile(path.join(output, "articles", "open-source-governed-agent-toolkit", "index.html"), "utf8");
const paper = await readFile(path.join(output, "paper", "index.html"), "utf8");
const faq = await readFile(path.join(output, "docs", "faq", "index.html"), "utf8");
const features = await readFile(path.join(output, "docs", "features", "index.html"), "utf8");
if (!home.includes("<strong>98.71%</strong>") || !home.includes("the evaluated full-history input was 77.81 times larger")) {
errors.push("Homepage is missing the plain-language benchmark proof.");
}
Expand All @@ -242,6 +245,28 @@ if (home.indexOf('<section class="hero">') > home.indexOf('<section class="bench
if (!home.includes("Evidence-linked project memory for coding agents.") || !home.includes("continue from verified context instead of starting from zero")) {
errors.push("Homepage is missing the cross-agent category or long-term vision.");
}
for (const primaryDestination of [
'href="/docs/features/">Features</a>',
'href="/docs/getting-started/">Install</a>',
'href="/docs/">Docs</a>'
]) {
if (!home.includes(primaryDestination)) errors.push(`Homepage navigation is missing ${primaryDestination}`);
}
for (const capability of [
"Project-owned memory",
"Cited context compilation",
"Project structure and derived views",
"Coding-agent integrations",
"Team memory and portability",
"Verify the boundary"
]) {
if (!features.includes(capability)) errors.push(`Features page is missing ${capability}`);
}
if (!features.includes('"@type":"CollectionPage"')
|| !features.includes('"@type":"ItemList"')
|| !features.includes('"numberOfItems":11')) {
errors.push("Features page is missing its visible capability collection structured data.");
}
for (const launchDirectoryMarkup of [
'href="https://startupbase.io/products/qarinah?utm_source=startupbase&amp;utm_medium=badge&amp;utm_campaign=launch-badge-dark"',
'src="https://statics.startupbase.io/site/badges/launched-on-sb-dark.svg"',
Expand Down
2 changes: 2 additions & 0 deletions website/static/llms.txt
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ This file is a convenience map for tools that choose to read it. It is not a ran
- [Qarinah alternatives](https://qarinah.io/alternatives/): Product-boundary comparison with Mem0, Letta, LangMem, LangGraph memory, Graphiti, Zep, and native coding-host memory.
- [Open-source governed-agent toolkit](https://qarinah.io/articles/open-source-governed-agent-toolkit/): How Qarinah, Maqam, Cockroach Browser, and Cockroach Crawler can compose with established agent, browser, web-data, and document tools.
- [Getting started](https://qarinah.io/docs/getting-started/): Install Qarinah, opt in one workspace, connect a supported host, and compile a cited context pack.
- [Features](https://qarinah.io/docs/features/): Complete product capability map for project-owned memory, cited retrieval, integrations, dashboards, team memory, portability, and boundaries.
- [Documentation index](https://qarinah.io/docs/): Documentation by task.
- [npm package](https://www.npmjs.com/package/qarinah): Published `qarinah` package and registry metadata.
- [GitHub repository](https://github.com/AjnasNB/qarinah): Source, releases, issues, and contribution history.
Expand All @@ -34,6 +35,7 @@ This file is a convenience map for tools that choose to read it. It is not a ran

## Technical documentation

- [Features](https://qarinah.io/docs/features/): Shipped project-memory, context-compilation, integration, team, export, and verification capabilities.
- [CLI reference](https://qarinah.io/docs/cli/): Every command, option, stdin mode, exit code, and machine-readable output.
- [JavaScript API reference](https://qarinah.io/docs/api/): Public exports, types, functions, and bounded programmatic workflows.
- [Host integrations](https://qarinah.io/docs/integrations/): Codex, Claude Code, Cursor, CLI, and consent-gated MCP integration guidance.
Expand Down